Переменные конфигурации расширений в Cotonti

Переменные конфигурации

Механизм Cotonti спроектирован таким образом, что позволяет при создании Расширения задать набор переменных, которые будут доступны для настройки через панель администрирования. Они отображаются на странице (Управление сайтом → расширения → 'имя расширения' → Конфигурация). Таким образом разработчик может создавать более гибкие расширения.

1. Формат задания переменных

Настройки переменных конфигурации загружаются из файла настроек Расширения (extension_name.setup.php) во время установки Расширения в панели администрирования.

Поэтому, если вы разрабатываете свое Расширение и изменили или добавили переменные в файл установки (setup файл), то вам необходимо произвести процедуру переустановки Расширения в Админ панели (Управление сайтом → Расширения → 'ваше расширение', кнопка Обновить).

Для описания переменных конфигурации в установочном файле Расширения (extension_name.setup.php) должен быть размещен текстовый блок, выделенный следующими маркерами:

[BEGIN_COT_EXT_CONFIG] 
... 
[END_COT_EXT_CONFIG]

Внутри этого блока должно находится описание переменных настройки. Описание каждой переменной находится на отдельной строке и задается отдельными «полями» в следующем формате:

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

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

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

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

2. Используемые типы переменных

2.1. string

Строка данных, максимальной длиной 255 символов. Отображается на странице настроек как обычное однострочное поле ввода. Значение поля Values для этого типа не используется.

2.2. select

Меню выбора. Отображается как стандартный раскрывающийся список. Элементы списка задаются в поле Values через запятую. Позволяет выбрать только один вариант из списка.

2.3. radio

Меню выбора в виде переключателя (или как их еще называют радио-кнопок). Используется для переменных, которые отображают параметр с несколькими возможными состояниями, выбрать из которых можно только один.

Обратите внимание! Для различных версий Siena, варианты задания и отображения опций несколько различаются:

• версии 0.9.18.1 и более ранних: поле Values не используется. Значение по умолчанию может быть только 1 или 0 (для состояний «включено|выключено»). Отображается на странице настроек всегда в виде пунктов «Да» / «Нет».
• для версий начиная с 0.9.19: поддерживается расширенный вариант использования, когда можно задать более двух пунктов с произвольными значениями. В этом случае в поле Values задаются значения списка (в точности аналогично типу Select).

2.4. text

Тип text используется для ввода текстовых данных без ограничения на длину строк (актуальный максимальный размер данных определяется настройками серверного ПО, например, смотри параметр post_max_size из php.ini файла). Значение поля Values для этого типа не используется. Надо также отметить, что тип text используется как тип по умолчанию в том случае, если актуальный тип не указан в описании переменной (или указан с ошибкой).

2.5. callback

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

2.6. hidden

Переменная аналогичная типу String, но скрытая от взгляда пользователя (не выводится на странице Конфигурации) и используемая программно из кода Расширения.

2.7. separator

Тип разделитель. По сути это не переменная, а описание визуального элемента в интерфейсе панели администрирования, который служит для отделения одной группы параметров от другой. Чтобы разделитель оказался в нужном месте списка настроек, ему, как и остальным переменным, надо правильно задать порядковый номер (в поле Order). Текст, указанный в поле Description, будет использован как заголовок при отображении разделителя.

2.8. range

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

2.9. custom

Тип custom добавлен в Cotonti в версии 0.9.18 (и дополнен в версии 0.9.19) для расширения ограниченного набора стандартных типов. Тип custom позволяет разработчику написать самостоятельный обработчик поля ввода данных, т.е. определить:

• как оно будет выглядеть;
• как будет обрабатывать введенные значения.

Имя функции обработчика, как и в случае с типом callback, задается в поле Values. Подробнее об этом типе смотри в разделе «Расширенные типы переменных».

Примеры использования:

