Docs For Class HTML

HTML_QuickForm (Constructor) [line 284]

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

Class constructor

Access: public

Parameters:

string	`$formName`	—	Form's name.
string	`$method`	—	(optional)Form's method defaults to 'POST'
string	`$action`	—	(optional)Form's action
string	`$target`	—	(optional)Form's target defaults to '_self'
mixed	`$attributes`	—	(optional)Extra attributes for <form> tag
bool	`$trackSubmit`	—	(optional)Whether to track if the form was submitted by adding a special hidden field

[ Top ]

accept [line 1680]

void accept(
object An
&$renderer)

Accepts a renderer

Since: 3.0
Access: public

Parameters:

object An &$renderer — HTML_QuickForm_Renderer object

[ Top ]

addElement [line 626]

HTML_QuickForm_Element &addElement(
mixed
$element)

Adds an element into the form

If $element is a string representing element type, then this method accepts variable number of parameters, their meaning and count depending on $element

Return: a reference to newly added element
Since: 1.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

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

[ Top ]

addFormRule [line 1221]

void addFormRule(
mixed
$rule)

Adds a global validation rule

This should be used when for a rule involving several fields or if you want to use some completely custom validation for your form. The rule function/method should return true in case of successful validation and array('element name' => 'error') when there were errors.

Throws: HTML_QuickForm_Error
Access: public

Parameters:

mixed $rule — Callback, either function name or array(&$object, 'method')

[ Top ]

addGroup [line 749]

HTML_QuickForm_group &addGroup(
array
$elements, [string
$name = null], [string
$groupLabel = ''], [string
$separator = null], [string
$appendName = true])

Adds an element group

Return: reference to a newly added group
Since: 2.8
Throws: HTML_QuickForm_Error
Access: public

Parameters:

array	`$elements`	—	array of elements composing the group
string	`$name`	—	(optional)group name
string	`$groupLabel`	—	(optional)group label
string	`$separator`	—	(optional)string to separate elements
string	`$appendName`	—	(optional)specify whether the group name should be used in the form element name ex: group[element]

[ Top ]

addGroupRule [line 1131]

void addGroupRule(
string
$group, mixed
$arg1, [string
$type = ''], [string
$format = null], [int
$howmany = 0], [string
$validation = 'server'], [bool
$reset = false])

Adds a validation rule for the given group of elements

Only groups with a name can be assigned a validation rule Use addGroupRule when you need to validate elements inside the group. Use addRule if you need to validate the group as a whole. In this case, the same rule will be applied to all elements in the group. Use addRule if you need to validate the group against a function.

Since: 2.5
Throws: HTML_QuickForm_Error
Access: public

Parameters:

string	`$group`	—	Form group name
mixed	`$arg1`	—	Array for multiple elements or error message string for one element
string	`$type`	—	(optional)Rule type use getRegisteredRules() to get types
string	`$format`	—	(optional)Required for extra rule data
int	`$howmany`	—	(optional)How many valid elements should be in the group
string	`$validation`	—	(optional)Where to perform validation: "server", "client"
bool	`$reset`	—	Client-side: whether to reset the element's value to its original state if validation failed.

[ Top ]

addRule [line 1065]

void addRule(
string
$element, string
$message, string
$type, [string
$format = null], [string
$validation = 'server'], [boolean
$reset = false], [boolean
$force = false])

Adds a validation rule for the given field

If the element is in fact a group, it will be considered as a whole. To validate grouped elements as separated entities, use addGroupRule instead of addRule.

Since: 1.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

string	`$element`	—	Form element name
string	`$message`	—	Message to display for invalid data
string	`$type`	—	Rule type, use getRegisteredRules() to get types
string	`$format`	—	(optional)Required for extra rule data
string	`$validation`	—	(optional)Where to perform validation: "server", "client"
boolean	`$reset`	—	Client-side validation: reset the form element to its original value if there is an error?
boolean	`$force`	—	Force the rule to be applied, even if the target form element does not exist

[ Top ]

apiVersion [line 342]

float apiVersion(
)

Returns the current API version

Since: 1.0
Access: public

[ Top ]

applyFilter [line 1241]

void applyFilter(
mixed
$element, mixed
$filter)

Applies a data filter for the given field(s)

Since: 2.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

mixed	`$element`	—	Form element name or array of such names
mixed	`$filter`	—	Callback, either function name or array(&$object, 'method')

[ Top ]

arrayMerge [line 1309]

array arrayMerge(
array
$a, array
$b)

Merges two arrays

