QuickForm2 Tutorial
Вернуться к: HTML_QuickForm2
QuickForm2 Tutorial
The purpose of this tutorial is to give users unfamiliar with HTML_QuickForm2 a basic understanding of package features. It describes the most common functionality and points to the parts of documentation that describe the package features in more depth.
If you are already familiar with PHP4 version of HTML_QuickForm, you can go directly to migration guide which contains step-by-step instructions for porting your scripts to HTML_QuickForm2.
Your first QuickForm2-based form
Builds and processes a form with a single input field
<?php
// Load the main class
require_once 'HTML/QuickForm2.php';
// Instantiate the HTML_QuickForm2 object
$form = new HTML_QuickForm2('tutorial');
// Set defaults for the form elements
$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
'name' => 'Joe User'
)));
// Add some elements to the form
$fieldset = $form->addElement('fieldset')->setLabel('QuickForm2 tutorial example');
$name = $fieldset->addElement('text', 'name', array('size' => 50, 'maxlength' => 255))
->setLabel('Enter your name:');
$fieldset->addElement('submit', null, array('value' => 'Send!'));
// Define filters and validation rules
$name->addFilter('trim');
$name->addRule('required', 'Please enter your name');
// Try to validate a form
if ($form->validate()) {
echo '<h1>Hello, ' . htmlspecialchars($name->getValue()) . '!</h1>';
exit;
}
// Output the form
echo $form;
?> Lets review the above example step by step.
Building the form
The line
<?php
$form = new HTML_QuickForm2('tutorial');
?> creates an instance of HTML_QuickForm2 that will contain objects representing form elements and other necessary information. We only pass the form's id to the constructor, which means that default values will be used for other parameters. In particular, the form's method will default to POST and the form's action to the current file. When using QuickForm2, it is easier to keep all the form related logic in one file.
Next we add a DataSource
<?php
$form->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
'name' => 'Joe User'
)));
?> containing the default value 'Joe User' for name element. DataSources are objects that provide elements' incoming values, they are searched in the order they were added to the form. When constructor of HTML_QuickForm2 considers the form submitted, it will automatically add a DataSource with submit values, so search will not reach the DataSource added above. However, when submit DataSource is not there, default value will be taken from the above DataSource.
To improve the presentation, we are adding a fieldset element to the form first:
<?php
$fieldset = $form->addElement('fieldset')->setLabel('QuickForm2 tutorial example');
?> and set its label (it will be output as <legend>, actually).
We then add a text input box and a submit button to the fieldset:
<?php
$name = $fieldset->addElement('text', 'name', array('size' => 50, 'maxlength' => 255))
->setLabel('Enter your name:');
$fieldset->addElement('submit', null, array('value' => 'Send!'));
?> Note that most of the setter methods are returning $this, so it is possible to chain method calls. Note also that we can arbitrarily nest fieldsets and other containers (you can't nest another HTML_QuickForm2 instance, however).
Checking input
The line
<?php
$name->addFilter('trim');
?> adds a filter for the element's value - the function that will be applied to it when getValue() is called. In this case it is a builtin trim() function, but can be any valid callback. Thus we will strip all leading and trailing whitespace from the name, as we do not need it and as we want to be sure that a name was entered, not just some spaces.
Next we define a rule for the field:
<?php
$name->addRule('required', 'Please enter your name');
?> This means that QuickForm2 will display an error message if the name was not entered. Note also that QuickForm2 will automatically mark required fields in the form.
Validating and processing
We now have the form built and rules defined and need to decide whether to process it or display:
<?php
if ($form->validate()) {
// Do some stuff
}
?> HTML_QuickForm2::validate() method will consider the form valid (i.e. return TRUE) if some data was actually submitted and all the rules defined for the form were satisfied. In our case this means that 'name' element was not left empty.
If the form is validated we need to process the values
<?php
echo '<h1>Hello, ' . htmlspecialchars($name->getValue()) . '!</h1>';
exit;
?> This is an example, in your scripts you'll usually want to store the values somewhere and to redirect to some other page to prevent a duplicate submit.
The last line is pretty easy:
<?php
echo $form;
?> If the form is not valid, which means that it either was not yet submitted or that there were errors, it will be displayed. Error messages (if any) will be displayed near the corresponding elements.
Further usage examples
More complex usage examples are installed with the package, they show built-in elements, rules, means to customize form output. Examples are installed to directory HTML_QuickForm2/examples under PEAR's doc_dir. If you have trouble finding where doc_dir is, you can use config-show command of PEAR installer.
Вернуться к: HTML_QuickForm2