Назначение Помощника форм
Большая часть пользовательского интерфейса в Invision Community содержит формы, будь то многочисленные страницы настроек в админцентре, публикация контента в фронтэнде, настройка профиля и многое другое.
Invision Community имеет мощный класс Помощника формы, который упрощает внедрение форм в ваших приложениях и плагинах. Он предоставляет такие функции, как автоматическая проверка и встроенная безопасность, заботится о создании пользовательского интерфейса (в случае более сложных типов полей, таких как матрицы и селектор нод/деревьев) и динамического поведения для вас. Формы, созданные с помощью Помощника формы, поддерживают широкий диапазон типов полей, имеют встроенную поддержку вкладок, используют возможности HTML5, где это применимо, и многое другое.
Если вам нужен ввод какой-либо информации от пользователей в вашем приложении или плагине, вы всегда должны использовать Помощник форм; никогда не реализуйте такую функциональность вручную и не обходите фреймворк.
Основной фрагмент, показывающий, как в конечном итоге будет выглядеть код вашей формы:
// Создать экземпляр формы
$form = new \IPS\Helpers\Form;
// Добавить поля формы
$form->add( ... );
$form->add( ... );
if ( $values = $form->values() )
{
// Форма отправлена; обрабатывайте значения формы здесь
}
// Отправить форму для вывода
\IPS\Output::i()->output = $form;
Создание формы
Чтобы создать форму, вы просто создаете экземпляр из Помощника формы. К возвращенному объекту вы можете добавлять поля, вкладки и т.д. (описано в следующих разделах).
// Создание формы с использованием значений по умолчанию
$form = new \IPS\Helpers\Form;
Никакие параметры не требуются, но есть несколько необязательных параметров, которые вы можете передать:
\IPS\Helpers\Form( [ string $formID='form' [, string $submitLang='save' [, \IPS\Http\Url $actionURL=NULL [, array $attributes=array() ]]]] );
- $formID (строка, необязательный) - Идентификатор для использования в HTML атрибуте id для этой формы.
- $submitLang (строка, необязательный) - Языковой ключ строки для использования в названии кнопки 'отправить'.
- $actionURL (\IPS\Http\Url, необязательный) - Объект URL-адреса, по которому должна быть отправлена форма (по умолчанию, формы отправляются на ту же страницу, которая их отображает).
- $attributes (массив, необязательный) - Массив ключ/значение других HTML атрибутов, которые вы хотели бы включить в тег <form>, например для функции javascript.
Добавление элементов формы
Добавление элемента формы выполняется методом $form->add(). Вы передаете ему объект элемента, который вы хотите - например, чтобы добавить текстовый ввод в свою форму, вы можете сделать следующее:
$form->add( new \IPS\Helpers\Form\Text('name') );
Вы можете использовать широкий диапазон встроенных типов полей форм. Некоторые из доступных классов:
- \IPS\Helpers\Form\Text для обычного ввода текста.
- \IPS\Helpers\Form\Editor для ввода текста WYSIWYG.
- \IPS\Helpers\Form\Upload для загрузки файлов.
- \IPS\Helpers\Form\Date для дат.
- \IPS\Helpers\Form\Select для окна выбора.
- \IPS\Helpers\Form\YesNo для переключателей да/нет.
Классы всех полей форм имеют похожий набор параметров. Каждый из них настраивается с помощью значений, которые вы передаете. Вот параметры, которые вы можете передать в классы полей форм:
- $name (строка, обязательный) - имя поля (используется в атрибуте имени в HTML).
- $defaultValue (mixed, необязательный) - стандартное значение поля, независимо от типа поля.
- $required (boolean, необязательный) - будет ли поле обязательным. Обратите внимание: передача true устанавливает HTML5 атрибут required, то есть форма не может быть отправлена, если она не заполнена. Передав NULL, вы отключите атрибут required, позволяя вместо этого проверять поле вручную на бэкэнд.
- $options (массив, необязательный) - Массив параметров. Допустимые значения зависят от типа поля; посмотрите документы по отдельным классам для получения дополнительной информации.
- $customValidationCode (функция, необязательный) - функция проверки значения поля.
- $prefix (строка, необязательный) - HTML строка для отображения перед полем HTML.
- $suffix (строка, необязательный) - HTML строка для отображения после поля HTML.
- $id (строка, необязательный) - Идентификатор, который будет использован в HTML атрибуте id.
Для всех доступных классов, просмотрите файлы в директории system/Helpers/Form/. Значения, приемлемые для $options описаны в исходном коде каждого класса в директории. Имейте в виду, что некоторые классы расширяют другие (например, CheckboxSet расширяет Select и имеет те же $options).
Например, чтобы создать окно с множественным выбором, вы должны сделать что-то вроде этого:
$form->add( new \IPS\Helpers\Form\Select( 'my_select_box', NULL, TRUE, array( 'options' => array( 0 => 'Foo', 1 => 'Bar', 2=> 'Baz' ), 'multiple' => TRUE ) ) );
Метки и описания
Свойство $name, в дополнение к имени, используемом для HTML поля, также используется для отображения метки (label). Помощник формы автоматически найдёт языковую строку с таким ключом, чтобы использовать её в качестве метки.
Он также будет искать языковую строку с _desc для описания.Например, если $name для вашего поля - my_field, в качестве описания будет использоваться языковая строка my_field_desc. Если языковая строка с этим ключом не существует, описание не будет использоваться.
Система также будет искать языковую строку с _warning для блока предупреждения (опять же, если строки не существует, не будет отображено). Обычно это всегда используется с переключателями (см. ниже), например, для отображения предупреждения, когда пользователь выбирает нежелательный вариант.
В дополнение к меткам и описаниям с автоматическим использованием языковой строки, также можно переопределить это поведение и установить свои собственные значения в контроллере. Например:
$input = new \IPS\Helpers\Form\Text( 'my_select_box', NULL, TRUE );
$input->description = "My Description";
$input->label = "My Label";
Важно отметить, что при установке описаний как данном случае, они будут добавлены точно такими же, как указаны, без дополнительной разметки. Если необходима разметка, вы должны установить свойство с помощью шаблона.
Проверка
Большинство классов будут автоматически проверять введённые данные, а параметр $options предоставляет способы настройки. Например, если вы создаёте элемент \IPS\Helpers\Form\Number, он будет автоматически проверен - является ли значение числом, и вы можете использовать $options для управления максимумом и минимумом вводимого числа вместе с количеством разрешенных десятичных знаков после точки. Система автоматически снова отобразит форму со встроенной ошибкой, если любой из элементов не пройдёт проверку, без необходимости предоставления дополнительного кода с вашей стороны. Однако, если вы хотите включить собственную проверку, вы можете сделать это с помощью свойства $customValidationCode - вы просто предоставляете метод обратного вызова, который генерирует исключение DomainException, если возникла ошибка. Например, если вы хотите сделать числовое поле, где число 7 не было разрешено, вы можете сделать это следующим образом:
$form->add( new \IPS\Helpers\Form\Number( 'my_field', NULL, TRUE, array(), function( $val )
{
if ( $val == 7 )
{
throw new \DomainException('form_bad_value');
}
} ) );
Обработка данных
Когда ваша форма будет отправлена, $form->values() вернет массив со значениями каждого элемента (если форма не была отправлена или проверка не пройдена, она возвращает FALSE). Имейте в виду, что защита CSRF обрабатывается автоматически при использовании централизованного класса \IPS\Helpers\Form и будет показано сообщение об ошибке, если ключ CSRF не будет соответствовать ожидаемому значению.
Значение, возвращаемое для каждого элемента, зависит от типа, а иногда и от параметров. Например, элемент \IPS\Helpers\Form\Text всегда возвращает строку в качестве значения. Однако \IPS\Helpers\Form\Number может вернуть целое число (int) или число с плавающей точкой (float). С другой стороны \IPS\Helpers\Form\Upload возвращает объект класса \IPS\File (или даже массив объектов, если это поле для загрузки нескольких файлов).
Если вы предпочитаете получать только строковые значения (например, вы хотите сохранить значения как объект JSON), вы можете передать TRUE в метод $form->values().
Рекомендации
Формы составляют большую часть пользовательского интерфейса в сообществе Invision Community. Важно представлять UI интерфейс как общую среду, согласующуюся с другими областями сайта. В связи с этим некоторые наши рекомендации:
- Всегда создавайте описание настроек положительно. Например, пишите "Включить функцию?" вместо "Отключить функцию?". Значение "Да" всегда должно означать, что и "Включить".
- Делайте метки короткими и понятными и используйте описания, если только оно необходимо. Например, для поля "Включить функцию?" не требуется добавлять описание в стиле "Установите значение в Да, чтобы включить функцию", т.к. это очевидно.
- Используйте префиксы и суффиксы, а не добавляйте информацию на ярлык или описание, где это возможно. Например, не используйте метку "Количество дней пред удалением" - сделайте метку более лаконичной - "Удалить после" и суффикс, который появится после поля - "дней".
- Никогда не обращайтесь в настройка в метках или описаниях. Например, не делайте такого описания "Применяется только, если настройка выше включена". Используйте переключатели для обозначения этого.
- Никогда не делайте указание определённого значения для какого-либо действия. Например, не делайте описание подобного этому "Оставьте поле пустым для неограниченного - используйте чекбокс "Неограниченно" или отдельную настройку, которая переключает другие настройки.