Merges two array like the PHP function array_merge but recursively. The main difference is that existing keys will not be renumbered if they are integers.

Return: merged array
Access: public

Parameters:

array	`$a`	—	original array
array	`$b`	—	array which will be merged into first one

[ Top ]

createElement [line 566]

HTML_QuickForm_Element &createElement(
string
$elementType)

Creates a new form element of the given type.

This method accepts variable number of parameters, their meaning and count depending on $elementType

Since: 1.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

string $elementType — type of element to add (text, textarea, file...)

[ Top ]

defaultRenderer [line 1703]

object a &defaultRenderer(
)

Returns a reference to default renderer object

Return: default renderer object
Since: 3.0
Access: public

[ Top ]

elementExists [line 397]

boolean elementExists(
[string
$element = null])

Returns true if element is in the form

Since: 1.0
Access: public

Parameters:

string $element — form name of element to check

[ Top ]

errorMessage [line 1990]

string errorMessage(
int
$value)

Return a textual error message for an QuickForm error code

Return: error message
Access: public

Parameters:

int $value — error code

[ Top ]

exportValue [line 1884]

mixed exportValue(
string
$element)

Returns a 'safe' element's value

This method first tries to find a cleaned-up submitted value, it will return a value set by setValue()/setDefaults()/setConstants() if submitted value does not exist for the given element.

Throws: HTML_QuickForm_Error
Access: public

Parameters:

string $element — Name of an element

[ Top ]

exportValues [line 1918]

array exportValues(
[mixed
$elementList = null])

Returns 'safe' elements' values

Unlike getSubmitValues(), this will return only the values corresponding to the elements present in the form.

Return: An assoc array of elements' values
Throws: HTML_QuickForm_Error
Access: public

Parameters:

mixed $elementList — Array/string of element names, whose values we want. If not set then return all elements.

[ Top ]

freeze [line 1606]

void freeze(
[mixed
$elementList = null])

Displays elements without HTML input tags

Since: 1.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

mixed $elementList — array or string of element(s) to be frozen

[ Top ]

getElement [line 773]

HTML_QuickForm_element &getElement(
string
$element)

Returns a reference to the element

Return: reference to element
Since: 2.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

string $element — Element name

[ Top ]

getElementError [line 924]

string getElementError(
string
$element)

Returns error corresponding to validated element

Return: error message corresponding to checked element
Since: 1.0
Access: public

Parameters:

string $element — Name of form element to check

[ Top ]

getElementType [line 963]

string getElementType(
string
$element)

Returns the type of the given element

Return: Type of the element, false if the element is not found
Since: 1.1
Access: public

Parameters:

string $element — Name of form element

[ Top ]

getElementValue [line 798]

mixed &getElementValue(
string
$element)

Returns the element's raw value

This returns the value as submitted by the form (not filtered) or set via setDefaults() or setConstants()

Return: element value
Since: 2.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

string $element — Element name

[ Top ]

getMaxFileSize [line 546]

int getMaxFileSize(
)

Returns the value of MAX_FILE_SIZE hidden element

Return: max file size in bytes
Since: 3.0
Access: public

[ Top ]

getRegisteredRules [line 1409]

array getRegisteredRules(
)

Returns an array of registered validation rules

Since: 1.0
Access: public

[ Top ]

getRegisteredTypes [line 1354]

array getRegisteredTypes(
)

Returns an array of registered element types

Since: 1.0
Access: public

[ Top ]

getRequiredNote [line 1493]

string getRequiredNote(
)

Returns the required note

Since: 2.0
Access: public

[ Top ]

getSubmitValue [line 830]

mixed getSubmitValue(
string
$elementName)

Returns the elements value after submit and filter

Return: submitted element value or null if not set
Since: 2.0
Access: public

Parameters:

string $elementName — Element name

[ Top ]

getSubmitValues [line 1843]

array getSubmitValues(
[bool
$mergeFiles = false])

Returns the values submitted by the form

Since: 2.0
Access: public

Parameters:

bool $mergeFiles — Whether uploaded files should be returned too

[ Top ]

getValidationScript [line 1745]

string getValidationScript(
)

Returns the client side validation script

Return: Javascript to perform validation, empty string if no 'client' rules were added
Since: 2.0
Access: public

[ Top ]

insertElementBefore [line 682]

HTML_QuickForm_element &insertElementBefore(
HTML_QuickForm_element
&$element, string
$nameAfter)

Inserts a new element right before the other element

