lib/tpl/<template>/conf/default.php
etc.Table of Contents
Configuration
Default Settings
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>;
Configuration Metadata
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.php
2):
$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'));
Classes
'' | 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. If given the _min and _max parameters are used for validation. |
'numericopt' | Like above, but accepts empty values. |
'onoff' | Checkbox input, setting output 0 or 1 (note that default values should be one of these integers, and not boolean). |
'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. |
'password' | Password input, minimal input validation, setting output plain text in quotes. Once set the password is not shown in the config manager any more. Can be obfuscated in config through the _code parameter. |
'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. |
'array' | a simple (one dimensional) array of string values, shown as comma separated list in the config manager but saved as PHP array(). Values may not contain commas themselves. _pattern matching on the array values supported. |
'regex' | Regular expression string, normally without delimiters; as for string , in addition tested to see if will compile and run as a regex. In addition to _pattern , also accepts _delimiter (default / ) and _pregflags (default ui ). |
Parameters
'_pattern' | String, a regular expression. Input is tested against this pattern before being accepted. Optional all classes, except onoff , multichoice and 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. |
'_code' | Sets the obfuscation option for password fields. May be plain , base64 or uuencode . When using the latter two, you need to use conf_decodeString() to access the plain value. |
'_combine' | Complimentary output setting values which can be combined into a single display checkbox .Optional for multicheckbox , ignored by other classes. |
'_code' | Encoding method to use, accepted values: base64 , uuencode , plain . Defaults to plain. |
'_min' | Minimum numeric value. Optional for numeric and numericopt , ignored by others. |
'_max' | Maximum numeric value. Optional for numeric and numericopt , ignored by others. |
'_delimiter' | String, default / , a single character used as a delimiter for testing regex input values. |
'_pregflags' | String, default ui , valid preg pattern modifiers used when testing regex input values, for more information see http://uk1.php.net/manual/en/reference.pcre.pattern.modifiers.php. |
'_multiple' | Bool, allow multiple comma separated email values. Optional for email , ignored by others. |
'_other' | How to handle other values (not listed in _choices ). Accepted values: always , exists , never . Default value always .exists only shows 'other' input field when the setting contains value(s) not listed in choices (e.g. due to manual editing or update changing _choices ). This is safer than never as it will not discard unknown/other values.Optional for multicheckbox , ignored by others. |
Examples
''multicheckbox'' with ''_other''
Let's say initially a plugin uses the syntax:
$meta['multi'] = array('multicheckbox', '_choices' => array('a','b','c','d'));
this means the multicheckbox will show four choices plus a string input.
Let's suppose also that the user inserts one or more extra values not in _choices
.
In the next release of the plugin the author's plugin decides to use the multicheckbox without the extra string, but, in order to be backwardly compatible, adopts:
$meta['multi'] = array('multicheckbox', '_other' => 'exists', '_choices' => array('a','b','c','d'));
which means:
- if the user has inserted comma separated values, they will be printed in the extra string;
- otherwise the extra string won't show.
Note also that if the user inserts comma separated values which already exist (or some of them) in _choices
but:
- they are already ticked, then the extra string will be removed and nothing else;
- they are not already ticked, then the extra string will be removed and the relative value will be ticked.
Accessing Settings
Core Settings
Inside inc/init.php the configurations settings are read into a global array $conf[]
. When no settings were set, these are read from the default settings file.
You can access the core settings anywhere by using the $conf[]
array.
$startpage = $conf['start'];
Plugin settings
You can access settings in plugins by using the $this->getConf('<setting>')
method.
In your plugin class you use:
$keyvalue = $this->getConf('key');
Template settings
In templates you can use tpl_getConf('<setting>')
.
$nicetoknow = tpl_getConf('special');
Labels in Configuration Manager
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).