[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::Текст по умолчанию:Это моя четвертая переменная
myvar5=05:callback:cot_get_parsers():none:Это один из доступных парсеров
myvar6=06:hidden::123foo:Этот параметр не виден для администраторов
myvar7=07:separator:::Разделитель отображается здесь
myvar8=08:range:1,100:50:Выбор из 100 чисел
myvar9=09:custom:custom_input_func(a,b,c):50:Пользовательская функция поля
[END_COT_EXT_CONFIG]

Теперь пользователь сможет изменять настройки вашего Расширения через панель администрирования. Доступ к указанным значениям в программном коде осуществляется через обращение к системному массиву $cfg. Для плагина значения переменных доступны таким образом:

$cfg['plugin']['имя_плагина']['myvar1'] 
$cfg['plugin']['имя_плагина']['myvar2'] 

где имя_плагина надо заменить на название вашего плагина. Для модулей доступ к переменным несколько отличается:

$cfg['имя_модуля']['myvar1']

где имя_модуля — это название модуля.

3. Подробнее о некоторых типах

3.1. Тип 'Select'

В описании переменной типа 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" (в случае выбора, если его не изменяет пользователь).

3.2. Тип 'Callback' и 'Custom'

В случае с типом callback вам нужно задать в поле Values имя функции, которая должна вернуть массив значений. Пример такого кода:

function get_parsers() { return array('Parser1', 'Parser2', 'Parser3'); } 

Эти значения будут использованы как возможные выборы в выпадающем списке для поля типа callback.

4. Локализация переменных конфигурации

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

Для локализации переменных конфигурации необходимо в описание каждой переменной добавить ключ, который будет ссылаться на соответствующий текст в языковом файле. Локализация осуществляется следующим образом:

• В поле Description для каждой переменной указывается специальный ключ.
• В языковом файле (например, lang/ru/config.php для русского языка) добавляется строка с переводом для этого ключа.

Пример:

Описание переменной в файле установки расширения (setup.php):

myvar1=01:string::50:{LNG_This_is_my_first_variable} 

Пример строки локализации в файле языка (lang/ru/config.php):

$LNG['This_is_my_first_variable'] = 'Это моя первая переменная'; 

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

5. Рабочие примеры переменных конфигурации

Для лучшего понимания процесса работы с переменными конфигурации приведены несколько примеров:

Пример 1: Переменная с типом select

[BEGIN_COT_EXT_CONFIG] 
site_color=01:select:blue,red,green:blue:Choose a color 
[END_COT_EXT_CONFIG] 

В этом примере переменная site_color имеет тип select, а возможные значения — blue, red, green. Значение по умолчанию — blue. Описание переменной будет переведено как "Choose a color" (можно локализовать на разные языки).

Пример 2: Переменная с типом radio

[BEGIN_COT_EXT_CONFIG] 
enable_feature=02:radio::1:Enable feature 
[END_COT_EXT_CONFIG] 

Здесь переменная enable_feature имеет тип radio. Это переключатель, где можно выбрать «включено» или «выключено» (1 и 0). Описание переменной — "Enable feature".

Пример 3: Переменная с типом callback

[BEGIN_COT_EXT_CONFIG] 
parser_type=03:callback:cot_get_parsers():html:Choose a parser 
[END_COT_EXT_CONFIG] 

В этом случае используется тип callback. Функция cot_get_parsers() вернет список доступных парсеров, и пользователь сможет выбрать один из них в выпадающем списке. Поле Values может содержать значение по умолчанию, например, html.

Пример 4: Переменная с типом custom

[BEGIN_COT_EXT_CONFIG] 
custom_field=04:custom:custom_input_function():some_default:Custom input field 
[END_COT_EXT_CONFIG] 

Переменная с типом custom позволяет использовать кастомную функцию для генерации поля ввода. Эта функция будет определена в коде расширения, а поле ввода будет выводиться в зависимости от возвращаемого значения функции. В данном случае значением по умолчанию будет some_default.

6. Доступ к значениям переменных

После того как переменные настроены, доступ к их значениям осуществляется через глобальный массив конфигурации $cfg. Для плагинов доступ будет таким:

$cfg['plugin']['myplugin']['site_color'] 
$cfg['plugin']['myplugin']['enable_feature'] 

Для модулей доступ будет следующим образом:

$cfg['module']['mymodule']['site_color'] 
$cfg['module']['mymodule']['enable_feature'] 

В этих примерах вы обращаетесь к значениям переменных с помощью соответствующих ключей, которые вы задаете в описании переменных (например, site_color, enable_feature).

7. Обновление переменных конфигурации

Если в процессе разработки или модификации расширения вам нужно изменить переменные конфигурации, это можно сделать следующим образом:

1. Измените описание переменной в файле установки (setup.php).
2. Обновите расширение через панель администрирования (Управление сайтом → Расширения → 'ваше расширение' → Обновить).

После этого система автоматически применит изменения в настройках переменных.

8. Заключение

Переменные конфигурации в Cotonti — это мощный инструмент для создания гибких и настраиваемых расширений. Правильное использование типов переменных, локализация, а также возможность задания кастомных функций для полей ввода делают этот механизм чрезвычайно полезным для разработчиков.

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