Difference between revisions of "PluginConfiguration"

Latest revision as of 14:49, 5 April 2011

Introduction

Traditionally, Geeklog and its plugins were configured through configuration files (config.php), which are PHP scripts that define a global array holding all the plugin configuration settings: $_CONF for Geeklog's core configuration, $_SP_CONF for the configuration of the Static Pages plugin, and so on.

While these files are easy to maintain and use for developers, they often caused issues for users, typically

• Parse and syntax errors due to typos and users being unfamiliar with PHP syntax
• Having to download, edit, and upload the config files to make changes

As of Geeklog 1.5.0, there is now a common Configuration Class that provides both a GUI (graphical front end) for easy access and a database schema to store configuration settings in the database.

As of Geeklog 1.8.0 the configuration class was updated with built in tab support while still being fully backwards compatible. Group rights were also extended to these tabs. The Geeklog Configuration checks to see if a group right exists for the tab and if so, then checks to see if the user has access to the tab. For plugin authors wishing to extend this functionality to their plugins all then need to do is add a Group right in the following format:

config.plugin_name.tab_name

Where the "plugin_name" is the name of the plugin and the "tab_name" is the name of the tab. The Geeklog core plugins have been updated with this feature so you can check them out for a complete example.

Usage in plugins

Plugins will still use their own global $_xx_CONF array to have configuration settings accessible at all times. However, that array is now initialized from the database and not by reading it from a config.php file any longer:

$my_config = config::get_instance();
    if ($my_config->group_exists('myplugin'))
        $_MY_CONF = $my_config->get_config('myplugin');

This will initialize a global array $_MY_CONF holding the configuration options for a plugin called 'myplugin'.

Backward compatibility

For a plugin that should also work on older Geeklog versions, you could check if the global variable $config exists and include a config.php file if it isn't set:

if (isset($config)) {
    $my_config = config::get_instance();
    if ($my_config->group_exists('myplugin'))
        $_MY_CONF = $my_config->get_config('myplugin');
} else {
    require_once $_CONF['path'] . 'plugins/myplugin/config.php';
}

Initialization

During installation/upgrade of a plugin, it will have to create a new group for its configuration and then add all of its config options:

$my_config = config::get_instance();
if ($my_config->group_exists('myplugin')) {
        DB_query ("DELETE FROM {$_TABLES['conf_values']} WHERE group_name = 'myplugin'");

$my_config->add('my_option1', 42, 'text', 0, 0, 0, 10, true, 'myplugin', 0);
...

See the description of the Configuration Class for details.

Tip: You will often need this initialization code in two places: In the installation script and when upgrading your (previously installed) plugin after the Geeklog version it's running on has been updated to 1.5.0 (or later). You may therefore want to put the code in a separate include file, e.g. install_defaults.php, as used by the plugins that are bundled with Geeklog.

Subgroups, Tabs and Fieldsets

As you've seen above, a plugin's configuration is called a "group" in the configuration table. The configuration options can be further sub-divided into Subgroups, Tabs and Fieldsets:

Subgroups

Every plugin will need to create at least one subgroup:

$my_config->('sg_main', NULL, 'subgroup', 0, 0, NULL, 0, true, 'myplugin', 0);

This creates a subgroup "sg_main". A subgroup is displayed in the second block on the Configuation admin panel, after you click on the plugin's entry in the first block. The display name that will show up in the second block is taken from the corresponding $LANG_configsubgroups['myplugin'] entry in the plugin's language file.

The convention is that name of subgroup entries starts with 'sg_'. The actual name is not important and is left for the plugin author to choose.

Tabs

A Tab is a group of options displayed once the user has selected a plugin and a subgroup in the Configuration admin panel. You can have more than one tab per subgroup:

$my_config->add('tab_main', NULL, 'tab', 0, 0, NULL, 0, true, 'myplugin', 0);
...
$my_config->add('tab_permissions', NULL, 'tab', 0, 0, NULL, 0, true, 'myplugin', 1);

The display name of a tab is taken from the corresponding entry in $LANG_tab['myplugin'] in the plugin's language file.

Again, there's a convention that entries for tab names should start with 'tab_' while the actual name is left to the plugin author. The tab name must be unique for the group (i.e. plugin) since the configuration security works off of the group and tab name.

Fieldsets

A fieldset is a group of options displayed once the user has selected a plugin, a subgroup and a tab in the Configuration admin panel. You can have 0, 1 or many fieldsets per tab. In the example below we will add 2 fieldsets to the permissions tab we just created:

$my_config->add('fs_perm_story', NULL, 'fieldset', 0, 0, NULL, 0, true, 'myplugin', 1);
...
$my_config->add('fs_perm_topic', NULL, 'fieldset', 0, 1, NULL, 0, true, 'myplugin', 1);

The display name of a fieldset is taken from the corresponding entry in $LANG_fs['myplugin'] in the plugin's language file.

Again, there's a convention that entries for fieldset names should start with 'fs_' while the actual name is left to the plugin author.

While you are not required to use fieldsets, they do group similar configuration items together and allow for easier readability. This is especially true if javascript is not enabled in the browser. When javascript is not enabled, all configuration items will be displayed in one long list. For this reason alone we suggest to have at least one fieldset per tab.

Tip: Refer to the code of the plugins bundled with Geeklog for implementation details.