Zend_Form

Zend_Form - Быстрый старт

Данное руководство охватывает основы создания форм, проверки корректности данных и визуализиции с использованием Zend_Form.

Создание объекта формы

Объекты форм создаются через простое инстанцирование Zend_Form:

  1.  

Для более сложных случаев использования вы можете создавать подклассы Zend_Form, но простые формы вы можете создавать, используя объект Zend_Form.

Если вы хотите указать атрибуты action и method (что во всех случаях является хорошей идеей), то можете сделать это с использованием аксессоров setAction() и setMethod():

  1. span style="color: #ff0000;">'/resource/process')
  2.      ->setMethod('post');

Приведенный выше код устанавливает значение атрибута action равным "/resource/process" и указывает способ отправки данных - HTTP POST. Эти атрибуты будут выведены после окончательного рендеринга формы.

Вы можете установить дополнительные HTML-атрибуты для тега <form>, используя методы setAttrib() и setAttribs(). Например, если нужно установить идентификатор элемента формы, то установите атрибут "id":

  1. span style="color: #ff0000;">'id', 'login');

Добавление элементов в форму

Форма без элементов бесмысленна. Zend_Form поставляется с некоторым начальным набором элементов, которые отвечают за рендеринг XHTML-кода с использованием помощников Zend_View. В этот список входят элементы:

  • button (кнопка)

  • checkbox (флажок опций, или несколько флажков опций через multiCheckbox)

  • hidden (спрятанное поле)

  • image (изображение)

  • password (пароль)

  • radio (переключатель)

  • reset (кнопка сброса)

  • select (выпадающий список - как обычный, так multi-select)

  • submit (кнопка отправки)

  • text (текстовое поле)

  • textarea (текстовая область)

Есть два способа добавления элементов в форму - вы можете инстанцировать нужные элементы и передавать их объекту формы, или передавать только тип элемента, в этом случае Zend_Form инстанцирует соответствующий объект за вас.

Некоторые примеры:

  1. // Инстанцирование элемента и его передача объекту формы:
  2. 'username'));
  3.  
  4. // Передача типа элемента объекту формы
  5. 'text', 'username');

По умолчанию элементы не имеют никаких валидаторов или фильтров. Это означает, что вам нужно установить к своим элементам, как минимум, валидаторы, и, возможно, фильтры. Вы можете делать это (a) до передачи элементов в форму, (b) через опции конфигурирования, которые передаются при создании элемента через Zend_Form, или (с) путем извлечения элементов формы из объекта формы и их конфигурирования.

Сначала рассмотрим создание валидаторов для конкретного объекта элемента. Вы можете передавать объекты Zend_Validate_* или имена валидаторов:

  1. span style="color: #ff0000;">'username');
  2.  
  3. // Передача объекта Zend_Validate_*:
  4. // Передача имени валидатора:
  5. $username->addValidator('alnum');

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

  1. // Передача шаблона
  2. $username->addValidator('regex''/^[a-z]/i'));

(Второй параметр используется для указания того, должен ли валидатор в том случае, если данные не прошли проверку, прерывать дальнейшую проверку в цепочке валидаторов; по умолчанию он равен false.)

Вы можете также указать элемент как обязательный для заполнения. Это может быть сделано как с помощью аксессора, так и путем передачи определенной опции при создании элемента. В первом случае:

  1. // Указание того, что элемент обязателен для заполнения:

Если элемент обязателен для заполнения, то в начало цепочки валидаторов добавляется валидатор 'NotEmpty', который проверяет, имеет ли элемент значение.

Фильтры регистрируются в основном так же, как и валидаторы. Для демонстрации добавим фильтр для приведения значения к нижнему регистру:

  1. $username->addFilter('StringToLower');

Таким образом, окончательно установка элемента получится такой, как показано ниже:

  1. $username->addValidator('alnum')
  2.          ->addValidator('regex''/^[a-z]/''StringToLower');
  3.  
  4. // или в более компактной форме:
  5. 'alnum''regex''/^[a-z]/i''StringToLower'));

