Latest revision as of 20:35, 11 August 2011

Guide to Adding 'Core' Configuration Items

Geeklog's move from a static configuration array to a database-based, web-managed configuration system using the Configuration Class in Geeklog 1.7.x has made adding new configuration parameters more complex. This guide includes step-by-step instructions for adding new configuration subgroups, tabs, fieldsets, and configuration parameters. Configuration groups are ignored, as for configuration parameters for Geeklog should always be in the 'Core' group. Other documentation exists about adding configuration items for plugins.

This article will often refer to collective sort of organizing types, which includes groups, subgroups, tabs, and fieldsets, as grouping types.

Adding subgroups, tabs, and fieldsets

Creating new subgroups, tabs, and fieldsets

There are two locations where new grouping types (and configuration parameters as well, but more on them later) must be added. The first is public_html/admin/install/config-install.php, used by new Geeklog installs to add a complete set of configuration parameters to the Geeklog database. The second is public_html/admin/install/lib-upgrade.php, where the Geeklog upgrade script goes to upgrade the database when a new Geeklog version is installed.

In both locations and for all these grouping types, the add method of the configuration class is used to add new grouping types. Below are some examples of adding these different grouping types:

• subgroup: $c->add('sg_site', NULL, 'subgroup', 0, 0, NULL, 0, TRUE, 'Core', 0);
• tab: $c->add('tab_site', NULL, 'tab', 0, 0, NULL, 0, TRUE, 'Core', 0);
• fieldset: $c->add('fs_site', NULL, 'fieldset', 0, 0, NULL, 0, TRUE, 'Core', 0);

There is complete documentation for the add method. The following parameters are particularly important for the grouping types:

• First Parameter: The internal name (i.e. not the display name).
• Third Parameter: The type. For grouping types, these are 'subgroup', 'tab', and 'fieldset'.
• Fourth Parameter: The subgroup number. This is a unique internal number to reference the subgroup. The fieldset and tab types use this to indicate which subgroup they belong under.
• Fifth Parameter: The fieldset number. This is the unique internal number to reference the fieldset. Subgroups do not use this number and use 0 by convention. Tabs do not use this number and use the number of the first fieldset they contain by convention.
• Tenth Parameter: The tab number. This is the unique internal number to reference the tab. Subgroups do not use this number and use 0 by convention. Fieldsets use this to indicate which tab they belong under.

In lib-upgrade.php, the code for the addition of the variables should be placed in the switch statement case for the previous version (e.g. if adding config value to 1.8.1, add the methods to the case statement for 1.8.0). Also in lib-upgrade.php, you will need to initialize the config class before you can execute the add methods above. This is easily done by using the following code:

global $_CONF;
require_once $_CONF['path_system'] . 'classes/config.class.php';
$c = config::get_instance();

Display text for subgroups, tabs, and fieldsets

Once the new grouping type(s) are added, the language file (by editing language/english.php must be updated. Each grouping type has its own language associative array in this file. In these arrays, the key is the grouping types' name (such as 'sg_site' used above) and the value is the plain text display ('Site', for the same case).

• subgroup: $LANG_configsubgroups['Core']
• tab: $LANG_tab['Core']
• fieldset: $LANG_fs['Core']

Adding configuration parameters

Creating new parameters

Like the grouping types, configuration parameters use the add method of the configuration class to add new parameters. These add methods are placed in both public_html/admin/install/config-install.php to be used in new installs and public_html/admin/install/lib-upgrade.php to be used in upgrades. Here is an example of adding a new configuration variable:

• $c->add('site_url', '', 'text', 0, 0, NULL, 20, TRUE, 'Core', 0);

The configuration class supports three basic types of configuration parameters, these are:

• text: Manual text box entry.
• select: HTML Select box (i.e. choice dropdown).
• hidden: Undisplayed config parameters.

The configuration class also allows the use of arrays by prepending the base type above with one of the following characters:

• @: array, the administrator cannot add keys
• *: array, the administrator can add named keys
•  %: array, the administrator can add numbered keys

The configuration class supports multidimensional arrays by prepending additional array symbols. For instance, @@example represents a two dimensional array.

Default/initial values are defined in the second parameter to the add method. These can be of any type (including arrays) and get serialized by Geeklog for storage in the database.

Value validation

Entered values for parameters are validated by a rules that are defined on a per-parameter basis. This rules are established in the $_CONF_VALIDATE array defined in public_html/admin/configuration_validation.php. Each parameter (for the 'Core' group) is a key in the $_CONF_VALIDATE['Core'] array. For instance, to add a validation function function to the 'site_url' parameter, the following entry is needed:

• $_CONF_VALIDATE['Core']['site_url'] = array('rule' => 'url');

Every parameter should have an entry in this array. The 'rule' key is interpreted as follows:

1. If a custom_validation_<rule> function exists, use that (e.g. "theme" -> custom_validation_theme() from public_html/admin/configuration.php).
2. If a method from the validator class with the same name as the rule exists, use that (e.g. "stringOrEmpty" -> stringOrEmpty() from system/classes/validator.class.php). Currently the validator class supports the following rules: notEmpty, alphaNumeric, between, blank, comparison (isgreater, isless, greaterorequal, lessorequal, equalto, notequal), custom (regex), date, time, boolean, decimal, email, equalTo, extension, ip, minlength, maxlength, multiple, numeric, phone, range, string, stringOrEmpty, url, and inList.
3. Otherwise assume the "rule" is a regexp

Parameter documentation

To reference additional information about variables from the congiruation web page, new parameters should be placed in public_html/docs/english/config.html (including their internal name, type, and description) with an anchor tag with the name 'desc_<parameter name>'.

Display text for parameters and selects

Finally, display text for each parameter name should be placed in the language/english.php file in the $LANG_confignames['Core'] associative array with the key being the internal name and the value the display text. Also, parameters with the 'select' type, need to update the $LANG_configselects['Core'] array. 'Select' types can use an existing numbered reference to an associative array of select values, or else create a new one. A new select needs a unique number index in $LANG_configselects['Core'] with an associative array of containing the displayed text as keys and the select values as values in the array.

Summary

While these instructions can seem intimidating, by using other parameters and grouping types as reference adding to Geeklog's configuration is manageable. While the complexity of adding configuration has increased for developers, it is a necessary sacrifice for granting both a easy to manage web frontend and providing validation protection to entered configuration values.