Plugin Development Part 2 Configuration Page

Part 2. Plugin Configuration Page

Admin backend has a capability to show configuration options for your plugin. These options are defined in config.php.

Here is a sample file:

<?php
class EquipmentConfig extends PluginConfig{
    function getOptions() {
        return array(
            new BooleanField(array(
                'id' => 'equipment_backend_enable',
                'label' => 'Enable Backend',
                'configuration' => array(
                'desc' => 'Staff backend interface')
            )),
            'equipment_frontend_enable' => new BooleanField(array(
                'id' => 'equipment_frontend_enable',
                'label' => 'Enable Frontend',
                'configuration' => array(
                'desc' => 'Client facing interface')
            )),
        );
    }

/// A chance to check the settings before saving
    function pre_save(&$config, &$errors) {
        global $msg;

        if($config['equipment_frontend_enable'] == 1){
                // Validate the settings ? 
                $errors['err'] = 'Validation failed, invalid setting: "Equipment Frontent"'; // example only
                return FALSE;
        }

        if (!$errors) {
            $msg = 'Configuration updated successfully'; // This is the default, and doesn't need to be set.
        }

        return true;
     }
}

This class extends PluginConfig which is located in [INSTALL_ROOT]/include/class.plugin.php.

The function getOptions() returns an array with the plugin configuration options. The array entry:

'equipment_frontend_enable' => new BooleanField(array(
    'id' => 'equipment_frontend_enable',
    'label' => 'Enable Frontend',
    'configuration' => array(
        'desc' => 'Client facing interface'
    )
)),

defines a configuration variable named equipment_frontend_enable, this variable will be represented by a checkbox with id equipment_frontend_enable, and label Enable Frontend. The checkbox will have a description title Client facing interface.

This data will be saved into the database TABLE_CONFIG namespaced for the plugin number (each time you install a plugin you increment the plugin number). So, this might be plugin.3 or plugin.44 as the namespace, but it means you can have as many plugins installed as you like, each calling $this->getConfig()->get('setting'); and have 'setting' be unique to all of them. You'll find the data either scalar stored or JSON encoded into the value field of the table.

The following is a list of class fields that are available, they are defined in [INSTALL_ROOT]/include/class.forms.php:

TextboxField - text box
TextareaField - text area
ThreadEntryField - rich text area, used for discussion threads
DatetimeField - JQuery datepicker
PhoneField - text box optimized for phone numbers
BooleanField - checkbox
ChoiceField - drop-down select field
SectionBreakField - horizontal section break

function pre_save(&$config, &$errors)

This function will be called when configuration is submitted by user. Any server-side validation or additional business logic for configuration processing should go here. To fail the checks, simply set an error message into the error's array: $array['err'] = "Your message"; and return false from pre_save.

Part 1 Getting Started

Part 2 Configuration Page

Part 3 Plugin Class

Part 4 Staff Panel Links

Part 5 Signals

Part 6 Dispatcher and Routing