Информационный портал
«SoftTime-INFO»

• Наши книги
• Форум PHP
• Форум Apache
• Форум "Регулярные выражения"
• Форум MySQL
• Форум "HTML+CSS+JavaScript"
• Форум "Разное"
• Учебник PHP
• Работа с Apache
• Справочник PHP
• Статьи о PHP
• Дистрибутивы
• Гостевая книга
• Задачи на PHP
• Downloads (web-приложения)
• Примеры PHP скриптов
• Примеры Javascript
• Примеры Action Script
• Типовые документы
• Раздел C++

Формуляры на все случаи жизни

Источник: http://www.php-mag.de/itr/online_artikel/psecom,id,491,nodeid,62.html
Автор: Томас Витковски
Перевод с немецкого: Антон Федорченко (antf)

В настоящее время редкое веб-приложение обходится без форм. Наверное, каждый разработчик потратил много времени, вставляя повторяющиеся комбинации html-тегов. Написание функций проверки данных также занимает некоторое время. Как вам кажется, наверное, неплохо бы эту работу автоматизировать? Как раз для этого и был задуман HTML_QuickForm. В этой статье мы расскажем о том, как этот пакет поможет вам избавиться от рутинной работы и при это придаст вашим приложениям более профессиональный вид.

Формы — это один из краеугольных каменей любого веб-приложения. Они являются связующим звеном между пользователем и приложением (или базой данных). Часто программист имеет дело с одной и той же последовательностью действий: размещение формы на странице, заполнение формы пользовательскими данными, их проверка, и, наконец, дальнейшая обработка (например, сохранение данных в базе или генерация на их основе нового формуляра). В этой ситуации многие неоправданно усложняют себе жизнь, программируя заново бесконечное количество функций для каждой формы. Однако не стоит каждый раз изобретать колесо. QuickForm предлагает быстрое и удобное решение для выполнения почти всех рутинных операций, с которыми сталкивается программист. Этот класс, а точнее библиотека классов, содержит большое количество функций, пригодных не только для создания формы, но и для проверки и обработки пользовательских данных.

При написании этой статьи мы пользовались версией 3.2 Примеры кода должны функционировать во всех версиях 3.х. Для установки QuickForm можно воспользоваться командой pear install HTML_QuickForm. К тому же вам потребуется установить еще одни пакет - HTML_Common. Существует альтернативный способ установки: необходимо загрузить tgz-архив с адреса pear.php.net/package/HTML_QuickForm и выполнить команду pear install HTML_QuickForm-3.2.tgz. На этой странице вы так же сможете найти подробный справочник по классам и функциям QuickForm.

Первый шаг

Для того, чтобы продемонстрировать основные функции QuickForm, создадим маленькую форму-пример, с помощью которой пользователь может подписаться на одну или несколько новостных лент. Для этого он должен указать полное имя, дату рождения и e-mail. К тому же мы хотим узнать хобби, которым занимается посетитель на досуге, а так же информацию о новостных лентах, на которые он хотел бы подписаться. Полный вариант кода формы, вы можете найти в листинге 1.

Рисунок 1. (Первая форма)

Для генерации нового формуляра нам прежде всего необходим объект класса HTML_QuickForm. Вот как мы его создаем:

<?php
  require_once('HTML/QuickForm.php');
  $form = new HTML_QuickForm('mainForm', 'post');
?>

В качестве первого параметра конструктор принимает имя формы, которое помещается в html-тег form. В качестве следующего параметра мы должны указать каким способом (POST или GET) пользовательские данные будут обратно возвращены в скрипт. В качестве третьего параметра можно указать url-адрес, куда будут посылаться данные. Обычно этот параметр оставляют пустым, поскольку данные возвращаются в тот же самый скрипт, где была сгенерирована форма. Все выгоды подобного подхода мы увидим ниже. А теперь добавим пару элементов на нашу форму. Для этого воспользуемся функцией addElement().

<?php
  $form->addElement('header', 'myHeader', 'Подписаться');
  $form->addElement('text', 'firstName', 'Имя:');
  $form->addElement('checkbox', 'inMailList', 'Подписаться на рассылку:');
?>

Она принимает, как минимум, три параметра: тип элемента, его имя (идентификатор), строку символов (метку), которая показывается рядом с элементом. В качестве типа может быть указан любой известный элемент html-формы. В этом примере мы используем элементы text (строка ввода) и checkbox (флажок). Элемент header представляет собой псевдоэлемент QuickForm, предназначенный для создания заголовков, которые улучшают внешний вид формы и помогают группировать элементы.

