PEAR HTML_QuickForm
Getting Started Guide
Contents
- Introduction
- Getting started
- Practical Examples
- Rules and Filters
- Defaults, Constants and processing
- Miscellaneous
- Reference: elements
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).
I receive a great deal of mail as a result of this article, much of it asking me to solve various PEAR/HTML_QuickForm/Smarty problems. Please bear in mind that the money that puts food on my family's table comes from the consultancy work that I do, so here's the deal. If you would like some help with a the points discussed in this article, mail me and tell me what that help is worth to you. Quote any amount you like, and if I'm able to help you out you can make a PayPal donation by way of thanks. Fair enough?
Thank you
Keith Edmunds
1. 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 environment your web server runs in:
<?php
phpinfo();
?>
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:
# Optionally check for upgrades first pear list-upgrades # Upgrade PEAR pear upgrade-all
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:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Testing PEAR HTML_QuickForm</title>
</head>
<body>
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->display();
?>
</body>
</html>
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:
require_once "HTML/QuickForm.php";
loads the class definitions for QuickForm. Next we instantiate an HTML_QuickForm object:
$form = new HTML_QuickForm('frmTest', 'get');
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
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
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
$form->display();
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:
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->addElement('text', 'MyTextBox', 'What is your name?');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
$form->display();
?>
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 do anything. 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:
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->addElement('text', 'MyTextBox', 'What is your name?');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
# If the form validates then freeze the data
$form->freeze();
}
$form->display();
?>
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:
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->addElement('text', 'MyTextBox', 'What is your name?');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
$form->addRule('MyTextBox', 'Your name is required', 'required');
if ($form->validate()) {
# If the form validates then freeze the data
$form->freeze();
}
$form->display();
?>
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:
$form->addRule('MyTextBox', 'Your name is required', 'required', '', 'client');
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
- emailorblank
- lettersonly
- alphanumeric
- numeric
- nopunctuation
- nonzero
Note that some rules (for example, maxlength) take an additional argument:
$form->addRule('postcode', 'Maximum postcode 8 characters', 'maxlength', 8, 'client');
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:
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->addElement('text', 'MyTextBox', 'What is your name?');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
$form->addRule('MyTextBox', 'Your name is required', 'required');
$form->applyFilter('MyTextBox', 'trim');
if ($form->validate()) {
# If the form validates then freeze the data
$form->freeze();
}
$form->display();
?>
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. Note that there are two underscores both
before and after the word ALL. 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 information 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):
<?php
require_once "HTML/QuickForm.php";
##########################################################
# The user information would normally come from a database
$user = array("firstname"=>"Mickey",
"lastname"=>"Mouse",
"sal_id"=>4,
"user_id"=>7);
# 'Salutation' comes from a lookup table comprising
# sal_id, sal_text
$salutations = array("0"=>"Mr",
"1"=>"Miss",
"2"=>"Mrs",
"3"=>"Dr",
"4"=>"Sir");
# End of "database-retrieved" information
##########################################################
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Edit username');
$form->addElement('hidden', 'user_id');
$form->addElement('select', 'sal_id', 'Address me as:', $salutations);
$form->addElement('text', 'firstname', 'First name:');
$form->addElement('text', 'lastname', 'Last name:');
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
echo "\n<HR>\n";
}
$form->display();
?>
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 database as mentioned above. The default values
for the form elements
can be set with an associative 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):
// First part of form as previous example
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
}
$form->setDefaults($user);
$form->display();
?>
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:
// First part of form as earlier example
$form->addElement('reset', 'btnClear', 'Clear');
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
$form->process('process_data', false);
}
else {
$form->setDefaults($user);
$form->display();
}
function process_data ($values) {
echo "<pre>";
foreach ($values as $key=>$value) {
echo $key."=".$value."<br>";
}
echo "</pre>";
}
?>
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 preceding 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:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Testing PEAR HTML_QuickForm</title>
<style type="text/css">
.ok { background: green; }
.warn { background: yellow; }
.error { background: red; }
</style>
</head>
<body>
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('textarea', 'MyTextArea', 'Details:', "class=warn");
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
$form->freeze();
}
$form->display();
?>
</body>
</html>
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:
// First part of form as previous example
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$attrs = array("class"=>"error",
"rows"=>"10",
"cols"=>"50");
$form->addElement('textarea', 'MyTextArea', 'Details:', $attrs);
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
}
$form->display();
?>
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):
<?php
require_once "HTML/QuickForm.php";
define ("OK", 0);
define ("WARNING", 1);
define ("ERROR", 2);
$status_list = array(OK=>"All OK",
WARNING=>"Warning",
ERROR=>"Error");
$styles = array (OK=>"ok",
WARNING=>"warn",
ERROR=>"error");
if (array_key_exists("status", $_GET)) {
$style = $styles[$_GET['status']];
}
else {
$style = $styles[0];
}
$attrs = array('onchange' =>
"javascript:location.href=
'?status='+this.options[this.selectedIndex].value;");
$form = new HTML_QuickForm('frmTest', 'get', null, null, "class=$style");
$form->addElement('select', 'status', 'Select status:', $status_list, $attrs);
$form->display();
?>
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:
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'Testing QuickForm');
$form->addElement('text', 'MyTextBox', 'What is your name?');
$buttons[] = &HTML_QuickForm::createElement('reset', 'btnClear', 'Clear');
$buttons[] = &HTML_QuickForm::createElement('submit', 'btnSubmit', 'Submit');
$form->addGroup($buttons, null, null, ' ');
$form->addRule('MyTextBox', 'Your name is required', 'required');
if ($form->validate()) {
# If the form validates then freeze the data
$form->freeze();
}
$form->display();
?>
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.
addElement('advcheckbox',
string element-name, // name of advcheckbox
string element-label, // label output before advcheckbox
string text, // label output after advcheckbox
mixed attributes, // string or array of attributes
mixed values); // see below
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
addElement('button',
string element-name, // name of button
string value, // text of button
mixed attributes); // string or array of attributes
checkbox
addElement('checkbox',
string element-name, // name of checkbox
string element-label, // label output before checkbox
string text, // label output after checkbox
mixed attributes); // string or array of attributes
date
This pseudo-element produces multiple select boxes for the user to input a date and/or time.
addElement('date',
string element-name, // name of date
string element-label, // label output before date
array options, // see below
mixed attributes); // string or array of attributes
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:
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$options = array(
'language' => 'en',
'format' => 'dMYHi',
'minYear' => 2001,
'maxYear' => 2005
);
$form->addElement('date', 'mydate', 'Choose date', $options);
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
$form->process('process_data', false);
}
else {
$form->display();
}
function process_data ($values) {
echo "<pre>";
var_dump($values);
echo "</pre>";
}
?>
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
To set default values for the date element simply create an array
and assign the required values to the format string elements defined above.
For example, to set the default date to 28th February 2005:
$form->setDefaults(array(
'my_date' => array('d'=>28, 'F'=>"February", 'Y'=>2005)));
Here's a complete example that sets the default date to today's date:
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$options = array(
'language' => 'en',
'format' => 'dMYHi',
'minYear' => 2000,
'maxYear' => 2010
);
$date_defaults = array(
'd' => date('d'),
'M' => date('M'),
'Y' => date('Y'),
'H' => date('H'),
'i' => date('i')
);
$form->setDefaults(array('mydate' => $date_defaults));
$form->addElement('date', 'mydate', 'Choose date', $options);
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
$form->process('process_data', false);
}
else {
$form->display();
}
function process_data ($values) {
echo "<pre>";
var_dump($values);
echo "</pre>";
}
?>
element
For user-defined elements. This section to be completed.
file
Note: The 'file' documentation was submitted by Leonie Price
addElement('file',
string element-name, // name of file element
string element_label, // label for file element
mixed attributes); // string or array of attributes
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:
<?php
require_once "HTML/QuickForm.php";
$uploadForm = new HTML_QuickForm('upload_form', 'post');
$path = "/path/to/uploads";
$file =& $uploadForm->addElement('file', 'filename', 'File:');
$uploadForm->addRule('filename', 'You must select a file', 'uploadedfile');
$uploadForm->addElement('submit', 'btnUpload', 'Upload');
if ($uploadForm->validate()) {
$uploadForm->process('process', true);
}
else {
$uploadForm->display();
}
function process($values) {
global $file;
if ($file->isUploadedFile()) {
$file->moveUploadedFile($path);
}
else {
print "No file uploaded";
}
}
?>
There are a couple of points to note in this code. Firstly, the code segment
$file =& $uploadForm->addElement('file', 'filename', 'File:');
creates a reference called $file to the file being uploaded, which is used later
in the process function.
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:
$uploadForm->addRule('filename', 'The file you selected is too large', 'maxfilesize', 524288);
mimetype - defines the type of file which may be uploaded. For example:
$uploadForm->addRule('filename', 'Must be a jpeg', 'mimetype', array('image/jpeg', 'image/jpeg') );
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
addElement('header',
string element-name, // name of header
string text); // text of header
hidden
addElement('hidden',
string element-name, // name of hidden element
string value, // value of hidden element
mixed attributes); // string or array of attributes
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.
addElement('hierselect',
string element-name, // name of hierselect element
string label, // text label
mixed attributes); // string or array of attributes
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:
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$main = array();
$secondary = array();
$main[0] = "England";
$main[1] = "Scotland";
$main[2] = "USA";
$secondary[0][0] = "London";
$secondary[0][1] = "Manchester";
$secondary[0][2] = "Liverpool";
$secondary[1][3] = "Edinburgh";
$secondary[1][4] = "Glasgow";
$secondary[2][5] = "Fort Worth";
$secondary[2][6] = "Boston";
$secondary[2][7] = "Los Angles";
$sel =& $form->addElement('hierselect', 'location', 'Location:');
$sel->setMainOptions($main);
$sel->setSecOptions($secondary);
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
$form->process('process_data', false);
}
else {
$form->display();
}
function process_data ($values) {
echo "<pre>";
var_dump($values);
echo "</pre>";
}
?>
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:
// First part of form as previous example
$form->setDefaults(array('location'=>array(1,4)));
$sel =& $form->addElement('hierselect', 'location', 'Location:');
$sel->setMainOptions($main);
$sel->setSecOptions($secondary);
$form->addElement('submit', 'btnSubmit', 'Submit');
// Rest of form as previous example
html
This pseudo-element adds raw HTML to a form.
addElement('html',
string html-text); // the HTML to add
image
Adds an image to a form.
addElement('image',
string element-name, // name for image
string src, // source file of image
mixed attributes); // string or array of attributes
link
Creates a link.
addElement('link',
string element-name, // name for link
string label, // label for link field
string href, // URI of link
string text, // text to display
mixed attributes); // string or array of attributes
password
addElement('password',
string element-name, // name for password
string label, // label for password field
mixed attributes); // string or array of attributes
radio
addElement('radio',
string element-name, // name for radio button
string label, // text to display before button
string text, // text to display after button
int value, // the value returned
mixed attributes); // string or array of attributes
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:
$form->setDefaults(array(element-name => value));
reset
addElement('reset',
string element-name, // name of reset
string value, // text of button
mixed attributes); // string or array of attributes
select
addElement('select',
string element-name, // name of select
string label, // label for select
mixed data, // data for select; see earlier text
mixed attributes); // string or array of attributes
static
This element displays static text on the form.
addElement('static',
string label, // label to display
string text); // text to display
submit
addElement('submit',
string element-name, // name of submit
string value, // text of button
mixed attributes); // string or array of attributes
text
addElement('text',
string element-name, // name of text box
string label, // label
mixed attributes); // string or array of attributes
textarea
addElement('textarea',
string element-name, // name of textarea
string label, // label
mixed attributes); // string or array of attributes