Configuration Variables Setup

The Cotonti mechanism is designed in such a way that when creating an Extension, it allows you to define a set of variables that will be available for configuration through the administration panel. They are displayed on the page (Site Management → Extensions → 'extension name' → Configuration). This way, the developer can create more flexible extensions.

Format for Defining Variables

Configuration variable settings are loaded from the Extension's setup file (extension_name.setup.php) during the installation of the Extension in the administration panel.

Therefore, if you are developing your own Extension and have changed or added variables in the setup file, you need to perform the reinstallation procedure for the Extension in the Admin panel (Site Management → Extensions → 'your extension', the Update button).

To describe configuration variables in the Extension's setup file (extension_name.setup.php), a text block must be placed, delimited by the following markers:

[BEGIN_COT_EXT_CONFIG]
...
[END_COT_EXT_CONFIG]

Inside this block, the descriptions of the configuration variables should be placed. The description of each variable is on a separate line and is defined by individual “fields” in the following format:

Variable=[Order]:[Type]:[Values]:[Default]:[Description]

Square brackets indicate that some fields can be omitted when defining a variable. The : and = signs are mandatory.

Let's look at the components of the format in more detail:

• Variable: The name of the variable for programmatic access, without the $ sign.
• Order: Sequence number. Used to control the display order (sorting) of input fields on the Configuration page.
• Type: Configuration variable type. See the next section “Used Variable Types” for details.
• Values: Allowed values. For select and radio types, a comma-separated list of values is specified. For the range type, this field specifies the minimum and maximum values for the range. For callback or custom types, the name of the handler function is specified here (see description in the next section). In other cases, the field is left empty.
• Default: Default value. For select and radio types, the default can only be one of the values listed in the Values field. For others, a string value is specified that will be used as the initial value or restored when clicking the reset button in the Configuration panel. The default value can be omitted (left empty).
• Description: Description. The text that will be displayed in the Configuration panel to explain the purpose of this setting. [When using multilingual sites, variable descriptions can be localized (translated) using language files. See the article “Extension Localization” for details.]

Used Variable Types

string

A data string with a maximum length of 255 characters. Displayed on the settings page as a regular single-line input field. The Values field is not used for this type.

select

Dropdown menu. Displayed as a standard drop-down list. List items are specified in the Values field separated by commas. Allows selecting only one option from the list.

radio

Selection menu in the form of radio buttons. Used for variables representing a parameter with several possible states, only one of which can be selected.

Note! For different Siena versions, the way options are defined and displayed differs slightly:

• versions Siena 0.9.18.1 and earlier: the Values field is not used. The default value can only be 1 or 0 (for “enabled/disabled” states). Always displayed as “Yes” / “No” options.
• starting from Siena 0.9.19: an extended version is supported, allowing more than two options with arbitrary values. In this case, the list values are specified in the Values field (exactly like the select type).

text

The text type is used for entering text data without string length restrictions (the actual maximum size is determined by server settings, e.g., the post_max_size parameter in the php.ini file). The Values field is not used for this type. Also note that text is used as the default type if the actual type is not specified in the variable description (or is specified incorrectly).

callback

The callback type is displayed similarly to select, with the only difference being that the list of items is not hard-coded in the description but generated by the specified function. The name of this function is specified in the Values field. For example, if the Values field contains cot_get_parsers(), the array returned by this function will be used to build the list. See the section “Advanced Variable Types” for more details.

hidden

A variable similar to the string type, but hidden from the user (not displayed on the Configuration page) and used programmatically from the Extension code.

separator

Separator type. Essentially not a variable, but a description of a visual element in the administration panel interface used to separate one group of parameters from another. Like other variables, it must have the correct order number (in the Order field) to appear in the right place. The text in the Description field will be used as the separator title.

range

Creates a dropdown menu of integer values from the range specified in the variable settings. The range boundaries (minimum and maximum) are specified in the Values field separated by a comma.

custom

The custom type was added in Cotonti 0.9.18 (and enhanced in 0.9.19) to extend the limited set of standard types. It allows the developer to write their own input field handler, i.e., to define:

• how it will look;
• how it will process entered values.

The handler function name, like with the callback type, is specified in the Values field. See the section “Advanced Variable Types” for details.

Usage examples:

