Установка значений конфигурации и их использование

Configuration values in extention_name.setup.php

Cotonti позволяет плагинам устанавливать определенные параметры конфигурации для администратора. Эти параметры отображаются на панели администрирования в разделе Конфигурация. Это позволяет создавать гибкие плагины с настраиваемыми значениями вместо жестко запрограммированных значений.

1. Формат конфигурации

Параметры конфигурации вашего плагина загружаются из установочного файла плагина (extention_name.setup.php) при его установке через панель администрирования.

Для наглядности, лучше сразу открыть файл конфигурации модуля 'Pages'.

Важно!. При добавлении или изменении параметра конфигурации в установочном файле, каждый раз нужно вернуться в карточку данного расширения и его обновить нажатием кнопки или ссылки (смотря какой шаблон админки) "Обновить".

смотрите скрин

Если вы решите использовать значения конфигурации в своем плагине, вам нужно будет включить следующий блок кода в свой pluginname.setup.php файл под тегом [END_COT_EXT].

[BEGIN_COT_EXT_CONFIG]
... тут мои значения конфигурации ...
[END_COT_EXT_CONFIG]

Этот блок кода должен содержать список значений конфигурации в соответствии с определенным синтаксисом.
Каждый параметр конфигурации должен находиться в отдельной строке.

администратор сайта видит так

Синтаксис выглядит следующим образом:

[Variable]=[Order]:[Type]:[Values]:[Default]:[Description]

Переменная: Имя переменной, без $

Квадратные скобки указаны как знак того, что некоторые поля могут быть опущены при задании переменной. Знаки : и =обязательны.

Рассмотрим подробнее составляющие формата:

• Variable: Имя переменной для доступа из програмного кода, без знака $.
• Order: Порядковый номер. Служит для контроля порядка отображения (сортировки) полей ввода на странице Конфигурации.
• Type: Тип переменной конфигурации.
• Values: Допустимые значения. Для переменных типа select and radio задается список значений разделенных запятыми. Для типа range в этом поле задаются минимальное и максимальное значение для задания диапазона возможных вариантов выбора. Для типа callback или custom здесь указывается имя функции обработчика (см. описание в следующем разделе). В остальных случаях поле остается пустым.
• Default: Значение по умолчанию. Для типов select и radio в качестве значения по умолчанию может быть только одно из тех, что указано в поле Values. Для остальных указывается значение (строковое), которое будет использовано как начальное, или восстановлено при нажатии кнопки сброс в панели Конфигурации. Значение по умолчанию может быть не задано (пустым).
• Description: Описание. Текст который будет отображен в панели Конфигурации для описания назначения данной настройки. При использовании мультиязычных сайтов описания переменных могут быть локализованы (переведены) посредством языковых файлов.

2. Поддерживаемые типы

'string'

Тип переменной в поле «string» и его допустимые значения.

Строка, максимальная длина которой составляет 255 символов. Будет отображаться на панели конфигурации в виде одной строки ввода. Значения полей для этого типа игнорируются.

'select'

Тип переменной в поле «select» и его допустимые значения.

Поле выбора (selectbox), строки, введенные в поле значений, будут параметрами. В описании переменной типа select в поле Values в качестве элементов списка могут быть указаны только простые строки. Эти строки будут использованы и как значения и как описание элемента списка при формировании кода.

Т.е. строка описания

var=01:select:v1,v2,v3:v1:Description

будет преобразована примерно в следующий html-код для использования на странице Конфигурации расширения (модуля/плагина):

<select name="var">
<option value="v1" selected>v1</option>
<option value="v2">v2</option>
<option value="v3">v3</option>
</select>

В тех случаях, когда надо задать описания пунктов списка отличные от реальных значений (v1,v2,v3) можно воспользоваться типом callback (см. ниже) или механизмом локализации переменных (об этом подробнее смотри в статье «Локализация Расширений»).

'radio'

Тип переменной в поле «radio» и его допустимые значения.

Переключатель, аналогичный select. Примечание: до версии 0.9.19 любые определенные значения не использовались (и внутренне устанавливались на значение по умолчанию `0,1`). Только с версии 0.9.19 можно определять пользовательский список (как «Значения» ('Values')).

'text'

Тип переменной в поле «text» и его допустимые значения.

Строка без максимальной длины. Также служит общим значением, если вы введете что-либо еще, кроме "string", "select" или 'radio', по умолчанию будет установлено значение "text". Значения полей игнорируются для этого типа.

'callback'

Тип переменной в поле «callback» и его допустимые значения.

Поле выбора (selectbox) с параметрами, сгенерированными функцией обратного вызова в поле «Значения» ('Values'). Например, если значения содержат 'cot_get_parsers()', то список параметров генерируется этой функцией в виде массива.

myvar5=05:callback:cot_get_parsers(html):none:This is one of the available parsers

В тех случаях, когда надо задать описания пунктов списка отличные от реальных значений (v1,v2,v3) можно воспользоваться типом callback или механизмом локализации переменных.

Визуально переменная типа callback на странице настроек отображается аналогично типу select, как выпадающий список, но перечень пунктов этого списка задается не в описании переменной, а формируется из массива данных, возвращаемого указанной функцией. Имя такой функции задается в описании (см. выше «Формат задания переменных»). Функция должна возвращать массив.

Обратите внимание для версий 0.9.18 и ниже допустим только «простой» нумерованный формат массива:

array(
'value1',
'value2',
'value3',
);

