README

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

Типовое создание формы проще продемонстрировать на примере:

$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

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

Также доступны настройки для самой формы:

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

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

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

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

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

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

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

Данные передаются в форму через вызов метода validate(). Каждое из полей проверяется по своему валидатору и хранит результат проверки. Проверка состояний формы:

• isSent() - отправлена ли форма;
• isValidated() - запускалась ли валидация;
• hasErrors() - есть ли ошибки;
• isValid() - валидна ли форма, т.е. валидация запускалась и ошибок нет.

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

Расширение

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

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

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

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