Joomla! Documentation™

Introduction

This is one of a series of API Guides, which aim to help you understand how to use the Joomla APIs through providing detailed explanations and sample code which you can easily install and run.

This guide describes more advanced features of the Joomla Form API than is covered in Basic form guide, and comprises the following aspects:

• setting the file Path to enable Joomla to find your definitions of your form, your form fields and your form field validation, in the case where you don't follow the Joomla standards.
• defining groupings of fields – Joomla provides two types, namely fieldsets and field groups.
• dynamically changing your form (after it's been loaded from an XML file)
• reflection-like methods which allow you to extract information from your form structure and data.

The guide concludes with a sample component with examples of the above aspects.

File Paths

By default Joomla will look in the …/models/forms folder of your component to find the XML definition of your form, within the site files if your form is being displayed on the front end, or within the administrator files if your form is being displayed on the back end. The static function addFormPath() allows you to add a different directory to the list of directories which Joomla will search.

Similarly addFieldPath() allows you to define a different directory for any custom form field definitions (the default being …/models/fields) and addRulePath() allows you to define a different directory for any custom validation rules (the default being …/models/rules).

There are examples of all three in the sample component code at the end of this guide.

Fieldsets

Fieldsets are associated with the <fieldset name="myfieldset"> element in the XML definition of the form. The advantage of using fieldsets is that in your layout file you can use

$form->renderFieldset("myfieldset");

to render all the fields which have <field> elements inside the <fieldset> opening and closing tags. This is instead of having to call renderField() for each field within the fieldset.

A fieldset can be viewed as a set of fields which should be displayed together in a form, and are thus similar in concept to the HTML <fieldset> element. However, note that renderFieldset() does not output the HTML <fieldset> or related tags.

Field Groups

Field groups are associated with the <fields name="mygroup"> element in the XML definition of the form. This affects the HTML name attribute which is assigned to HTML input elements of fields which are defined within the <fields> opening and closing tags in the XML form definition, and hence the name of the parameter as sent to the server in the HTTP POST request.

If you specify the option "control" => "myform" when you set up your Form instance then input field values will be sent to the server in the HTTP POST request keyed like

myform[field1]

myform[field2]

myform[field3]

If you enclose these fields in the XML form definition within a <fields name="mygroup"> element then the POST parameters will be sent with names like

myform[mygroup][field1]

myform[mygroup][field2]

myform[mygroup][field3]

If your component has a database table and you store a number of parameters in a json string in one of the columns of the table, then you can group the HTML input elements of those parameters inside a <fields> element. If you name the fields tag to match your column name then you can use the Joomla Table functionality to easily convert the PHP associative array arising from the POST parameters into the json string for storing in the database.

Examples of this approach can be seen in the Joomla MVC tutorial Adding an Image step and many of the Joomla core components.

Note that fieldsets and field groups are independent. In your form XML definition you can have <fields> elements within <fieldset> elements, and also <fieldset> elements within <fields> elements.