Skip to content

Latest commit

 

History

History
105 lines (82 loc) · 5.24 KB

extensions.cfg_param.en.md

File metadata and controls

105 lines (82 loc) · 5.24 KB

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.

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 which 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» respectively), 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.

Supported types

string

A string, max length 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 default 0,1 is set. Only Since 0.9.19 its able to define custom list (as «Values») and

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.

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']) { ... }

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 structure and click the "Config" button for a selected category).