Если плагин требует настроек со стороны пользователя, то поля для ввода или выбора значений настроек необходимо перечислить в конфигурационном файле плагина lib/config/settings.php.
Набор полей настроек плагина формируется в виде ассоциативного массива со списком параметров, как показано ниже:
<?php
return [
'setting_key' => [
'title' => '',
'description' => '',
'value' => '',
'control_type' => '',
'options' => [
[
'value' => '',
'title' => '',
'description' => '',
],
...
],
'control_separator' => '<hr>',
],
...
];
Описание параметров
setting_key— произвольный уникальный текстовый идентификатор поля настроекtitle— наименование поля настроекdescription— описание поля настроек (отображается под полем)control_type— тип поля для отображения и редактирования значения настроекoptions— массив значений для множественных полей: RADIOGROUP, SELECT, GROUPBOX, CONTACTvalue— значение по умолчанию, которое должно отображаться в поле настроек, если пользовательское значение не задано; для поля типа GROUPBOX необходимо указать массив значенийcontrol_separator— необязательный HTML-код для визуального разделения элементов множественных полей: RADIOGROUP и GROUPBOX, например,<hr>
Типы полей настроек
Фреймворк предоставляет набор предопределенных типов полей, которые можно использовать на странице настроек плагина. Указывать их следует путем обращения к константам класса waHtmlControl:
waHtmlControl::INPUT — однострочное текстовое поле.
waHtmlControl::PASSWORD — однострочное поле для ввода пароля типа 'password'.
waHtmlControl::TEXTAREA — многострочное текстовое поле.
waHtmlControl::FILE — кнопка выбора файла.
waHtmlControl::HIDDEN — скрытое поле.
waHtmlControl::CHECKBOX — флажок.
waHtmlControl::GROUPBOX — группа флажков. При использовании этого типа в подмассиве 'options' необходимо указать следующие значения:
value — идентификатор значения, который можно использовать в PHP-коде в качестве ключа для доступа к элементу ассоциативного массива настроек
title — текстовый заголовок рядом с флажком
description — подсказка справа от заголовка (отображается серым цветом)
waHtmlControl::RADIOGROUP — группа радиокнопок. При использовании этого типа в подмассиве 'options' необходимо указать следующие значения:
value — идентификатор значения
title — текстовый заголовок рядом с радиокнопкой
description — подсказка справа от заголовка (отображается серым цветом)
waHtmlControl::SELECT — выпадающий список. При использовании этого типа в подмассиве 'options' необходимо указать следующие значения:
value — идентификатор значения
title — текстовое значение элемента выпадающего списка
description — значение атрибута title элемента выпадающего списка <option></option>
waHtmlControl::CONTACT — список полей редактирования свойств контакта. По умолчанию в этих полях отражаются свойства текущего пользователя. Изменение значений этих полей в настройках плагина не изменяет свойства текущего пользователя, а лишь сохраняет введенные данные в таблицу с настройками плагина. При использовании этого типа в подмассиве 'options' необходимо указать отдельные массивы для каждого отображаемого элемента свойств контакта с элементами 'value', содержащими идентификаторы этого свойства:
['value' => 'phone'], ['value' => 'email'],
waHtmlControl::CONTACTFIELD — выпадающий список для выбора одного из контактных полей. Для того чтобы показать выбранным в списке какое-то поле, в элементе 'value' данного поля настроек укажите id соответствующего контактного поля. Например, для того чтобы элемент, соответствующий полю с номером телефона (имеющего id='phone') был выбран в списке по умолчанию, в подмассиве 'options' укажите следующее:
'value' => 'phone',
waHtmlControl::CUSTOM — пользовательский элемент для ввода настроек, сформированный с использованием произвольного HTML-кода. PHP-логику формирования HTML-кода пользовательского элемента рекомендуется оформлять в виде публичного статического метода основного класса плагина и указывать имя этого метода в файле settings.php, как показано ниже:
'control_type' => waHtmlControl::CUSTOM.' '.'somePlugin::settingCustomControl'
В этом примере вместо somePlugin нужно указать имя класса плагина, в котором объявлен метод, указанный в этой строке (имя метода может быть произвольным).
Динамическое формирование списка значений
Набор значений для множественных типов полей (RADIOGROUP, SELECT, GROUPBOX) можно формировать автоматически вместо указания фиксированного набора элементов с помощью подмассива 'options'. Для автоматического формирования набора значений нужно добавить элемент 'options_callback' и в нем указать в виде простого массива имя класса плагина и его статический метод, который должен вернуть набор значений, например:
'options_callback' => ['somePlugin', 'settingSelectValues'],
В этом примере метод settingSelectValues() некоторого класса плагина somePlugin должен вернуть массив, имеющий ту же структуру, которая описана выше для элемента 'options' для данного типа поля (в данном случае waHtmlControl::SELECT), например:
public static function settingSelectValues()
{
...
$data = [
[
'value' => '',
'title' => '',
'description' => ''
],
[
'value' => '',
'title' => '',
'description' => ''
],
...
];
return $data;
}
В этом случае элемент 'options' для данного поля настроек указывать не нужно.
Пример файла настроек плагина
<?php
return [
'hint' => [
'description' => '<h3>'._wp('Specify values requested below for correct plugin operation.').'</h3>',
'control_type' => waHtmlControl::HIDDEN,
],
'login' => [
'title' => _wp('Login name'),
'description' => _wp('Enter your registered login name.'),
'control_type' => waHtmlControl::INPUT,
],
'password' => [
'title' => _wp('Password'),
'description' => _wp('Enter your personal password.'),
'control_type' => waHtmlControl::PASSWORD,
],
'comments' => [
'title' => _wp('Comments'),
'description' => _wp('Optional comments.'),
'control_type' => waHtmlControl::TEXTAREA,
],
'icon' => [
'title' => _wp('Icon'),
'description' => _wp('Upload a 16*16px large icon file.'),
'control_type' => waHtmlControl::FILE,
],
'test_mode' => [
'title' => _wp('Test mode'),
'description' => _wp('Disable when you want to go live.'),
'control_type' => waHtmlControl::CHECKBOX,
'value' => 1,
],
'statuses' => [
'title' => _wp('Order statuses'),
'description' => _wp('Select the statuses of orders which you want to be exported.'),
'control_type' => waHtmlControl::GROUPBOX,
'options_callback' => ['somePlugin', 'settingOrderStatuses'],
'value' => ['new', 'completed'],
],
'export_mode' => [
'title' => _wp('Export mode'),
'description' => _wp('Select the desired export mode.'),
'control_type' => waHtmlControl::RADIOGROUP,
'options' => [
[
'value' => 'default',
'title' => _wp('default'),
'description' => _wp('default data fields'),
],
[
'value' => 'advanced',
'title' => _wp('advanced'),
'description' => _wp('all data fields'),
],
],
'value' => 'default',
],
'protocol' => [
'title' => _wp('Data exchange protocol'),
'description' => _wp('Select the desired data exchange protocol.'),
'control_type' => waHtmlControl::SELECT,
'options' => [
[
'value' => 1,
'title' => '1.0',
],
[
'value' => 2,
'title' => '2.0',
],
],
'value' => 1,
],
'personal_data' => [
'control_type' => waHtmlControl::CONTACT,
'options' => [
['value' => 'email'],
['value' => 'phone'],
],
],
'customer_phone' => [
'title' => _wp('Customer phone number'),
'description' => _wp('Select the contact field corresponding to customer’s phone number.'),
'control_type' => waHtmlControl::CONTACTFIELD,
'value' => 'phone',
],
'tags' => [
'title' => _wp('Export tags'),
'description' => _wp('Add tags which you want to export.'),
'control_type' => waHtmlControl::CUSTOM.' '.'somePlugin::settingCustomControl',
],
];
Как считывать значения настроек
PHP
$setting_value = wa('app_id')->getPlugin('plugin_id')->getSettings('settings_field_id');
Smarty
{$setting_value = $wa->setting('settings_field_id', '', 'app_id.plugin_id')}
