QuickForm Help

PEAR HTML_QuickForm Getting Started Guide

Contents:

1. Introduction
2. Getting Started
3. Pratical Example
4. Rules and Filters
5. Default, Constant and Processing
6. Miscelaneous
7. References

A note from the author

I hope you find this guide, or tutorial, call it what you will, useful, and I also hope it saves you some time. If you do find it useful, I would be grateful if you could make a donation using the button below (and if it wasn't useful, mail me and tell me why not).

Thank you Keith Edmunds http://www.linuxbackup.co.uk/quickform/

Introduction

What this is and what it isn't

This page is a simple introduction to one part of PEAR, HTML_QuickForm. It is by no means exhaustive; in fact, it covers a very small fraction of the total functionality of HTML_QuickForm. It is also not definitive: that role is taken by the source code itself, which is of course always right. However, for the newcomer to PEAR or HTML_QuickForm, the following should be a useful foundation to build upon.

Pre-requisites

It is assumed that you have installed both PHP and PEAR, and that you are familiar with PHP and HTML. Help with PEAR can be found at the PEAR website; help with PHP can be found at the PHP website. It is also assumed that your PHP scripts are correctly interpreted by your web server. The following script should display a host of information about the envrionment your web server runs in:

If, instead, you simply see the code above displayed in your browser window then you need to resolve this problem before proceeding. There are many tutorials setting up PHP on the Internet, and a simple search should find a suitable one.

Finally, it is a good idea to ensure that your PEAR installation is up to date. This can be done with the following command:

2. Getting started

Your first form

We will start by creating a very simple form. Copy the following code to a file, give it a .php extension, and display it in your browser:

Loading this file in your browser will simply show the words "Testing QuickForm" in black on a grey background. Not particularly exciting, but this does show that PEAR and QuickForm are installed correctly and working.

Let's consider the lines individually. The line:

loads the class definitions for QuickForm. Next we instantiate an HTML_QuickForm object:

This says that the name of the form is frmTest, and the method used to pass the form variables back to the PHP script will be GET. Of course, in this particular example there are no variables to pass back. By default, the form's action - the URI that will be called when the form is submitted - is the same URI that displayed the form in the first place. This may seem strange at first, but it is actually very useful, as we shall see.

The line

creates an element on the form. An element is any item which appears on the form. It may be a text box, a select item, plain text, etc. In this case it is a header, a psuedo-element included in QuickForm simply to improve presentation. This element has the name MyHeader and the text value Testing QuickForm.

Finally, the line

makes it all happen. This displays the form and allows the user to interact with it. Of course, in this example there isn't anything the user can do, so let's create a more complex example.

3. Practical Examples

A real form

Our examples in future will only show the code between the <?php> tags. Consider the following example:

We've added three new elements: a text box complete with a label, a reset button, and a submit button. The user can type into the text box; the reset button works, but the submit button does not appear to. We'll fix that in a moment, and later we will show the full syntax for each element that can be added.

Some theory

HTML_QuickForm introduces the concept of freezing elements of the form. Once an element is frozen it cannot be edited by the user. HTML_QuickForm enforces this by changing how the element is rendered: for example, in the case of a textbox the contents will be rendered simply as text, giving the user no opportunity to edit the text value.

HTML_QuickForm also introduces the concept of validating a form. A form is considered to be validated when the URI called to display it has one or more parameters (either GET or POST according the to the method used by the form), and all rules (which we will come on to shortly) have been satisfied.

Let's see these two concepts in action:

Now, immediately before the form is displayed we attempt to validate it. Remember, for the validation to succeed we need to call it with one or more GET parameters, but when we first call it there are no GET parameters so the validation returns FALSE and the form is not frozen. Finally, the form is displayed.

Now, however, the submit button does do something. The action parameter of the form is, by default, the URI that displayed the form in the first place, but we will now have a GET parameter appended as ?MyTextBox=myname&btnSubmit=Submit. This means that the validation will succeed (as there are, at this stage, no validation criteria to satisfy), and thus the form elements are frozen immediately prior to the form being re-displayed. Try it: you'll see that after you have entered a name and clicked on "Submit" the form is repainted, but the textbox has gone and is replaced simply by the text you typed in.

4. Rules and Filters

Checking input

HTML_QuickForm offers the facility to validate user input. By default, fields which are "required" are flagged as such to the user, and in the event that "required" input is missing a customisable error message is displayed. Consider the following:

Note the extra line, $form->addRule. This says that the element "MyTextBox" is required (ie, must not be left blank), and that if it is left blank the error message to the user is "Your name is required".

If you display the form now you will notice that the user is immediately informed that the name field is a required field. If you click on "Submit" while the name field is empty you will see the error message displayed. Filling in the name field and clicking on "Submit" once again validates, freezes and re-displays the form.

Client-side validation

In the above example the validation was carried out by the server when the form was submitted. It is possible to have the form rules validated at the client by using Javascript. A small change to the addRule line is all that is required:

In this example, if the validation rules are not satisfied a dialog box is displayed informing the user of the error. Arguably this lacks the clarity of the server-side validation, but it has the advantage of not needing to contact the server before informing the user of any input errors.

More validation rules

"Required" is not the only validation rule available. A full list

    * required
    * maxlength
    * rangelength
    * regex
    * email
    * emailorblank
    * lettersonly
    * alphanumeric
    * numeric
    * nopunctuation
    * nonzero

Note that some rules (for example, maxlength) take an addition argument:

In addition to the above list, it is possible to add user-defined rules.

Filters

In the previous example the validation rule will be satisfied by any input in the text box, including, for example, a single space. This is because the rule simply ensures that there are one or more characters in the textbox, and a space character satisfies the rule.

In this particular case what we really want is text string minus any leading and trailing spaces. We could write our own regex to do this, and change our rule to be a "regex" rule, but there is an easier way. The PHP built-in function trim does exactly what we want, and we can arrange to have the contents of the textbox run through trim immediately prior to being validated by using the applyFilter method:

If the user now enters only spaces in the textbox and then clicks Submit, the validation will fail because the spaces will be stripped prior to the rule being checked.

applyFilter takes two arguments. The first is either the name of an element or the string 'ALL', meaning that this filter applies to all elements on the form. The second argument is either a function, user-defined or built-in, or an array (the array format is not covered here).

5. Defaults, Constants and processing

Defaults

So far we have had no initial values present in the textbox when the form has been displayed. In this section we will look at how initial values, or default values, can be set for a form element. We'll change the example slightly here and assume that our form is being used to edit some informaton held in a database. We will use static arrays to represent the data retrieved from the database in order not to complicate the examples with the database code.

In this example we are going to edit a name and/or the salutation of someone in our database. Let's first look at our form without the default values added (we've omitted rules and filters for clarity):

