Home » HTML » HTML_QuickForm » Manual

Introduction

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.

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.

QuickHelp

QuickHelp – Answers to most Frequently Asked Questions

Description

This document is based on questions asked on PEAR general mailing list. You are encouraged to search the list archives to find more verbose answers and examples.

HTML_QuickForm FAQ

1. The forms I generate with HTML_QuickForm cannot be submitted. When I look at the page's HTML source, I see something like <formArray>.
2. When I pass some GET parameters to the script containing a form, QuickForm thinks that the form was already submitted, displaying validation errors.
3. How do I set default/constant values for 'date' element?
4. I receive weird "Call to a member function on a non-object" or "Undefined function" errors, especially when dealing with groups.
5. QuickForm generates code which does not validate as XHTML Strict!
6. The 'required' rule does not work for my elements!
7. How do I change * denotes required field and Invalid information entered. / Please correct these fields. validation messages?

The forms I generate with HTML_QuickForm cannot be submitted. When I look at the page's HTML source, I see something like <formArray>.

Recent versions of HTML_QuickForm package require HTML_Common package version 1.2.1 (CVS revision 1.8 in HTML/Common.php) to work properly. If (and only if) an older version of HTML_Common is loaded, these symptoms occur.

Please note that

              
$ pear list
              
            

command may tell you that you have HTML_Common 1.2.1 installed. In this case you also have an older version of HTML_Common somewhere and are including it instead of the proper one. Check your include_path setting in php.ini and/or use PHP's get_included_files() function to find out which file you are really including.

When I pass some GET parameters to the script containing a form, QuickForm thinks that the form was already submitted, displaying validation errors.

Constructor of HTML_QuickForm accepts a $trackSubmit parameter. Setting this to TRUE will make QuickForm check whether the form was actually submitted. This also helps if you have several forms defined on one page.

How do I set default/constant values for 'date' element?

Date element is essentially a group of selects, you define the structure of this group in the 'format' option when creating the element:

<?php
$form->addElement('date', 'foo', 'The date:', array('format' => 'Y m d'));
?>

Thus you pass the defaults as an array, just like you do with any other group:

<?php
$form->setDefaults(array(
    'foo' => array('Y' => 2004, 'm' => 9, 'd' => 29)
));
?>

To ease using it with database-backed applications, date element also accepts Unix timestamps (generated by mktime()) and strings. The strings are processed by strtotime() functions, so consider its limitations.

I receive weird "Call to a member function on a non-object" or "Undefined function" errors, especially when dealing with groups.

These errors tend to appear when you have something which is not a HTML_QuickForm_element in the $elements array passed to addGroup(). This "something" is usually either a PEAR_Error instance (check for these or setup a handler) or, if register_globals is switched on in php.ini, some submitted values (clear the array before adding elements to it).

QuickForm generates code which does not validate as XHTML Strict!

QuickForm does add a 'name' attribute to the <form> tag, which is invalid in XHTML Strict. Quickform does not depend on that attribute since release 3.2.2, and it's only kept for backwards compatibility. If you desire XHTML Strict compliance and your code does not depend on said attribute, you can remove it via removeAttribute() method.

The 'required' rule does not work for my elements!

• If your element is a file upload, you should use 'uploadedfile' rule instead.
• If your element is a group, you should use addGroupRule() method instead of addRule(). This applies to group-based elements like 'date' and 'hierselect' as well.

How do I change * denotes required field and Invalid information entered. / Please correct these fields. validation messages?

You should use setRequiredNote() and setJsWarnings() methods, respectively.

QuickForm element types

QuickForm element types – What elements can be added to QuickForm

Elements overview

As of release 3.2.5, HTML_QuickForm knows 23 element types that can be created via createElement() and added to the form via addElement(). These can be divided into two big groups: standard HTML elements and custom elements.

'button'

Class for <input type="button" /> elements, HTML_QuickForm_button

'checkbox'

Class for <input type="checkbox" /> elements, HTML_QuickForm_checkbox

'file'

Class for <input type="file" /> elements, HTML_QuickForm_file

'hidden'

Class for <input type="hidden" /> elements, HTML_QuickForm_hidden

'image'

Class for <input type="image" /> elements, HTML_QuickForm_image

'password'

Class for <input type="password" /> elements, HTML_QuickForm_password

'radio'

Class for <input type="radio" /> elements, HTML_QuickForm_radio

'reset'

Class for <input type="reset" /> elements, HTML_QuickForm_reset

'select'

Class for <select> elements, HTML_QuickForm_select. The class allows loading of <option> elements from array or database.

'submit'

Class for <input type="submit" /> elements, HTML_QuickForm_submit

'text'

Class for <input type="text" /> elements, HTML_QuickForm_text

'textarea'

Class for <textarea> elements, HTML_QuickForm_textarea

'xbutton'

Class for <button> elements, HTML_QuickForm_xbutton

'advcheckbox'

Class for an advanced checkbox type field, HTML_QuickForm_advcheckbox. Basically this fixes a problem that HTML has had where checkboxes can only pass a single value (the value of the checkbox when checked).

'autocomplete'

Class for a text field with autocompletion feature, HTML_QuickForm_autocomplete. The element looks like a normal HTML input text element that at every keypressed javascript event, searches the array of options for a match and autocompletes the text in case of match.

'date'

Class for a group of elements used to input dates (and times), HTML_QuickForm_date

'group'

Class for a form element group, HTML_QuickForm_group. QuickForm allows grouping of several elements into one entity and using this entity as a new element.

'header'

Class for adding headers to the form, HTML_QuickForm_header

'hiddenselect'

This class, HTML_QuickForm_hiddenselect, behaves as a select element, but instead of creating a <select> it creates hidden elements for all values already selected with setDefaults() or setConstants().

'hierselect'

Class to dynamically create "chained" HTML <select> elements, HTML_QuickForm_hierselect. Choosing an option in the first <select> changes the available options of the second select and so on.

'html'

Deprecated. A pseudo-element used for adding raw HTML to form, HTML_QuickForm_html. Intended for use with the default renderer only, template-based ones may (and probably will) completely ignore this.

'link'

Class for a link type field, HTML_QuickForm_link

'static'

Class for static data, HTML_QuickForm_static

Migration to version 3.2

Migration to version 3.2 – API changes to observe

Why these changes?

HTML_QuickForm has improved a lot since version 2.x. With the addition of a new renderer layer, a lot of methods that were located in the main QuickForm class were actually duplicates of methods in the renderers. Those methods were kept to give user time to adjust their code. With release 3.2 they will be removed, making QuickForm class much lighter and consistent.

At the same time, file upload validation was moved to the file element as this is a more appropriate place.

Removed methods

• QuickForm related
  • HTML_QuickForm::getAttributesString()
  • HTML_QuickForm::addElementGroup()
  • HTML_QuickForm::addHeader()
  • HTML_QuickForm::addData()
• Renderer related
  • HTML_QuickForm::setElementTemplate()
  • HTML_QuickForm::setHeaderTemplate()
  • HTML_QuickForm::setFormTemplate()
  • HTML_QuickForm::setRequiredNoteTemplate()
  • HTML_QuickForm::clearAllTemplates()
  • HTML_QuickForm_group::setElementTemplate()
  • HTML_QuickForm_group::setGroupTemplate()
• File upload related
  • HTML_QuickForm::isUploadedFile()
  • HTML_QuickForm::getUploadedFile()
  • HTML_QuickForm::moveUploadedFile()

How to adjust your code

QuickForm related

HTML_QuickForm::getAttributesString()

<?php
$form->getAttributes(true);
?>

will return the same value by using HTML_Common::getAttributes() method.

HTML_QuickForm::addElementGroup()

Arguments order was changed to conform to the way elements are usually added to QuickForm by addElement(). Use HTML_QuickForm::addGroup() instead and swap the element label with the element name.

HTML_QuickForm::addHeader()

A header is now considered like any other element. There is a new HTML_QuickForm_header element that extends HTML_QuickForm_static. Just use

<?php
$form->addElement('header', $header_name, $header_text);
?>

This will also allow you to customize the header rendering based on its name.

HTML_QuickForm::addData()

If you absolutely need this feature, use

<?php
$form->addElement('html', $data)
?>

or consider using some template-based renderer.

Renderer related

Those methods are now handled by the renderers. How to use these methods depends on your choice of renderer. With QuickForm default renderer, you can use these methods like that:

<?php
$form =& new HTML_QuickForm('myform');

$renderer =& $form->defaultRenderer();
$renderer->setFormTemplate('<table><form{attributes}>{content}</form></table>');
$renderer->setHeaderTemplate('<tr><td colspan="2"><b>{header}</b></td></tr>');
$renderer->setGroupTemplate('<table><tr>{content}</tr></table>');
$renderer->setGroupElementTemplate('<td>{element}<br /><!-- BEGIN required -->*<!-- END required -->{label}</td>');
?>