Выполнение этих действий для каждого элемента по отдельности может показаться несколько утомительным. Попробуем вариант (b) из перечисленных выше. Когда мы создаем новый элемент, используя Zend_Form::addElement() в качестве фабрики, то можем опционально передавать опции конфигурирования. Они могут включать в себя валидаторы и фильтры для использования. Таким образом, чтобы неявным образом сделать все это, попробуйте следующее:

  1. span style="color: #ff0000;">'text', 'username''validators''alnum''regex''/^[a-z]/i')
  2.     ),
  3.     'required''filters''StringToLower'),
  4. ));

Note: Если вы обнаружили, что настраиваете элементы, используя одни и те же опции во многих местах, то можете создать подкласс Zend_Form_Element и использовать его вместо выполнения этих процедур; это может избавить от лишней работы по набору кода.

Визуализация формы

Визуализация формы производится легко. Большинство элементов использует помощника Zend_View для генерации вывода и поэтому нуждаются в объекте вида для выполнения рендеринга. Есть два способа запустить рендеринг: использовать метод формы render() или просто вывести форму с помощью echo.

  1. // Явный вызов render() с передачей объекта вида:
  2. // Предполагается, что объект вида уже был установлен ранее через setView():

По умолчанию Zend_Form будет пытаться использовать объект вида, инициализированный в ViewRenderer, это означает, что вам не нужно будет вручную устанавливать объект вида при использовании MVC Zend Framework-а. Код для визуализации формы в скрипте вида весьма прост:

  1.  

Внутри себя Zend_Form использует "декораторы" для выполнения визуализации. Эти декораторы могут замещать содержимое переданного элемента, производить добавления в его начало и конец, производить наблюдение за ним. В результате вы можете комбинировать несколько декораторов для достижения нужного эффекта. По умолчанию в Zend_Form_Element используется четыре декоратора для получения нужного вывода; их установка выглядит приблизительно так:

  1. span style="color: #ff0000;">'ViewHelper',
  2.     'Errors''HtmlTag''tag' => 'dd''Label''tag' => 'dt')),
  3. ));

Код выше создает вывод наподобие следующего:

  1. <dt><label for="username" class="required">Username</dt>
  2. <dd>
  3.     <input type="text" name="username" value="123-abc" />
  4.     <ul class="errors">
  5.         <li>'123-abc' has not only alphabetic and digit characters</li>
  6.         <li>'123-abc' does not match against pattern '/^[a-z]/i'</li>
  7.     </ul>
  8. </dd>

Вы можете изменить набор декораторов, используемый элементом, если хотите иметь другой результат вывода; более подробную информацию читайте в разделе о декораторах.

Форма сама по себе просто производит обход содержащегося в ней списка элементов и окружает получившийся вывод тегами <form>. Переданные вами action и method устанавливаются в качестве атрибутов тега <form> - так же, как и остальные атрибуты, установленные через семейство методов setAttribs().

Элементы обходятся в том же порядке, в котором они были зарегистрированы, но если ваш элемент содержит атрибут order, то он используется для сортировки. Вы можете установить порядок элемента, используя:

  1.  

Или путем передачи в качестве опции при создании элемента:

  1. span style="color: #ff0000;">'text', 'username''order' => 10));

Проверка корректности данных формы

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

Откуда идут данные? Вы можете использовать $_POST, $_GET, и любые другие источники данных (например, запросы веб-сервисов):

  1. span style="color: #808080; font-style: italic;">// успех
  2. // неудача
  3. }

Вам может прийти в голову идея проверять данные одного элемента или группы элементов с помощью AJAX-запросов. Метод isValidPartial() будет проверять на корректность данные части формы. Его отличие от isValid() состоит в том, что если в данных формы отсутствует какой-либо ключ, то для этого элемента не будут производиться проверки на корректность заполнения:

  1. span style="color: #808080; font-style: italic;">// все предоставленные элементы прошли все проверки на корректность
  2. // один или более элементов не прошли проверку на корректность
  3. }

Для проверки части формы может также использоваться метод processAjax(). В отличие от isValidPartial(), в случае неуспеха он возвращает строку в формате JSON, содержащую сообщения об ошибках заполнения.

Если проверка на корректность заполнения была пройдена успешно, то вы можете извлечь прошедшие фильтрацию данные:

  1.  

Для того, чтобы извлечь нефильтрованные данные, используйте:

  1.  

Получение статуса ошибки

А что в том случае, если форма не прошла проверку на корректность? Как правило, вы можете просто вывести ее снова, и сообщения об ошибках будут отображены, если вы используете декораторы по умолчанию:

  1. span style="color: #808080; font-style: italic;">// или присвойте ее объекту вида и произведите его рендеринг...
  2. 'form');
  3. }

