This is an old revision of the document!

Configuration

DokuWiki allows to write highly flexible plugins and templates by making them highly configurable.

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 options¹⁾.

$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²⁾:

$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
`'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. once set the password is not shown in the config manager anymore.
`'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
`'regex'`	regular expression string, normally without delimiters; as for string, in addition tested to see if will compile & 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 & 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

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).

¹⁾

templates are analogous lib/tpl/<template>/conf/default.php etc.

²⁾

For templates it's totally analogous: lib/tpl/<your template>/conf/default.php and lib/tpl/<your template>/conf/metadata.php.

Table of Contents