Joomla! API

link
since	1.7.0
package	Joomla CMS

Method to instantiate the form object.

__construct( name, mixed||string|int options = []) :

since	1.7.0

Arguments

name: stringThe name of the form.
options: array<string|int, mixed>An array of form options.

Response

mixed

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

addFieldPath(string|string[] new = null) : string||string|int

static

since	1.7.0

Arguments

new: string|array<string|int, string>A path or array of paths to add.

Response

array<string|int, string>The list of paths that have been added.

Proxy for FormHelper::addFilterPath().

addFilterPath(string|string[] new = null) : string||string|int

static

see	FormHelper::addFilterPath()
since	4.0.0

Arguments

new: string|array<string|int, string>A path or array of paths to add.

Response

array<string|int, string>The list of paths that have been added.

Proxy for FormHelper::addFormPath().

addFormPath(string|string[] new = null) : string||string|int

static

see	FormHelper::addFormPath()
since	1.7.0

Arguments

new: string|array<string|int, string>A path or array of paths to add.

Response

array<string|int, string>The list of paths that have been added.

Adds a new child SimpleXMLElement node to the source.

addNode(\SimpleXMLElement source, \SimpleXMLElement new) :

static

since	1.7.0

Arguments

source: SimpleXMLElementThe source element on which to append.
new: SimpleXMLElementThe new element to append.

Response

void

Proxy for FormHelper::addRulePath().

addRulePath(string|string[] new = null) : string||string|int

static

see	FormHelper::addRulePath()
since	1.7.0

Arguments

new: string|array<string|int, string>A path or array of paths to add.

Response

array<string|int, string>The list of paths that have been added.

Method to bind data to the form.

bind( data) :

since	1.7.0

Arguments

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

Response

boolTrue on success.

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

bindLevel( group,  data) :

since	1.7.0

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.

Response

void

Method to filter the form data.

filter(mixed||string|int data,  group = null) :

since	4.0.0

Arguments

data: array<string|int, mixed>An array of field values to filter.
group: stringThe dot-separated form group path on which to filter the fields.

Response

mixedArray or false.

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

findField( name,  group = null) : \SimpleXMLElement|bool

since	1.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|boolThe XML element object for the field or boolean false on error.

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

findFieldsByFieldset( name) : \SimpleXMLElement[]|bool

since	1.7.0

Arguments

name: stringThe name of the fieldset.

Response

array<string|int, SimpleXMLElement>|boolBoolean false on error or array of SimpleXMLElement objects.

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

findFieldsByGroup( group = null,  nested = false) : \SimpleXMLElement[]|bool

since	1.7.0

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: boolTrue to also include fields in nested groups that are inside of the group for which to find fields.

Response

array<string|int, SimpleXMLElement>|boolBoolean false on error or array of SimpleXMLElement objects.

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

findGroup( group) : \SimpleXMLElement[]|bool

since	1.7.0

Arguments

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

Response

array<string|int, SimpleXMLElement>|boolAn array of XML element objects for the group or boolean false on error.

Returns the value of an attribute of the form itself

getAttribute( name,  default = null) :

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

Getter for the form data

getData() : \Joomla\Registry\Registry

since	3.2

Response

RegistryObject with the data

Return Exceptions thrown during the form validation process.

getErrors() : \Exception||string|int

since	1.7.0

Response

array<string|int, Exception>

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

getField( name,  group = null,  value = null) : \Joomla\CMS\Form\FormField|bool

since	1.7.0

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

FormField|boolThe FormField object for the field or boolean false on error.

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( name,  attribute,  default = null,  group = null) :

since	1.7.0
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.

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

getFieldset( set = null) : \Joomla\CMS\Form\FormField||string|int

since	1.7.0

Arguments

set: stringThe optional name of the fieldset.

Response

array<string|int, FormField>The array of FormField objects in the fieldset.

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

getFieldsets( group = null) : object||string|int

since	1.7.0

Arguments

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

Response

array<string|int, object>The array of fieldset objects.

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

getFieldXml( name,  group = null) : \SimpleXMLElement|bool

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|boolThe XML element object for the field or boolean false on error.

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() :

since	1.7.0

Response

stringThe form control string.

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

getGroup( group,  nested = false) : \Joomla\CMS\Form\FormField||string|int

since	1.7.0

Arguments

group: stringThe dot-separated form group path for which to get the form fields.
nested: boolTrue to also include fields in nested groups that are inside of the group for which to find fields.

Response

array<string|int, FormField>The array of FormField objects in the field group.

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

getInput( name,  group = null,  value = null) :

since	1.7.0

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.

Method to get an instance of a form.

getInstance( name,  data = null, mixed||string|int options = [],  replace = true, string|bool xpath = false) : \Joomla\CMS\Form\Form

static deprecated

since

1.7.0

deprecated

4.3 will be removed in 6.0 Use the FormFactory service from the container Example: Factory::getContainer()->get(FormFactoryInterface::class)->createForm($name, $options);

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: array<string|int, mixed>An array of form options.
replace: boolFlag to toggle whether form fields should be replaced if a field already exists with the same group/name.
xpath: string|boolAn optional xpath to search for the fields.

Response

FormForm instance.

Method to get the label for a field input.

getLabel( name,  group = null) :

since	1.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

stringThe form field label.

Method to get the form name.

getName() :

since	1.7.0

Response

stringThe name of the form.

Method to get the value of a field.

getValue( name,  group = null,  default = null) :

since	1.7.0

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.

Method to get the XML form object

getXml() : \SimpleXMLElement

