waHtmlControl

В большинстве случаев для получения HTML-кода стандартного элемента формы достаточно вызвать метод класса getControl.

Чтобы создать нестандартный элемент формы, нужно сначала вызвать метод registerControl, который должен возвращать HTML-код нового элемента, и затем вызвать метод getControl, в который в качестве параметра передать идентификатор нового типа элемента.

Методы

addNamespace
Добавляет пространство имен к значению атрибута name элемента формы.
getControl
Возвращает HTML-код элемента формы.
registerControl
Добавляет пользовательский тип элементов формы в список доступных.

public static final function addNamespace (&$params, $namespace = '')

Добавляет пространство имен в значение атрибута name элемента формы. Пространство имен создается путем формирования имени переменной-массива, ключом которого становится исходное значение атрибута name.

Параметры

&$params Массив параметров элемента формы, подробно он описан для метода getControl.
$namespace Значение пространства имен — в виде строки или массива строк. Если указано значение в виде простой строки, то именем переменной, отправляемой на сервер, становится значение пространства имен, а ключом отправляемой переменной-массива становится исходное значение атрибута name. Если указано значение в виде массива, то первый элемент массива используется в качестве имени переменной-массива, отправляемой на сервер, каждый последующий элемент становится ключом подмассива следующего уровня, а исходное значение атрибута name становится ключом вложенного подмассива самого нижнего уровня.

Пример

$params = [];
waHtmlControl::addNamespace($params, 'some');
$control = waHtmlControl::getControl(waHtmlControl::INPUT, 'test', $params);

Результат

<input ... name="some[test]" ...>

Пример

$params = [];
waHtmlControl::addNamespace($params, ['some', 'other']);
$control = waHtmlControl::getControl(waHtmlControl::INPUT, 'test', $params);

Результат

<input ... name="some[other][test]" ...>

public static function getControl ($type, $name, $params = [])

Возвращает HTML-код элемента формы.

Параметры

$type Тип элемента: одно из перечисленных ниже стандартных значений либо пользовательский тип элемента, который выше в коде был зарегистрирован с помощью метода registerControl. Обозначения стандартных типов элементов:
- waHtmlControl::CHECKBOX: тег <input type="checkbox">
- waHtmlControl::CONTACTFIELD: выпадающий список полей контактов.
- waHtmlControl::FILE: тег <input type="file">
- waHtmlControl::GROUPBOX: группа тегов <input type="checkbox>
- waHtmlControl::HELP: тег <p> с текстом
- waHtmlControl::HIDDEN: тег <input type="hidden>
- waHtmlControl::INPUT: тег <input type="text">
- waHtmlControl::PASSWORD: тег <input type="password">
- waHtmlControl::RADIOGROUP: группа тегов <input type="radio">
- waHtmlControl::SELECT: тег <select>
- waHtmlControl::TEXTAREA: тег <textarea>
- waHtmlControl::TITLE: тег <h3> в качестве заголовка
- waHtmlControl::COLORPICKER: поле для удобного выбора цвета
- waHtmlControl::CUSTOM: индивидуальный элемент, сформированный логикой вашего приложения или плагина
$name Строка, которая может быть использована для формирования значения атрибута name — с учетом значения 'namespace', указанного в параметрах элемента.
$params Массив параметров для формирования элементов формы в зависимости от типа элемента.
- waHtmlControl::CHECKBOX
  - value: значение атрибута value; значение по умолчанию — 1.
  - class: значение атрибута class.
  - style: значение атрибута style.
  - title: значение атрибута title.
  - checked: необязательный флаг, обозначающий необходимость добавления атрибута checked; значение по умолчанию — false.
- waHtmlControl::CONTACTFIELD
  - value: ID контактного поля, которое должно быть выбрано по умолчанию в выпадающем списке.
- waHtmlControl::FILE
  - class: значение атрибута class.
  - style: значение атрибута style.
- waHtmlControl::GROUPBOX
  - options: массив данных списка элементов типа checkbox. Поддерживается два режима формирования этого массива:
    
    Режим 1: ключ каждого элемента массива представляет собой значение для атрибута name соответствующего элемента checkbox, а значение — текстовую надпись, отображаемую справа от элемента checkbox, например:
