Search

Projects

Classes

Methods

⇦ Back to Joomla project (class list)

Class Form - list of methods

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.
Package: Joomla\CMS\Form
Copyright: (C) 2009 Open Source Matters, Inc.
License: GNU General Public License version 2 or later; see LICENSE.txt
Located at: Joomla/Form/Form.php
Project: Joomla

Method Summary

public
__construct
(mixed $name, array $options = [])

Method to instantiate the form object.
Parameters
  • string $name The name of the form.
  • array $options An array of form options.
Since
  • 1.7.0
Show source code of this method: __construct Source Code

public bool
(mixed $data)

Method to bind data to the form.
Parameters
  • mixed $data An array or object of data to bind to the form.
Returns
  • bool True on success.
Since
  • 1.7.0
Show source code of this method: bind Source Code

protected void
(mixed $group, mixed $data)

Method to bind data to the form for the group level.
Parameters
  • 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.
Returns
  • void
Since
  • 1.7.0
Show source code of this method: bindLevel Source Code

public array
()

Return all errors, if any.
Returns
  • array Array of error messages or RuntimeException objects.
Since
  • 1.7.0
Show source code of this method: getErrors Source Code

public \Joomla\CMS\Form\FormField|bool
(mixed $name, mixed $group = null, mixed $value = null)

Method to get a form field represented as a FormField object.
Parameters
  • 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.
Returns
  • \Joomla\CMS\Form\FormField|bool The FormField object for the field or boolean false on error.
Since
  • 1.7.0
Show source code of this method: getField Source Code

public mixed
(mixed $name, mixed $attribute, mixed $default = null, mixed $group = null)

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.
Parameters
  • 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.
Returns
  • mixed The attribute value for the field.
Since
  • 1.7.0
-
  • \UnexpectedValueException
Show source code of this method: getFieldAttribute Source Code

public \Joomla\CMS\Form\FormField[]
(mixed $set = null)

Method to get an array of FormField objects in a given fieldset by name. If no name is given then all fields are returned.
Parameters
  • string $set The optional name of the fieldset.
Returns
  • \Joomla\CMS\Form\FormField[] The array of FormField objects in the fieldset.
Since
  • 1.7.0
Show source code of this method: getFieldset Source Code

public array
(mixed $group = null)

Method to get an array of fieldset objects optionally filtered over a given field group.
Parameters
  • string $group The dot-separated form group path on which to filter the fieldsets.
Returns
  • array The array of fieldset objects.
Since
  • 1.7.0
Show source code of this method: getFieldsets Source Code

public string
()

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]" />`.
Returns
  • string The form control string.
Since
  • 1.7.0
Show source code of this method: getFormControl Source Code

public \Joomla\CMS\Form\FormField[]
(mixed $group, mixed $nested = false)

Method to get an array of FormField objects in a given field group by name.
Parameters
  • string $group The dot-separated form group path for which to get the form fields.
  • bool $nested True to also include fields in nested groups that are inside of the group for which to find fields.
Returns
  • \Joomla\CMS\Form\FormField[] The array of FormField objects in the field group.
Since
  • 1.7.0
Show source code of this method: getGroup Source Code

public string
(mixed $name, mixed $group = null, mixed $value = null)

Method to get a form field markup for the field input.
Parameters
  • 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.
Returns
  • string The form field markup.
Since
  • 1.7.0
Show source code of this method: getInput Source Code

public string
(mixed $name, mixed $group = null)

Method to get the label for a field input.
Parameters
  • string $name The name of the form field.
  • string $group The optional dot-separated form group path on which to find the field.
Returns
  • string The form field label.
Since
  • 1.7.0
Show source code of this method: getLabel Source Code

public string
()

Method to get the form name.
Returns
  • string The name of the form.
Since
  • 1.7.0
Show source code of this method: getName Source Code

public mixed
(mixed $name, mixed $group = null, mixed $default = null)

