Настройки плагина

Содержание...

Если плагин требует настроек со стороны пользователя, то поля для ввода или выбора значений настроек необходимо перечислить в конфигурационном файле плагина lib/config/settings.php.

Набор полей настроек плагина формируется в виде ассоциативного массива со списком параметров, как показано ниже:

<?php

return array(
    'setting_key' => array(
        'title'        => '',
        'description'  => '',
        'value'        => '',
        'control_type' => '',
        'options'      => array(
            array (
                'value'       => '',
                'title'       => '',
                'description' => '',
            ),
            ...
        ),
        'control_separator' => '<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', содержащими идентификаторы этого свойства:

array('value' => 'phone'),
array('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' => array('somePlugin', 'settingSelectValues'),

В этом примере метод settingSelectValues() некоторого класса плагина somePlugin должен вернуть массив, имеющий ту же структуру, которая описана выше для элемента 'options' для данного типа поля (в данном случае waHtmlControl::SELECT), например:

public static function  settingSelectValues()
{
    ...
    $data = array(
        array(
            'value' => '',
            'title' => '',
            'description' => ''
        ),
        array(
            'value' => '',
            'title' => '',
            'description' => ''
        ),
        ...
    );
    return $data;
}

В этом случае элемент 'options' для данного поля настроек указывать не нужно.

Пример файла настроек плагина

<?php

return array(
    'hint' => array(
        'description' => '<h3>'._wp('Specify values requested below for correct plugin operation.').'</h3>',
        'control_type' => waHtmlControl::HIDDEN,
    ),
    'login' => array(
        'title' => _wp('Login name'),
        'description' => _wp('Enter your registered login name.'),
        'control_type' => waHtmlControl::INPUT,
    ),
    'password' => array(
        'title' => _wp('Password'),
        'description' => _wp('Enter your personal password.'),
        'control_type' => waHtmlControl::PASSWORD,
    ),
    'comments' => array(
        'title' => _wp('Comments'),
        'description' => _wp('Optional comments.'),
        'control_type' => waHtmlControl::TEXTAREA,
    ),
    'icon' => array(
        'title' => _wp('Icon'),
        'description' => _wp('Upload a 16*16px large icon file.'),
        'control_type' => waHtmlControl::FILE,
    ),
    'test_mode' => array(
        'title' => _wp('Test mode'),
        'description' => _wp('Disable when you want to go live.'),
        'control_type' => waHtmlControl::CHECKBOX,
        'value' => 1,
    ),
    'statuses' => array(
        'title' => _wp('Order statuses'),
        'description' => _wp('Select the statuses of orders which you want to be exported.'),
        'control_type' => waHtmlControl::GROUPBOX,
        'options_callback' => array('somePlugin', 'settingOrderStatuses'),
        'value' => array('new', 'completed'),
    ),
    'export_mode' => array(
        'title' => _wp('Export mode'),
        'description' => _wp('Select the desired export mode.'),
        'control_type' => waHtmlControl::RADIOGROUP,
        'options' => array(
            array(
                'value' => 'default',
                'title' => _wp('default'),
                'description' => _wp('default data fields'),
            ),
            array(
                'value' => 'advanced',
                'title' => _wp('advanced'),
                'description' => _wp('all data fields'),
            ),
        ),
        'value' => 'default',
    ),
    'protocol' => array(
        'title' => _wp('Data exchange protocol'),
        'description' => _wp('Select the desired data exchange protocol.'),
        'control_type' => waHtmlControl::SELECT,
        'options' => array(
            array(
                'value' => 1,
                'title' => '1.0',
            ),
            array(
                'value' => 2,
                'title' => '2.0',
            ),
        ),
        'value' => 1,
    ),
    'personal_data' => array(
        'control_type' => waHtmlControl::CONTACT,
        'options' => array(
            array('value' => 'email',),
            array('value' => 'phone',),
        ),
    ),
    'customer_phone' => array(
        'title' => _wp('Customer phone number'),
        'description' => _wp('Select the contact field corresponding to customer’s phone number.'),
        'control_type' => waHtmlControl::CONTACTFIELD,
        'value' => 'phone',
    ),
    'tags' => array(
        'title' => _wp('Export tags'),
        'description' => _wp('Add tags which you want to export.'),
        'control_type' => waHtmlControl::CUSTOM.' '.'somePlugin::settingCustomControl',
    ),
);