Difference between revisions of "PluginConfiguration"

Revision as of 21:22, 14 February 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.

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.

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:

$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.

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