Options Api

Options are global settings stored in the database. They are available to any plugin, and can be edited by the administrator.

Use options for allowing admins control of how your plugin behaves.

Options admin screen

Adminstrators are able to edit the options from the Jojo "Edit options" page.


Adding new options via plugin API

Any plugin can add the options it needs into Jojo.

  1. create an api.php file in your plugin if one does not already exist.
  2. Copy-paste the following code into api.php
    $_options[] = array(
    'id' => '',
    'category' => '',
    'label' => '',
    'description' => '',
    'type' => '',
    'default' => '',
    'options' => ''
    );

  3. Customize the various parts of the above code (see below)
  4. In a browser, visit www.domain.com/setup/ to install the option you have just created.
  5. Visit www.domain.com/admin/options/ to verify the new option has been added correctly.


For examples of how to add options into Jojo, look in almost any of the plugins bundled with the Jojo download. All the default Jojo options are created and maintained using this same system.

Customize

When you create a new option, the following elements can be customized.

id

This is a unique ID for your option, and all PHP code will refer to this. Choose a unique name that is unlikely to clash with other plugins, which usually means including the plugin name in the ID.
  • The ID must not contain spaces or any special characters. Underscores are acceptable (and recommended) for separating words.
  • Longer IDs are ok, providing they are descriptive. Eg. contact_tracking_code, contact_success_message, contact_webmaster_copy are obvious and descriptive names for options.

category

On the "Edit options" page, the various options are sorted into categories. Use this element to place your option in the most appropriate category. You can create a new category if you need to.
Category names are case-sensitive, so chek the case of the category you wish to use.

label

The label is a descriptive label, or title for the user. Keep this short (a few words) but descriptive and obvious.

description

The description will appear below the option, and is for giving the user as much information as they need to be able to decide how to use your option.
The description is not used for any other purpose at this stage.

type

Options can be different types, which only effects the user interface. The default is "text" which displays a text box for the user to enter their value into.
Types include...
  • text - the default, a text box which accepts any input.
  • integer - a text box that only accepts numeric (integer) input.
  • textarea - a multiline input box for larger options.
  • radio - radio options accept a small number of predefined values, commonly "yes/no". If you use the radio type, be sure to set the default and options elements as well.

default

This can be optional, except for radio type options. When the option is installed for the first time, it is set to whatever default has been specified. Try to select defaults that are most appropriate for most websites - not everyone wants every possible feature of your plugin enabled.

options

Options are for listing the available values for a radio type option. This should be a comma separated list eg "yes,no" or "black,white,red".
Leave blank for all other types.

Reading the value of an option

Options are simply text fields in a database. However, we discourage you from accessing the database directly. Jojo provides a function for reading options, which uses caching to make reading options faster.

To read an option within PHP...

$value = Jojo::getOption('name_of_option');

To read an option within a Smarty template...

Simply use the code below to print the value of an option on a page.
{$OPTIONS.name_of_option}

You may also wist to test against an option using an if statement...
{if $OPTIONS.name_of_option=='yes'}do this{else}do that{/if}