Это старая версия документа!
Содержание
Конфигурация
Default Settings
Чтобы сделать плагин или шаблон настраиваемым, необходимо предоставить lib/plugins/<plugin>/conf/default.php который будет содержать настройки по умолчанию, и lib/plugins/<plugin>/conf/metadata.php который содержит описывающие метаданные конфигурации используемые диспетчером конфигурации для обработки/отображения параметров 1).
$conf[<setting>] = <value>;
Конфигурационные метаданные
Для каждого параметра lib/plugins/<your plugin>/conf/default.php должно быть $meta[<setting>] значение, определенное в lib/plugins/<your plugin>/conf/metadata.php2):
$meta[<setting>] = array(<setting class>, <param name> => <param value>);
Если для класса настроек не требуется никаких параметров (см. ниже), то это просто:
$meta[<setting>] = array(<setting class>);
Примеры:
$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'));
Классы
'' | DКласс по умолчанию («настройка»), текстовая область, минимальная проверка входных данных, вывод настроек в кавычках. |
|---|---|
'string' | Ввод текста в одну строку, минимальная проверка ввода, вывод в кавычках. |
'numeric' | Ввод текста, принимает числа и арифметические операторы, установка вывода без кавычек. Если заданы параметры _min и _max используются для проверки. |
'numericopt' | То же, что и выше, но принимает пустые значения. |
'onoff' | Входные данные флажка, выходные данные настройки 0 или 1 (обратите внимание, что значения по умолчанию должны быть одним из этих целых чисел, а не логическим значением).. |
'multichoice' | Выберите входные данные (единственный выбор), установите выходные данные в кавычках, обязательный _choices параметр. |
'email' | Ввод текста, ввод должен соответствовать формату адреса электронной почты, вывод должен быть заключен в кавычки. |
'password' | Ввод пароля, минимальная проверка ввода, настройка вывода обычного текста в кавычках. После установки пароль больше не отображается в менеджере конфигурации. Может быть запутан в конфигурации через _code параметр. |
'dirchoice' | Как multichoice, варианты выбора основаны на папках, найденных в месте, указанном в _dir параметре (обязательно). |
'multicheckbox' | Флажок для каждого варианта плюс строковый ввод «другое», настройка файла конфигурации представляет собой список отмеченных вариантов, разделенных запятыми. |
'fieldset' | Используется для группировки настроек конфигурации, но сам по себе не является настройкой. Чтобы это было понятно в языковых файлах, ключи для этого типа должны начинаться с _. |
'authtype' | Создает выборку доступных методов аутентификации на основе имен классов, inc/auth соответствующих шаблону authtype.class.php. |
'array' | простой (одномерный) массив строковых значений, отображаемый в виде списка, разделенного запятыми, в диспетчере конфигурации, но сохраняемый как PHP array(). Значения не могут содержать запятые. _patter nподдерживается сопоставление значений массива. |
'regex' | Строка регулярного выражения, обычно без разделителей; как и для string, дополнительно протестировано, чтобы увидеть, будет ли компилироваться и запускаться как регулярное выражение. В дополнение к _pattern, также принимает _delimiter (default /) и _pregflags (default ui). |
Параметры
'_pattern' | Строка, регулярное выражение. Ввод проверяется на соответствие этому шаблону перед принятием. Необязательно для всех классов, кроме onoff, multichoice и dirchoice которые его игнорируют. |
|---|---|
'_choices' | Массив вариантов выбора. Используется для заполнения поля выбора. Выбор будет заменен локализованной языковой строкой, индексированной по <setting name>_o_<choice>, если она существует.Требуется для multichoice & multicheckbox классов, игнорируется другими. |
'_dir' | Расположение каталога, который будет использоваться для заполнения списка выбора. Требуется dirchoice классом, игнорируется другими классами. |
'_code' | Устанавливает опцию запутывания для полей пароля. Может быть plain, base64 или uuencode. При использовании последних двух вам необходимо использовать conf_decodeString() для доступа к простому значению.. |
'_combine' | Дополнительные выходные значения настроек, которые можно объединить в один дисплей checkbox.Необязательно для multicheckbox, игнорируется другими классами. |
'_code' | Метод кодирования, допустимые значения: base64, uuencode, plain. По умолчанию — обычный. |
'_min' | Минимальное числовое значение. Необязательно для numeric и numericopt, игнорируется другими. |
'_max' | Максимальное числовое значение. Необязательно для numeric и numericopt, игнорируется другими. |
'_delimiter' | Строка, по умолчанию / — один символ, используемый в качестве разделителя для проверки входных значений регулярного выражения. |
'_pregflags' | Строка, по умолчанию ui, допустимые модификаторы шаблона preg, используемые при тестировании входных значений регулярных выражений, для получения дополнительной информации см. http://uk1.php.net/manual/en/reference.pcre.pattern.modifiers.php. |
'_multiple' | Bool, разрешить несколько значений email, разделенных запятыми. Необязательно для email, игнорируется другими. |
'_other' | Как обрабатывать другие значения (не перечисленные в _choices). Принятые значения: always, exists, never. Значение по умолчанию always.exists показывает поле ввода «другое», только если настройка содержит значение(я), не перечисленное в вариантах (например, из-за ручного редактирования или обновления, изменяющегоg _choices). Это безопаснее, чем never так как не отбрасывает неизвестные/другие значения.Необязательно для multicheckbox, игнорируется другими. |
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).