```
'options' => [
    1 => 'первый',
    2 => 'второй',
    3 => 'третий',
],
```
    Режим 2: каждый элемент массива представляет собой подмассив с ключами 'value' и 'title', содержащими соответственно значение для атрибута name и текстовую надпись, например:
```
'options' => [
    [
        'value' => 1,
        'title' => 'первый',
    ],
    [
        'value' => 2,
        'title' => 'второй',
    ],
    [
        'value' => 3,
        'title' => 'третий',
    ],
],
```
    Вместо указания фиксированного массива с помощью элемента 'options' можно указать динамически формируемый массив с помощью элемента 'options_callback' и значения типа callable. Пример:
```
'options_callback' => ['appMyClass', 'myCallbackMethod'],
```
    Массив элементов должен сформировать метод, указанный в значении типа callable.
  - value: массив значений для атрибута name, указанных в массиве 'options' и соответствующих элементам checkbox, которые должны быть отмечены по умолчанию.
  - options_wrapper: массив параметров оформления отдельных элементов типа CHECKBOX в пределах общего элемента GROUPBOX:
    - title_wrapper: обертка вокруг заголовка рядом с элементом CHECKBOX; по умолчанию используется значение ' %s';
    - description_wrapper: обертка вокруг подсказки рядом с элементом CHECKBOX; по умолчанию используется значение '<span class="hint">%s</span>';
    - control_separator: HTML-код, который должен размещаться между отдельными элементами CHECKBOX; по умолчанию используется значение '<br>';
    - custom_control_separator: HTML-код для переопределения значения control_separator.
- waHtmlControl::HELP
  - value: текст для отображения внутри тега <p>.
  - class: значение атрибута class.
  - style: значение атрибута style.
- waHtmlControl::HIDDEN
  - value: значение атрибута value.
  - class: значение атрибута class.
- waHtmlControl::INPUT и waHtmlControl::PASSWORD
  - value: значение атрибута value.
  - class: значение атрибута class.
  - style: значение атрибута style.
  - size: значение атрибута size.
  - maxlength: значение атрибута maxlength.
  - placeholder: значение атрибута placeholder.
  - readonly: флаг, обозначающий необходимость добавления атрибута readonly; значение по умолчанию — false.
  - autocomplete: флаг, обозначающий необходимость добавления атрибута autocomplete="on|off"; по умолчанию атрибут не добавляется.
  - autofocus: флаг, обозначающий необходимость добавления атрибута autofocus; значение по умолчанию — false.
- waHtmlControl::RADIOGROUP
  - options: массив данных списка элементов типа radio. Поддерживается два режима формирования этого массива:
    
    Режим 1: ключ каждого элемента массива представляет собой значение атрибута value соответствующего элемента radio, а значение — текстовую надпись, отображаемую справа от элемента radio, например:
```
'options' => [
    1 => 'первый',
    2 => 'второй',
    3 => 'третий',
],
```
    Режим 2: каждый элемент массива представляет собой подмассив с ключами 'value' и 'title', содержащими соответственно значение атрибута value и текстовую надпись, например:
```
'options' => [
    [
        'value' => 1,
        'title' => 'первый',
    ],
    [
        'value' => 2,
        'title' => 'второй',
    ],
    [
        'value' => 3,
        'title' => 'третий',
    ],
],
```
    Вместо указания фиксированного массива с помощью элемента 'options' можно указать динамически формируемый массив с помощью элемента 'options_callback' и значения типа callable. Пример:
```
'options_callback' => ['appMyClass', 'myCallbackMethod'],
```
    Массив элементов должен сформировать метод, указанный в значении типа callable.
  - value: одно из значений атрибута value из массива 'options', соответствующий элементу radio, который должен быть выбрать по умолчанию.
  - control_separator: фрагмент HTML-кода, который должен быть вставлен между элементами radio.
  - custom_control_separator: HTML-код для переопределения значения control_separator.