Method to get the value of a field.
Parameters
  • 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.
Returns
  • mixed The value of the field or the default value if empty.
Since
  • 1.7.0
Show source code of this method: getValue Source Code

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

Method to get a control group with label and input.
Parameters
  • 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.
  • array $options Any options to be passed into the rendering of the field
Returns
  • string A string containing the html for the control goup
Since
  • 3.2.3
Show source code of this method: renderField Source Code

public string
(mixed $name, mixed $options = [])

Method to get all control groups with label and input of a fieldset.
Parameters
  • string $name The name of the fieldset for which to get the values.
  • array $options Any options to be passed into the rendering of the field
Returns
  • string A string containing the html for the control goups
Since
  • 3.2.3
Show source code of this method: renderFieldset Source Code

public bool
(mixed $data, mixed $replace = true, mixed $xpath = null)

Method to load the form description from an XML string or object.
Parameters
  • string $data The name of an XML string or object.
  • bool $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.
Returns
  • bool True on success, false otherwise.
Since
  • 1.7.0
Show source code of this method: load Source Code

public bool
(mixed $file, mixed $reset = true, mixed $xpath = null)

Method to load the form description from an XML file.
Parameters
  • string $file The filesystem path of an XML file.
  • bool $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.
Returns
  • bool True on success, false otherwise.
Since
  • 1.7.0
Show source code of this method: loadFile Source Code

public bool
(mixed $name, mixed $group = null)

Method to remove a field from the form definition.
Parameters
  • 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.
Returns
  • bool True on success, false otherwise.
Since
  • 1.7.0
-
  • \UnexpectedValueException
Show source code of this method: removeField Source Code

public bool
(mixed $group)

Method to remove a group from the form definition.
Parameters
  • string $group The dot-separated form group path for the group to remove.
Returns
  • bool True on success.
Since
  • 1.7.0
-
  • \UnexpectedValueException
Show source code of this method: removeGroup Source Code

public bool
(mixed $xml = false)

Method to reset the form data store and optionally the form XML definition.
Parameters
  • bool $xml True to also reset the XML form definition.
Returns
  • bool True on success.
Since
  • 1.7.0
Show source code of this method: reset Source Code

public bool
(\SimpleXMLElement $element, mixed $group = null, mixed $replace = true, mixed $fieldset = 'default')

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.
Parameters
  • \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.
  • bool $replace True to replace an existing field if one already exists.
  • string $fieldset The name of the fieldset we are adding the field to.
Returns
  • bool True on success.
Since
  • 1.7.0
-
  • \UnexpectedValueException
Show source code of this method: setField Source Code

public bool
(mixed $name, mixed $attribute, mixed $value, mixed $group = null)

Method to set an attribute value for a field XML element.
Parameters
  • 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.
Returns
  • bool True on success.
Since
  • 1.7.0
-
  • \UnexpectedValueException
Show source code of this method: setFieldAttribute Source Code

public bool
(mixed &$elements, mixed $group = null, mixed $replace = true, mixed $fieldset = 'default')

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.
Parameters
  • 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.
  • bool $replace True to replace existing fields if they already exist.
  • string $fieldset The name of the fieldset we are adding the field to.
Returns
  • bool True on success.
Since
  • 1.7.0
-
  • \UnexpectedValueException
Show source code of this method: setFields Source Code

public bool
(mixed $name, mixed $group = null, mixed $value = null)

Method to set the value of a field. If the field does not exist in the form then the method will return false.
Parameters
  • 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.
Returns
  • bool True on success.
Since
  • 1.7.0
Show source code of this method: setValue Source Code

public mixed
(mixed $data, mixed $group = null)

Method to process the form data.
Parameters
  • array $data An array of field values to filter.
  • string $group The dot-separated form group path on which to filter the fields.
Returns
  • mixed Array or false.
Since
  • 4.0.0
Show source code of this method: process Source Code

public mixed
(mixed $data, mixed $group = null)

Method to filter the form data.
Parameters
  • array $data An array of field values to filter.
  • string $group The dot-separated form group path on which to filter the fields.
Returns
  • mixed Array or false.
Since
  • 4.0.0
Show source code of this method: filter Source Code

public bool
(mixed $data, mixed $group = null)

Method to validate form data.
Parameters
  • 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.
Returns
  • bool True on success.
Since
  • 1.7.0
Show source code of this method: validate Source Code

public mixed
(mixed $data, mixed $group = null)

Method to post-process form data.
Parameters
  • array $data An array of field values to post-process.
  • string $group The optional dot-separated form group path on which to filter the fields to be validated.
Returns
  • mixed Array or false.
Since
  • 4.0.0
Show source code of this method: postProcess Source Code

protected \SimpleXMLElement|bool
(mixed $name, mixed $group = null)

Method to get a form field represented as an XML element object.
Parameters
  • string $name The name of the form field.
  • string $group The optional dot-separated form group path on which to find the field.
Returns
  • \SimpleXMLElement|bool The XML element object for the field or boolean false on error.
Since
  • 1.7.0
Show source code of this method: findField Source Code

protected \SimpleXMLElement[]|bool
(mixed $name)

Method to get an array of `<field>` elements from the form XML document which are in a specified fieldset by name.
Parameters
  • string $name The name of the fieldset.
Returns
  • \SimpleXMLElement[]|bool Boolean false on error or array of SimpleXMLElement objects.
Since
  • 1.7.0
Show source code of this method: findFieldsByFieldset Source Code

protected \SimpleXMLElement[]|bool
(mixed $group = null, mixed $nested = false)

Method to get an array of `<field>` elements from the form XML document which are in a control group by name.
Parameters
  • 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.
  • bool $nested True to also include fields in nested groups that are inside of the group for which to find fields.
Returns
  • \SimpleXMLElement[]|bool Boolean false on error or array of SimpleXMLElement objects.
Since
  • 1.7.0
Show source code of this method: findFieldsByGroup Source Code

protected \SimpleXMLElement[]|bool
(mixed $group)

Method to get a form field group represented as an XML element object.
Parameters
  • string $group The dot-separated form group path on which to find the group.
Returns
  • \SimpleXMLElement[]|bool An array of XML element objects for the group or boolean false on error.
Since
  • 1.7.0
Show source code of this method: findGroup Source Code

protected \Joomla\CMS\Form\FormField|bool
(mixed $element, mixed $group = null, mixed $value = null)

Method to load, setup and return a FormField object based on field data.
Parameters
  • 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.
Returns
  • \Joomla\CMS\Form\FormField|bool The FormField object for the field or boolean false on error.
Since
  • 1.7.0
Show source code of this method: loadField Source Code

protected bool
()

Method to synchronize any field, form or rule paths contained in the XML document.
Returns
  • bool True on success.
Since
  • 1.7.0
-
  • Maybe we should receive all addXXXpaths attributes at once?
Show source code of this method: syncPaths Source Code

public static array
(mixed $new = null)

Proxy for {@link FormHelper::addFieldPath()}.
Parameters
  • mixed $new A path or array of paths to add.
Returns
  • array The list of paths that have been added.
Since
  • 1.7.0
Show source code of this method: addFieldPath Source Code

public static array
(mixed $new = null)

Proxy for FormHelper::addFormPath().
Parameters
  • mixed $new A path or array of paths to add.
Returns
  • array The list of paths that have been added.
Since
  • 1.7.0
-
  • \Joomla\CMS\Form\FormHelper::addFormPath()
Show source code of this method: addFormPath Source Code

public static array
(mixed $new = null)

Proxy for FormHelper::addRulePath().
Parameters
  • mixed $new A path or array of paths to add.
Returns
  • array The list of paths that have been added.
Since
  • 1.7.0
