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

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


	
			
Variable Summary
static array $forms
object $data
array $errors
string $name
array $options
object $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)
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])
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 (object &$element, [string $group = null], [boolean $replace = true])
boolean setFieldAttribute (string $name, string $attribute, mixed $value, [string $group = null])
boolean setFields (object &$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 (string $element, [string $group = null], [mixed $value = null], [object $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
object $xml (line 63)

The form XML definition.

  • since: 11.1
  • access: protected
Methods
static method addFieldPath (line 1931)

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.
static method addFormPath (line 1946)

Proxy for JFormHelper::addFormPath().

static array addFormPath ([mixed $new = null])
  • mixed $new: A path or array of paths to add.
static method addNode (line 2035)

Adds a new child SimpleXMLElement node to the source.

  • throws: Exception if an error occurs.
  • 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 method addRulePath (line 1961)

Proxy for JFormHelper::addRulePath().

static array addRulePath ([mixed $new = null])
  • mixed $new: A path or array of paths to add.
static method getInstance (line 1981)

Method to get an instance of a form.

  • return: instance.
  • throws: Exception if an error occurs.
  • since: 11.1
  • 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.
static method mergeNode (line 2063)

Adds a new child SimpleXMLElement node to the source.

  • since: 11.1
  • access: protected
static void mergeNode (SimpleXMLElement $source, SimpleXMLElement $new)
  • SimpleXMLElement $source: The source element on which to append.
  • SimpleXMLElement $new: The new element to append.
static method mergeNodes (line 2091)

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

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

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

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

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

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

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

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

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

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.
getErrors (line 256)

Return all errors, if any.

  • return: Array of error messages or JException objects.
  • since: 11.1
  • access: public
array getErrors ()
getField (line 272)

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

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
  • 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 340)

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

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

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

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

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

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

Method to get the form name.

  • return: The name of the form.
  • since: 11.1
  • access: public
string getName ()
getValue (line 610)

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.
load (line 643)

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

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

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.
loadFile (line 758)

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

Proxy for JFormHelper::loadRuleType().

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.
removeField (line 789)

Method to remove a field from the form definition.

  • return: True on success.
  • since: 11.1
  • 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 820)

Method to remove a group from the form definition.

  • return: True on success.
  • since: 11.1
  • access: public
boolean removeGroup (string $group)
  • string $group: The dot-separated form group path for the group to remove.
reset (line 849)

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

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
  • access: public
boolean setField (object &$element, [string $group = null], [boolean $replace = true])
  • object &$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 948)

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

  • return: True on success.
  • since: 11.1
  • 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 992)

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
  • access: public
boolean setFields (object &$elements, [string $group = null], [boolean $replace = true])
  • object &$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 1042)

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

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

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

Method to validate a JFormField object based on field data.

  • return: Boolean true if field value is valid, JException on failure.
  • since: 11.1
  • access: protected
mixed validateField (string $element, [string $group = null], [mixed $value = null], [object $input = 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.
  • object $input: An optional JRegistry object with the entire data set to validate against the entire form.

Documentation generated on Mon, 25 Jun 2012 13:54:57 -0500 by phpDocumentor 1.4.4