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 = array();
waHtmlControl::addNamespace($params, 'some');
$control = waHtmlControl::getControl(waHtmlControl::INPUT, 'test', $params);

Результат

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

Пример

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

Результат

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

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

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

Параметры

  • $type Тип элемента: одно из перечисленных ниже стандартных значений либо пользовательский тип элемента, который выше в коде был зарегистрирован с помощью метода registerControl. Обозначения стандартных типов элементов:
  • $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' => array(
            1 => 'первый',
            2 => 'второй',
            3 => 'третий',
        ),
        
        Режим 2: каждый элемент массива представляет собой подмассив с ключами 'value' и 'title', содержащими соответственно значение для атрибута name и текстовую надпись, например:
        'options' => array(
            array(
                'value' => 1,
                'title' => 'первый',
            ),
            array(
                'value' => 2,
                'title' => 'второй',
            ),
            array(
                'value' => 3,
                'title' => 'третий',
            ),
        ),
        

        Вместо указания фиксированного массива с помощью элемента 'options' можно указать динамически формируемый массив с помощью элемента 'options_callback' и значения типа callable. Пример:

        'options_callback' => array('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>'
    • 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' => array(
            1 => 'первый',
            2 => 'второй',
            3 => 'третий',
        ),
        

        Режим 2: каждый элемент массива представляет собой подмассив с ключами 'value' и 'title', содержащими соответственно значение атрибута value и текстовую надпись, например:
        'options' => array(
            array(
                'value' => 1,
                'title' => 'первый',
            ),
            array(
                'value' => 2,
                'title' => 'второй',
            ),
            array(
                'value' => 3,
                'title' => 'третий',
            ),
        ),
        

        Вместо указания фиксированного массива с помощью элемента 'options' можно указать динамически формируемый массив с помощью элемента 'options_callback' и значения типа callable. Пример:

        'options_callback' => array('appMyClass', 'myCallbackMethod'),

        Массив элементов должен сформировать метод, указанный в значении типа callable.

      • value: одно из значений атрибута value из массива 'options', соответствующий элементу radio, корторый должен быть выбрать по умолчанию.
      • control_separator: фрагмент HTML-кода, который должен быть вставлен между элементами radio.
    • waHtmlControl::SELECT
      • options: массив данных списка элементов option. Поддерживается два режима формирования этого массива:

        Режим 1: ключ каждого элемента массива представляет собой значение атрибута value соответствующего элемента option, а значение — текстовое значение в списке select, например:

        'options' => array(
            1 => 'первый',
            2 => 'второй',
            3 => 'третий',
        ),
        

        Режим 2: каждый элемент массива представляет собой подмассив с ключами 'value' и 'title', содержащими соответственно значение атрибута value и текстовую надпись, например:
        'options' => array(
            array(
                'value' => 1,
                'title' => 'первый',
            ),
            array(
                'value' => 2,
                'title' => 'второй',
            ),
            array(
                'value' => 3,
                'title' => 'третий',
            ),
        ),
        

        Вместо указания фиксированного массива с помощью элемента 'options' можно указать динамически формируемый массив с помощью элемента 'options_callback' и значения типа callable. Пример:

        'options_callback' => array('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.
    • Универсальные параметры для всех типов элементов
      • 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'.

Пример

$control_params = array(
    '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 = array(
    waHtmlControl::getControl(waHtmlControl::CHECKBOX, 'setting1', array(
        'checked' => true,
        'value'   => 1,
        'title'   => 'Флажок',
        'description'   => 'Включите или отключите',
    ) + $control_params),
    waHtmlControl::getControl(waHtmlControl::CONTACTFIELD, 'setting2', array(
        'title' => 'Контактное поле',
        'description'   => 'Выберите контактное поле',
    ) + $control_params),
    waHtmlControl::getControl(waHtmlControl::FILE, 'setting3', array(
        'title' => 'Файл',
        'description'   => 'Выберите файл на вашем компьютере',
    ) + $control_params),
    waHtmlControl::getControl(waHtmlControl::GROUPBOX, 'setting4', array(
        'options' => array(
            1 => 'первый',
            2 => 'второй',
            3 => 'третий',
        ),
        'value' => array(1, 3),
        'title' => 'Флажки',
        'description'   => 'Выберите любое количество вариантов',
    ) + $control_params),
    waHtmlControl::getControl(waHtmlControl::HIDDEN, 'setting5', array(
        'value' => ifset($setting5),
    )),
    waHtmlControl::getControl(waHtmlControl::INPUT, 'setting6', array(
        'title'       => 'Строка текста',
        'placeholder' => 'введите короткий текст',
    ) + $control_params),
    waHtmlControl::getControl(waHtmlControl::PASSWORD, 'setting7', array(
        'title' => 'Пароль',
        'placeholder' => 'введите пароль',
    ) + $control_params),
    waHtmlControl::getControl(waHtmlControl::RADIOGROUP, 'setting8', array(
        'options' => array(
            1 => 'первый',
            2 => 'второй',
            3 => 'третий',
        ),
        'value' => 2,
        'title' => 'Радиокнопки',
        'description'   => 'Выберите один из вариантов',
    ) + $control_params),
    waHtmlControl::getControl(waHtmlControl::SELECT, 'setting9', array(
        'options' => array(
            1 => 'первый',
            2 => 'второй',
            3 => 'третий',
        ),
        'value' => 3,
        'title' => 'Выпадающий список',
        'description'   => 'Выберите один из элементов списка',
    ) + $control_params),
    waHtmlControl::getControl(waHtmlControl::TEXTAREA, 'setting10', array(
        'value' => ifset($setting9),
        'title' => 'Многострочное поле',
        'placeholder' => 'введите длинный текст',
    ) + $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', array(__CLASS__, 'myControl'));
        wa()->getView()->assign('mycontrol', waHtmlControl::getControl('Mycontrol', $params));
        //...
    }
    public static function myControl($name, $params = array())
    {
        //...    реализация пользовательского элемента
        return '...';   //возвращаем HTML-код элемента
    }
}