HTML_QuickForm
[ class tree: HTML_QuickForm ] [ index: HTML_QuickForm ] [ all elements ]

Class: HTML_QuickForm

Source Location: /HTML_QuickForm-3.2.13/QuickForm.php

Class Overview

HTML_Common
   |
   --HTML_QuickForm

Create, validate and process HTML forms


Author(s):

Version:

  • Release: 3.2.13

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 124]
Create, validate and process HTML forms


[ Top ]


Class Variables

$_jsPostfix =  'Please correct these fields.'

[line 174]

Postfix message in javascript alert if error
  • Since: 1.0
  • Access: public

Type:   string


[ Top ]

$_jsPrefix =  'Invalid information entered.'

[line 166]

Prefix message in javascript alert if error
  • Since: 1.0
  • Access: public

Type:   string


[ Top ]

$_maxFileSize =  1048576

[line 223]

Value for maxfilesize hidden element if form contains file input
  • Since: 1.0
  • Access: public

Type:   integer


[ Top ]

$_submitFiles = array()

[line 215]

Array of submitted form files
  • Since: 1.0
  • Access: public

Type:   integer


[ Top ]



Method Detail

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 ]


Documentation generated on Sat, 01 Oct 2011 09:00:18 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.