В нашем примере мы так же хотим узнать дату рождения пользователя. Если бы мы пользовались только чистым html/php при создании соответствующего поля, нам пришлось бы потратить много времени и написать объемный кусок кода. Для решения этой задачи с помощью QuickForm мы можем воспользоваться элементом date, который автоматически преобразовывается в три поля select, предназначенных для выбора дня, месяца и года. В этом случае функции addElement() нужно передать ассоциативный массив в качестве четвертого параметра:

<?php
  $form->addElement('date', 'birthday', 'Дата рождения:', array('format'=>'d-F-Y', 'language'=>'ru', 'minYear'=>1900, 'maxYear'=>2000));
?>

Как видите, наряду с форматом даты и языком, мы указываем временной интервал для года. Язык необходим для поля выбора месяца, где перечисляются названия месяцев в полной или краткой форме. Формат даты QuickForm совместим с форматом php-функции date(). Подробную информацию о ней смотрите в мануале php.

Перед тем, как разместить формуляр на странице, присвоим некоторым элементам стандартные значения. На практике их источником часто является база данных или конфигурационный файл. в QuickForm применяется другой принцип. Для присвоения стандартных значений элементам необходимо создать ассоциативный массив в форме: ElementName => Value. Массив передается функции setDefaults(). Таким же образом можно присвоить элементам константные значения. В этом случае массив должен передаваться функции setConstants(). Константные значения отличаются о стандартных тем, что они не могут изменяться в ходе дальнейшего выполнения скрипта. Обратите внимание на то, что подобное значение является константным только в теле php-скрипта. Поскольку поле формы отображается на странице, пользователь может изменить его значение.

Создаем новые элементы

Класс HTML_QuickForm управляет всеми элементами формы. Отдельный же элемент является объектом класса HTML_QuickForm_Element. Если возникает потребность в изменении параметров уже созданного элемента формы, прежде всего необходимо получить ссылку на него с помощью getElement(). В нашем примере мы изменяем внешний вид элемента select.

<?php
  $select = &$form->getElement('newsletter');
  $select->setSize(4);
  $select->setMultiple(true);
?>

До этого момента мы исходили из того, что каждый элемент существует сам по себе. Однако часто требуется объединить несколько элементов в логический ряд. Чаще всего в группы объединяются элементы checkbox и radio-кнопки. Для того, чтобы объединить отдельные элементы в группы, прежде всего мы должны создать ассоциативный массив, содержащий элементы, входящие в данную группу. С этой целью мы воспользуемся функцией createElement().

<?php
  $checkbox = array();
  $checkbox[] = HTML_QuickForm::createElement('checkbox', 'garden', null, 'Gartenarbeit');
  ...
  $form->addGroup($checkbox, 'hobby', 'Ihre Hobbys:', '');
?>

В данном примере, при создании нового элемента checkbox, мы передаем конструктору четвертый параметр. Речь идет о тексте, отображаемом рядом с флажком. Впрочем, не стоит удивляться, что количество и характер параметров конструктора различны для каждого элемента формы. Функции addElement() и createElement() принимают только один основной параметр - тип элемента, в зависимости от него выбирается соответствующий класс (каждый элемент представляет собой отдельный класс, производный от HTML_QuickForm_Element), в конструктор которого и передаются остальные параметры.

Обработка данных

Теперь мы подошли к тому моменту, когда у нас уже есть простой экземпляр готовой формы, куда пользователь может вводить данные. При нажатии на кнопку ОК, данные посылаются обратно в скрипт. Но как же мы получим к ним доступ? Посмотрите на последние строчки кода из листинга 1:

<?php
  if ($form->validate()) {
    $form->process('process_data', false);
  } else {
    $form->display();
  }
?>

Форма, созданная с помощью с помощью QuickForm, имеет два состояния: либо она еще не отображена, либо пользовательские данные заполненной формы посылаются в скрипт на обработку. Во втором случае необходимо дополнительно различать: прошли ли данные проверку или нет. Функция validate() позволяет узнать состояние, в котором находится форма. Если она отображается впервые, функция возвращает false, а форма может быть прорисована в браузере при помощи display(). Функция возвратит то же значение (false), если данные формы уже были посланы в скрипт-обработчик, но не прошли проверку. В этом случае пользователь снова должен ввести некоторые данные, поэтому форма, дополненная сообщениями об ошибках, должна отобразиться еще раз. Только в том случае, если проверка пользовательских данных прошла успешно, функция validate() возвратит true. Затем данные могут пройти дальнейшую обработку внутри скрипта. Мы написали особую функцию process_data(), которая выводит последовательно все пользовательские данные в браузер. Теперь вы можете немного попрактиковаться.

