Docs For Class JForm

JForm

Description

Form Class for the Joomla Platform.

This class implements a robust API for constructing, populating, filtering, and validating forms. It uses XML definitions to construct form fields and a variety of field and rule classes to render and validate the form.

link: http://www.w3.org/TR/html4/interact/forms.html
link: http://www.w3.org/TR/html5/forms.html
since: 11.1

Located in /libraries/joomla/form/form.php (line 28)

Direct descendents

Class	Description
FOFForm	FOFForm is an extension to JForm which support not only edit views but also browse (record list) and read (single record display) views based on XML forms.

Variable Summary

static array $forms

object $data

array $errors

string $name

array $options

mixed $repeat

SimpleXMLElement $xml

Method Summary

static array addFieldPath ([mixed $new = null])

static array addFormPath ([mixed $new = null])

static void addNode (SimpleXMLElement $source, SimpleXMLElement $new)

static array addRulePath ([mixed $new = null])

static object JForm getInstance (string $name, [string $data = null], [array $options = array()], [string $replace = true], [string $xpath = false])

static void mergeNode (SimpleXMLElement $source, SimpleXMLElement $new)

static void mergeNodes (SimpleXMLElement $source, SimpleXMLElement $new)

JForm __construct (string $name, [array $options = array()])

boolean bind (mixed $data)

void bindLevel (string $group, mixed $data)

mixed filter (array $data, [string $group = null])

mixed filterField (string $element, mixed $value)

mixed findField (string $name, [string $group = null])

mixed &findFieldsByFieldset (string $name)

mixed &findFieldsByGroup ([mixed $group = null], [boolean $nested = false])

mixed &findGroup (string $group)

mixed getAttribute (string $name, [mixed $default = null])

string getControlGroup (string $name, [string $group = null], [mixed $default = null])

string getControlGroups (string $name)

JRegistry getData ()

array getErrors ()

mixed getField (string $name, [string $group = null], [mixed $value = null])

mixed getFieldAttribute (string $name, string $attribute, [mixed $default = null], [string $group = null])

array getFieldset ([string $set = null])

array getFieldsets ([string $group = null])

string getFormControl ()

array getGroup (string $group, [boolean $nested = false])

string getInput (string $name, [string $group = null], [mixed $value = null])

string getLabel (string $name, [string $group = null])

string getName ()

mixed getValue (string $name, [string $group = null], [mixed $default = null])

SimpleXMLElement getXml ()

boolean load (string $data, [string $replace = true], [string $xpath = false])

mixed loadField (string $element, [string $group = null], [mixed $value = null])

mixed loadFieldType (string $type, [boolean $new = true])

boolean loadFile (string $file, [string $reset = true], [string $xpath = false])

mixed loadRuleType (string $type, [boolean $new = true])

boolean removeField (string $name, [string $group = null])

boolean removeGroup (string $group)

boolean reset ([boolean $xml = false])

boolean setField (SimpleXMLElement $element, [string $group = null], [boolean $replace = true])

boolean setFieldAttribute (string $name, string $attribute, mixed $value, [string $group = null])

boolean setFields (array &$elements, [string $group = null], [boolean $replace = true])

boolean setValue (string $name, [string $group = null], [mixed $value = null])

boolean syncPaths ()

mixed validate (array $data, [string $group = null])

mixed validateField (SimpleXMLElement $element, [string $group = null], [mixed $value = null], [JRegistry $input = null])

Variables

static array $forms = array() (line 70)

Form instances.

since: 11.1
access: protected

object $data (line 35)

The JRegistry data store for form fields during display.

since: 11.1
access: protected

array $errors = array() (line 42)

The form object errors array.

since: 11.1
access: protected

string $name (line 49)

The name of the form instance.

since: 11.1
access: protected

array $options = array() (line 56)

The form object options for use in rendering and validation.

since: 11.1
access: protected

mixed $repeat = false (line 77)

Alows extensions to implement repeating elements

since: 3.2
access: public

SimpleXMLElement $xml (line 63)

The form XML definition.

since: 11.1
access: protected

Methods

static addFieldPath (line 1973)

Proxy for JFormHelper::addFieldPath().

return: The list of paths that have been added.
since: 11.1
access: public

static array addFieldPath ([mixed $new = null])

mixed $new: A path or array of paths to add.

Redefined in descendants as:

FOFForm::addFieldPath() : Proxy for FOFFormHelper::addFieldPath().

static addFormPath (line 1988)

Proxy for JFormHelper::addFormPath().

return: The list of paths that have been added.
see: JFormHelper::addFormPath()
since: 11.1
access: public

static array addFormPath ([mixed $new = null])

mixed $new: A path or array of paths to add.

Redefined in descendants as:

FOFForm::addFormPath() : Proxy for FOFFormHelper::addFormPath().

static addNode (line 2072)

Adds a new child SimpleXMLElement node to the source.

since: 11.1
access: protected

static void addNode (SimpleXMLElement $source, SimpleXMLElement $new)

SimpleXMLElement $source: The source element on which to append.
SimpleXMLElement $new: The new element to append.

static addRulePath (line 2003)

Proxy for JFormHelper::addRulePath().

return: The list of paths that have been added.
see: JFormHelper::addRulePath()
since: 11.1
access: public

static array addRulePath ([mixed $new = null])

mixed $new: A path or array of paths to add.

Redefined in descendants as:

FOFForm::addRulePath() : Proxy for FOFFormHelper::addRulePath().

static getInstance (line 2024)

Method to get an instance of a form.

return: instance.
since: 11.1
throws: InvalidArgumentException if no data provided.
throws: RuntimeException if the form could not be loaded.
access: public

static object JForm getInstance (string $name, [string $data = null], [array $options = array()], [string $replace = true], [string $xpath = false])

string $name: The name of the form.
string $data: The name of an XML file or string to load as the form definition.
array $options: An array of form options.
string $replace: Flag to toggle whether form fields should be replaced if a field already exists with the same group/name.
string $xpath: An optional xpath to search for the fields.

Redefined in descendants as:

FOFForm::getInstance() : Method to get an instance of a form.

static mergeNode (line 2100)

Update the attributes of a child node

since: 11.1
access: protected

static void mergeNode (SimpleXMLElement $source, SimpleXMLElement $new)

SimpleXMLElement $source: The source element on which to append the attributes
SimpleXMLElement $new: The new element to append

static mergeNodes (line 2126)

Merges new elements into a source <fields> element.

since: 11.1
access: protected

static void mergeNodes (SimpleXMLElement $source, SimpleXMLElement $new)

SimpleXMLElement $source: The source element.
SimpleXMLElement $new: The new element to merge.

Constructor __construct (line 87)

Method to instantiate the form object.

since: 11.1
access: public

JForm __construct (string $name, [array $options = array()])

string $name: The name of the form.
array $options: An array of form options.

bind (line 108)

Method to bind data to the form.

return: True on success.
since: 11.1
access: public

boolean bind (mixed $data)

mixed $data: An array or object of data to bind to the form.

bindLevel (line 170)

Method to bind data to the form for the group level.

since: 11.1
access: protected

void bindLevel (string $group, mixed $data)

string $group: The dot-separated form group path on which to bind the data.
mixed $data: An array or object of data to bind to the form for the group level.

filter (line 201)

Method to filter the form data.

return: Array or false.
since: 11.1
access: public

mixed filter (array $data, [string $group = null])

array $data: An array of field values to filter.
string $group: The dot-separated form group path on which to filter the fields.

filterField (line 1183)

Method to apply an input filter to a value based on field data.

return: The filtered value.
since: 11.1
access: protected

mixed filterField (string $element, mixed $value)

string $element: The XML element object representation of the form field.
mixed $value: The value to filter for the field.

findField (line 1448)

Method to get a form field represented as an XML element object.

return: The XML element object for the field or boolean false on error.
since: 11.1
access: protected

mixed findField (string $name, [string $group = null])

string $name: The name of the form field.
string $group: The optional dot-separated form group path on which to find the field.

findFieldsByFieldset (line 1540)

Method to get an array of <field /> elements from the form XML document which are in a specified fieldset by name.

return: Boolean false on error or array of SimpleXMLElement objects.
since: 11.1
access: protected

mixed &findFieldsByFieldset (string $name)

string $name: The name of the fieldset.

findFieldsByGroup (line 1574)

Method to get an array of <field /> elements from the form XML document which are in a control group by name.

return: Boolean false on error or array of SimpleXMLElement objects.
since: 11.1
access: protected

mixed &findFieldsByGroup ([mixed $group = null], [boolean $nested = false])

mixed $group: The optional dot-separated form group path on which to find the fields. Null will return all fields. False will return fields not in a group.
boolean $nested: True to also include fields in nested groups that are inside of the group for which to find fields.

findGroup (line 1647)

Method to get a form field group represented as an XML element object.

return: An array of XML element objects for the group or boolean false on error.
since: 11.1
access: protected

mixed &findGroup (string $group)

string $group: The dot-separated form group path on which to find the group.

getAttribute (line 2184)

Returns the value of an attribute of the form itself

return: Value of the attribute / default
since: 3.2
access: public

mixed getAttribute (string $name, [mixed $default = null])

string $name: Name of the attribute to get
mixed $default: Optional value to return if attribute not found

Redefined in descendants as:

FOFForm::getAttribute() : Returns the value of an attribute of the form itself

getControlGroup (line 637)

Method to get a control group with label and input.

return: A string containing the html for the control goup
since: 3.2
access: public

string getControlGroup (string $name, [string $group = null], [mixed $default = null])

string $name: The name of the field for which to get the value.
string $group: The optional dot-separated form group path on which to get the value.
mixed $default: The optional default value of the field value is empty.

getControlGroups (line 656)

Method to get all control groups with label and input of a fieldset.

return: A string containing the html for the control goups
since: 3.2
access: public

string getControlGroups (string $name)

string $name: The name of the fieldset for which to get the values.

getData (line 2212)

Getter for the form data

return: Object with the data
since: 3.2
access: public

JRegistry getData ()

Redefined in descendants as:

FOFForm::getData() : Returns a reference to the protected $data object, allowing direct access to and manipulation of the form's data.

getErrors (line 260)

Return all errors, if any.

return: Array of error messages or RuntimeException objects.
since: 11.1
access: public

array getErrors ()

getField (line 276)

Method to get a form field represented as a JFormField object.

return: The JFormField object for the field or boolean false on error.
since: 11.1
access: public

mixed getField (string $name, [string $group = null], [mixed $value = null])

string $name: The name of the form field.
string $group: The optional dot-separated form group path on which to find the field.
mixed $value: The optional value to use as the default for the field.

getFieldAttribute (line 310)

Method to get an attribute value from a field XML element. If the attribute doesn't exist or is null then the optional default value will be used.

return: The attribute value for the field.
since: 11.1
throws: UnexpectedValueException
access: public

mixed getFieldAttribute (string $name, string $attribute, [mixed $default = null], [string $group = null])

string $name: The name of the form field for which to get the attribute value.
string $attribute: The name of the attribute for which to get a value.
mixed $default: The optional default value to use if no attribute value exists.
string $group: The optional dot-separated form group path on which to find the field.

getFieldset (line 344)

Method to get an array of JFormField objects in a given fieldset by name. If no name is given then all fields are returned.

return: The array of JFormField objects in the fieldset.
since: 11.1
access: public

array getFieldset ([string $set = null])

string $set: The optional name of the fieldset.

getFieldsets (line 393)

Method to get an array of fieldset objects optionally filtered over a given field group.

return: The array of fieldset objects.
since: 11.1
access: public

array getFieldsets ([string $group = null])

string $group: The dot-separated form group path on which to filter the fieldsets.

getFormControl (line 498)

Method to get the form control. This string serves as a container for all form fields. For

example, if there is a field named 'foo' and a field named 'bar' and the form control is empty the fields will be rendered like: <input name="foo" /> and <input name="bar" />. If the form control is set to 'joomla' however, the fields would be rendered like: <input name="joomla[foo]" /> and <input name="joomla[bar]" />.

return: The form control string.
since: 11.1
access: public

string getFormControl ()

getGroup (line 514)

Method to get an array of JFormField objects in a given field group by name.

return: The array of JFormField objects in the field group.
since: 11.1
access: public

array getGroup (string $group, [boolean $nested = false])

string $group: The dot-separated form group path for which to get the form fields.
boolean $nested: True to also include fields in nested groups that are inside of the group for which to find fields.

getInput (line 556)

Method to get a form field markup for the field input.

return: The form field markup.
since: 11.1
access: public

string getInput (string $name, [string $group = null], [mixed $value = null])

string $name: The name of the form field.
string $group: The optional dot-separated form group path on which to find the field.
mixed $value: The optional value to use as the default for the field.

getLabel (line 577)

Method to get the label for a field input.

return: The form field label.
since: 11.1
access: public

string getLabel (string $name, [string $group = null])

string $name: The name of the form field.
string $group: The optional dot-separated form group path on which to find the field.

getName (line 595)

Method to get the form name.

return: The name of the form.
since: 11.1
access: public

string getName ()

getValue (line 611)

Method to get the value of a field.

return: The value of the field or the default value if empty.
since: 11.1
access: public

mixed getValue (string $name, [string $group = null], [mixed $default = null])

string $name: The name of the field for which to get the value.
string $group: The optional dot-separated form group path on which to get the value.
mixed $default: The optional default value of the field value is empty.

getXml (line 2224)

Method to get the XML form object

return: The form XML object
since: 3.2
access: public

SimpleXMLElement getXml ()

load (line 687)

Method to load the form description from an XML string or object.

The replace option works per field. If a field being loaded already exists in the current form definition then the behavior or load will vary depending upon the replace flag. If it is set to true, then the existing field will be replaced in its exact location by the new field being loaded. If it is false, then the new field being loaded will be ignored and the method will move on to the next field to load.

return: True on success, false otherwise.
since: 11.1
access: public

boolean load (string $data, [string $replace = true], [string $xpath = false])

string $data: The name of an XML string or object.
string $replace: Flag to toggle whether form fields should be replaced if a field already exists with the same group/name.
string $xpath: An optional xpath to search for the fields.

loadField (line 1731)

Method to load, setup and return a JFormField object based on field data.

return: The JFormField object for the field or boolean false on error.
since: 11.1
access: protected

mixed loadField (string $element, [string $group = null], [mixed $value = null])

string $element: The XML element object representation of the form field.
string $group: The optional dot-separated form group path on which to find the field.
mixed $value: The optional value to use as the default for the field.

loadFieldType (line 1803)

Proxy for JFormHelper::loadFieldType().

return: JFormField object on success, false otherwise.
since: 11.1
access: protected

mixed loadFieldType (string $type, [boolean $new = true])

string $type: The field type.
boolean $new: Flag to toggle whether we should get a new instance of the object.

Redefined in descendants as:

FOFForm::loadFieldType() : Proxy for FOFFormHelper::loadFieldType().

loadFile (line 811)

Method to load the form description from an XML file.

The reset option works on a group basis. If the XML file references groups that have already been created they will be replaced with the fields in the new XML file unless the $reset parameter has been set to false.

return: True on success, false otherwise.
since: 11.1
access: public

boolean loadFile (string $file, [string $reset = true], [string $xpath = false])

string $file: The filesystem path of an XML file.
string $reset: Flag to toggle whether form fields should be replaced if a field already exists with the same group/name.
string $xpath: An optional xpath to search for the fields.

loadRuleType (line 1819)

Proxy for JFormHelper::loadRuleType().

return: JFormRule object on success, false otherwise.
see: JFormHelper::loadRuleType()
since: 11.1
access: protected

mixed loadRuleType (string $type, [boolean $new = true])

string $type: The rule type.
boolean $new: Flag to toggle whether we should get a new instance of the object.

