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.

link

http://www.w3.org/TR/html4/interact/forms.html

http://www.w3.org/TR/html5/forms.html

since

11.1

package

Joomla.Platform

Methods

__construct

Method to instantiate the form object.

__construct(string $name, array $options = array()) 
since

11.1

Arguments

$name

stringThe name of the form.

$options

arrayAn array of form options.

addFieldPath

Proxy for {@link JFormHelper::addFieldPath()}.

addFieldPath(mixed $new = null) : array
static
since

11.1

Arguments

$new

mixedA path or array of paths to add.

Response

arrayThe list of paths that have been added.

addFormPath

Proxy for JFormHelper::addFormPath().

addFormPath(mixed $new = null) : array
static
see \JFormHelper::addFormPath()
since

11.1

Arguments

$new

mixedA path or array of paths to add.

Response

arrayThe list of paths that have been added.

addNode

Adds a new child SimpleXMLElement node to the source.

addNode(\SimpleXMLElement $source, \SimpleXMLElement $new) : void
static
since

11.1

Arguments

$source

\SimpleXMLElementThe source element on which to append.

$new

\SimpleXMLElementThe new element to append.

addRulePath

Proxy for JFormHelper::addRulePath().

addRulePath(mixed $new = null) : array
static
see \JFormHelper::addRulePath()
since

11.1

Arguments

$new

mixedA path or array of paths to add.

Response

arrayThe list of paths that have been added.

bind

Method to bind data to the form.

bind(mixed $data) : boolean
since

11.1

Arguments

$data

mixedAn array or object of data to bind to the form.

Response

booleanTrue on success.

bindLevel

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

bindLevel(string $group, mixed $data) : void
since

11.1

Arguments

$group

stringThe dot-separated form group path on which to bind the data.

$data

mixedAn array or object of data to bind to the form for the group level.

filter

Method to filter the form data.

filter(array $data, string $group = null) : mixed
since

11.1

Arguments

$data

arrayAn array of field values to filter.

$group

stringThe dot-separated form group path on which to filter the fields.

Response

mixedArray or false.

filterField

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

filterField(string $element, mixed $value) : mixed
since

11.1

Arguments

$element

stringThe XML element object representation of the form field.

$value

mixedThe value to filter for the field.

Response

mixedThe filtered value.

findField

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

findField(string $name, string $group = null) : \SimpleXMLElement|boolean
since

11.1

Arguments

$name

stringThe name of the form field.

$group

stringThe optional dot-separated form group path on which to find the field.

Response

\SimpleXMLElement|booleanThe XML element object for the field or boolean false on error.

findFieldsByFieldset

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

findFieldsByFieldset(string $name) : array<mixed,\SimpleXMLElement>|boolean
since

11.1

Arguments

$name

stringThe name of the fieldset.

Response

array<mixed,\SimpleXMLElement>|booleanBoolean false on error or array of SimpleXMLElement objects.

findFieldsByGroup

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

findFieldsByGroup(mixed $group = null, boolean $nested = false) : array<mixed,\SimpleXMLElement>|boolean
since

11.1

Arguments

$group

mixedThe 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

booleanTrue to also include fields in nested groups that are inside of the group for which to find fields.

Response

array<mixed,\SimpleXMLElement>|booleanBoolean false on error or array of SimpleXMLElement objects.

findGroup

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

findGroup(string $group) : array<mixed,\SimpleXMLElement>|boolean
since

11.1

Arguments

$group

stringThe dot-separated form group path on which to find the group.

Response

array<mixed,\SimpleXMLElement>|booleanAn array of XML element objects for the group or boolean false on error.

getAttribute

Returns the value of an attribute of the form itself

getAttribute(string $name, mixed $default = null) : mixed
since

3.2

Arguments

$name

stringName of the attribute to get

$default

mixedOptional value to return if attribute not found

Response

mixedValue of the attribute / default

getControlGroup

Method to get a control group with label and input.

getControlGroup(string $name, string $group = null, mixed $default = null) : string
deprecated
since

3.2

deprecated

3.2.3 Use renderField() instead of getControlGroup

Arguments

$name

stringThe name of the field for which to get the value.

$group

stringThe optional dot-separated form group path on which to get the value.

$default

mixedThe optional default value of the field value is empty.

Response

stringA string containing the html for the control goup

getControlGroups

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

getControlGroups(string $name) : string
deprecated
since

3.2

deprecated

3.2.3 Use renderFieldset() instead of getControlGroups

Arguments

$name

stringThe name of the fieldset for which to get the values.

Response

stringA string containing the html for the control goups

getData

Getter for the form data

getData() : \Joomla\Registry\Registry
since

3.2

Response

\Joomla\Registry\RegistryObject with the data

getErrors

Return all errors, if any.

getErrors() : array
since

11.1

Response

arrayArray of error messages or RuntimeException objects.

getField

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

getField(string $name, string $group = null, mixed $value = null) : \JFormField|boolean
since

11.1

Arguments

$name

stringThe name of the form field.

$group

stringThe optional dot-separated form group path on which to find the field.

$value

mixedThe optional value to use as the default for the field.