- waHtmlControl::SELECT
  - options: массив данных списка элементов option. Поддерживается два режима формирования этого массива:
    
    Режим 1: ключ каждого элемента массива представляет собой значение атрибута value соответствующего элемента option, а значение — текстовое значение в списке select, например:
```
'options' => [
    1 => 'первый',
    2 => 'второй',
    3 => 'третий',
],
```
    Ключи массива должны быть все числовыми или все текстовыми. Смешивание в одном массиве элементов с числовыми и текстовыми ключами может привести к непредсказуемым результатам.
    
    Режим 2: каждый элемент массива представляет собой подмассив с ключами 'value' и 'title', содержащими соответственно значение атрибута value и текстовую надпись, например:
```
'options' => [
    [
        'value' => 1,
        'title' => 'первый',
    ],
    [
        'value' => 2,
        'title' => 'второй',
    ],
    [
        'value' => 3,
        'title' => 'третий',
    ],
],
```
    Вместо указания фиксированного массива с помощью элемента 'options' можно указать динамически формируемый массив с помощью элемента 'options_callback' и значения типа callable. Пример:
```
'options_callback' => ['appMyClass', 'myCallbackMethod'],
```
    Массив элементов должен сформировать метод, указанный в значении типа callable.
  - value: одно из значений атрибута value из массива 'options', соответствующий элементу option, который должен быть выбран по умолчанию в выпадающем списке.
- waHtmlControl::TEXTAREA
  - value: содержимое элемента textarea.
  - class: значение атрибута class.
  - style: значение атрибута style.
  - cols: значение атрибута cols.
  - rows: значение атрибута rows.
  - wrap: значение атрибута wrap.
  - placeholder: значение атрибута placeholder.
  - readonly: флаг, обозначающий необходимость добавления атрибута readonly; значение по умолчанию — false.
  - autofocus: флаг, обозначающий необходимость добавления атрибута autofocus; значение по умолчанию — false.
  - wysiwyg: непустой массив параметров для вызова метода fromTextArea JavaScript-библиотеки CodeMirror. Наличие такого массива (который также допускается заменить на простое значение true) обозначает необходимость преобразования элемента textarea в пользовательский элемент с автоматической подсветкой программного кода. Для работы этого режима на странице с таким элементом должны быть подключены CSS- и JavaScript-файлы из директории wa-content/js/codemirror/. При использовании параметра wysiwyg значения параметров class, style, cols, rows, wrap, placeholder, readonly, autofocus игнорируются.
- waHtmlControl::TITLE
  - value: текст для отображения внутри тега <h3>.
  - description: текст для отображения внутри тега <h4>, следующего сразу за тегом <h3> в качестве подзаголовка.
  - class: значение атрибута class.
  - style: значение атрибута style.
- waHtmlControl::COLORPICKER
  - value: обозначение цвета, выбранное по умолчанию.
  - options: список дополнительных кнопок для быстрого выбора предустановленных цветов; ключи массива — обозначения цветов, значения — подмассивы в формате 'ID текущей локали' => 'название цвета' (названия цветов доступны пользователю в виде всплывающих подсказок title при наведении курсора).
- waHtmlControl::CUSTOM
  - callback: массив с именами PHP-класса и его публичного статичного метода, возвращающего HTML-код индивидуального элемента формы и принимающего следующие параметры:
    - $params: параметры элемента формы в виде массива, значения которых можно подставлять в возвращаемый HTML-код.
    - $namespace: значение пространства имён, указанное при создании элемента.