[BEGIN_COT_EXT_CONFIG]
myvar1=01:string::50:Thisismyfirstvariable
myvar2=02:select:1,2,3,4,5,6,7,8,9,10:7:Thisismysecondvariable
myvar3=03:radio::1:Thisismythirdvariable
myvar4=04:text::Defaulttextgoeshere:Thisismyfourthvariable
myvar5=05:callback:cot_get_parsers():none:Thisisoneoftheavailableparsers
myvar6=06:hidden::123foo:Thisoptionis not visibleforadmins
myvar7=07:separator:::Separatorisdisplayedhere
myvar8=08:range:1,100:50:Aselectionfrom100numbers
myvar9=09:custom:custom_input_func(a,b,c):50:Customfunctionfield
[END_COT_EXT_CONFIG]

Now the user can change your Extension settings through the administration panel. Access to these values in the code is done via the system array $cfg. For plugins, variable values are accessed like this:

$cfg['plugin']['plugin_name']['myvar1']
$cfg['plugin']['plugin_name']['myvar2']
...

where plugin_name should be replaced with your plugin’s name. For modules, access is slightly different:

$cfg['module_name']['myvar1']

where module_name is the module name.

More About Some Types

Type 'select'

In the description of a select-type variable, only simple strings can be specified as list items in the Values field. These strings will be used both as values and as labels for the list items. For example, the description var=01:select:v1,v2,v3:v1:Description will be converted to approximately the following HTML:

<select name="var">
 <option value="v1" selected>v1</option>
 <option value="v2">v2</option>
 <option value="v3">v3</option>
</select>

When you need different labels from the actual values (v1, v2, v3), you can use the callback type (see below) or the variable localization mechanism (see the article Extension Localization for details).

Type 'callback'

Visually, a callback-type variable is displayed like select — as a dropdown list, but the list items are not defined in the description; instead, they are generated from the array returned by the specified function. The function name is specified in the description (see “Format for Defining Variables” above). The function must return an array.

Note: For Siena 0.9.18 and earlier, only a simple indexed array is allowed:

array(
 'value1',
 'value2',
 'value3',
);

The array values (value1, value2, value3) will be used both as option values and as their labels (see the HTML example above in the 'select' type description).

Starting from Siena 0.9.19, associative arrays are supported where keys are used as values and array values as labels:

array(
 'key1' => 'title1',
 'key2' => 'title2',
 'key3' => 'title3',
);

This will be converted to:

<option value="key1">title1</option>
 <option value="key2">title2</option>
 <option value="key3">title3</option>

Regardless of version, the variable localization mechanism can be used (see link above). Localized labels have priority over those provided by the array.

The callback type may be needed when list items depend on additional conditions (e.g., settings of another Extension). The function can be specified with parameters — they will be passed when called.

myvar5=05:callback:cot_get_parsers(html):none:Thisisoneoftheavailableparsers

Type 'custom'

The custom type is designed to overcome the limitation of the standard types by allowing the developer to write their own processing code and control both the field's appearance and filtering of user-entered data. This almost unlimitedly extends the developer's ability to interact with the user via the administration panel.

The mechanism of this type is described in detail in a separate article with practical examples (“Type 'custom' in configuration variables”).

Note! This type only works in Cotonti starting from version Siena 0.9.19. Keep this in mind if you are developing for older versions.

Variable Localization

The process of localizing configuration variables is described in detail on the Extension Localization page. Here we only note that variable descriptions and values displayed in lists can be translated into the required languages and displayed depending on the selected site language.

Configuration Variables for Category Trees

Some Extensions, specifically Modules, can use the built-in Cotonti mechanism called “category tree structure”. For example, the 'page' and 'forums' modules have categories for pages and forum sections. By default, each created category has a predefined set of parameters (title, description, etc.). However, this set can be programmatically extended by adding extra configuration variables, similar to how we do it for Extension settings. The descriptions of these variables must be placed in the module's setup file (module_name.setup.php) inside a special block COT_EXT_CONFIG_STRUCTURE.

Here is an example of such a block from the 'page' module:

[BEGIN_COT_EXT_CONFIG_STRUCTURE]
order=01:callback:cot_page_config_order():title:
way=02:select:asc,desc:asc:
maxrowsperpage=03:string::30:
truncatetext=04:string::0:
allowemptytext=05:radio::0:
keywords=06:string:::
[END_COT_EXT_CONFIG_STRUCTURE]

As you can see, the variable description format is exactly the same as for Extensions.

Default settings for newly created categories can be changed on the module's general configuration page:

Site Management → Extensions → Module Name → Configuration

Individual category settings can be configured as follows:

Site Management → Extensions → Module Name → Structure button

then click the Config button next to the desired category.

based on materials from public source