View this page in	Last updated: Sun, 18 Oct 2009
English \| Brazilian Portuguese \| Chinese \| Dutch \| French \| German \| Hungarian \| Japanese \| Polish \| Russian \| Spanish \| Turkish

QuickStart

QuickStart – A tutorial for HTML_QuickForm

Introduction

The purpose of this tutorial is to give the new users of QuickForm an overview of its features and usage patterns. It describes a small subset of available functionality, but points to the parts of the documentation that give a more in-depth overview.

There also exists a somewhat bigger tutorial on QuickForm usage made by Keith Edmunds.

Your first form

Basic QuickForm usage


<?php
// Load the main class
require_once 'HTML/QuickForm.php';

// Instantiate the HTML_QuickForm object
$form = new HTML_QuickForm('firstForm');

// Set defaults for the form elements
$form->setDefaults(array(
    'name' => 'Joe User'
));

// Add some elements to the form
$form->addElement('header', null, 'QuickForm tutorial example');
$form->addElement('text', 'name', 'Enter your name:', array('size' => 50, 'maxlength' => 255));
$form->addElement('submit', null, 'Send');

// Define filters and validation rules
$form->applyFilter('name', 'trim');
$form->addRule('name', 'Please enter your name', 'required', null, 'client');

// Try to validate a form
if ($form->validate()) {
    echo '<h1>Hello, ' . htmlspecialchars($form->exportValue('name')) . '!</h1>';
    exit;
}

// Output the form
$form->display();
?>

Lets review this example step by step.

Building the form

The line


<?php
$form = new HTML_QuickForm('firstForm');
?>

creates a HTML_QuickForm object that will contain the objects representing elements and all the other necessary information. We only pass the form's name 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 QuickForm, it is easier to keep all the form related logic in one file.

You might guess that


<?php
$form->setDefaults(array(
    'name' => 'Joe User'
));
?>

sets the default value for name element to 'Joe User'. QuickForm has the concept of default values (set via setDefaults() method) and constant ones (set via setConstants()). The difference between them is that user's input overrides default values but not constant ones.

Our form will consist of three elements:


<?php
$form->addElement('header', null, 'QuickForm tutorial example');
$form->addElement('text', 'name', 'Enter your name:', array('size' => 50, 'maxlength' => 255));
$form->addElement('submit', null, 'Send');
?>

The first one is not the 'real' element, it is just a heading to improve presentation. The second one actually is a text input box and the third is a submit button. Note that parameters for addElement() method have different meanings for different elements. That is so because they are actually passed to these elements' constructors.

Checking input

The line


<?php
$form->applyFilter('name', 'trim');
?>

defines a filter for the 'name' element value - the function that will be applied to it after form submit. In this case it is a builtin trim() function, but can be any valid callback. Thus we will strip all whitespace from the name, as we do not actually 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 name field:


<?php
$form->addRule('name', 'Please enter your name', 'required', null, 'client');
?>

This means that QuickForm will display an error message if the name was not entered. The 'client' modifier is here to switch on client-side JavaScript validation in addition to server-side one. Note also that QuickForm 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
}
?>

The 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 empty.

If the form is validated we need to process the values


<?php
echo '<h1>Hello, ' . htmlspecialchars($form->exportValue('name')) . '!</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 process() and exportvalues() methods may be of interest here.

The last line is pretty easy:


<?php
$form->display();
?>

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.

Advanced features

You now should have an understanding of basic QuickForm functionality, but there are many more features in the package, each of them deserving a separate tutorial. This section will give a short overview of them and point you to the complete documentation.

Groups allow to combine several individual elements into one entity and to use it as one element. This is also used to create pseudo-elements like date and hierselect.

QuickForm offers a lot of possibilities to customize form layout and appearance. Form output is done via renderers - special classes containing necessary logic. There are renderers that directly output HTML and those that use template engines for this.

And finally, you can extend QuickForm by adding your own element types, rules and renderers.

Introduction (Previous) (Next) QuickHelp

Download Documentation	Last updated: Sun, 18 Oct 2009
Do you think that something on this page is wrong? Please file a bug report or add a note.
User Notes:
Note by: wiesemann 2007-07-20 16:01 UTC In reply to mlyons@course-source.net's note: You don't need to include select.php. You can simply create the select element like this: `<?php $conSelect =& HTML_QuickForm::createElement('select', ...); ?>` Note by: mlyons@course-source.net 2007-07-20 15:58 UTC Something that was less than obvious to me was how to set a select to a particular value based on what was submitted in the form. First you need to require the select.php code directly if you want to instantiate a select object outside of the form. Then you can use the setSelected method before adding the select control to the form. This example is for a form with a drop down for a DB connection: <?php require_once 'HTML/QuickForm.php'; require_once 'HTML/QuickForm/select.php'; $conName = $_REQUEST['conname']; // Instantiate the HTML_QuickForm object $form = new HTML_QuickForm('firstForm'); $fCons = array("dev"=>"Development", "beta"=>"Beta", "live"=>"Live"); // Add some elements to the form $form->addElement('header', null, 'QuickForm tutorial example'); // Create the select $conSelect = new HTML_QuickForm_select('conname', 'Database:', $fCons); // Set the selected value $conSelect->setSelected($conName); $form->addElement($conSelect); $form->addElement('submit', null, 'Send'); // Output the form $form->display(); ?>