defaultRenderer()will return a reference to QuickForm integrated renderer. You can of course use any other renderer available in QuickForm such as Sigma, ITX, Smarty, Flexy and so on. Have a look at their documentation to see which methods are available for them.

File upload related

File-related methods and rules have been moved to the file element HTML_QuickForm_file because it makes more sense this way and you don't have to include upload-related code if you are not using uploads. You have access to these methods like that:

<?php
$form = new HTML_QuickForm('myform');
$file =& $form->addElement('file', 'myfile', 'Your file:');
$form->addRule('myfile', 'Cannot exceed 1776 bytes', 'maxfilesize', 1776);
if ($file->isUploadedFile()) {
    $file->moveUploadedFile('/tmp', 'testfile.txt');
}
?>

or like that:

<?php
$file =& $form->getElement('myfile');
if ($file->isUploadedFile()) {
     $fileInfo = $file->getValue();
}
?>

Subpackages

Subpackages – An overview about subpackages and packages that use QuickForm

Subpackages for HTML_QuickForm

This section describes the available subpackages for HTML_QuickForm, e.g. custom elements or renderers.

HTML_QuickForm_advmultiselect

A custom element that emulates via two select boxes a select box that allows selecting of multiple options.

HTML_QuickForm_DHTMLRulesTableless

If you use the Tableless renderer (see below, HTML_QuickForm_Renderer_Tableless), this subpackage replaces the default client-side validation with a JavaScript alert window by dynamic (using DHTML) error messages that are printed directly above each erroneous element. (documentation)

HTML_QuickForm_Livesearch

This is another custom element. It creates an HTML input text element that at every keypressed javascript event, returns a list of options in a dynamic dropdown select box (especially useful to emulate a select box with a huge number of options). This element uses the AJAX technology.

HTML_QuickForm_Renderer_Tableless

This is a replacement for the default renderer of HTML_QuickForm that uses only XHTML and CSS but no table tags, and generates fully valid XHTML output. (documentation)

HTML_QuickForm_SelectFilter

Another custom element that is used to define dynamic filters on the client-side for select elements.

More subpackages

There are some more subpackages available that were not yet proposed as PEAR packages. An example is a DHTMLRules subpackage for forms using the default renderer by Justin Patrin that was not yet proposed as a PEAR package.

Packages that use HTML_QuickForm

This section describes some packages that makes working with HTML_QuickForm easier, either in the case of working with databases or in the case of forms that have multiple pages.

DB_DataObject_FormBuilder

FormBuilder aids in rapid application development using the packages DB_DataObject and HTML_QuickForm. (documentation)

DB_Table

This is a package that builds on PEAR DB and MDB2 to abstract datatypes and automate table creation, data validation, insert, update, delete, and select. It combines these with HTML_QuickForm to automatically generate input forms that match the table column definitions. (documentation)

HTML_QuickForm_Controller

If you want to create forms with multiple pages, this is the right package for you. It is an implementation of a PageController pattern. (documentation)

More packages

You can find more packages that have optional or required dependencies on HTML_QuickForm on the package site.

Creating a basic form

To be written.

constructor HTML_QuickForm::HTML_QuickForm()

constructor HTML_QuickForm::HTML_QuickForm() – Class constructor

Synopsis

void HTML_QuickForm::HTML_QuickForm ( string $formName = '' , string $method = 'post' , string $action = '' , string $target = '' , mixed $attributes = null , bool $trackSubmit = false )

Description

Constructor, sets <form> tag attributes and loads submitted values.

Parameter

string $formName

Form's name.

string $method

(optional) Form's method

string $action

(optional) Form's action

string $target

(optional) Form's target

mixed $attributes

(optional) Extra attributes for <form> tag

boolean $trackSubmit

(optional) Whether to track if the form was submitted by adding a special hidden field. If the name of such field is not present in the $_GET or $_POST values, the form will be considered as not submitted.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm::addElement()

HTML_QuickForm::addElement() – Adds an element into the form

Synopsis

object &HTML_QuickForm::addElement ( mixed $element )

Description

Adds an element into the form. If $element is a string representing an element type, then this method accepts variable number of parameters, their meaning and count depending on element type.

Parameters starting from second will be passed to the element's constructor, consult the docs for the appropriate element to find out which parameters to pass.

Parameter

mixed $element

element object or type of element to add (text, textarea, file...)

Return value

return reference to added element

Throws

Note

since 1.0

This function can not be called statically.

HTML_QuickForm::apiVersion()

HTML_QuickForm::apiVersion() – Returns the current API version

Synopsis

float HTML_QuickForm::apiVersion ( void )

Description

Returns the current API version

Throws

throws no exceptions thrown

Note

since 1.0

This function can be called statically.

HTML_QuickForm::createElement()

HTML_QuickForm::createElement() – Creates a new form element of the given type

Synopsis

object &HTML_QuickForm::createElement ( string $elementType )

Description

Creates a new form element of the given type. This method accepts variable number of parameters, their meaning and count depending on $elementType.

Parameters starting from second will be passed to the element's constructor, consult the docs for the appropriate element to find out which parameters to pass.

Parameter

string $elementType

type of element to create (text, textarea, file...)

Return value

return object, descendant of HTML_QuickForm_element

Throws

Note

since 1.0

This function can be called statically.

HTML_QuickForm::elementExists()

HTML_QuickForm::elementExists() – Checks if element is in the form

Synopsis

boolean HTML_QuickForm::elementExists ( string $element = null )

Description

Returns TRUE if element is in the form, FALSE otherwise.

Parameter

string $element

form name of element to check

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm::errorMessage()

HTML_QuickForm::errorMessage() – Returns an error message for error code

Synopsis

string HTML_QuickForm::errorMessage ( int $value )

Description

Returns a textual error message for QuickForm error code.

Parameter

integer $value

int error code

Return value

return error message

Throws

throws no exceptions thrown

Note

This function can be called statically.

HTML_QuickForm::getElementType()

HTML_QuickForm::getElementType() – Returns the type of an element

Synopsis

string HTML_QuickForm::getElementType ( string $element )

Description

Returns the type of the given element.

Parameter

string $element

Name of form element

Return value

return element type or FALSE if element is not found

Throws

throws no exceptions thrown

Note

since 1.1

This function can not be called statically.

HTML_QuickForm::getElement()

HTML_QuickForm::getElement() – Returns a reference to the element

Synopsis

object &HTML_QuickForm::getElement ( string $element )

Description

Returns a reference to the form element.

Parameter

string $element

Element name

Return value

return reference to element

Throws

Note

since 2.0

This function can not be called statically.

HTML_QuickForm::getMaxFileSize()

HTML_QuickForm::getMaxFileSize() – Returns the value of MAX_FILE_SIZE hidden element

Synopsis

int HTML_QuickForm::getMaxFileSize ( void )

Description

Returns the value of MAX_FILE_SIZE hidden element (used for file uploads).

Return value

return max file size in bytes

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

HTML_QuickForm::getRegisteredTypes()

HTML_QuickForm::getRegisteredTypes() – Returns registered element types

Synopsis

array HTML_QuickForm::getRegisteredTypes ( void )

Description

Returns an array of registered element types.

Throws

throws

Note

since 1.0

This function can be called statically.

HTML_QuickForm::insertElementBefore()

HTML_QuickForm::insertElementBefore() – Inserts a new element right before the other element

Synopsis

object &HTML_QuickForm::insertElementBefore ( object &$element , string $nameAfter )

Description

Inserts a new element right before the other element.

It is not possible to check whether the $element is already added to the form, therefore if you want to move the existing form element to a new position, you'll have to use removeElement():

<?php
$form->insertElementBefore($form->removeElement('foo', false), 'bar');
?>

Parameter

object &$element

Element to insert (instance of HTML_QuickForm_element)

string $nameAfter

Name of the element before which the new one is inserted

Return value

return reference to inserted element.

Throws

Note

since 3.2.4

This function can not be called statically.

HTML_QuickForm::isError()

HTML_QuickForm::isError() – Tells whether a result is an error

Synopsis

bool HTML_QuickForm::isError ( mixed $value )

Description

Tells whether a result is an error (i.e. whether $value is an instance of HTML_QuickForm_Error).

Parameter

mixed $value

result of some QuickForm function

Return value

return whether $value is an error

Throws

throws no exceptions thrown

Note

This function can be called statically.

HTML_QuickForm::isTypeRegistered()

HTML_QuickForm::isTypeRegistered() – Checks whether the form element type is supported

Synopsis

boolean HTML_QuickForm::isTypeRegistered ( string $type )

Description

Returns whether or not the form element type is supported. New types are added via HTML_QuickForm::registerElementType().

Parameter

string $type

Form element type

Throws

throws no exceptions thrown

Note

since 1.0

This function can be called statically.

HTML_QuickForm::registerElementType()

HTML_QuickForm::registerElementType() – Registers a new element type

Synopsis

void HTML_QuickForm::registerElementType ( string $typeName , string $include , string $className )

Description

Registers a new element type. After that, elements of this type may be created via createElement() and added to form via addElement().

