HTML_QuickForm

The PEAR::HTML_QuickForm package provides methods for creating, validating, processing HTML forms.

Introduction

Table of Contents
QuickStart -- A tutorial for HTML_QuickForm
QuickHelp -- Answers to most Frequently Asked Questions
QuickForm element types -- What elements can be added to QuickForm
Migration to version 3.2 -- API changes to observe

QuickForm is a convenience library for dealing with HTML forms. It provides Javascript and server-side form validation, and is customizable and extensible in many ways. QuickForm consists of multiple files. The main file is QuickForm.php and should be installed in your pear/HTML directory. The other important files are element.php, which handles all methods relative to form elements, and group.php, which deals with methods relative to groups of elements in the form. Both are located in your HTML/QuickForm directory along with the other form objects. input.php contains a common class for all the elements of input type (text, password...). QuickForm has objects for all the common form elements: select, text, password, checkbox, file, submit, reset, button, image, radio, hidden, textarea. QuickForm provides the possibility to create your own elements as long as you comply with the common API.

Creating a basic form

Table of Contents
constructor HTML_QuickForm::HTML_QuickForm() -- Class constructor
HTML_QuickForm::addElement() -- Adds an element into the form
HTML_QuickForm::apiVersion() -- Returns the current API version
HTML_QuickForm::createElement() -- Creates a new form element of the given type
HTML_QuickForm::elementExists() -- Checks if element is in the form
HTML_QuickForm::errorMessage() -- Returns an error message for error code
HTML_QuickForm::getElementType() -- Returns the type of an element
HTML_QuickForm::getElement() -- Returns a reference to the element
HTML_QuickForm::getMaxFileSize() -- Returns the value of MAX_FILE_SIZE hidden element
HTML_QuickForm::getRegisteredTypes() -- Returns registered element types
HTML_QuickForm::insertElementBefore() -- Inserts a new element right before the other element
HTML_QuickForm::isError() -- Tells whether a result is an error
HTML_QuickForm::isTypeRegistered() -- Checks whether the form element type is supported
HTML_QuickForm::registerElementType() -- Registers a new element type
HTML_QuickForm::removeElement() -- Removes an element
HTML_QuickForm::setMaxFileSize() -- Sets the value of MAX_FILE_SIZE hidden element
HTML_QuickForm::updateElementAttr() -- Updates Attributes for one or more elements

To be written.

Classes representing form elements

To be written

Base classes

Table of Contents
Class Summary HTML_QuickForm_element -- Base class for form elements
constructor HTML_QuickForm_element() -- Class constructor
HTML_QuickForm_element::accept() -- Accepts a renderer
HTML_QuickForm_element::apiVersion() -- Returns the current API version
HTML_QuickForm_element::exportValue() -- Returns a 'safe' element's value (package developer related)
HTML_QuickForm_element::freeze() -- Freezes the element
HTML_QuickForm_element::getFrozenHtml() -- Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() -- Returns the label for the element
HTML_QuickForm_element::getName() -- Returns the element name
HTML_QuickForm_element::getType() -- Returns the element type
HTML_QuickForm_element::getValue() -- Returns the value of the form element
HTML_QuickForm_element::isFrozen() -- Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() -- Called by HTML_QuickForm whenever form event is made on this element (package developer related)
HTML_QuickForm_element::setLabel() -- Sets a label for the element
HTML_QuickForm_element::setName() -- Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() -- Sets whether element value should persist on freeze()
HTML_QuickForm_element::setValue() -- Sets the value of the form element
HTML_QuickForm_element::unfreeze() -- Unfreezes the element
Class Summary HTML_QuickForm_input -- Base class for input form elements
constructor HTML_QuickForm_input() -- Class constructor
HTML_QuickForm_input::setType() -- Sets the element type

Standard HTML elements