значения массива (value1, value2, value3) будут использованы и как значения пунктов списка и как их названия (см. пример HTML кода выше в описании типа 'Select').

Начиная с версии 0.9.19 допустимо использовать ассоциативный массив ключи которого будут использованы как значения элементов списка, а строки массива, как описание (названия) элементов списка. Т.е. массив

array(
'key1' => 'title1',
'key2' => 'title2',
'key3' => 'title3',
);

будет преобразован в следующий список:

<option value="key1">title1</option>
<option value="key2">title2</option>
<option value="key3">title3</option>

Не зависимо от версии может быть использован механизм локализации переменных настройки (см. ссылку на статью выше). Локализованные описания элементов списка имеют приоритет над заданными массивом.

Тип callback может потребоваться в случаях, когда элементы списка зависят от дополнительных условий (например настроек другого Расширения). При описании переменной, функция может быть задана с параметрами. Эти параметры будут переданы ей при вызове.

'hidden'

Тип переменной в поле «hidden» и его допустимые значения.

То же, что и 'string', но такая опция не может быть отредактирована из панели администрирования и скорее управляется расширением напрямую.

'separator'

Тип переменной в поле «separator» и его допустимые значения.

На самом деле это не вариант, но он помещает разделитель в интерфейс администрирования в заданную позицию порядка (order).

'range'

Тип переменной в поле «range» и его допустимые значения.

Поле выбора с целочисленными параметрами в пределах заданного диапазона, границы диапазона (минимум и максимум). Поле «Значения» ('Values') представляет низкие и высокие значения диапазона, разделенные запятой. Создает меню выбора (в виде раскрывающегося списка) целых значений из диапазона заданного в настройках переменной.

myvar8=08:range:1,100:50:Выбор из 100 чисел/номеров

'custom'

Тип переменной в поле «custom» и его допустимые значения.

Он используется для расширения типов, определенных ядром. Пользовательский тип используется разработчиками для написания собственного обработчика для поля ввода, чтобы они могли определять:

фактический HTML-код поля (таким образом, представление представления);

способ обработки и фильтрации введенных данных.

Имя функции-обработчика задается (как в типе обратного вызова callback type) в поле «Значения» ('Values').

More info about using this type see in «Сustom type in config variables».

Пример кода конфигурации настроек модуля или плагина в котонти:

[BEGIN_COT_EXT_CONFIG]
myvar1=01:string::50:Это моя первая переменная
myvar2=02:select:1,2,3,4,5,6,7,8,9,10:7:Это моя вторая переменная
myvar3=03:radio::1:Это моя третья переменная
myvar4=04:text::Default text goes here your values:Это моя четвертая переменная
myvar5=05:callback:cot_get_parsers():none:Это один из доступных парсеров
myvar6=06:hidden::123foo:Эта опция недоступна для администраторов
myvar7=07:separator:::Separator is displayed here
myvar8=08:range:1,100:50:Выбор из 100 чисел/номеров
[END_COT_EXT_CONFIG]

Значения конфигурации вашего плагина будут сохранены в массиве $cfg и доступны следующим образом:

$cfg['plugin']['pluginname']['myvar1']
$cfg['plugin']['pluginname']['myvar2']
$cfg['plugin']['pluginname']['myvar3']
$cfg['plugin']['pluginname']['myvar4']

Вы могли бы, например, использовать его следующим образом:

while($i < $cfg['plugin']['pluginname']['myvar1'])
{
    ...
}

или реальный пример

$minimaxieditor = null;
if (Cot::$cfg['forums']['markup'] == 1) {
  $minimaxieditor = Cot::$cfg['forums']['minimaxieditor'];
}

3. Конфигурация структуры модулей и плагинов в котонти

Некоторые модули (например, 'page' и 'forums') имеют свои собственные деревья категорий.
 
По умолчанию каждая категория имеет несколько стандартных опций, но вы можете расширить их, используя конфигурацию структуры. Конфигурация структуры - это параметры конфигурации, которые можно задать для каждой категории в частности.
Он определяется в файле extention_name.setup.php настройки расширения так же, как и обычная конфигурация расширения, но с использованием блока COT_EXT_CONFIG_STRUCTURE.

Вот пример из модуля "page":

[BEGIN_COT_EXT_CONFIG_STRUCTURE]
order=01:callback:cot_page_config_order():title:
way=02:select:asc,desc:asc:
maxrowsperpage=03:string::30:
truncatetext=04:string::0:
allowemptytext=05:radio::0:
keywords=06:string:::
[END_COT_EXT_CONFIG_STRUCTURE]

Как вы видите, параметры в конфигурации структуры определены точно так же, как и в обычной конфигурации.    

Настройки структуры по умолчанию отображаются в разделе Администрирование => Расширения => (Имя расширения) => Конфигурация.
Они будут использоваться для всех категорий, для которых не установлены определенные параметры.

Конкретные параметры можно задать в разделе Администрирование => Расширения => (Имя расширения) => Структура => (Название категории) => Конфигурация (откройте структуру модуля и нажмите кнопку "Конфигурация" для выбранной категории).

4. Локализация расширений в котонти

Чтобы добавить описательный текст к значениям конфигурации, включите эти строки в свой plugins/lang/plugin.lang.XX.php файл:
 

$L['cfg_myvar1'] = "Моя переменная #1";
$L['cfg_myvar1_hint'] = "Введите здесь значение вашей переменной!";

Author: GHengeveld
translate:  Macik, webitproff