PHPXRef 0.7.1 : Joomla 4.2.2 documentation : Detail view of Form.php

Class: Form - X-Ref

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.

__construct($name, array $options = []) X-Ref

Method to instantiate the form object.

param: string $name The name of the form.
param: array $options An array of form options.

bind($data) X-Ref

Method to bind data to the form.

param: mixed $data An array or object of data to bind to the form.
return: boolean True on success.

bindLevel($group, $data) X-Ref

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

param: string $group The dot-separated form group path on which to bind the data.
param: mixed $data An array or object of data to bind to the form for the group level.
return: void

getErrors() X-Ref

Return all errors, if any.

return: array Array of error messages or RuntimeException objects.

getField($name, $group = null, $value = null) X-Ref

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

param: string  $name   The name of the form field.
param: string  $group  The optional dot-separated form group path on which to find the field.
param: mixed   $value  The optional value to use as the default for the field.
return: FormField|boolean  The FormField object for the field or boolean false on error.

getFieldAttribute($name, $attribute, $default = null, $group = null) X-Ref

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.

param: string  $name       The name of the form field for which to get the attribute value.
param: string  $attribute  The name of the attribute for which to get a value.
param: mixed   $default    The optional default value to use if no attribute value exists.
param: string  $group      The optional dot-separated form group path on which to find the field.
return: mixed  The attribute value for the field.

getFieldset($set = null) X-Ref

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

param: string  $set  The optional name of the fieldset.
return: FormField[]  The array of FormField objects in the fieldset.

getFieldsets($group = null) X-Ref

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

param: string $group The dot-separated form group path on which to filter the fieldsets.
return: array The array of fieldset objects.

getFormControl() X-Ref

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: string The form control string.

getGroup($group, $nested = false) X-Ref

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

param: string   $group   The dot-separated form group path for which to get the form fields.
param: boolean  $nested  True to also include fields in nested groups that are inside of the
return: FormField[]  The array of FormField objects in the field group.

getInput($name, $group = null, $value = null) X-Ref

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

param: string  $name   The name of the form field.
param: string  $group  The optional dot-separated form group path on which to find the field.
param: mixed   $value  The optional value to use as the default for the field.
return: string  The form field markup.

getLabel($name, $group = null) X-Ref

Method to get the label for a field input.

param: string  $name   The name of the form field.
param: string  $group  The optional dot-separated form group path on which to find the field.
return: string  The form field label.

getName() X-Ref

Method to get the form name.

return: string The name of the form.

getValue($name, $group = null, $default = null) X-Ref

Method to get the value of a field.

param: string  $name     The name of the field for which to get the value.
param: string  $group    The optional dot-separated form group path on which to get the value.
param: mixed   $default  The optional default value of the field value is empty.
return: mixed  The value of the field or the default value if empty.

renderField($name, $group = null, $default = null, $options = []) X-Ref

Method to get a control group with label and input.

param: string  $name     The name of the field for which to get the value.
param: string  $group    The optional dot-separated form group path on which to get the value.
param: mixed   $default  The optional default value of the field value is empty.
param: array   $options  Any options to be passed into the rendering of the field
return: string  A string containing the html for the control group

renderFieldset($name, $options = []) X-Ref

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

param: string  $name     The name of the fieldset for which to get the values.
param: array   $options  Any options to be passed into the rendering of the field
return: string  A string containing the html for the control groups

load($data, $replace = true, $xpath = null) X-Ref

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.

param: string   $data     The name of an XML string or object.
param: boolean  $replace  Flag to toggle whether form fields should be replaced if a field
param: string   $xpath    An optional xpath to search for the fields.
return: boolean  True on success, false otherwise.

loadFile($file, $reset = true, $xpath = null) X-Ref

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.

param: string   $file   The filesystem path of an XML file.
param: boolean  $reset  Flag to toggle whether form fields should be replaced if a field
param: string   $xpath  An optional xpath to search for the fields.
return: boolean  True on success, false otherwise.

removeField($name, $group = null) X-Ref

Method to remove a field from the form definition.

param: string  $name   The name of the form field for which remove.
param: string  $group  The optional dot-separated form group path on which to find the field.
return: boolean  True on success, false otherwise.

removeGroup($group) X-Ref

Method to remove a group from the form definition.

param: string $group The dot-separated form group path for the group to remove.
return: boolean True on success.

reset($xml = false) X-Ref

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

param: boolean $xml True to also reset the XML form definition.
return: boolean True on success.

setField(\SimpleXMLElement $element, $group = null, $replace = true, $fieldset = 'default') X-Ref

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.

param: \SimpleXMLElement  $element   The XML element object representation of the form field.
param: string             $group     The optional dot-separated form group path on which to set the field.
param: boolean            $replace   True to replace an existing field if one already exists.
param: string             $fieldset  The name of the fieldset we are adding the field to.
return: boolean  True on success.

setFieldAttribute($name, $attribute, $value, $group = null) X-Ref

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

param: string  $name       The name of the form field for which to set the attribute value.
param: string  $attribute  The name of the attribute for which to set a value.
param: mixed   $value      The value to set for the attribute.
param: string  $group      The optional dot-separated form group path on which to find the field.
return: boolean  True on success.

setFields(&$elements, $group = null, $replace = true, $fieldset = 'default') X-Ref

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.

param: array    &$elements  The array of XML element object representations of the form fields.
param: string   $group      The optional dot-separated form group path on which to set the fields.
param: boolean  $replace    True to replace existing fields if they already exist.
param: string   $fieldset   The name of the fieldset we are adding the field to.
return: boolean  True on success.

setValue($name, $group = null, $value = null) X-Ref

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

param: string  $name   The name of the field for which to set the value.
param: string  $group  The optional dot-separated form group path on which to find the field.
param: mixed   $value  The value to set for the field.
return: boolean  True on success.

process($data, $group = null) X-Ref

Method to process the form data.

param: array   $data   An array of field values to filter.
param: string  $group  The dot-separated form group path on which to filter the fields.
return: mixed  Array or false.

filter($data, $group = null) X-Ref

Method to filter the form data.

param: array   $data   An array of field values to filter.
param: string  $group  The dot-separated form group path on which to filter the fields.
return: mixed  Array or false.

validate($data, $group = null) X-Ref

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.

param: array   $data   An array of field values to validate.
param: string  $group  The optional dot-separated form group path on which to filter the
return: boolean  True on success.

postProcess($data, $group = null) X-Ref

Method to post-process form data.

param: array   $data   An array of field values to post-process.
param: string  $group  The optional dot-separated form group path on which to filter the
return: mixed  Array or false.

findField($name, $group = null) X-Ref

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

param: string  $name   The name of the form field.
param: string  $group  The optional dot-separated form group path on which to find the field.
return: \SimpleXMLElement|boolean  The XML element object for the field or boolean false on error.

findFieldsByFieldset($name) X-Ref

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

param: string $name The name of the fieldset.
return: \SimpleXMLElement[]|boolean Boolean false on error or array of SimpleXMLElement objects.

findFieldsByGroup($group = null, $nested = false) X-Ref

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

param: mixed    $group   The optional dot-separated form group path on which to find the fields.
param: boolean  $nested  True to also include fields in nested groups that are inside of the
return: \SimpleXMLElement[]|boolean  Boolean false on error or array of SimpleXMLElement objects.

findGroup($group) X-Ref

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

param: string $group The dot-separated form group path on which to find the group.
return: \SimpleXMLElement[]|boolean An array of XML element objects for the group or boolean false on error.

loadField($element, $group = null, $value = null) X-Ref

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

param: string  $element  The XML element object representation of the form field.
param: string  $group    The optional dot-separated form group path on which to find the field.
param: mixed   $value    The optional value to use as the default for the field.
return: FormField|boolean  The FormField object for the field or boolean false on error.

syncPaths() X-Ref

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

return: boolean True on success.

addFieldPath($new = null) X-Ref

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

param: mixed $new A path or array of paths to add.
return: array The list of paths that have been added.

addFormPath($new = null) X-Ref

Proxy for FormHelper::addFormPath().

param: mixed $new A path or array of paths to add.
return: array The list of paths that have been added.

addRulePath($new = null) X-Ref

Proxy for FormHelper::addRulePath().

param: mixed $new A path or array of paths to add.
return: array The list of paths that have been added.

addFilterPath($new = null) X-Ref

Proxy for FormHelper::addFilterPath().

param: mixed $new A path or array of paths to add.
return: array The list of paths that have been added.

getInstance($name, $data = null, $options = [], $replace = true, $xpath = false) X-Ref

Method to get an instance of a form.

param: string          $name     The name of the form.
param: string          $data     The name of an XML file or string to load as the form definition.
param: array           $options  An array of form options.
param: boolean         $replace  Flag to toggle whether form fields should be replaced if a field
param: string|boolean  $xpath    An optional xpath to search for the fields.
return: Form  Form instance.

addNode(\SimpleXMLElement $source, \SimpleXMLElement $new) X-Ref

Adds a new child SimpleXMLElement node to the source.

param: \SimpleXMLElement $source The source element on which to append.
param: \SimpleXMLElement $new The new element to append.
return: void

mergeNode(\SimpleXMLElement $source, \SimpleXMLElement $new) X-Ref

Update the attributes of a child node

param: \SimpleXMLElement $source The source element on which to append the attributes
param: \SimpleXMLElement $new The new element to append
return: void

mergeNodes(\SimpleXMLElement $source, \SimpleXMLElement $new) X-Ref

Merges new elements into a source `<fields>` element.

param: \SimpleXMLElement $source The source element.
param: \SimpleXMLElement $new The new element to merge.
return: void

getAttribute($name, $default = null) X-Ref

Returns the value of an attribute of the form itself

param: string  $name     Name of the attribute to get
param: mixed   $default  Optional value to return if attribute not found
return: mixed             Value of the attribute / default

getData() X-Ref

Getter for the form data

return: Registry Object with the data

getXml() X-Ref

Method to get the XML form object

return: \SimpleXMLElement The form XML object

getFieldXml($name, $group = null) X-Ref

Copyright:	(C) 2009 Open Source Matters, Inc.
License:	GNU General Public License version 2 or later; see LICENSE.txt
File Size:	1860 lines (66 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	0 files

PHP Cross Reference of Joomla 4.2.2 documentation

/libraries/src/Form/ -> Form.php (summary)

Defines 1 class