Response

\JFormField|booleanThe JFormField object for the field or boolean false on error.

getFieldAttribute

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.

getFieldAttribute(string $name, string $attribute, mixed $default = null, string $group = null) : mixed
since

11.1

throws

\UnexpectedValueException

Arguments

$name

stringThe name of the form field for which to get the attribute value.

$attribute

stringThe name of the attribute for which to get a value.

$default

mixedThe optional default value to use if no attribute value exists.

$group

stringThe optional dot-separated form group path on which to find the field.

Response

mixedThe attribute value for the field.

getFieldset

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

getFieldset(string $set = null) : array
since

11.1

Arguments

$set

stringThe optional name of the fieldset.

Response

arrayThe array of JFormField objects in the fieldset.

getFieldsets

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

getFieldsets(string $group = null) : array
since

11.1

Arguments

$group

stringThe dot-separated form group path on which to filter the fieldsets.

Response

arrayThe array of fieldset objects.

getFieldXml

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

getFieldXml(string $name, string $group = null) : \SimpleXMLElement|boolean
since

3.7.0

Arguments

$name

stringThe name of the form field.

$group

stringThe optional dot-separated form group path on which to find the field.

Response

\SimpleXMLElement|booleanThe XML element object for the field or boolean false on error.

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]" />.

getFormControl() : string
since

11.1

Response

stringThe form control string.

getGroup

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

getGroup(string $group, boolean $nested = false) : array
since

11.1

Arguments

$group

stringThe dot-separated form group path for which to get the form fields.

$nested

booleanTrue to also include fields in nested groups that are inside of the group for which to find fields.

Response

arrayThe array of JFormField objects in the field group.

getInput

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

getInput(string $name, string $group = null, mixed $value = null) : string
since

11.1

Arguments

$name

stringThe name of the form field.

$group

stringThe optional dot-separated form group path on which to find the field.

$value

mixedThe optional value to use as the default for the field.

Response

stringThe form field markup.

getInstance

Method to get an instance of a form.

getInstance(string $name, string $data = null, array $options = array(), boolean $replace = true, string|boolean $xpath = false) : \JForm
static
since

11.1

throws

\InvalidArgumentExceptionif no data provided.

\RuntimeExceptionif the form could not be loaded.

Arguments

$name

stringThe name of the form.

$data

stringThe name of an XML file or string to load as the form definition.

$options

arrayAn array of form options.

$replace

booleanFlag to toggle whether form fields should be replaced if a field already exists with the same group/name.

$xpath

string|booleanAn optional xpath to search for the fields.

Response

\JFormJForm instance.

getLabel

Method to get the label for a field input.

getLabel(string $name, string $group = null) : string
since

11.1

Arguments

$name

stringThe name of the form field.

$group

stringThe optional dot-separated form group path on which to find the field.

Response

stringThe form field label.

getName

Method to get the form name.

getName() : string
since

11.1

Response

stringThe name of the form.

getValue

Method to get the value of a field.

getValue(string $name, string $group = null, mixed $default = null) : mixed
since

11.1

Arguments

$name

stringThe name of the field for which to get the value.

$group

stringThe optional dot-separated form group path on which to get the value.

$default

mixedThe optional default value of the field value is empty.

Response

mixedThe value of the field or the default value if empty.

getXml

Method to get the XML form object

getXml() : \SimpleXMLElement
since

3.2

Response

\SimpleXMLElementThe form XML object

load

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

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

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.

since

11.1

Arguments

$data

stringThe name of an XML string or object.

$replace

stringFlag to toggle whether form fields should be replaced if a field already exists with the same group/name.

$xpath

stringAn optional xpath to search for the fields.

Response

booleanTrue on success, false otherwise.

loadField

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

loadField(string $element, string $group = null, mixed $value = null) : \JFormField|boolean
since

11.1

Arguments

$element

stringThe XML element object representation of the form field.

$group

stringThe optional dot-separated form group path on which to find the field.

$value

mixedThe optional value to use as the default for the field.

Response

\JFormField|booleanThe JFormField object for the field or boolean false on error.

loadFieldType

Proxy for {@link JFormHelper::loadFieldType()}.

loadFieldType(string $type, boolean $new = true) : \JFormField|boolean
since

11.1

Arguments

$type

stringThe field type.

$new

booleanFlag to toggle whether we should get a new instance of the object.

Response

\JFormField|booleanJFormField object on success, false otherwise.

loadFile

Method to load the form description from an XML file.

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

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.

since

11.1

Arguments

$file

stringThe filesystem path of an XML file.

$reset

stringFlag to toggle whether form fields should be replaced if a field already exists with the same group/name.

$xpath

stringAn optional xpath to search for the fields.

Response

booleanTrue on success, false otherwise.

loadRuleType

Proxy for JFormHelper::loadRuleType().

loadRuleType(string $type, boolean $new = true) : \JFormRule|boolean
see \JFormHelper::loadRuleType()
since

11.1

Arguments

$type

stringThe rule type.

$new

booleanFlag to toggle whether we should get a new instance of the object.

Response

\JFormRule|booleanJFormRule object on success, false otherwise.