After the require_once statement we initialise two arrays, $user and $salutations, that represent data which would normally be retrieved from a database as associative arrays. This form also introduces two new element types, the hidden and the select elements. We have merely created a hidden element called user_id - presumably a database key - but given it no value at this point. We could submit the value as the third parameter, but as we shall see we can set the value automatically. The syntax for the select element is very similar to that used for the textbox we saw earlier, but has a fourth parameter which is an array of values for the select box.

Our default values have been set in the array $user, which would normally be retrieved from a databse as mentioned above. The default values for the form elements can be set with an associated array of element-name=>element-value pairs. This is, of course, precisely how an associated array of values from a database would look, so with the addition of one setDefaults line we can set the defaults for every element on our form (only a few lines shown here for clarity):

Now when the form is displayed it shows the defaults set from the $user record.

Constants

Constants can be applied to form elements in a similar way to defaults using setConstants. The difference between defaults and constants is that the former can be changed interactively on the form by the user whereas the latter cannot be changed, either by the user or by a setDefaults call.

Processing

So far all we have done when the user has clicked on "Submit" is redisplay the form in its frozen state. In reality, of course, we would want to process the values submitted. We could put the code for processing the data immediately after the $form->validate() call, but that would result in a lot of code unrelated to the form creation function being part of that function. A tidier way is to use process method, which calls a callback function with the submitted values. An example:

We have introduced a few changes here. Firstly, by using an else clause after the validation test we ensure that we only display the form while it is unvalidated. Secondly, we have used the process method to call the user-defined function process_data to process the form data after validation. This function is called with a single parameter which consists of an associated array of element-name=>element-value pairs. The second parameter to process is only used when the user has uploaded files using the form; we shall ignore it for now. Finally, the process_data function simply lists out the data passed to it. Notice that the select control returns the selected item's index rather than the text itself, so this function could very easily be adapted to update the database with the new values. Furthermore, the hidden value user_id has been correctly set too.

6. Miscellaneous

Introduction

This chapter has a number of items which don't fit easily into the preceeding chapters but which are still useful to know about when working with HTML_QuickForm.

Attributes

As we have seen, the first argument to addElement is the type of element we wish to add to our form. The number, type and meaning of subsequent arguments depend upon the type of element being added, but many elements have an attributes parameter. This allows additional arguments to be placed in the HTML definition of the element, and takes the form of either a string or an array. Two examples should make the use of attributes clearer.