- Универсальные параметры для всех типов элементов
  - namespace: значение пространства имен.
  - id: дополнительное значение, которое необходимо добавить с символом подчеркивания _ в начало автоматически формируемого значения атрибута id.
  - title: значение параметра 'title', обычно отображается рядом с элементом.
  - description: значение параметра 'description', обычно отображается под элементом.
  - control_wrapper: шаблон HTML-обертки, внутри которой должен должен быть сформирован HTML-код элемента; шаблон должен содержать 3 вставки %s, каждая из которых соответствует — в указанном порядке — 1) значению параметра 'title', 2) HTML-коду элемента, 3) значению параметра 'description'.
  - title_wrapper: шаблон HTML-обертки для отображения значения параметра 'title'; шаблон по умолчанию: %s: (текст с двоеточием)
  - description_wrapper: шаблон HTML-обертки для отображения значения параметра 'description';
  - custom_title_wrapper: шаблон для переопределения значения title_wrapper;
  - custom_description_wrapper: шаблон для переопределения значения description_wrapper;
  - custom_control_wrapper: шаблон для переопределения значения control_wrapper.

Пример

$control_params = [
    'namespace'           => 'settings',
    'control_wrapper'     => '<div class="field"><div class="name">%s</div><div class="value">%s%s</div></div>',
    'title_wrapper'       => '%s',
    'description_wrapper' => '<br><span class="hint">%s</span>'
];

$controls = [
    waHtmlControl::getControl(waHtmlControl::CHECKBOX, 'setting1', [
        'checked' => true,
        'value'   => 1,
        'title'   => 'Флажок',
        'description'   => 'Включите или отключите',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::CONTACTFIELD, 'setting2', [
        'title' => 'Контактное поле',
        'description'   => 'Выберите контактное поле',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::FILE, 'setting3', [
        'title' => 'Файл',
        'description'   => 'Выберите файл на вашем компьютере',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::GROUPBOX, 'setting4', [
        'options' => [
            1 => 'первый',
            2 => 'второй',
            3 => 'третий',
        ],
        'value' => [1, 3],
        'title' => 'Флажки',
        'description'   => 'Выберите любое количество вариантов',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::HIDDEN, 'setting5', [
        'value' => ifset($setting5),
    ]),
    waHtmlControl::getControl(waHtmlControl::INPUT, 'setting6', [
        'title'       => 'Строка текста',
        'placeholder' => 'введите короткий текст',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::PASSWORD, 'setting7', [
        'title' => 'Пароль',
        'placeholder' => 'введите пароль',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::RADIOGROUP, 'setting8', [
        'options' => [
            1 => 'первый',
            2 => 'второй',
            3 => 'третий',
        ],
        'value' => 2,
        'title' => 'Радиокнопки',
        'description'   => 'Выберите один из вариантов',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::SELECT, 'setting9', [
        'options' => [
            1 => 'первый',
            2 => 'второй',
            3 => 'третий',
        ],
        'value' => 3,
        'title' => 'Выпадающий список',
        'description'   => 'Выберите один из элементов списка',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::TEXTAREA, 'setting10', [
        'value' => ifset($setting10),
        'title' => 'Многострочное поле',
        'placeholder' => 'введите длинный текст',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::COLORPICKER, 'setting11', [
        'value' => '#ff0000',
        'options' => [
            '#ff0000' => [
                'ru_RU' => 'красный',
            ],
            '#00ff00' => [
                'ru_RU' => 'зелёный',
            ],
        ],
    ] + $control_params),
];

public static function registerControl ($type, $callback)

Добавляет пользовательский тип элементов формы в список доступных для использования с помощью метода getControl.

Параметры

$type Строковое обозначение пользовательского типа элементов, записанное с начальной буквой в верхнем регистре и остальными буквами — в нижнем.
$callback Значение, которое можно вызвать как PHP-функцию (см. документацию для PHP-функции is_callable). Такая функция (обычно статический метод класса) должна принимать в качестве параметров значение name элемента формы и массив параметров для формирования элемента, подобный тем, которые описаны для стандартных элементов для метода getControl, и возвращать HTML-код пользовательского элемента формы.

Пример

class someClass
{
    public function execute()
    {
        //...
        waHtmlControl::registerControl('Mycontrol', [__CLASS__, 'myControl']);
        wa()->getView()->assign('mycontrol', waHtmlControl::getControl('Mycontrol', $params));
        //...
    }
    public static function myControl($name, $params = [])
    {
        //...    реализация пользовательского элемента
        return '...';   //возвращаем HTML-код элемента
    }
}