QuickForm2 Tutorial
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.