Table of Contents
Class Summary HTML_QuickForm_button -- HTML class for a button type element
constructor HTML_QuickForm_button() -- Class constructor
Class Summary HTML_QuickForm_checkbox -- HTML class for a checkbox type field
constructor HTML_QuickForm_checkbox() -- Class constructor
HTML_QuickForm_checkbox::getChecked() -- Returns whether a checkbox is checked
HTML_QuickForm_checkbox::getText() -- Returns the checkbox text
HTML_QuickForm_checkbox::setChecked() -- Sets whether a checkbox is checked
HTML_QuickForm_checkbox::setText() -- Sets the checkbox text
Class Summary HTML_QuickForm_file -- HTML class for a file type element
constructor HTML_QuickForm_file() -- Class constructor
HTML_QuickForm_file::getSize() -- Returns size of file element
HTML_QuickForm_file::getValue() -- Returns information about the uploaded file
HTML_QuickForm_file::isUploadedFile() -- Checks if the element contains an uploaded file
HTML_QuickForm_file::moveUploadedFile() -- Moves an uploaded file into the destination
HTML_QuickForm_file::setSize() -- Sets size of file element
Class Summary HTML_QuickForm_hidden -- HTML class for a hidden type element
constructor HTML_QuickForm_hidden() -- Class constructor
Class Summary HTML_QuickForm_image -- HTML class for a image type element
constructor HTML_QuickForm_image() -- Class constructor
HTML_QuickForm_image::setAlign() -- Sets alignment for image element
HTML_QuickForm_image::setBorder() -- Sets border size for image element
HTML_QuickForm_image::setSource() -- Sets source for image element
Class Summary HTML_QuickForm_password -- HTML class for a password type field
constructor HTML_QuickForm_password() -- Class constructor
HTML_QuickForm_password::setMaxlength() -- Sets maxlength of password element
HTML_QuickForm_password::setSize() -- Sets size of password element
Class Summary HTML_QuickForm_radio -- HTML class for a radio type element
constructor HTML_QuickForm_radio() -- Class constructor
HTML_QuickForm_radio::getChecked() -- Returns whether radio button is checked
HTML_QuickForm_radio::getText() -- Returns the radio text
HTML_QuickForm_radio::setChecked() -- Sets whether radio button is checked
HTML_QuickForm_radio::setText() -- Sets the radio text
Class Summary HTML_QuickForm_reset -- HTML class for a reset type element
constructor HTML_QuickForm_reset() -- Class constructor
Class Summary HTML_QuickForm_select -- Class to dynamically create an HTML SELECT
constructor HTML_QuickForm_select() -- Class constructor
HTML_QuickForm_select::addOption() -- Adds a new OPTION to the SELECT
HTML_QuickForm_select::getMultiple() -- Returns the select mutiple attribute
HTML_QuickForm_select::getPrivateName() -- Returns the element name (possibly with brackets appended)
HTML_QuickForm_select::getSelected() -- Returns an array of the selected values
HTML_QuickForm_select::getSize() -- Returns the select field size
HTML_QuickForm_select::load() -- Loads options from different types of data sources
HTML_QuickForm_select::loadArray() -- Loads the options from an associative array
HTML_QuickForm_select::loadDbResult() -- Loads the options from DB_result object
HTML_QuickForm_select::loadQuery() -- Queries a database and loads the options from the results
HTML_QuickForm_select::setMultiple() -- Sets the select mutiple attribute
HTML_QuickForm_select::setSelected() -- Sets the default values of the select box
HTML_QuickForm_select::setSize() -- Sets the select field size, only applies to 'multiple' selects
Class Summary HTML_QuickForm_submit -- HTML class for a submit type element
constructor HTML_QuickForm_submit() -- Class constructor
Class Summary HTML_QuickForm_text -- HTML class for a text field
constructor HTML_QuickForm_text -- Class constructor
HTML_QuickForm_text::setMaxlength() -- Sets maxlength of text field
HTML_QuickForm_text::setSize() -- Sets size of text field
Class Summary HTML_QuickForm_textarea -- HTML class for a textarea type field
constructor HTML_QuickForm_textarea() -- Class constructor
HTML_QuickForm_textarea::setCols() -- Sets width in cols for textarea element
HTML_QuickForm_textarea::setRows() -- Sets height in rows for textarea element
HTML_QuickForm_textarea::setWrap() -- Sets wrap type for textarea element

Custom elements

