Class JForm

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.

Direct known subclasses

FOFForm

Package: Joomla\Platform\Form
Copyright: Copyright (C) 2005 - 2017 Open Source Matters, Inc. All rights reserved.
License: General Public License version 2 or later; see LICENSE
Since: 11.1
Link: http://www.w3.org/TR/html4/interact/forms.html
Link: http://www.w3.org/TR/html5/forms.html
Located at joomla/form/form.php

Methods summary

`public`	# `__construct( string $name, array $options = array() )` Method to instantiate the form object. Method to instantiate the form object. Parameters `$name` `string` - $name The name of the form. `$options` `array` - $options An array of form options. Since 11.1
`public boolean`	# `bind( mixed $data )` Method to bind data to the form. Method to bind data to the form. Parameters `$data` `mixed` - $data An array or object of data to bind to the form. Returns `boolean` - True on success. Since 11.1
`protected`	# `bindLevel( string $group, mixed $data )` Method to bind data to the form for the group level. Method to bind data to the form for the group level. Parameters `$group` `string` - $group The dot-separated form group path on which to bind the data. `$data` `mixed` - $data An array or object of data to bind to the form for the group level. Since 11.1
`public mixed`	# `filter( array $data, string $group = null )` Method to filter the form data. Method to filter the form data. Parameters `$data` `array` - $data An array of field values to filter. `$group` `string` - $group The dot-separated form group path on which to filter the fields. Returns `mixed` - Array or false. Since 11.1
`public array`	# `getErrors( )` Return all errors, if any. Return all errors, if any. Returns `array` - Array of error messages or RuntimeException objects. Since 11.1
`public JFormField\|boolean`	# `getField( string $name, string $group = null, mixed $value = null )` Method to get a form field represented as a JFormField object. Method to get a form field represented as a JFormField object. Parameters `$name` `string` - $name The name of the form field. `$group` `string` - $group The optional dot-separated form group path on which to find the field. `$value` `mixed` - $value The optional value to use as the default for the field. Returns `JFormField\|boolean` - The JFormField object for the field or boolean false on error. Since 11.1
`public mixed`	# `getFieldAttribute( string $name, string $attribute, mixed $default = null, string $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. 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 `$name` `string` - $name The name of the form field for which to get the attribute value. `$attribute` `string` - $attribute The name of the attribute for which to get a value. `$default` `mixed` - $default The optional default value to use if no attribute value exists. `$group` `string` - $group The optional dot-separated form group path on which to find the field. Returns `mixed` - The attribute value for the field. Throws `UnexpectedValueException` Since 11.1
`public array`	# `getFieldset( string $set = null )` Method to get an array of JFormField objects in a given fieldset by name. If no name is given then all fields are returned. Method to get an array of JFormField objects in a given fieldset by name. If no name is given then all fields are returned. Parameters `$set` `string` - $set The optional name of the fieldset. Returns `array` - The array of JFormField objects in the fieldset. Since 11.1
`public array`	# `getFieldsets( string $group = null )` Method to get an array of fieldset objects optionally filtered over a given field group. Method to get an array of fieldset objects optionally filtered over a given field group. Parameters `$group` `string` - $group The dot-separated form group path on which to filter the fieldsets. Returns `array` - The array of fieldset objects. Since 11.1
`public string`	# `getFormControl( )` 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]" />`. 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 11.1
`public array`	# `getGroup( string $group, boolean $nested = false )` Method to get an array of JFormField objects in a given field group by name. Method to get an array of JFormField objects in a given field group by name. Parameters `$group` `string` - $group The dot-separated form group path for which to get the form fields. `$nested` `boolean` - $nested True to also include fields in nested groups that are inside of the group for which to find fields. Returns `array` - The array of JFormField objects in the field group. Since 11.1
`public string`	# `getInput( string $name, string $group = null, mixed $value = null )` Method to get a form field markup for the field input. Method to get a form field markup for the field input. Parameters `$name` `string` - $name The name of the form field. `$group` `string` - $group The optional dot-separated form group path on which to find the field. `$value` `mixed` - $value The optional value to use as the default for the field. Returns `string` - The form field markup. Since 11.1
`public string`	# `getLabel( string $name, string $group = null )` Method to get the label for a field input. Method to get the label for a field input. Parameters `$name` `string` - $name The name of the form field. `$group` `string` - $group The optional dot-separated form group path on which to find the field. Returns `string` - The form field label. Since 11.1
`public string`	# `getName( )` Method to get the form name. Method to get the form name. Returns `string` - The name of the form. Since 11.1
`public mixed`	# `getValue( string $name, string $group = null, mixed $default = null )` Method to get the value of a field. Method to get the value of a field. Parameters `$name` `string` - $name The name of the field for which to get the value. `$group` `string` - $group The optional dot-separated form group path on which to get the value. `$default` `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 11.1
`public string`	# `getControlGroup( string $name, string $group = null, mixed $default = null )` Method to get a control group with label and input. Method to get a control group with label and input. Deprecated 3.2.3 Use renderField() instead of getControlGroup Parameters `$name` `string` - $name The name of the field for which to get the value. `$group` `string` - $group The optional dot-separated form group path on which to get the value. `$default` `mixed` - $default The optional default value of the field value is empty. Returns `string` - A string containing the html for the control goup Since 3.2
`public string`	# `getControlGroups( string $name )` Method to get all control groups with label and input of a fieldset. Method to get all control groups with label and input of a fieldset. Deprecated 3.2.3 Use renderFieldset() instead of getControlGroups Parameters `$name` `string` - $name The name of the fieldset for which to get the values. Returns `string` - A string containing the html for the control goups Since 3.2
`public string`	# `renderField( string $name, string $group = null, mixed $default = null, array $options = array() )` Method to get a control group with label and input. Method to get a control group with label and input. Parameters `$name` `string` - $name The name of the field for which to get the value. `$group` `string` - $group The optional dot-separated form group path on which to get the value. `$default` `mixed` - $default The optional default value of the field value is empty. `$options` `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
`public string`	# `renderFieldset( string $name, array $options = array() )` Method to get all control groups with label and input of a fieldset. Method to get all control groups with label and input of a fieldset. Parameters `$name` `string` - $name The name of the fieldset for which to get the values. `$options` `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
`public boolean`	# `load( string $data, string $replace = true, string $xpath = false )` Method to load the form description from an XML string or object. 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. Parameters `$data` `string` - $data The name of an XML string or object. `$replace` `string` - $replace Flag to toggle whether form fields should be replaced if a field already exists with the same group/name. `$xpath` `string` - $xpath An optional xpath to search for the fields. Returns `boolean` - True on success, false otherwise. Since 11.1
`public boolean`	# `loadFile( string $file, string $reset = true, string $xpath = false )` Method to load the form description from an XML file. 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. Parameters `$file` `string` - $file The filesystem path of an XML file. `$reset` `string` - $reset Flag to toggle whether form fields should be replaced if a field already exists with the same group/name. `$xpath` `string` - $xpath An optional xpath to search for the fields. Returns `boolean` - True on success, false otherwise. Since 11.1
`public boolean`	# `removeField( string $name, string $group = null )` Method to remove a field from the form definition. Method to remove a field from the form definition. Parameters `$name` `string` - $name The name of the form field for which remove. `$group` `string` - $group The optional dot-separated form group path on which to find the field. Returns `boolean` - True on success, false otherwise. Throws `UnexpectedValueException` Since 11.1
`public boolean`	# `removeGroup( string $group )` Method to remove a group from the form definition. Method to remove a group from the form definition. Parameters `$group` `string` - $group The dot-separated form group path for the group to remove. Returns `boolean` - True on success. Throws `UnexpectedValueException` Since 11.1
`public boolean`	# `reset( boolean $xml = false )` Method to reset the form data store and optionally the form XML definition. Method to reset the form data store and optionally the form XML definition. Parameters `$xml` `boolean` - $xml True to also reset the XML form definition. Returns `boolean` - True on success. Since 11.1
`public boolean`	# `setField( SimpleXMLElement $element, string $group = null, boolean $replace = true, string $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. 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 `$element` `SimpleXMLElement` - $element The XML element object representation of the form field. `$group` `string` - $group The optional dot-separated form group path on which to set the field. `$replace` `boolean` - $replace True to replace an existing field if one already exists. `$fieldset` `string` - $fieldset The name of the fieldset we are adding the field to. Returns `boolean` - True on success. Throws `UnexpectedValueException` Since 11.1
`public boolean`	# `setFieldAttribute( string $name, string $attribute, mixed $value, string $group = null )` Method to set an attribute value for a field XML element. Method to set an attribute value for a field XML element. Parameters `$name` `string` - $name The name of the form field for which to set the attribute value. `$attribute` `string` - $attribute The name of the attribute for which to set a value. `$value` `mixed` - $value The value to set for the attribute. `$group` `string` - $group The optional dot-separated form group path on which to find the field. Returns `boolean` - True on success. Throws `UnexpectedValueException` Since 11.1
`public boolean`	# `setFields( array & $elements, string $group = null, boolean $replace = true, string $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. 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 `$elements` `array` - &$elements The array of XML element object representations of the form fields. `$group` `string` - $group The optional dot-separated form group path on which to set the fields. `$replace` `boolean` - $replace True to replace existing fields if they already exist. `$fieldset` `string` - $fieldset The name of the fieldset we are adding the field to. Returns `boolean` - True on success. Throws `UnexpectedValueException` Since 11.1
`public boolean`	# `setValue( string $name, string $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. Method to set the value of a field. If the field does not exist in the form then the method will return false. Parameters `$name` `string` - $name The name of the field for which to set the value. `$group` `string` - $group The optional dot-separated form group path on which to find the field. `$value` `mixed` - $value The value to set for the field. Returns `boolean` - True on success. Since 11.1
`public boolean`	# `validate( array $data, string $group = null )` Method to validate form data. 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. Parameters `$data` `array` - $data An array of field values to validate. `$group` `string` - $group The optional dot-separated form group path on which to filter the fields to be validated. Returns `boolean` - True on success. Since 11.1
`protected mixed`	# `filterField( string $element, mixed $value )` Method to apply an input filter to a value based on field data. Method to apply an input filter to a value based on field data. Parameters `$element` `string` - $element The XML element object representation of the form field. `$value` `mixed` - $value The value to filter for the field. Returns `mixed` - The filtered value. Since 11.1
`protected SimpleXMLElement\|boolean`	# `findField( string $name, string $group = null )` Method to get a form field represented as an XML element object. Method to get a form field represented as an XML element object. Parameters `$name` `string` - $name The name of the form field. `$group` `string` - $group The optional dot-separated form group path on which to find the field. Returns `SimpleXMLElement\|boolean` - The XML element object for the field or boolean false on error. Since 11.1
`protected SimpleXMLElement[]\|boolean &`	# `findFieldsByFieldset( string $name )` Method to get an array of `<field>` elements from the form XML document which are in a specified fieldset by name. Method to get an array of `<field>` elements from the form XML document which are in a specified fieldset by name. Parameters `$name` `string` - $name The name of the fieldset. Returns `SimpleXMLElement[]\|boolean` - Boolean false on error or array of SimpleXMLElement objects. Since 11.1
`protected SimpleXMLElement[]\|boolean &`	# `findFieldsByGroup( mixed $group = null, boolean $nested = false )` Method to get an array of `<field>` elements from the form XML document which are in a control group by name. Method to get an array of `<field>` elements from the form XML document which are in a control group by name. Parameters `$group` `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. `$nested` `boolean` - $nested True to also include fields in nested groups that are inside of the group for which to find fields. Returns `SimpleXMLElement[]\|boolean` - Boolean false on error or array of SimpleXMLElement objects. Since 11.1
`protected SimpleXMLElement[]\|boolean &`	# `findGroup( string $group )` Method to get a form field group represented as an XML element object. Method to get a form field group represented as an XML element object. Parameters `$group` `string` - $group The dot-separated form group path on which to find the group. Returns `SimpleXMLElement[]\|boolean` - An array of XML element objects for the group or boolean false on error. Since 11.1
`protected JFormField\|boolean`	# `loadField( string $element, string $group = null, mixed $value = null )` Method to load, setup and return a JFormField object based on field data. Method to load, setup and return a JFormField object based on field data. Parameters `$element` `string` - $element The XML element object representation of the form field. `$group` `string` - $group The optional dot-separated form group path on which to find the field. `$value` `mixed` - $value The optional value to use as the default for the field. Returns `JFormField\|boolean` - The JFormField object for the field or boolean false on error. Since 11.1
`protected JFormField\|boolean`	# `loadFieldType( string $type, boolean $new = true )` Proxy for `JFormHelper::loadFieldType()`. Proxy for `JFormHelper::loadFieldType()`. Parameters `$type` `string` - $type The field type. `$new` `boolean` - $new Flag to toggle whether we should get a new instance of the object. Returns `JFormField\|boolean` - JFormField object on success, false otherwise. Since 11.1
`protected JFormRule\|boolean`	# `loadRuleType( string $type, boolean $new = true )` Proxy for JFormHelper::loadRuleType(). Proxy for JFormHelper::loadRuleType(). Parameters `$type` `string` - $type The rule type. `$new` `boolean` - $new Flag to toggle whether we should get a new instance of the object. Returns `JFormRule\|boolean` - JFormRule object on success, false otherwise. Since 11.1 See `JFormHelper::loadRuleType()`
`protected boolean`	# `syncPaths( )` Method to synchronize any field, form or rule paths contained in the XML document. Method to synchronize any field, form or rule paths contained in the XML document. Returns `boolean` - True on success. Since 11.1
`protected boolean`	# `validateField( SimpleXMLElement $element, string $group = null, mixed $value = null, Joomla\Registry\Registry $input = null )` Method to validate a JFormField object based on field data. Method to validate a JFormField object based on field data. Parameters `$element` `SimpleXMLElement` - $element The XML element object representation of the form field. `$group` `string` - $group The optional dot-separated form group path on which to find the field. `$value` `mixed` - $value The optional value to use as the default for the field. `$input` `Joomla\Registry\Registry` - $input An optional Registry object with the entire data set to validate against the entire form. Returns `boolean` - Boolean true if field value is valid, Exception on failure. Throws `InvalidArgumentException` `UnexpectedValueException` Since 11.1
`public static array`	# `addFieldPath( mixed $new = null )` Proxy for `JFormHelper::addFieldPath()`. Proxy for `JFormHelper::addFieldPath()`. Parameters `$new` `mixed` - $new A path or array of paths to add. Returns `array` - The list of paths that have been added. Since 11.1
`public static array`	# `addFormPath( mixed $new = null )` Proxy for JFormHelper::addFormPath(). Proxy for JFormHelper::addFormPath(). Parameters `$new` `mixed` - $new A path or array of paths to add. Returns `array` - The list of paths that have been added. Since 11.1 See `JFormHelper::addFormPath()`
`public static array`	# `addRulePath( mixed $new = null )` Proxy for JFormHelper::addRulePath(). Proxy for JFormHelper::addRulePath(). Parameters `$new` `mixed` - $new A path or array of paths to add. Returns `array` - The list of paths that have been added. Since 11.1 See `JFormHelper::addRulePath()`
`public static JForm`	# `getInstance( string $name, string $data = null, array $options = array(), boolean $replace = true, string\|boolean $xpath = false )` Method to get an instance of a form. Method to get an instance of a form. Parameters `$name` `string` - $name The name of the form. `$data` `string` - $data The name of an XML file or string to load as the form definition. `$options` `array` - $options An array of form options. `$replace` `boolean` - $replace Flag to toggle whether form fields should be replaced if a field already exists with the same group/name. `$xpath` `string\|boolean` - $xpath An optional xpath to search for the fields. Returns `JForm` - JForm instance. Throws `InvalidArgumentException` - if no data provided. `RuntimeException` - if the form could not be loaded. Since 11.1
`protected static`	# `addNode( SimpleXMLElement $source, SimpleXMLElement $new )` Adds a new child SimpleXMLElement node to the source. Adds a new child SimpleXMLElement node to the source. Parameters `$source` `SimpleXMLElement` - $source The source element on which to append. `$new` `SimpleXMLElement` - $new The new element to append. Since 11.1
`protected static`	# `mergeNode( SimpleXMLElement $source, SimpleXMLElement $new )` Update the attributes of a child node Update the attributes of a child node Parameters `$source` `SimpleXMLElement` - $source The source element on which to append the attributes `$new` `SimpleXMLElement` - $new The new element to append Since 11.1
`protected static`	# `mergeNodes( SimpleXMLElement $source, SimpleXMLElement $new )` Merges new elements into a source `<fields>` element. Merges new elements into a source `<fields>` element. Parameters `$source` `SimpleXMLElement` - $source The source element. `$new` `SimpleXMLElement` - $new The new element to merge. Since 11.1
`public mixed`	# `getAttribute( string $name, mixed $default = null )` Returns the value of an attribute of the form itself Returns the value of an attribute of the form itself Parameters `$name` `string` - $name Name of the attribute to get `$default` `mixed` - $default Optional value to return if attribute not found Returns `mixed` - Value of the attribute / default Since 3.2
`public Joomla\Registry\Registry`	# `getData( )` Getter for the form data Getter for the form data Returns `Joomla\Registry\Registry` - Object with the data Since 3.2
`public SimpleXMLElement`	# `getXml( )` Method to get the XML form object Method to get the XML form object Returns `SimpleXMLElement` - The form XML object Since 3.2
`public SimpleXMLElement\|boolean`	# `getFieldXml( string $name, string $group = null )` Method to get a form field represented as an XML element object. Method to get a form field represented as an XML element object. Parameters `$name` `string` - $name The name of the form field. `$group` `string` - $group The optional dot-separated form group path on which to find the field. Returns `SimpleXMLElement\|boolean` - The XML element object for the field or boolean false on error. Since 3.7.0

Magic methods summary

Properties summary

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

Namespaces

Classes

Interfaces

Exceptions

Constants

Functions

Class JForm

Direct known subclasses

Methods summary

Parameters

Since

Parameters

Returns

Since

Parameters

Since

Parameters

Returns

Since

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Throws

Since

Parameters

Returns

Since

Parameters

Returns

Since

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Since

Returns

Since

Parameters

Returns

Since

Deprecated

Parameters

Returns

Since

Deprecated

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Throws

Since

Parameters

Returns

Throws

Since

Parameters

Returns