Parameter

string $typeName

Name of element type

string $include

Include path for element type

string $className

Element class name

Throws

throws no exceptions thrown

Note

since 1.0

This function can be called statically.

HTML_QuickForm::removeElement()

HTML_QuickForm::removeElement() – Removes an element

Synopsis

object &HTML_QuickForm::removeElement ( string $elementName , boolean $removeRules = true )

Description

Removes an element from the form.

Parameter

string $elementName

The element name

boolean $removeRules

TRUE if rules for this element are to be removed too

Return value

return reference to element being removed.

Throws

Note

since 2.0

This function can not be called statically.

HTML_QuickForm::setMaxFileSize()

HTML_QuickForm::setMaxFileSize() – Sets the value of MAX_FILE_SIZE hidden element

Synopsis

void HTML_QuickForm::setMaxFileSize ( int $bytes )

Description

Sets the value of MAX_FILE_SIZE hidden element (used for file uploads).

Parameter

integer $bytes

Size in bytes

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

HTML_QuickForm::updateElementAttr()

HTML_QuickForm::updateElementAttr() – Updates Attributes for one or more elements

Synopsis

void HTML_QuickForm::updateElementAttr ( mixed $elements , mixed $attrs )

Description

Updates Attributes for one or more elements

This may not work for groups and group-based elements (date, hierselect). To ensure proper behaviour, you should update attributes of grouped elements manually.

Parameter

mixed $elements

Array of element names/objects or string of elements to be updated

mixed $attrs

Array or string of html attributes

Throws

throws no exceptions thrown

Note

since 2.10

This function can not be called statically.

Classes representing form elements

To be written

Base classes

Class Summary HTML_QuickForm_element

Class Summary HTML_QuickForm_element – Base class for form elements

Description

This is a base class for all QuickForm elements. It defines the API that is implemented by all the child classes representing actual form elements. You should use these elements, there is no need to directly instantiate HTML_QuickForm_element.

If you would like to create your own element to use with QuickForm, you should extend this class or one of its descendants and make sure to implement all methods defined here. There is also toHtml() method defined in HTML_Common that should be implemented.

Class Trees for HTML_QuickForm_element

• HTML_Common
  • HTML_QuickForm_element

constructor HTML_QuickForm_element()

constructor HTML_QuickForm_element() – Class constructor

Synopsis