Table of Contents
Class Summary HTML_QuickForm_advcheckbox -- HTML class for an advanced checkbox type field
constructor HTML_QuickForm_advcheckbox() -- Class constructor
HTML_QuickForm_advcheckbox::getOnclickJs() -- Create the javascript for the onclick event
HTML_QuickForm_advcheckbox::getPrivateName() -- Gets the private name for the element
HTML_QuickForm_advcheckbox::setValues() -- Sets the values used by the hidden element
Class Summary HTML_QuickForm_autocomplete -- HTML class for a text field with autocompletion feature
constructor HTML_QuickForm_autocomplete -- Class constructor
HTML_QuickForm_autocomplete::setoptions() -- Sets the options for the autocomplete input text element
Class Summary HTML_QuickForm_date -- Class for a group of elements used to input dates (and times).
constructor HTML_QuickForm_date() -- Class constructor
Class Summary HTML_QuickForm_header -- A pseudo-element used for adding headers to form
constructor HTML_QuickForm_header() -- Class constructor
Class Summary HTML_QuickForm_hiddenselect -- Creates hidden elements with select's values
constructor HTML_QuickForm_hiddenselect() -- Class constructor
Class Summary HTML_QuickForm_hierselect -- Class to dynamically create chained HTML Select elements, each select changes the content of the next.
constructor HTML_QuickForm_hierselect() -- Class constructor
HTML_QuickForm_hierselect::setMainOptions() -- Sets the options for the first select
HTML_QuickForm_hierselect::setSecOptions() -- Sets the options for the secondary select
Class Summary HTML_QuickForm_html -- A pseudo-element used for adding raw HTML to form (deprecated)
constructor HTML_QuickForm_html() -- Class constructor
Class Summary HTML_QuickForm_link -- HTML class for a link type field
constructor HTML_QuickForm_link() -- Class constructor
HTML_QuickForm_link::setHref() -- Sets the links href
Class Summary HTML_QuickForm_static -- HTML class for static data
constructor HTML_QuickForm_static() -- Class constructor
HTML_QuickForm_static::setText() -- Sets the text

Using groups

Table of Contents
HTML_QuickForm::addGroup() -- Adds an element group
Class Summary HTML_QuickForm_group -- HTML class for a form element group
constructor HTML_QuickForm_group() -- Class constructor
HTML_QuickForm_group::getElementName() -- Returns the name of an element inside the group
HTML_QuickForm_group::getElements() -- Gets the grouped elements
HTML_QuickForm_group::getGroupType() -- Gets the group type based on its elements.
HTML_QuickForm_group::setElements() -- Sets the grouped elements

To be written.

Working with elements' values

This section covers the methods QuickForm offers for managing form element's values and working with submitted values.

Getting, setting and processing element values

Table of Contents
HTML_QuickForm::setConstants() -- Sets constant form values
HTML_QuickForm::setDefaults() -- Sets default form values
HTML_QuickForm::exportValue() -- Returns the element's "safe" value
HTML_QuickForm::exportValues() -- Returns "safe" elements' values
HTML_QuickForm::getElementValue() -- Returns the element's raw value
HTML_QuickForm::getSubmitValue() -- Returns the submitted element's value
HTML_QuickForm::getSubmitValues() -- Returns the values submitted by the form
HTML_QuickForm::process() -- Performs the form data processing

Validation and filters

Table of Contents
Introduction - validation and filters -- How to process submitted data
HTML_QuickForm::addRule() -- Adds a validation rule for the given field
HTML_QuickForm::addGroupRule() -- Adds a validation rule for the given group
HTML_QuickForm::addFormRule() -- Adds a global validation rule
HTML_QuickForm::isElementRequired() -- Returns whether the form element is required
HTML_QuickForm::validate() -- Performs the server side validation
HTML_QuickForm::getElementError() -- Returns error corresponding to validated element
HTML_QuickForm::setElementError() -- Set error message for a form element
HTML_QuickForm::registerRule() -- Registers a new validation rule
HTML_QuickForm::getRegisteredRules() -- Returns registered validation rules
HTML_QuickForm::isRuleRegistered() -- Returns whether the rule is supported
HTML_QuickForm::applyFilter() -- Applies a filter for the given field(s)

QuickForm also provides validation rules support. You can code your own validation rules, register them in QuickForm and then call them in your script. By default, QuickForm can handle validation against regular expressions (preg_match style) and check for required elements. If you want client-side validation, QuickForm can generate the javascript code needed. Server-side validation is always on by default.

QuickForm can also make use of filters for data import into the form or for data processing once the form has been submitted. Filters work the same way as rules except that you don't need to register them. You write your filter functions and call them in your script. You can call any php function (ie. trim, addslashes, htmlentities, etc.) and have them applied recursively to your element values.

Outputting the form

Your form can be customised in many ways. QuickForm can use different kind of renderers and provides a default one which allows for customization of the form, the elements, the error messages, the headers, the required elements note and the required elements sign. You can also write your own renderers.

