To make a plugin or template configurable you have to provide a lib/plugins/<plugin>/conf/default.php which will hold the default settings and a lib/plugins/<plugin>/conf/metadata.php which holds the describing Configuration Metadata which is used by the Configuration Manager to handle/display the options1).
$conf[<setting>] = <value>;
For every setting in lib/plugins/<your plugin>/conf/default.php there should be a $meta[<setting>] value defined in lib/plugins/<your plugin>/conf/metadata.php2):
$meta[<setting>] = array(<setting class>, <param name> => <param value>);
If no parameter is required for a setting class (see below), it's simply:
$meta[<setting>] = array(<setting class>);
Examples:
$meta['_basic'] = array('fieldset'); $meta['title'] = array('string'); $meta['lang'] = array('dirchoice','_dir' => DOKU_INC.'inc/lang/'); $meta['dmode'] = array('numeric','_pattern' => '/0[0-7]{3,4}/'); // only accept octal representation $meta['allowdebug'] = array('onoff'); $meta['passcrypt'] = array('multichoice','_choices' => array('smd5','md5','sha1','ssha','crypt','mysql','my411'));
'' | default class ('setting'), textarea, minimal input validation, setting output in quotes |
|---|---|
'string' | single line text input, minimal input validation, setting output in quotes |
'numeric' | text input, accepts numbers and arithmetic operators, setting output without quotes |
'onoff' | checkbox input, setting output 0 or 1 |
'multichoice' | select input (single choice), setting output with quotes, required _choices parameter |
'email' | text input, input must conform to email address format, setting output in quotes |
'richemail' | text input, input must conform to email address header format, may include a text part and replacement patterns, setting output in quotes |
'password' | password input, minimal input validation, setting output plain text in quotes |
'dirchoice' | as multichoice, selection choices based on folders found at location specified in _dir parameter (required) |
'multicheckbox' | a checkbox for each choice plus an “other” string input, config file setting is a comma separated list of checked choices |
'fieldset' | used to group configuration settings, but is not itself a setting. To make this clear in the language files the keys for this type should start with '_' |
'authtype' | creates a selection of available authentication methods, based on the class names in inc/auth that match the authtype.class.php pattern |
'_pattern' | string, a regular expression. input is tested against this pattern before being accepted optional all classes, except onoff, multichoice & dirchoice which ignore it |
|---|---|
'_choices' | array of choices. used to populate a selection box. choice will be replaced by a localised language string, indexed by <setting name>_o_<choice>, if one exists required by 'multichoice' & 'multicheckbox' classes, ignored by others |
'_dir' | location of directory to be used to populate choice list required by 'dirchoice' class, ignored by other classes |
'_combine' | complimentary output setting values which can be combined into a single display checkbox optional for 'multicheckbox', ignored by other classes |
You can access the in plugins by using the $this->getConf('<setting>') method. In templates you can use $tpl_getConf('<setting>').
For every setting in lib/plugins/<your plugin>/conf/default.php there can be a $lang[<setting>] value defined in lib/plugins/<your plugin>/lang/en/settings.php. This value will be displayed as the label of the setting in the configuration manager. If the label file is left out or doesn't contain a value for the setting, the configuration manager will display ”plugin <plugin name> <setting>” as the label instead. You can also create a settings.php file for other languages. Again, this also applies to templates (see localization for further details).
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 3.0 Unported