3.10 Хелперы и формы

1. Основные хелперы

2. Создание собственных элементов форм

3. Валидация форм

4. Создание собственных валидаторов

Для генерации полей (элементов) формы в шаблоне используется механизм хелперов. Данное решение освобождает от необходимости заботиться о восстановлении значений формы, в случае неправильного её заполнения и о выделении ошибочно заполненных полей. Файлы с классами хелперов расположены в каталоге system/forms. Следует отметить, что хелперами генерируется валидный xhtml-код. Запускаются они из шаблона следующим образом:

{form->helper_name ...}

Хелперы могут принимать различные параметры, но есть и несколько общих:

• name - параметр, определяющий имя элемента формы
• value (content для textarea) - параметр, определяющий значение для элемента формы
• freeze - параметр, определяющий, что поле будет заморожено, т.е. вместо активного элемента, с которым можно производить различные действия (отмечать щелчком, редактировать значение, выбирать значение из списка), будет обычная надпись

Также могут быть указаны любые параметры html-синтаксиса, используемые в тегах. Например: style, class, id. Примеры их использования:

{form->text style="form_text_field" id="some_field" name="login"}

К использованию доступны следующие хелперы:

• caption - используется для вывода названия поля формы. С помощью параметра name указывается, к какому из полей формы относится этот заголовок.

  {form->caption name="title" value="Название" onError='<span style="color: red;">%s</span>' onRequired='<span style="color: red;">*</span> %s'}

  Этот хелпер, при отсутствии ошибок и при условии, что поле формы с именем title будет заполнено без ошибок, сгенерирует следующий код:

  Название

  В вышеприведённом коде перечислены все возможные аргументы, которые могут быть использованы в хелпере
  • onError - определяет отображение заголовка для поля в случае - если поле, к которому относится надпись, введено с ошибками.
    Сгенерированный хтмл:

    <span style="color: red;">Название</span>

    Отображение:
    Название
    Для остальных элементов, не caption, задается имя класса в случае ошибки.
  • onRequired - параметр, отвечающий за знак, выводимый перед заголовком поля и обозначающий, что данное поле является обязательным к заполнению. Значением по умолчанию для данного параметра является:
    

    <span style="color: red;">*</span> %s

    Для вышеприведённого кода, в случае, если поле формы title является обязательным к заполнению, сгенерированный хтмл будет:

    <span style="color: red;">*</span> Название

    Отображение:
    * Название
• checkbox - хелпер для вывода checkbox'ов. Типичный пример использования хелпера:

  {form->checkbox name="save" text="Запомнить" value="off" values="off|on"}

  По вызову данного кода будет сгенерирован следующй html:

  <input id="formElm_save_default" name="save" type="hidden" value="off" /><input id="formElm_save_on" name="save" type="checkbox" value="on" />&nbsp;<label for="formElm_save_on" style="cursor: pointer; cursor: hand;">Запомнить</label>

  В браузере пользователя это будет выглядеть следующим образом:
   Запомнить
  В качестве принимаемых параметров кроме вышеописанных name и value, checkbox также может принимать парметр text, который будет выводить текст, поясняющий назначение данного чекбокса. Этот параметр необязательный и параметр values, в котором перечислены значения, отправляемые на сервер при выключенном и включенном состоянии соответственно (значение по умолчанию: 0|1).
• file - хелпер, предоставлящий стандартное поле выбора файла. Пример использования:

  {form->file name="file"}

  Сгенерированный html:

  <input name="file" type="file" />

  Отображение:
• radio - хелпер для генерации элемента интерфейса "радио-кнопка" (radio-button). Пример использования:

  {form->radio name="field" text="sample radio button" value=10}

  Html:

  <input id="formElm_field_10" name="field" type="radio" value="10" />&nbsp;<label for="formElm_field_10" style="cursor: pointer; cursor: hand;">sample radio button</label>

  Отображение:
   sample radio button
• select - хелпер для генерации выпадающего списка. Пример использования: В пхп заранее сформируем массив с пунктами выпадающего списка:

  <?php
      ...
      $data = array(
          '1' => 'One',
          '2' => 'Two',
          '3' => 'Three'
      );
      $this->smarty->assign('data', $data);
      ...
  ?>

  А в шаблоне вызовем хелпер:

  {form->select name="sample_select" options=$data one_item_freeze=1 value="2" emptyFirst=1}

  То будет сгенерировано:

  <select id="formElm_sample_select" name="sample_select">
  <option value="">&nbsp;</option>
  <option value="1">One</option>
  <option selected="selected" style="font-weight: bold;" value="2">Two</option>
  <option value="3">Three</option>
  </select>

  Отображение:
    One Two Three

  Если был указан параметр multiple=true, то в конец имени элемента добавится "[]" при условии, что оно уже не кончается на [].

  Дополнительные параметры, которые может принимать данный хелпер:
  • emptyFirst - установленный в значение "1", данный параметр добавит к массиву пунктов списка первый пункт, с пустым значением. Значение по умолчанию: "0"
  • one_item_freeze - установленный в значение "1", данный параметр "заморозит" (т.е. превратит из списка в обычную надпись) список в случае, если имеется лишь 1 вариант для выбора. Значение по умолчанию: "0"