Warning: 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(): $form->insertElementBefore($form->removeElement('foo', false), 'bar');

Return: reference to inserted element
Throws: HTML_QuickForm_Error
Since: 3.2.4
Access: public

Parameters:

HTML_QuickForm_element	`&$element`	—	Element to insert
string	`$nameAfter`	—	Name of the element before which the new one is inserted

[ Top ]

isElementFrozen [line 1441]

boolean isElementFrozen(
string
$element)

Returns whether or not the form element is frozen

Since: 1.0
Access: public

Parameters:

string $element — Form element name

[ Top ]

isElementRequired [line 1425]

boolean isElementRequired(
string
$element)

Returns whether or not the form element is required

Since: 1.0
Access: public

Parameters:

string $element — Form element name

[ Top ]

isError [line 1974]

bool isError(
mixed
$value)

Tell whether a result from a QuickForm method is an error (an instance of HTML_QuickForm_Error)

Return: whether $value is an error
Access: public

Parameters:

mixed $value — result code

[ Top ]

isFrozen [line 1642]

boolean isFrozen(
)

Returns whether or not the whole form is frozen

Since: 3.0
Access: public

[ Top ]

isRuleRegistered [line 1371]

mixed isRuleRegistered(
string
$name, [bool
$autoRegister = false])

Returns whether or not the given rule is supported

Return: true if previously registered, false if not, new rule name if auto-registering worked
Since: 1.0
Access: public

Parameters:

string	`$name`	—	Validation rule name
bool	`$autoRegister`	—	Whether to automatically register subclasses of HTML_QuickForm_Rule

[ Top ]

isSubmitted [line 1957]

bool isSubmitted(
)

Tells whether the form was already submitted

This is useful since the _submitFiles and _submitValues arrays may be completely empty after the trackSubmit value is removed.

Access: public

[ Top ]

isTypeRegistered [line 1339]

boolean isTypeRegistered(
string
$type)

Returns whether or not the form element type is supported

Since: 1.0
Access: public

Parameters:

string $type — Form element type

[ Top ]

process [line 1660]

mixed process(
mixed
$callback, [bool
$mergeFiles = true])

Performs the form data processing

Return: Whatever value the $callback function returns
Since: 1.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

mixed	`$callback`	—	Callback, either function name or array(&$object, 'method')
bool	`$mergeFiles`	—	Whether uploaded files should be processed too

[ Top ]

registerElementType [line 360]

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

Registers a new element type

Since: 1.0
Access: public

Parameters:

string	`$typeName`	—	Name of element type
string	`$include`	—	Include path for element type
string	`$className`	—	Element class name

[ Top ]

registerRule [line 379]

void registerRule(
string
$ruleName, string
$type, string
$data1, [string
$data2 = null])

Registers a new validation rule

Since: 1.0
Access: public

Parameters:

string	`$ruleName`	—	Name of validation rule
string	`$type`	—	Either: 'regex', 'function' or 'rule' for an HTML_QuickForm_Rule object
string	`$data1`	—	Name of function, regular expression or HTML_QuickForm_Rule classname
string	`$data2`	—	Object parent of above function or HTML_QuickForm_Rule file path

[ Top ]

removeElement [line 1019]

HTML_QuickForm_element &removeElement(
string
$elementName, [boolean
$removeRules = true])

Removes an element

The method "unlinks" an element from the form, returning the reference to the element object. If several elements named $elementName exist, it removes the first one, leaving the others intact.

Return: a reference to the removed element
Throws: HTML_QuickForm_Error
Since: 2.0
Access: public

Parameters:

string	`$elementName`	—	The element name
boolean	`$removeRules`	—	True if rules for this element are to be removed too

[ Top ]

setConstants [line 487]

void setConstants(
[array
$constantValues = null], [mixed
$filter = null])

Initializes constant form values.

These values won't get overridden by POST or GET vars

Since: 2.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

array	`$constantValues`	—	values used to fill the form
mixed	`$filter`	—	(optional) filter(s) to apply to all default values

[ Top ]

setDatasource [line 419]

void setDatasource(

&$datasource, [mixed
$defaultsFilter = null], [mixed
$constantsFilter = null], object
$datasource)

Sets a datasource object for this form object

Datasource default and constant values will feed the QuickForm object if the datasource implements defaultValues() and constantValues() methods.

Since: 3.3
Throws: HTML_QuickForm_Error
Access: public

Parameters:

