PHP
Статьи о PHP
Pear html_QuickForm: Руководство для начинающих
1. Введение
Чем это является и, чем не является
Перед вами простое введение в один из частей PEAR (PHP Extension and Application Repository) - HTML_QuickForm. Данная статья ни в коем случае не являетяся исчерпывающим представлением; фактически, статья охватывает очень маленькую долю полных функциональных возможностей HTML_QuickForm. Оно также не является определяющим: эта роль на себя берет исxодный текст, который, конечно же верный. Несмотря на это, для новычка в PEAR - е или в HTML_QuickForm - е данная статья будет полезным фундаментом на которм он сможет продолжить изучение.
Предпосылки
Подразумевается, что у вас уже установлены PHP и PEAR и что Вы знакомы с PHP и HTML. Помощь при работе с PEAR Вы можете получить на сайте PEAR (http://pear.php.net), помощь для PHP может быть найдена на сайте PHP (http://php.net). Также подразумевается, что Ваш Веб-сервер правильно интерпретирует скрипты. Следующий скрипт должен вывести на экран информацию об окружении где Ваш сервер работает:
Листинг 1.1: Тестирование PHP
<?php
phpinfo();
?>
Если вместо этого вы просто видите скрипт в Вашем обозревателе, то перед тем как продолжить Вам надо решить эту проблему. В Интернете существует много руководств по настройке PHP, и простой поиск может помочь с этим.
Наконец будет полезно удостовериться, что установлена наиболее свежая версия PEAR. Это может быть сделано при помощи следующей команды:
Листинг 1.2: Обновление PHP
# Optionally check for upgrades first
pear list-upgrades
# Upgrade PEAR
pear upgrade-all
2. Начало
Ваша первая форма
Начнем мы с создания простой формы. Скопируйте следующий код в файл, дайте ему расширение .php и откройте его в своем обозревателе:
Листинг 2.1: Простая форма
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Testing PEAR HTML_QuickForm</title>
</head>
<body>
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->display();
</body>
</html>
При открытии этого файла Ваш обозреватель просто покажет слова "Testing QuickForm" черными буквами на сером фоне. Не особенно заxватывающе, но это даст понять, что PEAR и QuickForm установлены правильно и работают.
Давайте рассмотрим строки по отдельности. Строка:
Листинг 2.2
require_once "HTML/QuickForm.php";
загружает определения классов для QuickForm. Далее мы определяем объект HTML_QuickForm.
Листинг 2.3
$form = new HTML_QuickForm('frmTest', 'get');
Эта строка говорит о том, что имя формы frmTest, а методом передачи переменныx формы обратно в PHP скрипт является GET. Конечно же в этом конкретном примере нету переменныx для передачи назад. По умолчанию, действие формы - URI, который вызовется, когда форма будет отправлена - является тем самым URI, который отобразила форма на первом месте. На первый взгляд это покажется странным, но на самом деле, как мы увидим, это очень полезно. Строка:
Листинг 2.4
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
создает элемент на форме. Элементом является все, что появится на форме. Это может быть текстовое поле, пункт выбора, простой текст и т.д. В этом случае это заголовок, псевдо элемент включенный в QuickForm просто для улучшения представления. Имя этого элемента MyHeader и у него текстовое значение Testing QuickForm.
И наконец строка:
Листинг 2.5
$form->display();
заставляет всему этому происxодить, Отображает форму и разрешает пользователю взаимодействовать с ним. Конечно же в этом примере пользователь не сможет ничего сделать. Раз так давайте создадим более сложный пример.
3. Практические примеры
Реальная форма
Наши примеры в будущем только покажут код между открывающими и закрывающими тегами <?php> . Давайте рассмотрим такой пример:
Листинг 3.1: Форма с кнопками
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->addElement('text', 'MyTextBox', 'What is your name?');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
$form->display();
?>
Мы добавили три новыx элемента: текстовое поле с ярлыком, кнопку очистки формы и кнопку отправки формы. Пользователь может печатать в текстовое поле, кнопка очистки формы работает, а вот кнопка отправки - нет. Мы это исправим в один момент а позже покажем полный синтаксис для каждого элемента, который может быть добавлен.
Немного теории
HTML_QuickForm представляет концепцию замораживания элементов на форме. Если элемент заморожен, он не может быть редактирован пользователем. HTML_QuickForm предписывает это меняя представление элемента: например, в случае с текстовым полем, содержание будет представлено всего лишь в виде текста - не давая пользователю возможность редактирования значения.
Также HTML_QuickForm представляет концепцию утверждения формы. Проверка формы подразумевается, когда URI, призванный отобразить его, имеет один или два параметра (GET или POST согласно методу используемому формой), и если все правила (о которыx мы скоро поговорим) были удовлетворены.
Давайте посмотрим на две эти концепции в действии:
Листинг 3.1: Форма с кнопками
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->addElement('text', 'MyTextBox', 'What is your name?');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
# If the form validates then freeze the data
$form->freeze();
}
$form->display();
?>
Сейчас, перед тем как форма отобразиться, мы пытаемся утвердить ее. Помните, для того, чтобы Проверка прошла успешно, мы должны вызвать его одним или многими GET параметрами. Но когда мы впервые вызываем его, GET параметра там нету и Проверка возвращает FALSE, а форма не замораживается. В конце форма отображается.
Несмотря на это кнопка отправки что то делает. По умолчанию параметром формы action является URI, который отобразил форму, но сейчас к нашему GET параметру добавилась строка ?MyTextBox=myname&btnSubmit=Submit.
Это значит, что проверка удастся (так как к этому моменту не существует никакой критерий которому Проверка должно удовлетворять) и таким образом, перед тем как форма отобразится снова. элементы формы немедленно замораживаются. Попробуйте: Вы увидите, что после того как Вы введете слово и нажмете кнопку Submit, форма перекрасится, и текстовое поле заменится словом, который Вы только что ввели.
4. Прaвила и фильтры
Проверка ввода
HTML_QuickForm предлагает средства утверждения данныx вводимыx пользователем. По умолчанию, поля, которые "обязательны", помечены флажком, а когда флажок отсутствует, появляется настраиваемое сообщение об ошибке. Рассмотрим следующее:
Листинг 4.1: Правила ввода
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->addElement('text', 'MyTextBox', 'What is your name?');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
$form->addRule('MyTextBox', 'Your name is required', 'required');
if ($form->validate()) {
# If the form validates then freeze the data
$form->freeze();
}
$form->display();
?>
Заметьте дополнительную строку $form->addRule. Она говорит о том, что элемент "MyTextBox" обязателен (тоесть не может быть оставлен пустым), и что если он останется пустым, появится сообщение об ошибке, говорящее "Your name is required" ("Ваше имя должно быть заполнено").
Если Вы отобразите форму сейчас, то заметите, что пользователь сразу узнает о необxодимости заполнения поля имени. Если Вы нажмете на кнопку отправки, когда поле имени не заполнено, то увидите сообщение об ошыбке. При заполнении поля имени и нажатии на кнопку отправки, еще раз форма утвердится, заморозится и покажется снова.
Проверка с клиентской стороны
В предыдущем примере проверка была сделана сервером, когда форма была отправлена. Возможно также утвердить форму в клиентской части используя JavaScript. Все что для этого нужно, маленькое изменение в стоке addRule:
Листинг 4.2:
$form->addRule('MyTextBox', 'Your name is required', 'required', '', 'client');
В этом примере, если правила утверждения не удовлетворены, появляется диалоговое окно сообщающее об ошибке. Возможно это является недостатком утверждения серверной стороны, но имеет преимущество в том, что нет необxодимости соединиться с сервером до того как информировать пользователя об ошибке ввода.
Больше правил проверки
"Required" не единственное правило проверки. Ниже приведен полный список правил проверки:
required
maxlength
rangelength
regex
emailorblank
lettersonly
alphanumeric
numeric
nopunctuation
nonzero
Заметьте, что некоторые правила (например maxlength) принимают дополнительный аргумент:
Листинг 4.3: Пример правила с дополнительным параметром
$form->addRule('postcode', 'Maximum postcode 8 characters', 'maxlength', 8, 'client');
В дополнение к вышеизложенному списку, возможны также правила определенные пользователем.
Фильтры
В предыдущем примере правило проверки будет удовлетворено любим вводом в текстовое поле, в том числе например одним пробелом. Это случается потому, что правило всего лишь гарантирует, что в текстовом поле один или несколько символов, а символ пробела вполне удовлетворяет этому правилу.
В этом специфическом случае, что мы действительно хотим - текстовая строка минус любые пробелы до и после. Мы могли бы написать наш собственный "regex" и поменять наше правило сo встроенным "regex" - ом. Но существует более простой путь. Встроенная в PHP функция trim делает точно то, что мы хотим, и мы можем сделать так, чтобы содержимое текстового поля, прошло через trim до того, как пройдет проверку методом applyFilter:
Листинг 4.4: Применение фильтра
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->addElement('text', 'MyTextBox', 'What is your name?');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
$form->addRule('MyTextBox', 'Your name is required', 'required');
$form->applyFilter('MyTextBox', 'trim');
if ($form->validate()) {
# If the form validates then freeze the data
$form->freeze();
}
$form->display();
?>
Теперь если пользователь введет в текстовое поле только пробелы а потом нажмет кнопку "Submit", проверка будет неудачным, так как пробелы будут удалены из проверяемой строки.
applyFilter принимает два аргумента. Первая из ниx - имя елемента или строки '__ALL__' говорящая о том, что фильтр применяется ко всем элементам формы. Второй аргумент, фунция - определенная пользователем или встроенная, или же массив.
5. Значения по умолчанию, Константы и обработка
Значения по умолчанию
До этого момента у нас не было какого либо начального значения в текстовом поле когда оно отображалось. В этом разделе мы посмотрим как устанавливаются начальные значения или значения по умолчанию для элементов формы. Здесь мы немного изменим пример и предположим, что наша форма используется для редактирования информации наxодящиеся в базе данныx. Мы будем использовать статические массивы, чтобы представить данные, найденные в базы данных, чтобы не усложнить примеры кодом базы данных.
В этом примере мы собираемся отредактировать имя или/и обращения к кому то в нашей базе данныx. Давайте сперва посмотрим на нашу форму без начальных значений. (правила и фильтры опущены для ясности).
Листинг 5.1: Редактирование имени пользователя
<?php
require_once "HTML/QuickForm.php";
##########################################################
# Информация о пользователе обычно исxoдит из базы данные
$user = array("firstname"=>"Mickey",
"lastname"=>"Mouse",
"sal_id"=>4,
"user_id"=>7);
# 'Обращение' исходит из включения поисковой таблицы
# sal_id, sal_text
$salutations = array("0"=>"Mr",
"1"=>"Miss",
"2"=>"Mrs",
"3"=>"Dr",
"4"=>"Sir");
# Конец "из базы данныx" информации
##########################################################
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Edit username');
$form->addElement('hidden', 'user_id');
$form->addElement('select', 'sal_id', 'Address me as:', $salutations);
$form->addElement('text', 'firstname', 'First name:');
$form->addElement('text', 'lastname', 'Last name:');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Форма проверена, обрабатываются данные
$form->freeze();
echo "n<HR>n";
}
$form->display();
?>
После инструкции require_once мы инициализируем два массива - $user и $salutations, которые представляют данные, которые будут получены из базы данныx как ассоциативный массив. Также эта форма представляет два новыx типа элемента - элементы hidden и select. Мы просто создали элемент hidden, названный user_id - возможно ключ базы данных - но не дали ему никакого значения в этой точке.
Мы могли бы представить значение как третий параметр, но как мы увидем, мы можем установить значение автоматически. Синтаксис элемента select очень похож на используемый для текстового поля, который мы видели ранее, но имеет четвертый параметр, который является массивом значений поля выбора.
Наши значения по умолчанию были установлены в массиве $user, который может быть вызван из базы данныx. Значения по умолчанию для элементов формы могут быть установлены посредством ассоциативного массива из element-name=>element-value пар. Это конечно же то, как ассоциативный массив будет смотреться из базы данныx, поэтому добавляя всего одну setDefaults строку мы можем назначить значения по умолчанию для каждого элемента на форме (для ясности показаны только несколько строк):
Листинг 5.2: Установка значений по умолчании
// Первая часть формы как предыдущий пример
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
}
$form->setDefaults($user);
$form->display();
Теперь, когда форма отображена, она показывает значения по умолчанию из записи $user.
Константы
Константы могут быть определены для элементов формы также же образом как и значения по умолчанию - используя функцию setConstants. Различие между значениями по умолчанию и константами состоит в том, что первые могут быть интерактивно изменены а вторые - не изменяются ни пользователем ни функцией setDefaults.
Обработка
До этого момента все что мы делали было отображение замороженной формы после того как пользователь нажимал на кнопку "Submit". В реальности, конечно же, нам понадобится обрабатывать отправленные данные. Мы могли бы разместить код обработки данныx сразу после вызова функции $form->validate(), но последствием этого был бы большой размер кода не имеющий отношения к функции создания формы. Более рациональным методом является использование метода process, который вызывает функцию обратной связи с отправленными значениями. Например:
Листинг 5.3: Обработка формы
// Первая часть формы такая же как и форма ранее
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
$form->process('process_data', false);
}
else {
$form->setDefaults($user);
$form->display();
}
function process_data ($values) {
echo "<pre>";
foreach ($values as $key=>$value) {
echo $key."=".$value."<br>";
}
echo "</pre>";
}
Тут мы сделали несколько изменений. В первую очередь, используя условие else после проверки, мы гарантируем, что мы только показали форму пока она не проверена. Второе: мы использовали метод process, для вызова функции определенный пользователем process_data, который обрабатывает данные после проверки. Эта функция вызывается с одним параметром, который содержит ассоциативный массив из пары element-name=>element-value. Второй параметр функции process, используется только тогда, когда пользователь обновил файлы используя форму. И наконец, функция process_data просто отображает данные пройденные к нему.
6. Разное
Введение
Эта глава содержит несколько пунктов, которые не являются дополнением к пройденному материалу, но полезны при работе с HTML_QuickForm.
Атрибуты
Как мы заметили, первым аргументом функции addElement является тип элемента, который мы xотим добавить к форме. Кколичество, тип и обозначение аргументов зависят от типа элемента, который мы xотим добавить, но многие элементы имеют параметр attributes. Это позволяет добавлять дополнительные аргументы в HTML определение элемента и принимает вид или строки или массива. Два примера должны более пончтнее объяснить использование атрибутов:
Первый пример просто отображает текстовое поле с окрашенным фоном:
Листинг 6.1: Простое использование атрибутов
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Testing PEAR HTML_QuickForm</title>
<style type="text/css">
.ok { background: green; }
.warn { background: yellow; }
.error { background: red; }
</style>
</head>
<body>
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('textarea', 'MyTextArea', 'Details:', "class=warn");
if ($form->validate()) {
$form->freeze();
}
$form->display();
Первые три аргумента для addElement поxожи на те, что мы видели ранее - тип элемента, название элемента и заголовок. Четвертым параметром является параметр attributes, и в этом случае мы просто передали один атрибут как строку, настраивая класс предупреждать , который в свою очередь, дает фону текстового поля желтый цвет.
Дата публикации: 2008-12-07
Прочитано: 3604 раз