Redefined in descendants as:

FOFForm::loadRuleType() : Proxy for FOFFormHelper::loadRuleType().

removeField (line 843)

Method to remove a field from the form definition.

return: True on success.
since: 11.1
throws: UnexpectedValueException
access: public

boolean removeField (string $name, [string $group = null])

string $name: The name of the form field for which remove.
string $group: The optional dot-separated form group path on which to find the field.

removeGroup (line 874)

Method to remove a group from the form definition.

return: True on success.
since: 11.1
throws: UnexpectedValueException
access: public

boolean removeGroup (string $group)

string $group: The dot-separated form group path for the group to remove.

reset (line 903)

Method to reset the form data store and optionally the form XML definition.

return: True on success.
since: 11.1
access: public

boolean reset ([boolean $xml = false])

boolean $xml: True to also reset the XML form definition.

setField (line 931)

Method to set a field XML element to the form definition. If the replace flag is set then the field will be set whether it already exists or not. If it isn't set, then the field will not be replaced if it already exists.

return: True on success.
since: 11.1
throws: UnexpectedValueException
access: public

boolean setField (SimpleXMLElement $element, [string $group = null], [boolean $replace = true])

SimpleXMLElement $element: The XML element object representation of the form field.
string $group: The optional dot-separated form group path on which to set the field.
boolean $replace: True to replace an existing field if one already exists.

setFieldAttribute (line 992)

Method to set an attribute value for a field XML element.

return: True on success.
since: 11.1
throws: UnexpectedValueException
access: public

boolean setFieldAttribute (string $name, string $attribute, mixed $value, [string $group = null])

string $name: The name of the form field for which to set the attribute value.
string $attribute: The name of the attribute for which to set a value.
mixed $value: The value to set for the attribute.
string $group: The optional dot-separated form group path on which to find the field.

setFields (line 1035)

Method to set some field XML elements to the form definition. If the replace flag is set then the fields will be set whether they already exists or not. If it isn't set, then the fields will not be replaced if they already exist.

return: True on success.
since: 11.1
throws: UnexpectedValueException
access: public

boolean setFields (array &$elements, [string $group = null], [boolean $replace = true])

array &$elements: The array of XML element object representations of the form fields.
string $group: The optional dot-separated form group path on which to set the fields.
boolean $replace: True to replace existing fields if they already exist.

setValue (line 1081)

Method to set the value of a field. If the field does not exist in the form then the method will return false.

return: True on success.
since: 11.1
access: public

boolean setValue (string $name, [string $group = null], [mixed $value = null])

string $name: The name of the field for which to set the value.
string $group: The optional dot-separated form group path on which to find the field.
mixed $value: The value to set for the field.

syncPaths (line 1832)

Method to synchronize any field, form or rule paths contained in the XML document.

return: True on success.
todo: Maybe we should receive all addXXXpaths attributes at once?
since: 11.1
access: protected

boolean syncPaths ()

validate (line 1116)

Method to validate form data.

Validation warnings will be pushed into JForm::errors and should be retrieved with JForm::getErrors() when validate returns boolean false.

return: True on sucess.
since: 11.1
access: public

mixed validate (array $data, [string $group = null])

array $data: An array of field values to validate.
string $group: The optional dot-separated form group path on which to filter the fields to be validated.

validateField (line 1891)

Method to validate a JFormField object based on field data.

return: Boolean true if field value is valid, Exception on failure.
throws: InvalidArgumentException
throws: UnexpectedValueException
since: 11.1
access: protected

mixed validateField (SimpleXMLElement $element, [string $group = null], [mixed $value = null], [JRegistry $input = null])

SimpleXMLElement $element: The XML element object representation of the form field.
string $group: The optional dot-separated form group path on which to find the field.
mixed $value: The optional value to use as the default for the field.
JRegistry $input: An optional JRegistry object with the entire data set to validate against the entire form.

Documentation generated on Tue, 19 Nov 2013 15:03:34 +0100 by phpDocumentor 1.4.3