Using HTML Quickform for Form Processing - Steps for the Example
(Page 2 of 13 )
The first step when using HTML_QuickForm is to load the code that defines the module with require or include. HTML_QuickForm is installed under your PEAR base directory at HTML/QuickForm.php.
Next, you create a new HTML_QuickForm object. The HTML_Quickform() constructor takes one argument: the name of the form. This string is used as the value for the name and id attributes of the <form> tag in the page.
The addElement() method adds a new element to the form. The order in which you add elements is the order in which they are displayed. The first argument to addElement() is the type of element you want to add. Valid element types for HTML_QuickForm are mostly the same as the valid values for type attribute of an HTML <input> tag: hidden, reset, checkbox, file, image, password, radio, button, submit, and text. Also valid are select and textarea, which correspond to the HTML <select> and <textarea> tags. HTML_QuickForm also has a few special element types of its own: hiddenselect, link, advcheckbox, date, static, header, and html. The next section covers all of these element types. This example form just uses three: text, select, and submit.
The second argument to each addElement() call is the name of the form element. This string is used as the value for the name attribute of the HTML tag for the element. The third argument to addElement() is a label for the form element. Each element’s label is displayed next to the element. The call to addElement() that adds a select element to the form has a fourth argument: an array of choices to display as <option> tags within the select box. These lines add the title text box to the form:
// Add a text box
$form->addElement('text','title','Book Title:');
These lines add the subject <select> menu, with three choices, to the form:
// Add a select box
$subjects = array('Math','Ice Fishing','Anatomy');
$form->addElement('select','subject','Subject(s): ',$subjects);
After the elements are added to the form, you call addRule() to add a validation rule. HTML_QuickForm includes many common validation rules, and you can write your own as well. The first argument to addRule() is the element to which the rule applies. The second argument is the error text to display when the rule is broken, and the third argument is the name of the rule. The required rule used in this example ensures that something is entered in the title text box.
Once all of the elements and rules are defined, you can display or process the form as necessary. This example first calls the form’s validate() method. This returns true if form data has been submitted, and it passes all the rules defined by addRule(). It returns false if the submitted data fail one or more of the rules or if no data was submitted. If validate() succeeds, the process() method runs the specified form-processing callback function. If validate() fails, the display() method displays the form. The first time the page is loaded, the form is displayed because validate() fails when no form data is submitted. On subsequent submissions of the form, it is only redisplayed if the submitted data fails at least one rule. The process() method calls the praise_book() function and passes it one argument: an array of the submitted form data. The keys in this array correspond to the names of the form elements. The praise_book() function uses this array to display a message about the submitted book.
The display() method lays out the form elements and their labels in a table. The HTML source code of the example form looks like this:
<table border="0">
<form action="qf-intro-example.php" method="post" name="book" id="book">
<tr>
<td align="right" valign="top"><font color="red">*</font><b>Book
Title:</b></td>
<td valign="top" align="left"><input name="title" type="text" /></td>
</tr>
<tr>
<td align="right" valign="top"><b>Subject(s): </b></td>
<td valign="top" align="left"><select name="subject">
<option value="0">Math</option>
<option value="1">Ice Fishing</option>
<option value="2">Anatomy</option>
</select></td>
</tr>
<tr>
<td align="right" valign="top"><b></b></td>
<td valign="top" align="left">
<input name="save" value="Save Book" type="submit" />
</td>
</tr>
<tr>
<td></td>
<td align="left" valign="top"><font size="1" color="#FF0000">*</font>
<font size="1"> denotes required field</font>
</td>
</tr>
</form>
</table>
By default, HTML_QuickForm uses the POST method and sets the action of the form to the value of $_SERVER['PHP_SELF']. You can override these settings by passing arguments to the HTML_QuickForm constructor. Remember that the first argument to the constructor is the form name. The second argument is the method to use. To create a form that uses the GET method, pass GET:
$form = new HTML_QuickForm('myform','GET');
The third argument to the constructor is an alternate URL to use as the form action:
$form = new HTML_QuickForm('myform','POST','/store/purchase.php');
To give the form a target attribute, which submits the form to a named frame or window, pass the frame or window name as a fourth argument to the constructor:
$form = new HTML_QuickForm('myform','POST','/store/purchase.php','shopframe');
If you want default values for the method and action URL, you can pass empty strings for those arguments:
// use the default method (POST), but change the action URL
$form = new HTML_QuickForm('myform','','/store/purchase.php');
// submit the form to a new blank window, but use the default method and URL
$form = new HTML_QuickForm('myform','','','_blank');
To include arbitrary attribute/value pairs in the <form> tag, pass those as a fifth argument to the constructor. You can specify the attributes and values as a string:
$form = new HTML_QuickForm('myform','','','','class="big" style="bold"');
Or, you can specify the attributes as an array:
$form = new HTML_QuickForm('myform','','','', array('class' => 'big', 'style' => 'bold'));
 This chapter is from Essential PHP Tools: Modules, Extensions, and Accelerators, by David Sklar, (Apress, 2004, ISBN: 1590592808). Check it out at your favorite bookstore today.
Buy this book now. |
Next: Individual Elements >>
More Graphic Design Articles
More By Apress Publishing
/ 160 