Form customization and output helpers

Table of Contents
HTML_QuickForm::freeze() -- "Freezes" the form's elements
HTML_QuickForm::isElementFrozen() -- Checks whether the element is frozen
HTML_QuickForm::isFrozen() -- Checks whether the form is frozen
HTML_QuickForm::setRequiredNote() -- Sets required note
HTML_QuickForm::setJsWarnings() -- Sets JavaScript warning messages
HTML_QuickForm::getRequiredNote() -- Returns the required note
HTML_QuickForm::getValidationScript() -- Returns the client side validation script
HTML_QuickForm::accept() -- Accepts a renderer
HTML_QuickForm::defaultRenderer() -- Returns a reference to default renderer object
HTML_QuickForm::toArray() -- Returns the form's contents in an array
HTML_QuickForm::toHtml() -- Returns an HTML version of the form

Basic renderers

Table of Contents
Introduction - renderers -- How to output the form
HTML_QuickForm_Renderer_Default -- Default renderer
HTML_QuickForm_Renderer_Default::clearAllTemplates() -- Clears all templates
HTML_QuickForm_Renderer_Default::setElementTemplate() -- Sets element template
HTML_QuickForm_Renderer_Default::setFormTemplate() -- Sets form template
HTML_QuickForm_Renderer_Default::setGroupElementTemplate() -- Sets template for group elements
HTML_QuickForm_Renderer_Default::setGroupTemplate() -- Sets template for a group wrapper
HTML_QuickForm_Renderer_Default::setHeaderTemplate() -- Sets header template
HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate() -- Sets the template for 'required' note
HTML_QuickForm_Renderer_Default::toHtml() -- Returns the HTML
HTML_QuickForm_Renderer_Array -- Array representation of the form
constructor HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array() -- Constructor
HTML_QuickForm_Renderer_Array::setElementStyle() -- Sets a style to use for element rendering
HTML_QuickForm_Renderer_Array::toArray() -- Returns the resultant array

These renderers are based on pre-3.0 HTML_QuickForm code and require no external classes to do their work.

Template-based renderers

Table of Contents
HTML_QuickForm_Renderer_ArraySmarty -- A renderer for 'static' Smarty templates
constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty() -- Constructor
HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate() -- Sets the way elements with validation errors are rendered
HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate() -- Sets the way required elements are rendered
HTML_QuickForm_Renderer_ITDynamic -- Dynamic renderer for Integrated Templates
constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic() -- Constructor
HTML_QuickForm_Renderer_ITDynamic::setElementBlock() -- Sets the block to use for element rendering
HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock() -- Sets the name of a block to use for header rendering
HTML_QuickForm_Renderer_ITStatic -- Static renderer for Integrated Templates
constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic() -- Constructor
HTML_QuickForm_Renderer_ITStatic::setErrorTemplate() -- Sets the way elements with validation errors are rendered
HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate() -- Sets the way required elements are rendered
HTML_QuickForm_Renderer_QuickHtml -- Render form elements into HTML in an easy and flexible manner
constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml() -- Constructor
HTML_QuickForm_Renderer_QuickHtml::toHtml() -- Returns the HTML
HTML_QuickForm_Renderer_QuickHtml::elementToHtml() -- Renders a specific form element into HTML

These renderers use template engines to actually generate the HTML for the form.

Renderer infrastructure

Table of Contents
HTML_QuickForm_Renderer -- Abstract base class for renderers (package developer related)
HTML_QuickForm_Renderer::startForm() -- Start visiting a form (package developer related)
HTML_QuickForm_Renderer::finishForm() -- Finish visiting a form (package developer related)
HTML_QuickForm_Renderer::startGroup() -- Start visiting a group (package developer related)
HTML_QuickForm_Renderer::finishGroup() -- Finish visiting a group (package developer related)
HTML_QuickForm_Renderer::renderElement() -- Visit an element (package developer related)
HTML_QuickForm_Renderer::renderHeader() -- Visit a header (package developer related)
HTML_QuickForm_Renderer::renderHidden() -- Visit a hidden element (package developer related)
HTML_QuickForm_Renderer::renderHtml() -- Visit a raw HTML/text element (package developer related)

If you want to modify an existing renderer or write a new one, this section will be of interest to you.