Если нужно проанализировать ошибки, то есть два способа их получения. getErrors() возвращает ассоциативный массив имен элементов и кодов ошибок (где коды ошибок представлены в виде массива). getMessages() возвращает ассоциативный массив имен элементов и сообщений об ошибках (где сообщения об ошибках представлены в виде ассоциативного массива пар 'код ошибки'/'сообщение об ошибке'). Если элемент не имеет ошибок, то он не будет включен в массив.

Объединяя изложенное

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

  • username

  • password

  • submit

Для примера предположим, что корректное имя пользователя должно содержать только буквенно-цифровые символы, начинаться с буквы, иметь длину не меньше 6 и не больше 20 символов, кроме этого, имена пользователей должны быть приведены к нижнему регистру. Пароль должен содержать как минимум 6 символов. Переданное значение кнопки использоваться не будет, поэтому проверка для нее может не производиться.

Мы используем мощь конфигурационных опций Zend_Form для построения формы:

  1. span style="color: #ff0000;">'/user/login')
  2.      ->setMethod('post');
  3.  
  4. // Создание и конфигурирование элемента username
  5. 'text', 'username');
  6. $username->addValidator('alnum')
  7.          ->addValidator('regex''/^[a-z]+/'))
  8.          ->addValidator('stringLength''StringToLower');
  9.  
  10. // Создание и конфигурирование элемента password
  11. 'password', 'password''StringLength'// Добавление элементов в форму:
  12. // addElement() используется в качестве "фабрики"
  13.      // для создания кнопки 'Login':
  14.      ->addElement('submit', 'login''label' => 'Login'));

Затем создается контроллер для отображения формы и ее обработки:

  1. span style="color: #808080; font-style: italic;">// здесь должен быть код для создания формы, приведенный выше
  2. // рендеринг user/form.phtml
  3. 'form''index'// проверка на корректность не пройдена, выводим форму снова
  4. 'form'// аутентификация...
  5.     }
  6. }

...и скрипт вида для отображения формы:

  1.  

Как вы наверное заметили, код контроллера не является полным - после успешно проведенной проверки должна производиться авторизация пользователя (например, используя Zend_Auth).

Использование объекта Zend_Config

Все классы Zend_Form можно конфигурировать, используя Zend_Config. Вы можете передавать объект Zend_Config либо конструктору, либо через метод setConfig(). Посмотрим, как можно создать описанную выше форму, используя файл INI. Во-первых, будем следовать рекомендации размещать конфигурации в разделах, отражающих местонахождение релиза, и сфокусируемся на разделе 'development'. Во-вторых, установим раздел для данного контроллера ('user') и ключ для формы ('login'):

  1. [development]
  2. ; общие метаданные для формы
  3. user.login.action = "/user/login"
  4. user.login.method = "post"
  5.  
  6. ; элемент username
  7. user.login.elements.username.type = "text"
  8. user.login.elements.username.options.validators.alnum.validator = "alnum"
  9. user.login.elements.username.options.validators.regex.validator = "regex"
  10. user.login.elements.username.options.validators.regex.options.pattern = "/^[a-z]/i"
  11. user.login.elements.username.options.validators.strlen.validator = "StringLength"
  12. user.login.elements.username.options.validators.strlen.options.min = "6"
  13. user.login.elements.username.options.validators.strlen.options.max = "20"
  14. user.login.elements.username.options.required = true
  15. user.login.elements.username.options.filters.lower.filter = "StringToLower"
  16.  
  17. ; элемент password
  18. user.login.elements.password.type = "password"
  19. user.login.elements.password.options.validators.strlen.validator = "StringLength"
  20. user.login.elements.password.options.validators.strlen.options.min = "6"
  21. user.login.elements.password.options.required = true
  22.  
  23. ; элемент кнопки
  24. user.login.elements.submit.type = "submit"

Вы можете потом передать это конструктору формы:

  1. span style="color: #ff0000;">'development'

... и вся форма будет определена.

Заключение

Надеемся, что благодаря этому небольшому обучающему руководству вы смогли получить представление о мощи и гибкости Zend_Form. Для получения более подробной информации читайте раздел далее.


Zend_Form