cmsx/form

CMSx Form component

Компонент для работы с формами

Создание и настройка формы

Типовое создание формы проще продемонстрировать на примере:, _(*1)

$f = new \CMSx\Form('myform');
$f->addInput('name', 'Имя')
  ->setIsRequired(true);
$f->addSelect('city')
  ->setOptions('Москва', 'Киев', 'Минск')
$f->addInput('email', 'E-mail')
  ->setRegexp('/[some_regexp]/uis');

Сейчас существуют элементы следующих типов: * Input - текстовое поле * Password - поле пароль * Hidden - скрытое поле * Select - выбор из списка вариантов <select> * Radio - выбор из списка вариантов input[type=radio] * Checkbox - один чекбокс * CheckboxListing - выбор из списка нескольких вариантов input[type=checkbox] * Textarea - текстовое поле * Caption - заголовок и текст без input'a, _(*2)

Т.е. создав объект формы мы добавляем к нему поля по отдельности. Каждый из методов add* создает в форме и возвращает добавленный объект соответствующего элемента, обладающего своим набором настроек. Все элементы наследуют класс CMSx\Form\Element, поэтому можно легко дополнить и расширить этот набор., _(*3)

Также доступны настройки для самой формы: * setAction() - Установить action; * setFormAttributes() - Атрибуты для тега формы; * setSubmitButton($text, $attr = null) - Текст и атрибуты кнопки submit; * setTmpl*() - Шаблоны sprintf() для формирования разметки формы., _(*4)

Отрисовка формы

После настройки формы, можно отрисовать форму целиком, при помощи $f->render(). Будет сформирован тег <form>, содержащий все настроенные поля, а также кнопка "отправить"., _(*5)

Можно сгенерировать части формы по отдельности, с помощью методов render*. Если требуется нестандартная компоновка, к каждому из элементов формы можно обратиться по отдельности: $f->field('email'). Для них можно вызвать метод render(), в результате будет отрисован соответствующий элемент ввода, или получить другие свойства, например getLabel(), getIsRequired() и т.п., _(*6)

Валидация формы

При настройке формы, для каждого из полей можно указать параметры валидации: * Обязательно к заполнению: setIsRequired() * Проверка по регулярному выражению: setRegexp() * Проверка по фильтру (callback): setFilter() * Проверка по списку опций: setOptions(). Все выборы из списка (select, radiobutton, checkbox listing) автоматически проверяются на соответствие значения заданным вариантам., _(*7)

Данные передаются в форму через вызов метода validate(). Каждое из полей проверяется по своему валидатору и хранит результат проверки. Проверка состояний формы: * isSent() - отправлена ли форма; * isValidated() - запускалась ли валидация; * hasErrors() - есть ли ошибки; * isValid() - валидна ли форма, т.е. валидация запускалась и ошибок нет., _(*8)

Если форма валидна, данные из неё можно получить вызвав метод getValues() или getValue($field). Даже если пользователь отправил лишние поля, они не попадут в "чистые данные". Пока форма не валидна, данные в форме недоступны. Можно получить "сырые" значения, обратившить к методу getTaintedValues() по каждому элементу., _(*9)

Расширение

Базовые классы формы сделаны таким образом, чтобы максимально упростить наследование и конфигурацию под свои потребности. Так, в форме и каждом элементе предусмотрен метод init(), вызываемый после конструктора, позволяющий отнаследоваться и донастроить элемент., _(*10)

Для единообразия у формы предусмотрен метод process() в котором должна располагаться логика обработки формы: отправка на E-mail, сохранение в базу и т.п. Поскольку часто валидация и выполнение логики связаны, предусмотрен совмещенный метод validateAndProcess()., _(*11)

Для создания дополнительных обработчиков формы, можно переопределять методы beforeValidation() и afterValidation(), позволяющие заложить любую логику и сложные правила до и после основной валидации полей. Метод beforeValidation() позволяет также изменять отправляемые на валидацию данные., _(*12)

Формирование всего HTML кода формы сделано с использованием шаблонов функции sprintf() в сочетании с разделенными методами отрисовки частей элемента render*, дающее неограниченные возможности по тонкой донастройке., _(*13)