Фильтры и правила проверки данных

Часто веб-приложение сохраняет данные в базе, причем они могут не только не соответствовать действительности, но и создавать угрозу безопасности веб-приложения. Quick-Form снабжает нас мощным инструментом контроля данных. Пакет содержит встроенные фильтры и правила проверки данных. Их функциональность мы можем как угодно изменять. Фильтры представляют собой набор определенных инструкций, предназначенных для коррекции данных, а правила служат для проверки данных на соответствие определенному условию. Самый распространенный пример применения фильтра — удаление лишних пробелов с помощью функции trim(). Вернемся к предыдущему листингу: допустим, мы хотим сохранить в базе данных имя пользователя и при этом удалить ведущие и конечные пробелы. Для этого мы создадим оператор: $form->applyFilter('firstName', 'trim'); Имя конкретного элемента можно заменить на '__ALL__' . В этом случае указанный фильтр будет применен ко всем элементам формы. В качестве фильтра может быть применена любая php-функция, которая принимает строку в качестве единственного параметра и возвращает строковое значение. Приведем пример кода из листинга 2, который дополняет наш первый пример:

<?php
  $form->addRule('firstName', 'Укажите, пожалуйста, ваше имя:', 'required');
  $form->addRule('surname', 'Фамилия должна состоять как минимум из пяти букв:', 'minlength', 5);
?>

Таким образом, к нашей форме было добавлено два правила. Первое служит для проверки, ввел ли пользователь свое имя при подписке на новости. Второе следит за тем, чтобы фамилия пользователя, если только она указана, содержала не более пяти символов. За каждым элементом может быть закреплено сколько угодно правил проверки данных. Наряду с именем элемента, функция AddRule() требует указать сообщение об ошибке, которое появится рядом с элементом в случае, если данные не прошли проверку. В качестве третьего параметра необходимо указать правило, на соответствие которому будут проверяться данные. Таблица 1 содержит некоторые из них:

QuickFrom не ограничивает ваши возможности только встроенными правилами. Любая php-функция, которая принимает в качестве параметра строку и возвращает булевское значение может быть использована при проверке данных. Правда, такую функцию нужно зарегистрировать при помощи registerRule(). Мы дополнили второй пример функцией checkMailInDatabase(), которая должна проверить существует ли введенный пользователем e-mail в базе данных. Если адрес существует, выдается соответствующее сообщение об ошибке, уведомляя пользователя, что под таким адресом регистрироваться уже нельзя.

До сих пор мы проверяли данные на сервере. Однако иногда бывает полезно провести проверку прямо в браузере при помощи JavaScript. Чтобы правило применялось на клиентской стороне, необходимо передать функции AddRule() строку “client” в качестве четвертого параметра (“server” - значение по умолчанию). В этом случае данные будут проверятся при нажатии на кнопку Submit. Если данные поля формы не соответствуют правилу, появится сообщение об ошибке. Однако не стоит полагаться на то, что JavaScript включен в браузере клиента. Для более надежной проверки данных необходимо либо отказаться от проверки в браузере, либо создавать два однотипных правила: одно будет контролировать данные на стороне сервера, другое — на стороне клиента.

Если вы используете правила и фильтры одновременно, имейте в виду, что сначала QuickForm применяет фильтры и только потом правила.

Создаем индивидуальный дизайн

Наша форма выглядит достаточно солидно, на некоторые недочеты, мы, конечно же, можем посмотреть сквозь пальцы. Однако и в этой области QuickForm показывает свою гибкость. Сначала изменим текст, которые напоминает пользователю о наличии обязательных полей (* обязательные поля). С помощью функции setRequiredNote() мы можем добавить любой текст, который заменит английский вариант надписи. Сам по себе QuickForm не отвечает за прорисовку формы, эту задачу он передает рендереру, который представляет собой объект класса HTML_QuickForm_Renderer_Default. Ссылку на него мы можем получить с помощью функции defaultRenderer(). Таким образом можно изменить внешний вид не только всей формы, но и отдельных ее элементов. Для прорисовки формы рендерер нуждается в несложных шаблонах, которые могут быть инициализированы функциями setFormTemplate(), setHeaderTemplate(), setElementTemplate(). Займемся сначала общим видом формы. QuickForm заключает ее содержимое в таблицу, поэтому шаблон формы должен иметь вид:

  <table><form {attributes}>{content}</form></table>

Обе подстановки {attributes} и {content} распознаются рендерером и заменяются соответствующим содержимым. В третьем примере (листинг 3) мы изменяем по-нашему желанию дизайн формы подписки на новости. Форма располагается по центру, а таблице присвоен CSS-класс. А вот как выглядит шаблон для заголовка:

  <tr><td>{header}</td></tr>

Теперь займемся внешним видом элементов. В этом случае шаблон усложняется:

  <tr>
    <td>
      <!-- BEGIN required --><b>*</b><!-- END required -->
      {label}
    </td>
    <td>
      <!-- BEGIN error -->{error}<!-- END error -->
      {element}
    </td>
  </tr>

Три подстановки {label}, {error}, {element} заменяются на соответствующие фрагменты html-кода, формирующие сам элемент, его описание и сообщение об ошибке. В дополнение к этому вы найдете два комментария html, которые безусловно необходимы. Комментарий required обрамляет код, который выводится рядом с обязательным элементом (обычно это звездочка), error отмечает сообщение об ошибке, которое высвечивается в случае неудачной проверки данных. Иллюстрация два показывает форму с измененным дизайном:

Иллюстрация 2. (Старый формуляр с новым дизайном)

Загрузка файлов на сервер

Давайте перейдем к другой теме и займемся загрузкой файлов на сервер. Для решения этой часто встречающейся проблемы QuickForm содержит очень быстрое и изящное решение - элемент file. О том, как можно без особых трудностей реализовать функцию загрузки файлов на сервер, нам расскажет фрагмент кода, взятый из листинга 4:

<?php
  require_once('HTML/QuickForm.php');
  $form = new HTML_QuickForm('mainForm', 'post');
  $file =& $form->addElement('file', 'myFile', 'Файл:');
  $form->addElement('submit', 'submit', 'OK');
  if ($form->validate()) 
  {
    if ($file->isUploadedFile()) 
    {
      $file->moveUploadedFile('/tmp');
      $fileInfo = $file->getValue();
      print_r($fileInfo);
    }
  }  else 
  {
    $form->display();
  }
?>

Элемент file, на объект которого мы получаем ссылку, отвечает прежде всего за отображение поля выбора файла с кнопкой «обзор». При нажатии на кнопку появляется классическое диалоговое окно Windows с предложением выбрать файл. Если пользователь заполнил формуляр, первое условие выполнится. Функция isUploadedFile() следит за тем, чтобы во-первых файл был выбран пользователем, и во-вторых за тем, чтобы файл был успешно загружен на сервер. А теперь мы можем, с помощью moveUploadedFile(), переместить загруженный файл в нужный каталог и переименовать его, указав новое имя в качестве второго параметра. С помощью функции getValue() мы можем узнать некоторые характеристики файла, например, оригинальное имя и размер.

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

• uploadedfile: пользователь должен выбрать файл, а файл должен успешно загрузиться на сервер
• maxfilesize: размер файла (в байтах) не должен превышать указанную величину
• mimitype: файл должен соответствовать определенному типу mime
• filename: проверка имени файла на соответствие регулярному выражению.

Заключение

HTML_QuickForm предлагает несколько классов, которые программист должен иметь под рукой, создавая форму. Так вы сэкономите много времени и нервов. К сожалению, рамки данной статьи не позволяют рассмотреть все возможности этого мощного пакета. Тем, кто собирается интенсивно использовать QuickForm, можно посоветовать обратить внимание на возможность привязки пакета к одной из известных систем обработки шаблонов. Впрочем всем, кто хотел бы углубиться в предмет, мы настоятельно рекомендуем посмотреть неплохую документацию по классам, доступную по адресу pear.php.net/manual/en/package.html.html-quickform.php.

Ссылки

PEAR основной пакет: http://pear.php.net/package/PEAR
HTML_QuickForm: http://pear.php.net/package/HTML_QuickForm
HTML_Common: http://pear.php.net/package/HTML_Common