The first example simply displays a textarea with a coloured background. As this example requires some style definitions the whole file is shown here:

The first three arguments to addElement are similar to those we have seen before: the type of element, the name of the element, and the caption. The fourth parameter is attributes, and in this case we have simply passed one attribute as a string, setting the class to "warn" which, in turn, sets the background of the text area to yellow.

In the second example we change not only the class of the textarea, but also its height and width. In this example, because we want to pass multiple values as attributes we use an associative array:

Further use of attributes

One other use of attributes is to pass Javascript code. The following (somewhat contrived) example causes the form to react immediately to a change in a select box without the user having to click on a submit button (this assumes that the user's browser supports Javascript):

Element groups

By default, each element on the form is rendered to a seperate line. Whilst this is a reasonable default, it does make some elements look untidy. In our earlier examples it would be more aesthetic to have the "Clear" and "Submit" buttons on one line.

Element grouping allows us to create a hybrid element which itself consists of multiple individual elements, and then to add this hybrid element to the form as one entity. Consider the following:

The first argument to addGroup is an array of the elements to add, which is created on the two line above. The fourth argument is the text to place between the elements, the separator text, which in this case is a simple space.

Note: Do not confuse element groups with HTML groups, such as are often used with radio buttons.

7. Reference: elements

Introduction

This chapter gives a brief overview of each type of element; it is not yet complete and is somewhat terse in places. In some cases the descriptions are taken straight from the source code. All arguments other then the type of element (the first argument to addElement) are optional.

advcheckbox

Normally a checkbox only passes a value back to the form when it is checked. Unchecked boxes not only pass no value back, but also the checkbox variable does not exist in the values passed to the process routine. The advcheckbox overcomes these problems.

If values is omitted then the value returned is an empty string if not checked, and '1' if checked. If a string value is passed then the return value is empty string/supplied string, and if an array of two strings is passed they are taken as the unchecked/checked values to return.

button

checkbox

date

This pseudo-element produces multiple select boxes for the user to input a date and/or time.

options is an array which sets the language, the date/time format, and the minimum and maximum year offered in the select boxes. The format string determines not only the date/time format, but also the number of select boxes shown. The value of the date returned is an associative array, each element key being the relevant format character and the value being the value selected by the user. An example should make this clear:

The possible values for the format string are:

D = Short names of days
l = Long names of days
d = Day numbers
M = Short names of months
F = Long names of months
m = Month numbers
Y = Four digit year
h = 12 hour format
H = 23 hour  format
i = Minutes
s = Seconds
a = am/pm
A = AM/PM

element

For user-defined elements. This section to be completed.

file

Note: The 'file' documentation was submitted by Leonie Price

This is a pseudo-element that displays a text box and button, and provides all the supporting functions needed to manage the uploading of files.

Warning: The official documentation records this element as being depreciated, and may not be supported in future versions of QuickForm.

Let's look at an example of the use of the file element:

There are a couple of points to note in this code. Firstly, the code segment

creates a reference called $file to the file being uploade, which is used later in the process funtion.

Secondly, the rule to check that a file has been selected, uploadedfile, exists specifically for the file element. There are other custom rules for the file element:

• maxfilesize - sets the maximum file size that may be uploaded. For example:

• mimetype - deines the type of file which may be uploaded. For example:

Finally, after validation the process function is called. The final argument, true, indicates that the uploaded file(s) should be processed with the form.

header

hidden

hiddenselect

This section to be completed.

hierselect

This pseudo-element dynamically creates two HTML Select elements. The values available in the second Select element are determined by the value selected in the first. For example, the first box could list countries and the second cities; only the cities which exist in the selected country would be available.

The methods setMainOptions and setSecOptions are used to populate the two select boxes. The argument to setMainOptions is a single dimension array; the argument to setSecOptions is a two-dimension array, the first dimension being the key used to associate the secondary option to the appropriate main option. The value returned is a two-element array, the first element being the value of the main option and the second element being the value of the secondary options. An example should make the use of hierselect easier to understand:

Warning: Note that if a default value for the main box is set this does not automatically set the contents for the secondary box

Set default as follows:

Warning: The setDefaults line must precede the addElement line

html

This pseudo-element adds raw HTML to a form.

image

Adds an image to a form.

link

Creates a link.

password

radio

Note: Adding multiple radio buttons with the same element-name will cause them to behave as a group (ie, only one can be selected).

To select a default radio button from a group, use:

reset

select

static

This element displays static text on the form.

submit

text

textarea

This work is licensed under the Creative Commons - Attribution / Share Alike license.