mergeNode

Update the attributes of a child node

mergeNode(\SimpleXMLElement $source, \SimpleXMLElement $new) : void
static
since

11.1

Arguments

$source

\SimpleXMLElementThe source element on which to append the attributes

$new

\SimpleXMLElementThe new element to append

mergeNodes

Merges new elements into a source <fields> element.

mergeNodes(\SimpleXMLElement $source, \SimpleXMLElement $new) : void
static
since

11.1

Arguments

$source

\SimpleXMLElementThe source element.

$new

\SimpleXMLElementThe new element to merge.

removeField

Method to remove a field from the form definition.

removeField(string $name, string $group = null) : boolean
since

11.1

throws

\UnexpectedValueException

Arguments

$name

stringThe name of the form field for which remove.

$group

stringThe optional dot-separated form group path on which to find the field.

Response

booleanTrue on success, false otherwise.

removeGroup

Method to remove a group from the form definition.

removeGroup(string $group) : boolean
since

11.1

throws

\UnexpectedValueException

Arguments

$group

stringThe dot-separated form group path for the group to remove.

Response

booleanTrue on success.

renderField

Method to get a control group with label and input.

renderField(string $name, string $group = null, mixed $default = null, array $options = array()) : string
since

3.2.3

Arguments

$name

stringThe name of the field for which to get the value.

$group

stringThe optional dot-separated form group path on which to get the value.

$default

mixedThe optional default value of the field value is empty.

$options

arrayAny options to be passed into the rendering of the field

Response

stringA string containing the html for the control goup

renderFieldset

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

renderFieldset(string $name, array $options = array()) : string
since

3.2.3

Arguments

$name

stringThe name of the fieldset for which to get the values.

$options

arrayAny options to be passed into the rendering of the field

Response

stringA string containing the html for the control goups

reset

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

reset(boolean $xml = false) : boolean
since

11.1

Arguments

$xml

booleanTrue to also reset the XML form definition.

Response

booleanTrue on success.

setField

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.

setField(\SimpleXMLElement $element, string $group = null, boolean $replace = true, string $fieldset = 'default') : boolean
since

11.1

throws

\UnexpectedValueException

Arguments

$element

\SimpleXMLElementThe XML element object representation of the form field.

$group

stringThe optional dot-separated form group path on which to set the field.

$replace

booleanTrue to replace an existing field if one already exists.

$fieldset

stringThe name of the fieldset we are adding the field to.

Response

booleanTrue on success.

setFieldAttribute

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

setFieldAttribute(string $name, string $attribute, mixed $value, string $group = null) : boolean
since

11.1

throws

\UnexpectedValueException

Arguments

$name

stringThe name of the form field for which to set the attribute value.

$attribute

stringThe name of the attribute for which to set a value.

$value

mixedThe value to set for the attribute.

$group

stringThe optional dot-separated form group path on which to find the field.

Response

booleanTrue on success.

setFields

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.

setFields( &$elements, string $group = null, boolean $replace = true, string $fieldset = 'default') : boolean
since

11.1

throws

\UnexpectedValueException

Arguments

$elements

$group

stringThe optional dot-separated form group path on which to set the fields.

$replace

booleanTrue to replace existing fields if they already exist.

$fieldset

stringThe name of the fieldset we are adding the field to.

Response

booleanTrue on success.

setValue

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

setValue(string $name, string $group = null, mixed $value = null) : boolean
since

11.1

Arguments

$name

stringThe name of the field for which to set the value.

$group

stringThe optional dot-separated form group path on which to find the field.

$value

mixedThe value to set for the field.

Response

booleanTrue on success.

syncPaths

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

syncPaths() : boolean
since

11.1

todo

Maybe we should receive all addXXXpaths attributes at once?

Response

booleanTrue on success.

validate

Method to validate form data.

validate(array $data, string $group = null) : boolean

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

since

11.1

Arguments

$data

arrayAn array of field values to validate.

$group

stringThe optional dot-separated form group path on which to filter the fields to be validated.

Response

booleanTrue on success.

validateField

Method to validate a JFormField object based on field data.

validateField(\SimpleXMLElement $element, string $group = null, mixed $value = null, \Joomla\Registry\Registry $input = null) : boolean
since

11.1

throws

\InvalidArgumentException

\UnexpectedValueException

Arguments

$element

\SimpleXMLElementThe XML element object representation of the form field.

$group

stringThe optional dot-separated form group path on which to find the field.

$value

mixedThe optional value to use as the default for the field.

$input

\Joomla\Registry\RegistryAn optional Registry object with the entire data set to validate against the entire form.

Response

booleanBoolean true if field value is valid, Exception on failure.

Properties

data

The Registry data store for form fields during display.

errors

The form object errors array.

Type(s)

array

name

The name of the form instance.

Type(s)

string

options

The form object options for use in rendering and validation.

Type(s)

array

xml

The form XML definition.

Type(s)

\SimpleXMLElement

forms

Form instances.

static

Type(s)

array<mixed,\JForm>

repeat

Alows extensions to implement repeating elements

Type(s)

boolean