Options are an important part of any plugin or extension when you need to provide the administrator with the ability to set or choose some variable or alternative in your plugin.

{eac}Doojigger makes it relatively easy to add options to the plugin's administrator settings screen.

Registering Options

First, when defining options, they must be registered with the base plugin.

For a derivative plugin, this is done with:

$this->registerPluginOptions( {option_group}, {option_meta} );

or

$this->registerNetworkOptions( {option_group}, {option_meta} );

registerPluginOptions() is used for site administrator options while registerNetworkOptions() is used for network (multisite) administrator options.

{option_group} is the group name under which the options will appear. {eac}Doojigger uses 'plugin_settings' for site options and 'network_settings' for network options.

{option_group} may also be an array with 2 values. The first being the group name as above, the second being the name of a tab you wish the options to appear on. The default tab is "General".

$this->registerPluginOptions( [ 'plugin_settings'  , 'general' ], {option_meta} );

{option_meta} is an array of options to be added/registered (see below).

For a plugin extension, the following methods may be used, using the same format as above.

In the extension's __construct() method, the extension must register itself with the base plugin. In doing so, it can also register options using:

$this->registerExtension( {option_group}, {option_meta} );

Where {option_group} is typically the short class name ($this->className)

If, after registering, the extension needs to add additional options, it can do so using:

$this->registerExtensionOptions( {option_group}, {option_meta} );

This can be done in the __construct() or the initialize() method.

Option Meta Data

The {option_meta} array mentioned above is an array of arrays defining options/settings that can be updated from the plugin's 'settings' page.

• Each option name is automatically prefixed with the plugin name (i.e. 'eacDoojigger').
• Option names must be unique across the plugin and all extensions.

An option is defined as:

'my_option_name'   => array(
                        'type'          =>  'type: {input type}',
                        'label'         =>  'label: {field label}',
                        'title'         =>  'title: information text/html to be displayed',
                        'options'       =>  array({option,...}),
                        'default'       =>  'default: {default option or value}',
                        'info'          =>  'info: Information/instructions',
                        'attributes'    =>  html attributes array ['name="value", name="value"'],
                        'class'         =>  css class name(s) (added to attributes)
                        'style'         =>  css style declaration(s) (added to attributes)
                        'encrypt'       =>  true
                ),

The option array is registered as:

$this->registerPluginOptions( [ 'plugin_settings'  , 'general' ],
    [
        $array_of_option
    ]
);

my_option_name screen shot

Option Name

The option name may be any valid name passed to the WordPress option methods. If the name is prefixed with '_', '-', or '.' it will not be saved to the database. This is most useful for button or display options.

Option Type

The option 'type' value can be any html input type (text, textarea, select, checkbox, radio, etc.). As well as:

• 'codeedit-js', 'codeedit-html', 'codeedit-css', 'codeedit-php' - these types invoke the code editor javascript.
• 'display' - a custom display field which will translate none-scalable values.
• 'disabled' - a disabled text field.
• 'readonly' - A disabled text field that can be enabled by double-clicking.
• 'custom' - a custom input field defined and processed by your filter code.

custom input types use 2 filters...

1. To define the input field. The filter name is options_form_input_{option_name}. It takes 4 arguments: the current html for the field ($html) which should be overwritten, the field name ($fieldName), the meta data/field definition ($metaData), the current field value ($currentValue). Your filter must return the html to display the field.

   public function form_input_option_name($html, $fieldName, $metaData, $currentValue)
   {
       $html = "<inuput ... />";
       return $html;
   }
   $this->add_filter( 'options_form_input_option_name', array($this, 'form_input_option_name'), 10, 4 );

2. To process the field value when it is submitted. The filter name is options_form_post_{option_name}. It takes 4 arguments: the submitted value for the field ($value), the field name ($fieldName), the meta data/field definition ($metaData), the prior field value ($priorValue). Your filter must return the value of the field.

   public function form_post_option_name($value, $fieldName, $metaData, $priorValue)
   {
       return $value;
   }
   $this->add_filter( 'options_form_post_option_name', array($this, 'form_post_option_name'), 10, 4 );

Note: This 2nd filter (options_form_post_{option_name}) is available for any option and may be necessary for some field types (i.e. buttons) to perform an action when submitted.

Option Label

The label value is used as the html <label> value.

Option Title

The title value is displayed as a <blockquote> above the field.

Option Options

The options value is an array of values used in select, checkbox, and radio fields. Each value may be a single option or an array of ['label'=>'option'].

Option Default

The default value for the option (when the option is not set in the wp_options table).

Option Info

The info value is displayed as a <cite> below the field.

Option Attributes

The attributes value is an array of input attributes passed to the input field (i.e. ["placeholder='First Name'"] or ['min="0"', 'max="12"','step="1"']).

Option Class

The class value is a string of CSS/DOM class names passed to the input field.

Option Style

The style value is a string of CSS style declarations passed to the input field.

Option Encrypt

The encrypt option (when truthy) causes the value to be encrypted before being stored in the database. When retrieving the option, use $this->get_option_decrypt(...);

Other Values

width and height may also be set to control the width (columns) of a field and/or the height (rows) of a textarea field.

Plugins must register any options with:

$this->registerPluginOptions( [ 'plugin_settings'  , 'general' ],
    [
        'my_option_name'   => array(
                        'type'          =>  'type: {input type}',
                        'label'         =>  'label: {field label}',
                        'title'         =>  'title: information text/html to be displayed',
                        'options'       =>  array({option,...}),
                        'default'       =>  'default: {default option or value}',
                        'info'          =>  'info: Information/instructions',
                        'attributes'    =>  html attributes array ['name="value", name="value"']
                ),
    ]
);

Extensions must register with:

$this->registerExtension( [ $this->className  , 'My Tab Name' ],
    [
        'my_option_name'   => array(
                        'type'          =>  'type: {input type}',
                        'label'         =>  'label: {field label}',
                        'title'         =>  'title: information text/html to be displayed',
                        'options'       =>  array({option,...}),
                        'default'       =>  'default: {default option or value}',
                        'info'          =>  'info: Information/instructions',
                        'attributes'    =>  html attributes array ['name="value", name="value"']
                ),
    ]
);

Example (myAwesomeExtension):

    $this->registerExtension( [ $this->className, 'Awesome Examples' ],
        [
            'my_option_name'    => array(
                                    'type'          =>  'type: {input type}',
                                    'label'         =>  'label: {field label}',
                                    'title'         =>  'title: information text/html to be displayed',
                                //  'options'       =>  array({option,...}),
                                    'default'       =>  'default: {default option or value}',
                                    'info'          =>  'info: Information/instructions',
                                //  'attributes'    =>  html attributes array ['name="value", name="value"']
                                ),
            'my_option_name_a'  => array(
                                    'type'          =>  'text',
                                    'label'         =>  "Short Label A",
                                    'info'          =>  "(text field) Instructions, description, etc."
                                ),
            'my_option_name_b'  => array(
                                    'type'          =>  'checkbox',
                                    'label'         =>  "Short Label B",
                                    'options'       =>  ['single','checkbox','options'],
                                    'default'       =>  ['single','checkbox','options'],
                                    'info'          =>  "(checkbox field) Instructions, description, etc."
                                ),
            'my_option_name_c'  => array(
                                    'type'          =>  'radio',
                                    'label'         =>  "Short Label C",
                                    'options'       =>  [ ['associated'=>'A'],['radio'=>'R'],['options'=>'O'] ],
                                    'default'       =>  'A',
                                    'info'          =>  "(radio field) Instructions, description, etc."
                                ),
        ]
    );

1. My Awesome Plugin with My Awesome Extension