void constructor HTML_QuickForm_element::HTML_QuickForm_element ( string $elementName = null , mixed $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Name of the element

mixed $elementLabel

Label(s) for the element

mixed $attributes

Associative array of tag attributes or HTML attributes name="value" pairs

Throws

throws no exceptions thrown

See

see setName(), setLabel()

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_element::accept()

HTML_QuickForm_element::accept() – Accepts a renderer

Synopsis

void HTML_QuickForm_element::accept ( object HTML_QuickForm_Renderer &$renderer , bool $required = false , string $error = null )

Description

This method rarely needs to be called directly, it is usually called from HTML_QuickForm::accept() method.

Parameter

object HTML_QuickForm_Renderer &$renderer

an instance of HTML_QuickForm_Renderer subclass

boolean $required

Whether an element is required

string $error

An error message associated with an element

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_element::apiVersion()

HTML_QuickForm_element::apiVersion() – Returns the current API version

Synopsis

float HTML_QuickForm_element::apiVersion ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_element::exportValue()

HTML_QuickForm_element::exportValue() – Returns a 'safe' element's value (package developer related)

Synopsis

mixed HTML_QuickForm_element::exportValue ( array &$submitValues , bool $assoc = false )

Description

This method is not intended to be called directly. It is called by HTML_QuickForm::exportValue() and HTML_QuickForm::exportValues() methods.

The method first tries to find a value for itself in a passed array, if such a value is not found it takes the display value via getValue(). It then filters out the values that cannot possibly be submitted by this element and returns the result.

Parameter

array &$submitValues

array of submitted values to search

boolean $assoc

whether to return the value as associative array

Throws

throws no exceptions thrown

See

see getValue(), HTML_QuickForm::exportValue(), HTML_QuickForm::exportValues().

Note

This function can not be called statically.

HTML_QuickForm_element::freeze()

HTML_QuickForm_element::freeze() – Freezes the element

Synopsis

void HTML_QuickForm_element::freeze ( )

Description

When the element is displayed after the call to freeze(), only its value is displayed without the input tags, thus the element cannot be edited. If persistant freeze is set, then hidden field containing the element value will be output, too.

This method makes sense only with the elements that actually are editable in the first place. It has no effect on buttons, images, hidden fields, static content and the like.

Throws

throws no exceptions thrown

See

see unfreeze(), isFrozen(), setPersistantFreeze(), getFrozenHtml(), HTML_QuickForm::freeze(), HTML_QuickForm::isFrozen().

Note

This function can not be called statically.

Example

Freezing the text element

<?php
require_once 'HTML/QuickForm.php';

$text =& HTML_QuickForm::createElement('text', 'freezeMe');
$text->setValue('Some value');
echo $text->toHtml() . "\n";
$text->freeze();
echo $text->toHtml() . "\n";
$text->setPersistantFreeze(false);
echo $text->toHtml() . "\n";
$text->unfreeze();
echo $text->toHtml() . "\n";
?>

Output

<input name="freezeMe" type="text" value="Some value" />
Some value<input type="hidden" name="freezeMe" value="Some value" />
Some value
<input name="freezeMe" type="text" value="Some value" />

      

HTML_QuickForm_element::getFrozenHtml()

HTML_QuickForm_element::getFrozenHtml() – Returns the value of field without HTML tags

Synopsis

string HTML_QuickForm_element::getFrozenHtml ( )

Description

This method returns the HTML for the element in frozen state. There is rarely a need to call it directly.

Throws

throws no exceptions thrown

See

see isFrozen(), setPersistantFreeze(), freeze().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_element::getLabel()

HTML_QuickForm_element::getLabel() – Returns the label for the element

Synopsis

string HTML_QuickForm_element::getLabel ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setLabel().

Note

since 1.3

This function can not be called statically.

HTML_QuickForm_element::getName()

HTML_QuickForm_element::getName() – Returns the element name

Synopsis

string HTML_QuickForm_element::getName ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setName().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_element::getType()

HTML_QuickForm_element::getType() – Returns the element type

Synopsis

string HTML_QuickForm_element::getType ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_element::getValue()

HTML_QuickForm_element::getValue() – Returns the value of the form element

Synopsis

mixed HTML_QuickForm_element::getValue ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setValue(), HTML_QuickForm::getElementValue().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_element::isFrozen()

HTML_QuickForm_element::isFrozen() – Returns whether or not the element is frozen

Synopsis

bool HTML_QuickForm_element::isFrozen ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see freeze().

Note

since 1.3

This function can not be called statically.

HTML_QuickForm_element::onQuickFormEvent()

HTML_QuickForm_element::onQuickFormEvent() – Called by HTML_QuickForm whenever form event is made on this element (package developer related)

Synopsis

void HTML_QuickForm_element::onQuickFormEvent ( string $event , mixed $arg , object &$caller )

Description

This method is not intended to be called directly.

If you are creating your own element, you should override this method and create handlers for each of available QuickForm events.

'addElement'

This event is sent by HTML_QuickForm::addElement() method when adding a new element to the form. Its handler should usually send 'createElement' and 'updateValue' events.

'createElement'

This event is sent by HTML_QuickForm::createElement() method after the element object is instantiated. Its handler should usually call class constructor using the contents of $arg as parameters.

'setGroupValue'

The event is sent by HTML_QuickForm_group::setValue() method to each of the grouped elements. The handler generally should set the element's value to $arg.

'updateValue'

The event is sent by QuickForm when the element is added to the form and when form default and constant values are set. The handler for this event is the most complex one: it should search for element's value within form's constant, submit (if applicable) and default values (in that order) and set the element's value to the found one.

Parameter

string $event

Name of event

mixed $arg

event arguments

object &$caller

calling object

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_element::setLabel()

HTML_QuickForm_element::setLabel() – Sets a label for the element

Synopsis

void HTML_QuickForm_element::setLabel ( mixed $label )

Description

Label is a description text that will be displayed near the element. Some renderers can handle multiple labels for the element.

Parameter

mixed $label

Display text for the element

Throws

throws no exceptions thrown

See

see getLabel().

Note

since 1.3

This function can not be called statically.

HTML_QuickForm_element::setName()

HTML_QuickForm_element::setName() – Sets the input field name

Synopsis

void HTML_QuickForm_element::setName ( string $name )

Description

This package is not documented yet.

Parameter

string $name

Input field name attribute

Throws

throws no exceptions thrown

See

see getName().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_element::setPersistantFreeze()

HTML_QuickForm_element::setPersistantFreeze() – Sets whether element value should persist on freeze()

Synopsis

void HTML_QuickForm_element::setPersistantFreeze ( bool $persistant = false )

Description

Sets whether an element value should be kept in an hidden field when the element is frozen or not.

Parameter

boolean $persistant

True if persistant value

Throws

throws no exceptions thrown

See

see freeze(), getFrozenHtml().

Note

since 2.0

This function can not be called statically.

HTML_QuickForm_element::setValue()

HTML_QuickForm_element::setValue() – Sets the value of the form element

Synopsis

void HTML_QuickForm_element::setValue ( mixed $value )

Description

This sets the display value for the element. It can be different from its submit value.

Parameter

mixed $value

Default value of the form element

Throws

throws no exceptions thrown

See

see getValue().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_element::unfreeze()

HTML_QuickForm_element::unfreeze() – Unfreezes the element

Synopsis

void HTML_QuickForm_element::unfreeze ( )

Description

Unfreezes the element so that it becomes editable again.

Throws

throws no exceptions thrown

See

see freeze(), isFrozen(), setPersistantFreeze(), getFrozenHtml(), HTML_QuickForm::freeze(), HTML_QuickForm::isFrozen().

Note

This function can not be called statically.

Class Summary HTML_QuickForm_input

Class Summary HTML_QuickForm_input – Base class for input form elements

Description

Since <input> elements have very similar HTML representations, they have this common base class. You don't need to instantiate it directly, use one of the child classes.

Class Trees for HTML_QuickForm_input

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input

HTML_QuickForm_input Inherited Methods

constructor HTML_QuickForm_input()

constructor HTML_QuickForm_input() – Class constructor

Synopsis

void constructor HTML_QuickForm_input::HTML_QuickForm_input ( string $elementName = null , mixed $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

mixed $elementLabel

Label(s) for the input field

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_input::setType()

HTML_QuickForm_input::setType() – Sets the element type

Synopsis

void HTML_QuickForm_input::setType ( string $type )

Description

This package is not documented yet.

Parameter

string $type

Element type

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Standard HTML elements

Class Summary HTML_QuickForm_button

Class Summary HTML_QuickForm_button – HTML class for a button type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_button

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_button

HTML_QuickForm_button Inherited Methods

constructor HTML_QuickForm_button()

constructor HTML_QuickForm_button() – Class constructor

Synopsis

void constructor HTML_QuickForm_button::HTML_QuickForm_button ( string $elementName = null , string $value = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $value

(optional)Input field value

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_checkbox

Class Summary HTML_QuickForm_checkbox – HTML class for a checkbox type field

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_checkbox

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_checkbox

HTML_QuickForm_checkbox Inherited Methods

constructor HTML_QuickForm_checkbox()

constructor HTML_QuickForm_checkbox() – Class constructor

Synopsis

void constructor HTML_QuickForm_checkbox::HTML_QuickForm_checkbox ( string $elementName = null , string $elementLabel = null , string $text = '' , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

string $text

(optional)Checkbox display text

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_checkbox::getChecked()

HTML_QuickForm_checkbox::getChecked() – Returns whether a checkbox is checked

Synopsis

bool HTML_QuickForm_checkbox::getChecked ( )

Description

Returns TRUE if checkbox has a "checked" attribute, FALSE otherwise. getValue() is an alias for this method. Thus the only value checkbox element can have in QuickForm is TRUE.

Throws

throws no exceptions thrown

See

see setChecked().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_checkbox::getText()

HTML_QuickForm_checkbox::getText() – Returns the checkbox text

Synopsis

string HTML_QuickForm_checkbox::getText ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setText().

Note

since 1.1

This function can not be called statically.

HTML_QuickForm_checkbox::setChecked()

HTML_QuickForm_checkbox::setChecked() – Sets whether a checkbox is checked

Synopsis

void HTML_QuickForm_checkbox::setChecked ( bool $checked )

Description

This sets or removes the element's "checked" attribute based on $checked value. setValue() is an alias for this method.

Parameter

boolean $checked

Whether the field is checked or not

Throws

throws no exceptions thrown

See

see getChecked().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_checkbox::setText()

HTML_QuickForm_checkbox::setText() – Sets the checkbox text

Synopsis

void HTML_QuickForm_checkbox::setText ( string $text )

Description

This means the text that would be displayed with the checkbox, automatically enclosed in <label> tags. The label in QuickForm's sense is set via setLabel().

Parameter

string $text

Throws

throws no exceptions thrown

See

see getText().

Note

since 1.1

This function can not be called statically.

Class Summary HTML_QuickForm_file

Class Summary HTML_QuickForm_file – HTML class for a file type element

Description

Alongside the usual element's methods, the class has special methods for working with uploaded files. When the class is included it also registers rules for validating the uploaded files.

Class Trees for HTML_QuickForm_file

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_file

HTML_QuickForm_file Inherited Methods

constructor HTML_QuickForm_file()

constructor HTML_QuickForm_file() – Class constructor

Synopsis

void constructor HTML_QuickForm_file::HTML_QuickForm_file ( string $elementName = null , string $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

string $elementLabel

Input field label

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_file::getSize()

HTML_QuickForm_file::getSize() – Returns size of file element

Synopsis

int HTML_QuickForm_file::getSize ( )

Description

This means 'size' attribute of the <input /> element, not size of the uploaded file.

Throws

throws no exceptions thrown

See

see setSize().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_file::getValue()

HTML_QuickForm_file::getValue() – Returns information about the uploaded file

Synopsis

array HTML_QuickForm_file::getValue ( )

Description

Returns the information about the file upload, as in the $_FILES array. Note that while there exists a setValue() method, the method does nothing at all. The file element does not have a value if the form was not submitted.

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

HTML_QuickForm_file::isUploadedFile()

HTML_QuickForm_file::isUploadedFile() – Checks if the element contains an uploaded file

Synopsis

bool HTML_QuickForm_file::isUploadedFile ( )

Description

This package is not documented yet.

Return value

returns true if file has been uploaded, false otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_file::moveUploadedFile()

HTML_QuickForm_file::moveUploadedFile() – Moves an uploaded file into the destination

Synopsis

bool HTML_QuickForm_file::moveUploadedFile ( string $dest , string $fileName = '' )

Description

This package is not documented yet.

Parameter

string $dest

Destination directory path

string $fileName

New file name (if not given, original file name will be used).

Return value

returns true if file has been moved successfully, false otherwise.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_file::setSize()

HTML_QuickForm_file::setSize() – Sets size of file element

Synopsis

void HTML_QuickForm_file::setSize ( int $size )

Description

This package is not documented yet.

Parameter

integer $size

Size of file element

Throws

throws no exceptions thrown

See

see getSize().

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_hidden

Class Summary HTML_QuickForm_hidden – HTML class for a hidden type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_hidden

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_hidden

HTML_QuickForm_hidden Inherited Methods

constructor HTML_QuickForm_hidden()

constructor HTML_QuickForm_hidden() – Class constructor

Synopsis

void constructor HTML_QuickForm_hidden::HTML_QuickForm_hidden ( string $elementName = null , string $value = '' , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $value

(optional)Input field value

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_image

Class Summary HTML_QuickForm_image – HTML class for a image type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_image

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_image

HTML_QuickForm_image Inherited Methods

constructor HTML_QuickForm_image()

constructor HTML_QuickForm_image() – Class constructor

Synopsis

void constructor HTML_QuickForm_image::HTML_QuickForm_image ( string $elementName = null , string $src = '' , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Element name attribute

string $src

(optional)Image source

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_image::setAlign()

HTML_QuickForm_image::setAlign() – Sets alignment for image element

Synopsis

void HTML_QuickForm_image::setAlign ( string $align )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('align' => $align));
?>

Parameter

string $align

alignment for image element

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_image::setBorder()

HTML_QuickForm_image::setBorder() – Sets border size for image element

Synopsis

void HTML_QuickForm_image::setBorder ( string $border )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('border' => $border));
?>

Parameter

string $border

border for image element

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_image::setSource()

HTML_QuickForm_image::setSource() – Sets source for image element

Synopsis

void HTML_QuickForm_image::setSource ( string $src )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('src' => $src));
?>

Parameter

string $src

source for image element

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_password

Class Summary HTML_QuickForm_password – HTML class for a password type field

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_password

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_password

HTML_QuickForm_password Inherited Methods

constructor HTML_QuickForm_password()

constructor HTML_QuickForm_password() – Class constructor

Synopsis

void constructor HTML_QuickForm_password::HTML_QuickForm_password ( string $elementName = null , string $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_password::setMaxlength()

HTML_QuickForm_password::setMaxlength() – Sets maxlength of password element

Synopsis

void HTML_QuickForm_password::setMaxlength ( string $maxlength )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('maxlength' => $maxlength));
?>

Parameter

string $maxlength

Maximum length of password field

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_password::setSize()

HTML_QuickForm_password::setSize() – Sets size of password element

Synopsis

void HTML_QuickForm_password::setSize ( string $size )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('size' => $size));
?>

Parameter

string $size

Size of password field

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_radio

Class Summary HTML_QuickForm_radio – HTML class for a radio type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_radio

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_radio

HTML_QuickForm_radio Inherited Methods

constructor HTML_QuickForm_radio()

constructor HTML_QuickForm_radio() – Class constructor

Synopsis

void constructor HTML_QuickForm_radio::HTML_QuickForm_radio ( string $elementName = null , mixed $elementLabel = null , string $text = null , string $value = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

mixed $elementLabel

Label(s) for a field

string $text

Text to display near the radio

string $value

Input field value

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_radio::getChecked()

HTML_QuickForm_radio::getChecked() – Returns whether radio button is checked

Synopsis

string HTML_QuickForm_radio::getChecked ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setChecked().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_radio::getText()

HTML_QuickForm_radio::getText() – Returns the radio text

Synopsis

string HTML_QuickForm_radio::getText ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setText().

Note

since 1.1

This function can not be called statically.

HTML_QuickForm_radio::setChecked()

HTML_QuickForm_radio::setChecked() – Sets whether radio button is checked

Synopsis

void HTML_QuickForm_radio::setChecked ( bool $checked )

Description

This package is not documented yet.

Parameter

boolean $checked

Whether the field is checked or not

Throws

throws no exceptions thrown

See

see getChecked().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_radio::setText()

HTML_QuickForm_radio::setText() – Sets the radio text

Synopsis

void HTML_QuickForm_radio::setText ( string $text )

Description

This means the text that would be displayed with the radio, automatically enclosed in <label> tags. The label in QuickForm's sense is set via setLabel().

Parameter

string $text

Text to display near the radio button

Throws

throws no exceptions thrown

See

see getText().

Note

since 1.1

This function can not be called statically.

Class Summary HTML_QuickForm_reset

Class Summary HTML_QuickForm_reset – HTML class for a reset type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_reset

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_reset

HTML_QuickForm_reset Inherited Methods

constructor HTML_QuickForm_reset()

constructor HTML_QuickForm_reset() – Class constructor

Synopsis

void constructor HTML_QuickForm_reset::HTML_QuickForm_reset ( string $elementName = null , string $value = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $value

(optional)Input field value

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_select

Class Summary HTML_QuickForm_select – Class to dynamically create an HTML SELECT

Description

The highlight of this class is that it allows populating the options from associative array or from the database.

Class Trees for HTML_QuickForm_select

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_select

HTML_QuickForm_select Inherited Methods

constructor HTML_QuickForm_select()

constructor HTML_QuickForm_select() – Class constructor

Synopsis

void constructor HTML_QuickForm_select::HTML_QuickForm_select ( string $elementName = null , mixed $elementLabel = null , mixed $options = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Select name attribute

mixed $elementLabel

Label(s) for the select

mixed $options

Data to be used to populate options

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

See

see load().

Note

since 1.0

This function can not be called statically.

Example

<?php
$select = $quickform->createElement(
    'select', 'selectname',
    'Label for select',
    array('fr' => 'French', 'de' => 'German', 'en_GB' => 'British English'),
    array('id' => 'selectname', 'onchange' => '...'));
);
?>

HTML_QuickForm_select::addOption()

HTML_QuickForm_select::addOption() – Adds a new OPTION to the SELECT

Synopsis

void HTML_QuickForm_select::addOption ( string $text , string $value , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $text

Display text for the OPTION

string $value

Value for the OPTION

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_select::getMultiple()

HTML_QuickForm_select::getMultiple() – Returns the select mutiple attribute

Synopsis

bool HTML_QuickForm_select::getMultiple ( )

Description

This method returns TRUE if a multiple attribute is present in the select, FALSE otherwise.

Return value

returns true if multiple select, false otherwise

Throws

throws no exceptions thrown

See

see setMultiple().

Note

since 1.2

This function can not be called statically.

HTML_QuickForm_select::getPrivateName()

HTML_QuickForm_select::getPrivateName() – Returns the element name (possibly with brackets appended)

Synopsis

string HTML_QuickForm_select::getPrivateName ( )

Description

If select has a multiple attribute present, then this method returns the name with brackets appended, else the result is identical to getName().

Throws

throws no exceptions thrown

See

see getName(), getMultiple().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_select::getSelected()

HTML_QuickForm_select::getSelected() – Returns an array of the selected values

Synopsis

array HTML_QuickForm_select::getSelected ( )

Description

This function is an alias to getValue().

Return value

returns of selected values

Throws

throws no exceptions thrown

See

see getValue(), setSelected().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_select::getSize()

HTML_QuickForm_select::getSize() – Returns the select field size

Synopsis

int HTML_QuickForm_select::getSize ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setSize().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_select::load()

HTML_QuickForm_select::load() – Loads options from different types of data sources

Synopsis

PEAR_Error HTML_QuickForm_select::load ( mixed &$options , mixed $param1 = null , mixed $param2 = null , mixed $param3 = null , mixed $param4 = null )

Description

This method is a simulated overloaded method. The arguments, other than the first are optional and only mean something depending on the type of the first argument.

If the first argument is an array then all arguments are passed in order to loadArray(). If the first argument is a DB_Result then all arguments are passed in order to loadDbResult(). If the first argument is a string or a DB connection then all arguments are passed in order to loadQuery().

Parameter

mixed &$options

Options source currently supports assoc array or DB_result

mixed $param1

(optional) See function detail

mixed $param2

(optional) See function detail

mixed $param3

(optional) See function detail

mixed $param4

(optional) See function detail

Return value

returns TRUE on success

Throws

throws PEAR_Error

See

see loadArray(), loadDbResult(), loadQuery().

Note

since 1.1

This function can not be called statically.

HTML_QuickForm_select::loadArray()

HTML_QuickForm_select::loadArray() – Loads the options from an associative array

Synopsis

mixed HTML_QuickForm_select::loadArray ( array $arr , mixed $values = null )

Description

The array should have the form 'option value' => 'option text'.

Parameter

array $arr

Associative array of options

mixed $values

(optional) Array or comma delimited string of selected values

Return value

returns TRUE on success

Throws

throws PEAR_Error

See

see load(), addOption().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_select::loadDbResult()

HTML_QuickForm_select::loadDbResult() – Loads the options from DB_result object

Synopsis

mixed HTML_QuickForm_select::loadDbResult ( object DB_Result &$result , string $textCol = null , string $valueCol = null , mixed $values = null )

Description

If no column names are specified the first two columns of the result are used as the text and value columns respectively.

Parameter

object &$result

DB_result object

string $textCol

(optional) Name of column to display as the OPTION text

string $valueCol

(optional) Name of column to use as the OPTION value

mixed $values

(optional) Array or comma delimited string of selected values

Return value

returns TRUE on success or PEAR_Error

Throws

throws PEAR_Error

See

see load(), addOption().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_select::loadQuery()

HTML_QuickForm_select::loadQuery() – Queries a database and loads the options from the results

Synopsis

mixed HTML_QuickForm_select::loadQuery ( mixed &$conn , string $sql , string $textCol = null , string $valueCol = null , mixed $values = null )

Description

If no column names are specified the first two columns of the result are used as the text and value columns respectively.

Parameter

mixed &$conn

Either an existing DB connection or a valid dsn

string $sql

SQL query string

string $textCol

(optional) Name of column to display as the OPTION text

string $valueCol

(optional) Name of column to use as the OPTION value

mixed $values

(optional) Array or comma delimited string of selected values

Throws

throws PEAR_Error

See

see load(), loadDbResult(), addOption().

Note

since 1.1

This function can not be called statically.

HTML_QuickForm_select::setMultiple()

HTML_QuickForm_select::setMultiple() – Sets the select mutiple attribute

Synopsis

void HTML_QuickForm_select::setMultiple ( bool $multiple )

Description

This method just adds or removes the multiple attribute of select depending on $multiple value.

Parameter

boolean $multiple

Whether the select supports multi-selections

Throws

throws no exceptions thrown

See

see getMultiple().

Note

since 1.2

This function can not be called statically.

HTML_QuickForm_select::setSelected()

HTML_QuickForm_select::setSelected() – Sets the default values of the select box

Synopsis

void HTML_QuickForm_select::setSelected ( mixed $values )

Description

This method is an alias for setValue(). For multiple selects you can pass either an array or a comma delimited string of values.

Parameter

mixed $values

Array or comma delimited string of selected values

Throws

throws no exceptions thrown

See

see getSelected().

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_select::setSize()

HTML_QuickForm_select::setSize() – Sets the select field size, only applies to 'multiple' selects

Synopsis

void HTML_QuickForm_select::setSize ( int $size )

Description

This package is not documented yet.

Parameter

integer $size

Size of select field

Throws

throws no exceptions thrown

See

see getSize().

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_submit

Class Summary HTML_QuickForm_submit – HTML class for a submit type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_submit

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_submit

HTML_QuickForm_submit Inherited Methods

constructor HTML_QuickForm_submit()

constructor HTML_QuickForm_submit() – Class constructor

Synopsis

void constructor HTML_QuickForm_submit::HTML_QuickForm_submit ( string $elementName = null , string $value = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

string $value

Input field value

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_text

Class Summary HTML_QuickForm_text – HTML class for a text field

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_text

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_text

HTML_QuickForm_text Inherited Methods

constructor HTML_QuickForm_text

constructor HTML_QuickForm_text – Class constructor

Synopsis

void constructor HTML_QuickForm_text::HTML_QuickForm_text ( string $elementName = null , string $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_text::setMaxlength()

HTML_QuickForm_text::setMaxlength() – Sets maxlength of text field

Synopsis

void HTML_QuickForm_text::setMaxlength ( string $maxlength )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('maxlength' => $maxlength));
?>

Parameter

string $maxlength

Maximum length of text field

Throws

throws no exceptions thrown

Note

since 1.3

This function can not be called statically.

HTML_QuickForm_text::setSize()

HTML_QuickForm_text::setSize() – Sets size of text field

Synopsis

void HTML_QuickForm_text::setSize ( string $size )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('size' => $size));
?>

Parameter

string $size

Size of text field

Throws

throws no exceptions thrown

Note

since 1.3

This function can not be called statically.

Class Summary HTML_QuickForm_textarea

Class Summary HTML_QuickForm_textarea – HTML class for a textarea type field

HTML class for a textarea type field

This package is not documented yet.

Class Trees for HTML_QuickForm_textarea

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_textarea

HTML_QuickForm_textarea Inherited Methods

constructor HTML_QuickForm_textarea()

constructor HTML_QuickForm_textarea() – Class constructor

Synopsis

void constructor HTML_QuickForm_textarea::HTML_QuickForm_textarea ( string $elementName = null , mixed $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

mixed $elementLabel

Label(s) for a field

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_textarea::setCols()

HTML_QuickForm_textarea::setCols() – Sets width in cols for textarea element

Synopsis

void HTML_QuickForm_textarea::setCols ( string $cols )

Description

This package is not documented yet.

Parameter

string $cols

Width expressed in cols

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_textarea::setRows()

HTML_QuickForm_textarea::setRows() – Sets height in rows for textarea element

Synopsis

void HTML_QuickForm_textarea::setRows ( string $rows )

Description

This package is not documented yet.

Parameter

string $rows

Height expressed in rows

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_textarea::setWrap()

HTML_QuickForm_textarea::setWrap() – Sets wrap type for textarea element

Synopsis

void HTML_QuickForm_textarea::setWrap ( string $wrap )

Description

This package is not documented yet.

Parameter

string $wrap

Wrap type

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_xbutton

Class Summary HTML_QuickForm_xbutton – Class for HTML 4.0 <button> element

Class for HTML 4.0 <button> element

This class is named 'xbutton' since the name 'button' was already taken by class representing an <input type="button" /> HTML element. Available since HTML_QuickForm release 3.2.3

Class Trees for HTML_QuickForm_xbutton

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_xbutton

HTML_QuickForm_xbutton Inherited Methods

constructor HTML_QuickForm_xbutton()

constructor HTML_QuickForm_xbutton() – Class constructor

Synopsis

void constructor HTML_QuickForm_xbutton::HTML_QuickForm_xbutton ( string $elementName = null , string $elementContent = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional) Button name

string $elementContent

(optional) Button content (HTML to add between <button></button> tags)

mixed $attributes

(optional) Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

since 3.2.3

HTML_QuickForm_xbutton::setContent()

HTML_QuickForm_xbutton::setContent() – Sets the contents of the element

Synopsis

void HTML_QuickForm_xbutton::setContent ( string $content )

Description

Sets the contents of the button element: HTML to add between <button></button> tags.

Parameter

string $content

HTML to add between <button></button> tags

Throws

throws no exceptions thrown

Note

This function can not be called statically.

since 3.2.3

Custom elements

Class Summary HTML_QuickForm_advcheckbox

Class Summary HTML_QuickForm_advcheckbox – HTML class for an advanced checkbox type field

Description

HTML class for an advanced checkbox type field. Basically this fixes a problem that HTML has had where checkboxes can only pass a single value (the value of the checkbox when checked). A value for when the checkbox is not checked cannot be passed, and furthermore the checkbox variable doesn't even exist if the checkbox was submitted unchecked.

It works by creating a hidden field with the passed-in name and creating the checkbox with no name, but with a javascript onclick which sets the value of the hidden field.

Class Trees for HTML_QuickForm_advcheckbox

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_checkbox
        • HTML_QuickForm_advcheckbox

HTML_QuickForm_advcheckbox Inherited Methods

constructor HTML_QuickForm_advcheckbox()

constructor HTML_QuickForm_advcheckbox() – Class constructor

Synopsis

void constructor HTML_QuickForm_advcheckbox::HTML_QuickForm_advcheckbox ( string $elementName = null , string $elementLabel = null , string $text = null , mixed $attributes = null , mixed $values = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

string $text

(optional)Text to put after the checkbox

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

mixed $values

(optional)Values to pass if checked or not checked

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_advcheckbox::getOnclickJs()

HTML_QuickForm_advcheckbox::getOnclickJs() – Create the javascript for the onclick event

Synopsis

string HTML_QuickForm_advcheckbox::getOnclickJs ( string $elementName )

Description

Create the javascript for the onclick event which will set the value of the hidden field.

Parameter

string $elementName

The element name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_advcheckbox::getPrivateName()

HTML_QuickForm_advcheckbox::getPrivateName() – Gets the private name for the element

Synopsis

string HTML_QuickForm_advcheckbox::getPrivateName ( string $elementName )

Description

This is the name that will be used by the actual checkbox.

Parameter

string $elementName

The element name to make private

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_advcheckbox::setValues()

HTML_QuickForm_advcheckbox::setValues() – Sets the values used by the hidden element

Synopsis

void HTML_QuickForm_advcheckbox::setValues ( mixed $values )

Description

If $values is a string then it will be used for checked state. If it is an array, then $values[0] will be used for unchecked state and $values[1] for checked.

Parameter

mixed $values

The values, either a string or an array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary HTML_QuickForm_autocomplete

Class Summary HTML_QuickForm_autocomplete – HTML class for a text field with autocompletion feature

Description

The element looks like a normal HTML input text element that at every keypressed javascript event searches the array of options for a match and autocompletes the text in case of match. This is similar to the browsers' behaviour when one enters the URL into the Address field.

Class Trees for HTML_QuickForm_autocomplete

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_input
      • HTML_QuickForm_text
        • HTML_QuickForm_text

HTML_QuickForm_autocomplete Inherited Methods

constructor HTML_QuickForm_autocomplete

constructor HTML_QuickForm_autocomplete – Class constructor

Synopsis

void constructor HTML_QuickForm_autocomplete::HTML_QuickForm_autocomplete ( string $elementName = null , string $elementLabel = null , array $options = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

array $options

Autocomplete options

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_autocomplete::setoptions()

HTML_QuickForm_autocomplete::setoptions() – Sets the options for the autocomplete input text element

Synopsis

void HTML_QuickForm_autocomplete::setOptions ( array $options )

Description

The strings in this array will be checked by the javascript function for a match with the text being typed. In case of a match the text will be autocompleted.

Parameter

array $options

Array of options for the autocomplete input text element

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary HTML_QuickForm_date

Class Summary HTML_QuickForm_date – Class for a group of elements used to input dates (and times).

Description

The element is basically a group of <select>s that allow to input dates and times.

Class Trees for HTML_QuickForm_date

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_group
      • HTML_QuickForm_date

HTML_QuickForm_date Inherited Methods

constructor HTML_QuickForm_date()

constructor HTML_QuickForm_date() – Class constructor

Synopsis

void constructor HTML_QuickForm_date::HTML_QuickForm_date ( string $elementName = null , mixed $elementLabel = null , array $options = array() , mixed $attributes = null )

Description

The $options parameter controls the element's appearance. It is an associative array of the form 'option name' => 'option value'.

'language'

Language code to use for display. Default is 'en'. date element supports many languages. If your one is not supported, send us the translation, we'll gladly include it.

'format'

Format string for the date, based on PHP's date() function. The following characters are recognised:

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
y => Two digit year
h => 12 hour format
H => 23 hour  format
i => Minutes
s => Seconds
a => am/pm
A => AM/PM
g => 12 hour format w/o leading zeroes
W => week of the year

Default is 'dMY'.

'minYear'

Minimum year in year select. Default is 2001.

'maxYear'

Maximum year in year select. Default is 2010.

On 'minYear' and 'maxYear'

When 'minYear' > 'maxYear' the years in the select will be displayed in descending order.

'addEmptyOption'

Should an empty option be added to the top of each select box? Default is FALSE. This may be set for individual fields also, if one passes an array of the form array('format char' => TRUE, ..., 'another format char' => FALSE)

'emptyOptionValue'

The value passed by the empty option. Default is ''.

'emptyOptionText'

The text displayed for the empty option. Default is ' '. This may be set for individual fields also, if one passes an array of the form array('format char' => 'some text', ..., 'another format char' => 'some other text')

'optionIncrement'

Step to increase the option values by. Works for 'i' and 's' formats currently. Default is array('i' => 1, 's' => 1).

Parameter

string $elementName

Element's name

mixed $elementLabel

Label(s) for an element

array $options

Options to control the element's display

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary HTML_QuickForm_header

Class Summary HTML_QuickForm_header – A pseudo-element used for adding headers to form

Description

This element is used for adding headers to the form. Unlike usual static elements, the headers are usually rendered using a special template.

Class Trees for HTML_QuickForm_header

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_static
      • HTML_QuickForm_header

HTML_QuickForm_header Inherited Methods

constructor HTML_QuickForm_header()

constructor HTML_QuickForm_header() – Class constructor

Synopsis

void constructor HTML_QuickForm_header::HTML_QuickForm_header ( string $elementName = null , string $text = null )

Description

This package is not documented yet.

Parameter

string $elementName

Header name

string $text

Header text

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary HTML_QuickForm_hiddenselect

Class Summary HTML_QuickForm_hiddenselect – Creates hidden elements with select's values

Description

This class takes the same arguments as a select element, but instead of creating a <select> it creates hidden elements for all values already selected with setDefaults() or setConstants(). This is useful if you have a select ring that you don't want visible, but you need all selected values to be passed.

Class Trees for HTML_QuickForm_hiddenselect

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_select
      • HTML_QuickForm_hiddenselect

HTML_QuickForm_hiddenselect Inherited Methods

constructor HTML_QuickForm_hiddenselect()

constructor HTML_QuickForm_hiddenselect() – Class constructor

Synopsis

void constructor HTML_QuickForm_hiddenselect::HTML_QuickForm_hiddenselect ( string $elementName = null , mixed $elementLabel = null , mixed $options = null , mixed $attributes = null )

Description

Note that some parameters are unused, as the element is in fact hidden.

Parameter

string $elementName

Select name attribute

mixed $elementLabel

Label(s) for the select (not used)

mixed $options

Data to be used to populate options

mixed $attributes

Either a typical HTML attribute string or an associative array (not used)

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_hierselect

Class Summary HTML_QuickForm_hierselect – Class to dynamically create chained HTML Select elements, each select changes the content of the next.

Description

Class to dynamically create "chained" HTML Select elements. Choosing an option in the first <select> changes the content of the second select and so on.

This element is considered as a group. Selects will be named groupName[0], groupName[1], ...

Creating a hierselect element based on values from a database table

<?php
require_once 'HTML/QuickForm.php';
$form = new HTML_QuickForm('example');

$form->setDefaults(array('test' => array('4','15')));
$sel =& $form->addElement('hierselect', 'test', 'Test:', null, '/');

$mainOptions = $db->getAssoc('select pkparent, par_desc from parent');

$result = $db->query("select fk_parent, pkchild, chi_desc from child");
while ($result->fetchInto($row)) {
    $secOptions[$row[0]][$row[1]] = $row[2];
}
// Using setMainOptions and setSecOptions is now deprecated 
// use setOptions.

$sel->setOptions(array($mainOptions, $secOptions));

$form->display();
?>

Creating more than two select elements is just as simple.

Creating a hierselect element with three select elements

<?php
require_once 'HTML/QuickForm.php';
$form = new HTML_QuickForm('example');

$select1[0] = 'Pop';
$select1[1] = 'Classical';
$select1[2] = 'Funeral doom';

// second select
$select2[0][0] = '--- Artist ---';
$select2[0][1] = 'Red Hot Chil Peppers';
$select2[0][2] = 'The Pixies';
      
$select2[1][0] = '--- Artist ---';
$select2[1][1] = 'Wagner';
$select2[1][2] = 'Strauss';
      
$select2[2][0] = '--- Artist ---';
$select2[2][1] = 'Pantheist';
$select2[2][2] = 'Skepticism';
     
// Create a third select with prices for the cds
$select3[0][0][0] = '--- Choose the artist ---';
$select3[0][1][0] = '15.00$';
$select3[0][2][1] = '17.00$';
$select3[1][0][0] = '--- Choose the artist ---';
$select3[1][1][0] = '15.00$';
$select3[1][2][1] = '17.00$';
$select3[2][0][0] = '--- Choose the artist ---';
$select3[2][1][0] = '15.00$';
$select3[2][2][1] = '17.00$';     

// Create the Element
$sel =& $form->addElement('hierselect', 'cds', 'Choose CD:');

// And add the selection options
$sel->setOptions(array($select1, $select2, $select3));

$form->display();
?>

Class Trees for HTML_QuickForm_hierselect

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_group
      • HTML_QuickForm_hierselect

HTML_QuickForm_hierselect Inherited Methods

constructor HTML_QuickForm_hierselect()

constructor HTML_QuickForm_hierselect() – Class constructor

Synopsis

void constructor HTML_QuickForm_hierselect::HTML_QuickForm_hierselect ( string $elementName = null , string $elementLabel = null , mixed $attributes = null , mixed $separator = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

If you are displaying several forms on one page, then hierselects in these forms should have unique names. In the other case the values for last hierselect with the same name will overwrite the values for the previous one. It is extremely difficult to cleanly fix this behaviour with current QuickForm architecture, therefore please rely on this workaround. See Request #5718.

string $elementLabel

(optional)Input field label in form

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array.

mixed $separator

String to separate the grouped elements

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_hierselect::setOptions()

HTML_QuickForm_hierselect::setOptions() – Sets the options for the select elements

Synopsis

void HTML_QuickForm_hierselect::setOptions ( array $options )

Description

Sets the options for the select elements within hierselect. Note that the actual number of selects that will be displayed is governed by the number of the elements in the array passed to this function.

Parameter

array $options

Array of options for the elements, having the following structure:

array(
  // options for the first element
  array(
    'key_1' => 'value 1',
    'key_2' => 'value 2',
    ...
    'key_N' => 'value N',
  ),
  // options for the second element
  array(
    'key_1' => array(
      'key_1_1' => 'value 1.1',
      'key_1_2' => 'value 1.2',
      ...
      'key_1_M1' => 'value 1.M1'
    ),
    'key_2' => array(
      'key_2_1' => 'value 2.1',
      'key_2_2' => 'value 2.2',
      ...
      'key_2_M2' => 'value 2.M2'
    ),
    ...
    'key_N' => array(
      'key_N_1' => 'value N.1',
      'key_N_2' => 'value N.2',
      ...
      'key_N_MN' => 'value N.MN'
    )
  )
  // options for further elements
  ...
)

The options for subsequent elements should have keys for all options of the previous elements. Having a select without options is invalid HTML and will break hierselect's JavaScript. See also Bug #5218.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

since 3.2.2

Example

Setting the hierselect options

<?php
$select1 = $select2 = $select3 = array();

$select1[0] = 'Pop';
$select1[1] = 'Classical';
$select1[2] = 'Funeral doom';

// second select
$select2[0][0] = '--- Artist ---';
$select2[0][1] = 'Red Hot Chil Peppers';
$select2[0][2] = 'The Pixies';
      
$select2[1][0] = '--- Artist ---';
$select2[1][1] = 'Wagner';
$select2[1][2] = 'Strauss';
      
$select2[2][0] = '--- Artist ---';
$select2[2][1] = 'Pantheist';
$select2[2][2] = 'Skepticism';
     
// Create a third select with prices for the cds
$select3[0][0][0] = '--- Choose the artist ---';
$select3[0][1][0] = '15.00$';
$select3[0][2][1] = '17.00$';
$select3[1][0][0] = '--- Choose the artist ---';
$select3[1][1][0] = '15.00$';
$select3[1][2][1] = '17.00$';
$select3[2][0][0] = '--- Choose the artist ---';
$select3[2][1][0] = '15.00$';
$select3[2][2][1] = '17.00$';     

// Create the Element
$sel =& $form->addElement('hierselect', 'cds', 'Choose CD:');

// And add the selection options
$sel->setOptions(array($select1, $select2, $select3));
?>

HTML_QuickForm_hierselect::setMainOptions()

HTML_QuickForm_hierselect::setMainOptions() – DEPRECATED: Sets the options for the first select

Synopsis

void HTML_QuickForm_hierselect::setMainOptions ( array $options )

Description

Format is standard key/value pairs for select elements. Example is available in the docs for setSecOptions().

This method has been deprecated. Use setOptions() instead.

Parameter

array $options

Array of options for the first select

Throws

throws no exceptions thrown

See

see HTML_QuickForm_select::loadArray(), setSecOptions().

Note

This function can not be called statically.

This function is deprecated. That means that future versions of this package may not support it anymore.

Deprecated in release 3.2.2

HTML_QuickForm_hierselect::setSecOptions()

HTML_QuickForm_hierselect::setSecOptions() – DEPRECATED: Sets the options for the secondary select

Synopsis

void HTML_QuickForm_hierselect::setSecOptions ( array $options )

Description

Sets the options for the secondary select. Options are passed as a two-dimensional array, where the first key is parent id and the second key is child id, as it is needed to know the parent option to which the secondary option relates.

This method has been deprecated. Use setOptions() instead.

Parameter

array $options

Array of options for the second select

Throws

throws no exceptions thrown

See

see setMainOptions().

Note

This function can not be called statically.

This function is deprecated. That means that future versions of this package may not support it anymore.

Deprecated in release 3.2.2

Example

Setting the hierselect options

<?php
$hierSel =& $form->addElement('hierselect', 'test', 'Test:', null, '/');

$main[0] = 'Pop';
$main[1] = 'Classical';
$main[2] = 'Funeral doom';

$sec[0][1] = 'Red Hot Chili Peppers';
$sec[0][2] = 'The Pixies';
$sec[1][3] = 'Wagner';
$sec[1][4] = 'Strauss';
$sec[2][5] = 'Pantheist';
$sec[2][6] = 'Skepticism';

$hierSel->setMainOptions($main);
$hierSel->setSecOptions($sec);
?>

Class Summary HTML_QuickForm_html

Class Summary HTML_QuickForm_html – A pseudo-element used for adding raw HTML to form (deprecated)

Description

A pseudo-element used for adding raw HTML to form output. Its contents are output as is, without applying any element template.

This element is deprecated. No fixes and changes to its behaviour will be done and it will be removed in the next major version of the package. If you really need to add raw html to the form, you may consider using 'static' element instead.

The element can be used with the Default Renderer only, all other Renderers completely ignore this. Consider using some template-based renderer instead of relying on this feature.

Class Trees for HTML_QuickForm_html

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_static
      • HTML_QuickForm_html

HTML_QuickForm_html Inherited Methods

constructor HTML_QuickForm_html()

constructor HTML_QuickForm_html() – Class constructor

Synopsis

void constructor HTML_QuickForm_html::HTML_QuickForm_html ( string $text = null )

Description

This package is not documented yet.

Parameter

string $text

raw HTML to add

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary HTML_QuickForm_link

Class Summary HTML_QuickForm_link – HTML class for a link type field

Description

This is used to add <a href="...">...</a> tag within a standard element template.

Class Trees for HTML_QuickForm_link

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_static
      • HTML_QuickForm_link

HTML_QuickForm_link Inherited Methods

constructor HTML_QuickForm_link()

constructor HTML_QuickForm_link() – Class constructor

Synopsis

void constructor HTML_QuickForm_link::HTML_QuickForm_link ( mixed $elementName = null , string $elementLabel = null , string $href = null , string $text = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

mixed $elementName

string $elementLabel

(optional)Link label

string $href

(optional)Link href

string $text

(optional)Link display text

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_link::setHref()

HTML_QuickForm_link::setHref() – Sets the links href

Synopsis

void HTML_QuickForm_link::setHref ( string $href )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('href' => $href));
?>

Parameter

string $href

Throws

throws

Note

since 1.0

This function can not be called statically.

Class Summary HTML_QuickForm_static

Class Summary HTML_QuickForm_static – HTML class for static data

Description

A static element is an element that cannot have a submit value and thus cannot change due to user input. Such elements are usually used to improve form presentation. Note that elements of HTML_QuickForm_static type are by default rendered inside the same template as the normal form elements.

Class Trees for HTML_QuickForm_static

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_static

HTML_QuickForm_static Inherited Methods

constructor HTML_QuickForm_static()

constructor HTML_QuickForm_static() – Class constructor

Synopsis

void constructor HTML_QuickForm_static::HTML_QuickForm_static ( string $elementName = null , mixed $elementLabel = null , string $text = null )

Description

This package is not documented yet.

Parameter

string $elementName

Name of the element

mixed $elementLabel

(optional)Label

string $text

(optional)Display text

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_static::setText()

HTML_QuickForm_static::setText() – Sets the text

Synopsis

void HTML_QuickForm_static::setText ( string $text )

Description

This text is essentially the static element itself. Note that setValue() is an alias for setText().

Parameter

string $text

text of the element

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Using groups

To be written.

HTML_QuickForm::addGroup()

HTML_QuickForm::addGroup() – Adds an element group

Synopsis

object &HTML_QuickForm::addGroup ( array $elements , string $name = null , mixed $groupLabel = '' , string $separator = null , string $appendName = true )

Description

Adds an element group.

Parameter

array $elements

array of elements composing the group

string $name

(optional) group name

mixed $groupLabel

(optional) group label

mixed $separator

(optional) string or array of strings to separate elements

boolean $appendName

(optional) specify whether the group name should be used in the form element name: groupName[elementName] vs elementName

Return value

return reference to added group of elements

Throws

Note

since 2.8

This function can not be called statically.

Example

Using addGroup()

<?php

$group[] =& HTML_QuickForm::createElement('text', 'first', 'First');
$group[] =& HTML_QuickForm::createElement('text', 'last', 'Last');

$form->addGroup($group, 'name', 'Name:', ',&nbsp;');

?>

Class Summary HTML_QuickForm_group

Class Summary HTML_QuickForm_group – HTML class for a form element group

Description

Groups allow you to combine several individual elements into one entity and to use it as usual form element. Most of the group's methods use the methods of the grouped elements to do their job. For example, groups do not have values themselves, their setValue() and getValue() methods just call the appropriate methods of grouped elements to set and get their values.

Groups can be used both for visual grouping of the elements (e.g. putting "Submit" and "Reset" buttons on one line), grouping of the elements with the same name (e.g. groups of checkboxes and radiobuttons) and logical grouping of the elements (e.g. group for person's name consisting of two text fields for first and last name).

Class Trees for HTML_QuickForm_group

• HTML_Common
  • HTML_QuickForm_element
    • HTML_QuickForm_group

HTML_QuickForm_group Inherited Methods

constructor HTML_QuickForm_group()

constructor HTML_QuickForm_group() – Class constructor

Synopsis

void constructor HTML_QuickForm_group::HTML_QuickForm_group ( string $elementName = null , array $elementLabel = null , array $elements = null , mixed $separator = null , bool $appendName = true )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Group name

array $elementLabel

(optional)Group label

array $elements

(optional)Group elements

mixed $separator

(optional)Use a string for one separator, use an array to alternate the separators.

boolean $appendName

(optional)whether to change elements' names to the form $groupName[$elementName] or leave them as is.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_group::getElementName()

HTML_QuickForm_group::getElementName() – Returns the name of an element inside the group

Synopsis

mixed HTML_QuickForm_group::getElementName ( mixed $index )

Description

Returns the name of an element inside the group. This is the name that will be shown in the form HTML output.

Parameter

mixed $index

Element name or element index in the group

Return value

returns string with element name, false if not found

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

HTML_QuickForm_group::getElements()

HTML_QuickForm_group::getElements() – Gets the grouped elements

Synopsis

array &HTML_QuickForm_group::getElements ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

since 2.4

This function can not be called statically.

HTML_QuickForm_group::getGroupType()

HTML_QuickForm_group::getGroupType() – Gets the group type based on its elements.

Synopsis

string HTML_QuickForm_group::getGroupType ( )

Description

Will return 'mixed' if elements contained in the group are of different types.

Return value

returns group elements type

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_group::setElements()

HTML_QuickForm_group::setElements() – Sets the grouped elements

Synopsis

void HTML_QuickForm_group::setElements ( array $elements )

Description

This package is not documented yet.

Parameter

array $elements

Array of elements

Throws

throws no exceptions thrown

Note

since 1.1

This function can not be called statically.

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

HTML_QuickForm::setConstants()

HTML_QuickForm::setConstants() – Sets constant form values

Synopsis

void HTML_QuickForm::setConstants ( array $constantValues = null , mixed $filter = null )

Description

Sets constant form values. These values won't be overridden by either default (set via setDefaults()) or submitted (POST or GET) values.

Parameter

array $constantValues

values used to fill the form, array('element name' => 'element value')

mixed $filter

(optional) filter(s) to apply to all default values

Throws

Note

since 2.0

This function can not be called statically.

HTML_QuickForm::setDefaults()

HTML_QuickForm::setDefaults() – Sets default form values

Synopsis

void HTML_QuickForm::setDefaults ( array $defaultValues = null , mixed $filter = null )

Description

Sets default form values. There are overriden by either constant (set via setConstants()) or submitted (POST or GET) values.

Parameter

array $defaultValues

values used to fill the form, array('element name' => 'element value')

mixed $filter

(optional) filter(s) to apply to all default values

Throws

Note

since 1.0

This function can not be called statically.

HTML_QuickForm::isSubmitted()

HTML_QuickForm::isSubmitted() – Tells whether the form was already submitted

Synopsis

boolean HTML_QuickForm::isSubmitted ( void )

Description

Tells whether the form was already submitted. Using this method when $trackSubmit parameter of QuickForm's constructor is used is more reliable than checking whether form's submit values are empty.

Throws

throws no exceptions thrown