object	`$datasource`	—	datasource object implementing the informal datasource protocol
mixed	`$defaultsFilter`	—	string or array of filter(s) to apply to default values
mixed	`$constantsFilter`	—	string or array of filter(s) to apply to constants values
	`&$datasource`	—

[ Top ]

setDefaults [line 447]

void setDefaults(
[array
$defaultValues = null], [mixed
$filter = null])

Initializes default form values

Since: 1.0
Throws: HTML_QuickForm_Error
Access: public

Parameters:

array	`$defaultValues`	—	values used to fill the form
mixed	`$filter`	—	(optional) filter(s) to apply to all default values

[ Top ]

setElementError [line 943]

void setElementError(
string
$element, [string
$message = null])

Set error message for a form element

Since: 1.0
Access: public

Parameters:

string	`$element`	—	Name of form element to set error for
string	`$message`	—	Error message, if empty then removes the current error message

[ Top ]

setJsWarnings [line 1461]

void setJsWarnings(
string
$pref, string
$post)

Sets JavaScript warning messages

Since: 1.1
Access: public

Parameters:

string	`$pref`	—	Prefix warning
string	`$post`	—	Postfix warning

[ Top ]

setMaxFileSize [line 523]

void setMaxFileSize(
[int
$bytes = 0])

Sets the value of MAX_FILE_SIZE hidden element

Since: 3.0
Access: public

Parameters:

int $bytes — Size in bytes

[ Top ]

setRequiredNote [line 1478]

void setRequiredNote(
string
$note)

Sets required-note

Since: 1.1
Access: public

Parameters:

string $note — Message indicating some elements are required

[ Top ]

toArray [line 1861]

array toArray(
[bool
$collectHidden = false])

Returns the form's contents in an array.

The description of the array structure is in HTML_QuickForm_Renderer_Array docs

Return: of form contents
Since: 2.0
Access: public

Parameters:

bool $collectHidden — Whether to collect hidden elements (passed to the Renderer's constructor)

[ Top ]

toHtml [line 1725]

string toHtml(
[string
$in_data = null])

Returns an HTML version of the form

Return: Html version of the form
Since: 1.0
Access: public

Parameters:

string $in_data — (optional) Any extra data to insert right before form is rendered. Useful when using templates.

[ Top ]

updateElementAttr [line 983]

void updateElementAttr(
mixed
$elements, mixed
$attrs)

Updates Attributes for one or more elements

Since: 2.10
Access: public

Parameters:

mixed	`$elements`	—	Array of element names/objects or string of elements to be updated
mixed	`$attrs`	—	Array or sting of html attributes

[ Top ]

validate [line 1508]

boolean validate(
)

Performs the server side validation

Return: true if no error found
Throws: HTML_QuickForm_Error
Since: 1.0
Access: public

[ Top ]

Class: HTML_QuickForm

Class Overview

Author(s):

Version:

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

Class Variables

$_jsPostfix = 'Please correct these fields.'

$_jsPrefix = 'Invalid information entered.'

$_maxFileSize = 1048576

$_submitFiles = array()

Method Detail

HTML_QuickForm (Constructor) [line 284]

Parameters:

accept [line 1680]

Parameters:

addElement [line 626]

Parameters:

addFormRule [line 1221]

Parameters:

addGroup [line 749]

Parameters:

addGroupRule [line 1131]

Parameters:

addRule [line 1065]

Parameters:

apiVersion [line 342]

applyFilter [line 1241]

Parameters:

arrayMerge [line 1309]

Parameters:

createElement [line 566]

Parameters:

defaultRenderer [line 1703]

elementExists [line 397]

Parameters:

errorMessage [line 1990]

Parameters:

exportValue [line 1884]

Parameters:

exportValues [line 1918]

Parameters:

freeze [line 1606]

Parameters:

getElement [line 773]

Parameters:

getElementError [line 924]

Parameters:

getElementType [line 963]

Parameters:

getElementValue [line 798]

Parameters:

getMaxFileSize [line 546]

getRegisteredRules [line 1409]

getRegisteredTypes [line 1354]

getRequiredNote [line 1493]

getSubmitValue [line 830]

Parameters:

getSubmitValues [line 1843]

Parameters:

getValidationScript [line 1745]

insertElementBefore [line 682]

Parameters:

isElementFrozen [line 1441]

Parameters:

isElementRequired [line 1425]

Parameters:

isError [line 1974]

Parameters:

isFrozen [line 1642]

isRuleRegistered [line 1371]

Parameters:

isSubmitted [line 1957]

isTypeRegistered [line 1339]

Parameters:

process [line 1660]

Parameters: