HTML_Common
[ class tree: HTML_Common ] [ index: HTML_Common ] [ all elements ]
Packages:
default
Cache_Lite
Crypt
HTML_Common
HTML_QuickForm
HTTP_Request
Image_Text
Log
Mail
Mail_Mime
Net_SMTP
PEAR
QuickForm
Smarty
SmartyGettext
Text_CAPTCHA
Text_Password
Welcompose
Welcompose_Plugins
XML_RPC


Files:
Common.php

Classes:
HTML_Common
HTML_QuickForm
HTML_QuickForm_advcheckbox
HTML_QuickForm_autocomplete
HTML_QuickForm_button
HTML_QuickForm_checkbox
HTML_QuickForm_date
HTML_QuickForm_element
HTML_QuickForm_file
HTML_QuickForm_group
HTML_QuickForm_header
HTML_QuickForm_hidden
HTML_QuickForm_hiddenselect
HTML_QuickForm_hierselect
HTML_QuickForm_html
HTML_QuickForm_image
HTML_QuickForm_input
HTML_QuickForm_link
HTML_QuickForm_password
HTML_QuickForm_radio
HTML_QuickForm_reset
HTML_QuickForm_select
HTML_QuickForm_static
HTML_QuickForm_submit
HTML_QuickForm_text
HTML_QuickForm_textarea
HTML_QuickForm_xbutton

Class: HTML_QuickForm

Source Location: /pear/HTML/QuickForm.php

Class Overview

HTML_Common
   |
   --HTML_QuickForm

Create, validate and process HTML forms


Author(s):

Version:

  • 2.0

Variables

Methods

Inherited Methods

Class: HTML_Common

HTML_Common::HTML_Common()
Class constructor
HTML_Common::apiVersion()
Returns the current API version
HTML_Common::charset()
Sets the charset to use by htmlspecialchars() function
HTML_Common::display()
Displays the HTML to the screen
HTML_Common::getAttribute()
Returns the value of the given attribute
HTML_Common::getAttributes()
Returns the assoc array (default) or string of attributes
HTML_Common::getComment()
Returns the HTML comment
HTML_Common::getTabOffset()
Returns the tabOffset
HTML_Common::removeAttribute()
Removes an attribute
HTML_Common::setAttribute()
Sets the value of the attribute
HTML_Common::setAttributes()
Sets the HTML attributes
HTML_Common::setComment()
Sets the HTML comment to be displayed at the beginning of the HTML string
HTML_Common::setLineEnd()
Sets the line end style to Windows, Mac, Unix or a custom string.
HTML_Common::setTab()
Sets the string used to indent HTML
HTML_Common::setTabOffset()
Sets the tab offset
HTML_Common::toHtml()
Abstract method. Must be extended to return the objects HTML
HTML_Common::updateAttributes()
Updates the passed attributes without changing the other existing attributes

Class Details

[line 99]
Create, validate and process HTML forms



Tags:

author:  Bertrand Mansion <bmansion@mamasam.com>
author:  Adam Daniel <adaniel1@eesus.jnj.com>
version:  2.0
since:  PHP 4.0.3pl1


[ Top ]

Class Variables

$_jsPostfix =  'Please correct these fields.'

[line 148]

Postfix message in javascript alert if error



Tags:

since:  1.0
access:  public

Type:   string


[ Top ]

$_jsPrefix =  'Invalid information entered.'

[line 140]

Prefix message in javascript alert if error



Tags:

since:  1.0
access:  public

Type:   string


[ Top ]

$_maxFileSize =  1048576

[line 197]

Value for maxfilesize hidden element if form contains file input



Tags:

since:  1.0
access:  public

Type:   integer


[ Top ]

$_submitFiles = array()

[line 189]

Array of submitted form files



Tags:

since:  1.0
access:  public

Type:   integer


[ Top ]


Class Methods

constructor HTML_QuickForm [line 258]

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

Class constructor



Tags:

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 ]

method accept [line 1636]

void accept( object An &$renderer)

Accepts a renderer



Tags:

since:  3.0
access:  public


Parameters:

object An   &$renderer   HTML_QuickForm_Renderer object

[ Top ]

method addElement [line 597]

object reference &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




Tags:

return:  to 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 ]

method addFormRule [line 1185]

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.




Tags:

throws:  HTML_QuickForm_Error
access:  public


Parameters:

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

[ Top ]

method addGroup [line 719]

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

Adds an element group



Tags:

return:  to added group of elements
since:  2.8
throws:  PEAR_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 ]

method addGroupRule [line 1095]

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.




Tags:

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 ]

method addRule [line 1029]

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.




Tags:

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 ]

method apiVersion [line 316]

float apiVersion( )

Returns the current API version



Tags:

since:  1.0
access:  public


Overrides HTML_Common::apiVersion() (Returns the current API version)

[ Top ]

method applyFilter [line 1204]

void applyFilter( mixed $element, mixed $filter)

Applies a data filter for the given field(s)



Tags:

since:  2.0
access:  public


Parameters:

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

[ Top ]

method arrayMerge [line 1272]

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.




Tags:

return:  merged array


Parameters:

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

[ Top ]

method createElement [line 537]

object extended &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




Tags:

return:  class of HTML_element
since:  1.0
throws:  HTML_QuickForm_Error
access:  public


Parameters:

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

[ Top ]

method defaultRenderer [line 1659]

object a &defaultRenderer( )

Returns a reference to default renderer object



Tags:

return:  default renderer object
since:  3.0
access:  public


[ Top ]

method elementExists [line 371]

boolean elementExists( [string $element = null])

Returns true if element is in the form



Tags:

since:  1.0
access:  public


Parameters:

string   $element   form name of element to check

[ Top ]

method errorMessage [line 1943]

string errorMessage( int $value)

Return a textual error message for an QuickForm error code



Tags:

return:  error message
access:  public


Parameters:

int   $value   error code

[ Top ]

method exportValue [line 1839]

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.




Tags:

access:  public


Parameters:

string   $element   Name of an element

[ Top ]

method exportValues [line 1873]

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.




Tags:

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 ]

method freeze [line 1563]

void freeze( [mixed $elementList = null])

Displays elements without HTML input tags



Tags:

since:  1.0
throws:  HTML_QuickForm_Error
access:  public


Parameters:

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

[ Top ]

method getElement [line 743]

object reference &getElement( string $element)

Returns a reference to the element



Tags:

return:  to element
since:  2.0
throws:  HTML_QuickForm_Error
access:  public


Parameters:

string   $element   Element name

[ Top ]

method getElementError [line 894]

string getElementError( string $element)

Returns error corresponding to validated element



Tags:

return:  error message corresponding to checked element
since:  1.0
access:  public


Parameters:

string   $element   Name of form element to check

[ Top ]

method getElementType [line 933]

string getElementType( string $element)

Returns the type of the given element



Tags:

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 ]

method getElementValue [line 768]

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()




Tags:

return:  element value
since:  2.0
throws:  HTML_QuickForm_Error
access:  public


Parameters:

string   $element   Element name

[ Top ]

method getMaxFileSize [line 517]

int getMaxFileSize( )

Returns the value of MAX_FILE_SIZE hidden element



Tags:

return:  max file size in bytes
since:  3.0
access:  public


[ Top ]

method getRegisteredRules [line 1372]

array getRegisteredRules( )

Returns an array of registered validation rules



Tags:

since:  1.0
access:  public


[ Top ]

method getRegisteredTypes [line 1317]

array getRegisteredTypes( )

Returns an array of registered element types



Tags:

since:  1.0
access:  public


[ Top ]

method getRequiredNote [line 1456]

string getRequiredNote( )

Returns the required note



Tags:

since:  2.0
access:  public


[ Top ]

method getSubmitValue [line 800]

mixed getSubmitValue( string $elementName)

Returns the elements value after submit and filter



Tags:

return:  submitted element value or null if not set
since:  2.0
access:  public


Parameters:

string   $elementName   Element name

[ Top ]

method getSubmitValues [line 1799]

array getSubmitValues( [bool $mergeFiles = false])

Returns the values submitted by the form



Tags:

since:  2.0
access:  public


Parameters:

bool   $mergeFiles   Whether uploaded files should be returned too

[ Top ]

method getValidationScript [line 1701]

string getValidationScript( )

Returns the client side validation script



Tags:

return:  Javascript to perform validation, empty string if no 'client' rules were added
since:  2.0
access:  public


[ Top ]

method insertElementBefore [line 652]

object HTML_QuickForm_element &insertElementBefore( object 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');




Tags:

return:  reference to inserted element
throws:  HTML_QuickForm_Error
since:  3.2.4
access:  public


Parameters:

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

[ Top ]

method isElementFrozen [line 1404]

boolean isElementFrozen( string $element)

Returns whether or not the form element is frozen



Tags:

since:  1.0
access:  public


Parameters:

string   $element   Form element name

[ Top ]

method isElementRequired [line 1388]

boolean isElementRequired( string $element)

Returns whether or not the form element is required



Tags:

since:  1.0
access:  public


Parameters:

string   $element   Form element name

[ Top ]

method isError [line 1928]

bool isError( mixed $value)

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



Tags:

return:  whether $value is an error
access:  public


Parameters:

mixed   $value   result code

[ Top ]

method isFrozen [line 1599]

boolean isFrozen( )

Returns whether or not the whole form is frozen



Tags:

since:  3.0
access:  public


[ Top ]

method isRuleRegistered [line 1334]

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

Returns whether or not the given rule is supported



Tags:

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 ]

method isSubmitted [line 1912]

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.




Tags:

access:  public


[ Top ]

method isTypeRegistered [line 1302]

boolean isTypeRegistered( string $type)

Returns whether or not the form element type is supported



Tags:

since:  1.0
access:  public


Parameters:

string   $type   Form element type

[ Top ]

method process [line 1616]

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

Performs the form data processing



Tags:

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 ]

method registerElementType [line 334]

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

Registers a new element type



Tags:

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 ]

method registerRule [line 353]

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

Registers a new validation rule



Tags:

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 ]

method removeElement [line 989]

object 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.




Tags:

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 ]

method setConstants [line 458]

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

Initializes constant form values.

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




Tags:

since:  2.0
access:  public


Parameters:

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

[ Top ]

method setDatasource [line 392]

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.




Tags:

since:  3.3
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 ]

method setDefaults [line 419]

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

Initializes default form values



Tags:

since:  1.0
access:  public


Parameters:

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

[ Top ]

method setElementError [line 913]

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

Set error message for a form element



Tags:

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 ]

method setJsWarnings [line 1424]

void setJsWarnings( string $pref, string $post)

Sets JavaScript warning messages



Tags:

since:  1.1
access:  public


Parameters:

string   $pref   Prefix warning
string   $post   Postfix warning

[ Top ]

method setMaxFileSize [line 494]

void setMaxFileSize( [int $bytes = 0])

Sets the value of MAX_FILE_SIZE hidden element



Tags:

since:  3.0
access:  public


Parameters:

int   $bytes   Size in bytes

[ Top ]

method setRequiredNote [line 1441]

void setRequiredNote( string $note)

Sets required-note



Tags:

since:  1.1
access:  public


Parameters:

string   $note   Message indicating some elements are required

[ Top ]

method toArray [line 1817]

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




Tags:

return:  of form contents
since:  2.0
access:  public


Parameters:

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

[ Top ]

method toHtml [line 1681]

string toHtml( [string $in_data = null])

Returns an HTML version of the form



Tags:

return:  Html version of the form
since:  1.0
access:  public


Overrides HTML_Common::toHtml() (Abstract method. Must be extended to return the objects HTML)

Parameters:

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

[ Top ]

method updateElementAttr [line 953]

void updateElementAttr( mixed $elements, mixed $attrs)

Updates Attributes for one or more elements



Tags:

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 ]

method validate [line 1470]

boolean validate( )

Performs the server side validation



Tags:

return:  true if no error found
since:  1.0
access:  public


[ Top ]

method _reindexFiles [line 870]

array _reindexFiles( mixed $value, string $key)

A helper function to change the indexes in $_FILES array



Parameters:

mixed   $value   Some value from the $_FILES array
string   $key   The key from the $_FILES array that should be appended

[ Top ]

Documentation generated on Sun, 08 Jan 2012 17:51:57 +0100 by phpDocumentor 1.4.3