-
  • \Joomla\CMS\Form\FormHelper::addRulePath()
Show source code of this method: addRulePath Source Code

public static array
(mixed $new = null)

Proxy for FormHelper::addFilterPath().
Parameters
  • mixed $new A path or array of paths to add.
Returns
  • array The list of paths that have been added.
Since
  • 4.0.0
-
  • \Joomla\CMS\Form\FormHelper::addFilterPath()
Show source code of this method: addFilterPath Source Code

public static \Joomla\CMS\Form\Form
(mixed $name, mixed $data = null, mixed $options = [], mixed $replace = true, mixed $xpath = false)

Method to get an instance of a form.
Parameters
  • 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.
  • bool $replace Flag to toggle whether form fields should be replaced if a field already exists with the same group/name.
  • string|bool $xpath An optional xpath to search for the fields.
Returns
  • \Joomla\CMS\Form\Form Form instance.
Since
  • 1.7.0
Deprecated
  • 5.0
-
  • \InvalidArgumentException if no data provided.
  • \RuntimeException if the form could not be loaded.
Show source code of this method: getInstance Source Code

protected static void
(\SimpleXMLElement $source, \SimpleXMLElement $new)

Adds a new child SimpleXMLElement node to the source.
Parameters
  • \SimpleXMLElement $source The source element on which to append.
  • \SimpleXMLElement $new The new element to append.
Returns
  • void
Since
  • 1.7.0
Show source code of this method: addNode Source Code

protected static void
(\SimpleXMLElement $source, \SimpleXMLElement $new)

Update the attributes of a child node
Parameters
  • \SimpleXMLElement $source The source element on which to append the attributes
  • \SimpleXMLElement $new The new element to append
Returns
  • void
Since
  • 1.7.0
Show source code of this method: mergeNode Source Code

protected static void
(\SimpleXMLElement $source, \SimpleXMLElement $new)

Merges new elements into a source `<fields>` element.
Parameters
  • \SimpleXMLElement $source The source element.
  • \SimpleXMLElement $new The new element to merge.
Returns
  • void
Since
  • 1.7.0
Show source code of this method: mergeNodes Source Code

public mixed
(mixed $name, mixed $default = null)

Returns the value of an attribute of the form itself
Parameters
  • string $name Name of the attribute to get
  • mixed $default Optional value to return if attribute not found
Returns
  • mixed Value of the attribute / default
Since
  • 3.2
Show source code of this method: getAttribute Source Code

public \Joomla\Registry\Registry
()

Getter for the form data
Returns
  • \Joomla\Registry\Registry Object with the data
Since
  • 3.2
Show source code of this method: getData Source Code

public \SimpleXMLElement
()

Method to get the XML form object
Returns
  • \SimpleXMLElement The form XML object
Since
  • 3.2
Show source code of this method: getXml Source Code

public \SimpleXMLElement|bool
(mixed $name, mixed $group = null)

Method to get a form field represented as an XML element object.
Parameters
  • string $name The name of the form field.
  • string $group The optional dot-separated form group path on which to find the field.
Returns
  • \SimpleXMLElement|bool The XML element object for the field or boolean false on error.
Since
  • 3.7.0
Show source code of this method: getFieldXml Source Code

Properties Summary

protected \Joomla\Registry\Registry
$data
The Registry data store for form fields during display.
Since
  • 1.7.0
protected array
$errors
The form object errors array.
Since
  • 1.7.0
protected string
$name
The name of the form instance.
Since
  • 1.7.0
protected array
$options
The form object options for use in rendering and validation.
Since
  • 1.7.0
protected \SimpleXMLElement
$xml
The form XML definition.
Since
  • 1.7.0
protected static \Joomla\CMS\Form\Form[]
$forms
Form instances.
Since
  • 1.7.0
public bool
$repeat
Allows extensions to implement repeating elements
Since
  • 3.2

Tags Summary

Since
1.7.0