Cotonti / Open Source PHP Content Management FrameworkContent Management Framework

Configuration values

Documentation / Extending Cotonti / Extensions / Configuration values

Setting config values and using them

Cotonti allows for plugins to set certain configuration options for the administrator. These options are displayed in the Administration Panel under Configuration. This enables you to create flexible plugins with customisable values instead of hard-coded values.

#1. Configuration format

The configuration options for your plugin are loaded from the plugin setup file (pluginname.setup.php) when it is installed through the Administration Panel. One consequence is that you will need to update the plugin when you add or change a configuration option in the setup file. If you decide to use configuration values in your plugin, you will have to include the following block of code in your pluginname.setup.php file, underneath the [END_COT_EXT] tag.

[BEGIN_COT_EXT_CONFIG]
...
[END_COT_EXT_CONFIG]

This code block should contain a list of configuration values, according to a specific syntax. Each configuration option should go on it’s own line. The syntax is like this:

 

[Variable]=[Order]:[Type]:[Values]:[Default]:[Description]
  • Variable: Name of the variable, without $
  • Order: The order in wich it will be displayed in the configuration panel.
  • Type: One of the several types listed below.
  • Values: For types 'select' and 'radio' (only since 0.9.19), the list of values, separated by commas. For 'callback' type it is the name of the function which generates an array of options. For 'range' type it is low and high values for the array to be generated. Otherwise empty.
  • Default: The default value. For ‘select’ it should be a value listed in the field 'Values', or empty. For ‘radio’: prior 0.9.19 it should be 0 or 1 (for «No» ans «Yes» respectivly), and for 0.9.19 and next it should be a value listed in the field 'Values'.
  • Description: Text to be displayed in the configuration panel.

#2. Supported types

string

A string, max lenght is 255 chars.
Will be displayed in the configuration panel as a single line of input.
The field Values is ignored for this type.

select

A selectbox, lines entered in the field Values will be the options.

radio

A radio box, similar to select. Note: prior to 0.9.19 any defined Values not used (and internaly set to default `0,1`). Only since 0.9.19 its able to define custom list (as «Values») .

text

String with no maximum length. Also serves as the catch-all value, if you put anything else than 'string', 'select' or 'radio', it will be defaulted to 'text'.
The field Values is ignored for this type.

callback

A selectbox with options generated by a callback function in the Values field. For example, if Values contains 'cot_get_parsers()' then the list of options is generated by that function as an array.

hidden

Same as string, but such an option cannot be edited from Administration panel and is rather managed by an extension directly.

separator

Isn't really an option, but it puts a separator in Administration interface at the given Order position.

range

A selectbox with integer options within a given range. The Values field represents low and high values of the range separated by comma.

custom

custom type is fully functional only since 0.9.19. It's used to extens core defined types. Type custom used by developers to write own handler for input field, so they can define:

  • actual HTML code of a field (so view representation);
  • the way it handle and filter inputed data.

Name of handler function is set (as in callback type) in Valuesfield. More info about using this type see in Подробнее об этом типе смотри в разделе «Сustom type in config variables».

 

Example:

[BEGIN_COT_EXT_CONFIG]
myvar1=01:string::50:This is my first variable
myvar2=02:select:1,2,3,4,5,6,7,8,9,10:7:This is my second variable
myvar3=03:radio::1:This is my third variable
myvar4=04:text::Default text goes here:This is my fourth variable
myvar5=05:callback:cot_get_parsers():none:This is one of the available parsers
myvar6=06:hidden::123foo:This option is not visible for admins
myvar7=07:separator:::Separator is displayed here
myvar8=08:range:1,100:50:A selection from 100 numbers
[END_COT_EXT_CONFIG]

Your plugin configuration values will be stored in the $cfg array and are accessible like this:

$cfg['plugin']['pluginname']['myvar1']
$cfg['plugin']['pluginname']['myvar2']
$cfg['plugin']['pluginname']['myvar3']
$cfg['plugin']['pluginname']['myvar4']

You could, for example, use it like this:

while($i < $cfg['plugin']['pluginname']['myvar1'])
{
	...
}

#3. Structure configuration

Some modules (e.g. 'page' and 'forums') have their own category trees. By default each category has several standard options, but you can extend them using structure configuration. Structure configuration is configuration options which can be set for each category in particular. It is defined in extension setup-file just like the normal extension configuration but using COT_EXT_CONFIG_STRUCTURE block. Here is an example 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 see, the options in structure configuration are defined exactly the same way as normal configuration.

Default structure settings are displayed in Administration => Extensions => (Extension name) => Configuration. They will be used for all categories which don't have particular options set for them. Particular options can be set in Administration => Extensions => (Extension name) => Structure => (Category name) => Configuration (open module strcture and click the "Config" button for a selected category).



1. Hodges  2014-01-26 12:39

Thanks: 0

Please update this page to include the following information:

To add descriptive text to the config values include these lines in your plugins/lang/plugin.lang.XX.php file:
$L['cfg_myvar1'] = "My Variable #1";

$L['cfg_myvar1_hint'] = "Input your variable value here!";

Total: 1, on page: 1

Only registered users can post new comments