since	3.2

Response

SimpleXMLElementThe form XML object

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

load(string|\SimpleXMLElement data,  replace = true,  xpath = null) :

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	1.7.0

Arguments

data: string|SimpleXMLElementThe name of an XML string or object.
replace: boolFlag 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

boolTrue on success, false otherwise.

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

loadField(string|\SimpleXMLElement element,  group = null,  value = null) : \Joomla\CMS\Form\FormField|bool

since	1.7.0

Arguments

element: string|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.

Response

FormField|boolThe FormField object for the field or boolean false on error.

Method to load the form description from an XML file.

loadFile( file,  reset = true,  xpath = null) :

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	1.7.0

Arguments

file: stringThe filesystem path of an XML file.
reset: boolFlag 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

boolTrue on success, false otherwise.

Update the attributes of a child node

mergeNode(\SimpleXMLElement source, \SimpleXMLElement new) :

static

since	1.7.0

Arguments

source: SimpleXMLElementThe source element on which to append the attributes
new: SimpleXMLElementThe new element to append

Response

void

Merges new elements into a source <fields> element.

mergeNodes(\SimpleXMLElement source, \SimpleXMLElement new) :

static

since	1.7.0

Arguments

source: SimpleXMLElementThe source element.
new: SimpleXMLElementThe new element to merge.

Response

void

Method to post-process form data.

postProcess(mixed||string|int data,  group = null) :

since	4.0.0

Arguments

data: array<string|int, mixed>An array of field values to post-process.
group: stringThe optional dot-separated form group path on which to filter the fields to be validated.

Response

mixedArray or false.

Method to process the form data.

process(mixed||string|int data,  group = null) :

since	4.0.0

Arguments

data: array<string|int, mixed>An array of field values to filter.
group: stringThe dot-separated form group path on which to filter the fields.

Response

mixedArray or false.

Method to remove a field from the form definition.

removeField( name,  group = null) :

since	1.7.0
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

boolTrue on success, false otherwise.

Method to remove a group from the form definition.

removeGroup( group) :

since	1.7.0
throws	`UnexpectedValueException`

Arguments

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

Response

boolTrue on success.

Method to get a control group with label and input.

renderField( name,  group = null,  default = null, mixed||string|int options = []) :

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: array<string|int, mixed>Any options to be passed into the rendering of the field

Response

stringA string containing the html for the control group

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

renderFieldset( name, mixed||string|int options = []) :

since	3.2.3

Arguments

name: stringThe name of the fieldset for which to get the values.
options: array<string|int, mixed>Any options to be passed into the rendering of the field

Response

stringA string containing the html for the control groups

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

reset( xml = false) :

since	1.7.0

Arguments

xml: boolTrue to also reset the XML form definition.

Response

boolTrue on success.

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,  group = null,  replace = true,  fieldset = 'default') :

since	1.7.0
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: boolTrue to replace an existing field if one already exists.
fieldset: stringThe name of the fieldset we are adding the field to.

Response

boolTrue on success.

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

setFieldAttribute( name,  attribute,  value,  group = null) :

since	1.7.0
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

boolTrue on success.

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(\SimpleXMLElement||string|int &elements,  group = null,  replace = true,  fieldset = 'default') :

since	1.7.0
throws	`UnexpectedValueException`

Arguments

elements: array<string|int, SimpleXMLElement>The array of XML element object representations of the form fields.
group: stringThe optional dot-separated form group path on which to set the fields.
replace: boolTrue to replace existing fields if they already exist.
fieldset: stringThe name of the fieldset we are adding the field to.

Response

boolTrue on success.

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

setValue( name,  group = null,  value = null) :

since	1.7.0

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

boolTrue on success.

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

syncPaths() :

since	1.7.0
todo	Maybe we should receive all addXXXpaths attributes at once?

Response

boolTrue on success.

Method to validate form data.

validate(mixed||string|int data,  group = null) :

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

since	1.7.0

Arguments

data: array<string|int, mixed>An array of field values to validate.
group: stringThe optional dot-separated form group path on which to filter the fields to be validated.

Response

boolTrue on success.

The Registry data store for form fields during display.

since	1.7.0

Type(s)

Registry

The form object errors array.

since	1.7.0

Type(s)

array<string|int, Exception>

The name of the form instance.

since	1.7.0

Type(s)

string

The form object options for use in rendering and validation.

since	1.7.0

Type(s)

array<string|int, mixed>

The form XML definition.

since	1.7.0

Type(s)

SimpleXMLElement

Form instances.

static

since	1.7.0

Type(s)

array<string|int, Form>

Allows extensions to implement repeating elements

since	3.2

Type(s)

bool

Form

Methods

__construct

Arguments

Response

addFieldPath

Arguments

Response

addFilterPath

Arguments

Response

addFormPath

Arguments

Response

addNode

Arguments

Response

addRulePath

Arguments

Response

bind

Arguments

Response

bindLevel

Arguments

Response

filter

Arguments

Response

findField

Arguments

Response

findFieldsByFieldset

Arguments

Response

findFieldsByGroup

Arguments

Response

findGroup

Arguments

Response

getAttribute

Arguments

Response

getData

Response

getErrors

Response

getField

Arguments

Response

getFieldAttribute

Arguments

Response

getFieldset

Arguments

Response

getFieldsets

Arguments

Response

getFieldXml

Arguments

Response

getFormControl

Response

getGroup

Arguments

Response

getInput

Arguments

Response

getInstance

Arguments

Response

getLabel

Arguments

Response

getName

Response

getValue