DokuWiki

It's better when it's simple

User Tools

Site Tools


Sidebar

Translations of this page?:

Learn about DokuWiki

Advanced Use

Corporate Use

Our Community


Follow us on Facebook, Twitter and other social networks.

devel:configuration

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

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

1) templates are analogous lib/tpl/<template>/conf/default.php etc.
2) For templates it's totally analogous: lib/tpl/<your template>/conf/default.php and lib/tpl/<your template>/conf/metadata.php.
devel/configuration.txt · Last modified: 2013/08/03 23:46 by ChrisS