Joomla! CMS 2.5 API

package	Joomla.Platform
subpackage	Form
link	http://www.w3.org/TR/html4/interact/forms.html http://www.w3.org/TR/html5/forms.html
since	11.1

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.

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.

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.

Adds a new child SimpleXMLElement node to the source.

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

static

since	11.1
throws	`\Exception`if an error occurs.

Arguments

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

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.

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.

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.

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.

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.

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

findField(string $name, string $group = null) : mixed

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

mixedThe XML element object for the field or boolean false on error.

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

findFieldsByFieldset(string $name) : mixed

since	11.1

Arguments

$name: stringThe name of the fieldset.

Response

mixedBoolean false on error or array of SimpleXMLElement objects.

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

findFieldsByGroup(mixed $group = null, boolean $nested = false) : mixed

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

mixedBoolean false on error or array of SimpleXMLElement objects.

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

findGroup(string $group) : mixed

since	11.1

Arguments

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

Response

mixedAn array of XML element objects for the group or boolean false on error.

Return all errors, if any.

getErrors() : array

since	11.1

Response

arrayArray of error messages or JException objects.

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

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

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

mixedThe JFormField 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(string $name, string $attribute, mixed $default = null, string $group = null) : mixed

since	11.1

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

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.

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 .

getFormControl() : string

since	11.1

Response

stringThe form control string.

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.

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.

Method to get an instance of a form.

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

static

since	11.1
throws	`\Exception`if an error occurs.

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

objectJForm instance.

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.

Method to get the form name.

getName() : string

since	11.1

Response

stringThe name of the form.

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.

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.

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

loadField(string $element, string $group = null, mixed $value = null) : mixed

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

mixedThe JFormField object for the field or boolean false on error.

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

loadFieldType(string $type, boolean $new = true) : mixed

since	11.1

Arguments

$type: stringThe field type.
$new: booleanFlag to toggle whether we should get a new instance of the object.

Response

mixedJFormField object on success, false otherwise.

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.

Proxy for JFormHelper::loadRuleType().

loadRuleType(string $type, boolean $new = true) : mixed

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

mixedJFormRule object on success, false otherwise.

Adds a new child SimpleXMLElement node to the source.

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

static

since	11.1

Arguments

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

Merges new elements into a source element.

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

static

since	11.1

Arguments

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

Method to remove a field from the form definition.

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

since	11.1

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.

Method to remove a group from the form definition.

removeGroup(string $group) : boolean

since	11.1

Arguments

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

Response

booleanTrue on success.

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.

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( &$element, string $group = null, boolean $replace = true) : boolean

since	11.1

Arguments

$element
$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.

Response

booleanTrue on success.

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

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.

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

since	11.1

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.

Response

booleanTrue 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(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.

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.

Method to validate form data.

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

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

mixedTrue on sucess.

Method to validate a JFormField object based on field data.

validateField(string $element, string $group = null, mixed $value = null, object $input = null) : mixed

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.
$input: objectAn optional JRegistry object with the entire data set to validate against the entire form.

Response

mixedBoolean true if field value is valid, JException on failure.

The JRegistry data store for form fields during display.

since	11.1

Type(s)

object

The form object errors array.

since	11.1

Type(s)

array

The name of the form instance.

since	11.1

Type(s)

string

The form object options for use in rendering and validation.

since	11.1

Type(s)

array

The form XML definition.

since	11.1

Type(s)

object

Form instances.

static

since	11.1

Type(s)

array

JForm

Methods

__construct

Arguments

addFieldPath

Arguments

Response

addFormPath

Arguments

Response

addNode

Arguments

addRulePath

Arguments

Response

bind

Arguments

Response

bindLevel

Arguments

filter

Arguments

Response

filterField

Arguments

Response

findField

Arguments

Response

findFieldsByFieldset

Arguments

Response

findFieldsByGroup

Arguments

Response

findGroup

Arguments

Response

getErrors

Response

getField

Arguments

Response

getFieldAttribute

Arguments

Response

getFieldset

Arguments

Response

getFieldsets

Arguments

Response

getFormControl

Response

getGroup

Arguments

Response

getInput

Arguments

Response

getInstance

Arguments

Response

getLabel

Arguments

Response

getName

Response

getValue

Arguments

Response

load

Arguments

Response

loadField

Arguments

Response

loadFieldType

Arguments

Response