• textarea - хелпер для генерации текстареи

  {form->textarea content="содержимое текстареи" name="sample"}

  Html:

  <textarea cols="20" id="formElm_sample" name="sample" rows="5">содержимое текстареи</textarea>

  Этот хелпер используется аналогично text, с тем лишь отличием, что значение, которое будет показано в этом поле - записывается в параметр content.
• text - хелпер для отображение поля стандарнтного поля ввода.

  {form->text value="содержимое" name="sample"}

  Html:

  <input id="formElm_sample" name="sample" type="text" value="содержимое" />

• Остальные хелперы: password, image, hidden, submit, reset, используются аналогично хелперу text.

Mzz позволяет легко расширять список доступных хелперов форм. Все хелперы располагаются в каталоге forms. Создание элемента рассмотрим на примере элемента формы типа text.
Все элементы формы наследуются от класса formElement. Создадим файл с именем formAdvancedTextField.php в каталоге forms:

<?php
 
class formAdvancedTextField extends formElement
{
    public function __construct()
    {
        $this->setAttribute('type', 'text');
        $this->setAttribute('value', '');
    }
 
    public function render($attributes = array(), $value = null)
    {
        return $this->renderTag('input', $attributes);
    }
}
 
?>

Всё. Теперь в шаблонах можно использовать новый тип хелпера. Запуск его не будет отличаться от запуска базовых хелперов:

{form->advancedText name="new_helper" value="new helper value"}

В mzz генерация и валидация форм разделены. Стандартные правила валидации располагаются в каталоге system/forms/validators. Для валидации формы вначале нужно подключить класс валидатора форм и создать объект этого класса. Это делается так:

fileLoader::load('forms/validators/formValidator');
$validator = new formValidator();

Единственным аргументом для конструктора класса formValidator является имя поля, свидетельствующего о том, что форма отправлена. По умолчанию используется значение submit. Для добавления правила валидации формы используется следующий синтаксис:

$validator->add('имя валидатора', 'имя поля', 'сообщение об ошибке', 'дополнительные параметры');

В базовый набор валидаторов входят следующие:

• required - данный валидатор означает, что поле формы обязательно должно быть заполнено. Пример использования:

  $validator->add('required', 'title', 'Необходимо назвать новость');

• numeric - обязывает поле формы быть числовым.
• regex - валидатор, позволяющий в качестве критерия для валидации использовать регулярное выражение. При этом регулярное выражение передаётся в массиве дополнительных параметров. Пример:

  $validator->add('regex', 'name', 'Недопустимые символы в идентификаторе', '/^[a-zа-я0-9_\.\-! ]+$/i');

• uploaded - этот валидатор проверяет, что указанное поле - является полем типа file, а также что файл был загружен на сервер без ошибок.
• callback - валидатор, использующий для валидации callback-функцию. Имя этой функции, а также другие дополнительные аргументы передаются в массиве дополнительных параметров. В случае, если callback-функция возвращает значение true - считается, что валидация прошла успешно, поле заполнено без ошибок. Примеры использования этого валидатора:

  <?php
      $validator->add('callback', 'name', 'Введённое значение ошибочно', array('sample_callback', time(), mt_rand(1, 10)));
   
      function sample_callback($value, $time, $rand)
      {
          echo 'Введено значение: ' . $value . '<br />';
          echo 'Время и дата вызова: ' . date('H:i:s d.m.Y', $time) . '<br />';
          echo 'Случайное число в интервале от 1 до 10: ' . $rand;
          return true;
      }
  ?>

  <?php
      $validator->add('callback', 'email', 'Введён неправильный e-mail', array('is_valid_email')); 
   
      function is_valid_email($email)
      {
          return preg_match('/^[a-zA-Z0-9\._-]+\@(\[?)[a-zA-Z0-9\-\.]+\.([a-zA-Z]{2,4}|[0-9]{1,3})(\]?)$/', $email));
      }
  ?>

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

  Отправленное из формы значение всегда будет передаваться в callback-функцию и всегда будет идти первым аргументом.

Валидаторы, так же как и хелперы, также могут быть легко расширены новыми. Создаваемые правила должны быть отнаследованы от базового класса formAbstractRule. Как и в случае с callback-функциями, валидация считается пройденной, если валидатор возвращает true, и проваленной в противном случае. Рассмотрим процесс создания валидаторов на примере. Пусть это будет новый валидатор, который проверяет, что введённое число попадает в определёный диапазон.

Создадим файл formRangeRule.php в каталоге system/forms/validators:

<?php
 
class formRangeRule extends formAbstractRule
{
    public function validate()
    {
        // проверяем, что введённое значение больше либо равно минимального
        // и меньше либо равно максимального
        return $this->value >= $this->params[0] && $this->value <= $this->params[1];
    }
}
 
?>

Полученный валидатор можно использовать следующим образом:

<?php
 
$validator->add('range', 'hour', 'Введённое число не входит в интервал от 1 до 24', array(1, 24));
 
?>