class JForm


Located at : UKNOWVA_ROOT/libraries/joomla/form/form.php

Form Class for the Joomla Framework.

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.

Methods

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

Method to instantiate the form object.

boolean
bind(mixed $data)

Method to bind data to the form.

bindComponentParams($data, $group = 'params')

No description

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

Method to filter the form data.

array
getErrors()

Return all errors, if any.

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

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

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.

array
getFieldset($set = null, $forcegroup = 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.

array
getFieldsets(string $group = null)

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

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: and . If the form control is set to 'joomla' however, the fields would be rendered like: and .

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

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

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

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

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

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

string
getName()

Method to get the form name.

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

Method to get the value of a field.

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

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

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

Method to load the form description from an XML file.

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

Method to remove a field from the form definition.

boolean
removeGroup(string $group)

Method to remove a group from the form definition.

boolean
reset(boolean $xml = false)

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

boolean
setField(object $element, string $group = null, boolean $replace = true)

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.

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

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

boolean
setFields(object $elements, string $group = null, boolean $replace = true)

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.

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.

mixed
validate(array $data, string $group = null)

Method to validate form data.

static array
addFieldPath(mixed $new = null)

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

static array
addFormPath(mixed $new = null)

Proxy for JFormHelper::addFormPath().

static array
addRulePath(mixed $new = null)

Proxy for JFormHelper::addRulePath().

static object
getInstance(string $name, string $data = null, array $options = array(), string $replace = true, string $xpath = false)

Method to get an instance of a form.

Details

at line 86
void __construct(string $name, array $options = array())

Method to instantiate the form object.

Parameters

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

Return Value

void

at line 107
boolean bind(mixed $data)

Method to bind data to the form.

Parameters

mixed $data An array or object of data to bind to the form.

Return Value

boolean True on success.

at line 182
bindComponentParams($data, $group = 'params')

Parameters

$data
$group

at line 211
mixed filter(array $data, string $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.

Return Value

mixed Array or false.

at line 265
array getErrors()

Return all errors, if any.

Return Value

array Array of error messages or JException objects.

at line 281
mixed getField(string $name, string $group = null, mixed $value = null)

Method to get a form field represented as a JFormField 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.

Return Value

mixed The JFormField object for the field or boolean false on error.

at line 312
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.

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.

Return Value

mixed The attribute value for the field.

at line 345
array getFieldset($set = null, $forcegroup = 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.

Parameters

$set
$forcegroup

Return Value

array The array of JFormField objects in the fieldset.

$forcegroup was added by uKnowva team in version 2.4.2 to encompass the field names in a particular array. Actually need by the apps manager

at line 393
array getFieldsets(string $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.

Return Value

array The array of fieldset objects.

at line 489
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: and . If the form control is set to 'joomla' however, the fields would be rendered like: and .

Return Value

string The form control string.

at line 505
array getGroup(string $group, boolean $nested = false)

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

Parameters

string $group The dot-separated form group path for which to get the form fields.
boolean $nested True to also include fields in nested groups that are inside of the group for which to find fields.

Return Value

array The array of JFormField objects in the field group.

at line 541
string getInput(string $name, string $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.

Return Value

string The form field markup.

at line 561
string getLabel(string $name, string $group = 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.

Return Value

string The form field markup.

at line 578
string getName()

Method to get the form name.

Return Value

string The name of the form.

at line 594
mixed getValue(string $name, string $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.

Return Value

mixed The value of the field or the default value if empty.

at line 625
boolean load(string $data, string $replace = true, string $xpath = false)

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

string $data The name of an XML string or object.
string $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.

Return Value

boolean True on success, false otherwise.

at line 728
boolean loadFile($file, $reset = true, $xpath = false)

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
$reset
$xpath

Return Value

boolean True on success, false otherwise.

at line 757
boolean removeField(string $name, string $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.

Return Value

boolean True on success.

at line 786
boolean removeGroup(string $group)

Method to remove a group from the form definition.

Parameters

string $group The dot-separated form group path for the group to remove.

Return Value

boolean True on success.

at line 814
boolean reset(boolean $xml = false)

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

Parameters

boolean $xml True to also reset the XML form definition.

Return Value

boolean True on success.

at line 840
boolean setField(object $element, string $group = null, boolean $replace = true)

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

object $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.
boolean $replace True to replace an existing field if one already exists.

Return Value

boolean True on success.

at line 906
boolean setFieldAttribute(string $name, string $attribute, mixed $value, string $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.

Return Value

boolean True on success.

at line 947
boolean setFields(object $elements, string $group = null, boolean $replace = true)

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

object $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.
boolean $replace True to replace existing fields if they already exist.

Return Value

boolean True on success.

at line 993
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.

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.

Return Value

boolean True on success.

at line 1025
mixed validate(array $data, string $group = null)

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

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.

Return Value

mixed True on sucess.

at line 1757
static array addFieldPath(mixed $new = null)

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

Parameters

mixed $new A path or array of paths to add.

Return Value

array The list of paths that have been added.

at line 1772
static array addFormPath(mixed $new = null)

Proxy for JFormHelper::addFormPath().

Parameters

mixed $new A path or array of paths to add.

Return Value

array The list of paths that have been added.

See also

JFormHelper::addFormPath()

at line 1787
static array addRulePath(mixed $new = null)

Proxy for JFormHelper::addRulePath().

Parameters

mixed $new A path or array of paths to add.

Return Value

array The list of paths that have been added.

See also

JFormHelper::addRulePath()

at line 1807
static object getInstance(string $name, string $data = null, array $options = array(), string $replace = true, string $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.
string $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.

Return Value

object JForm instance.

Exceptions

Exception if an error occurs.