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.

The Joomla Form class and API enables you to easily develop HTML forms and handle the user's input.

This page describes how you interact in general with the Joomla Form class and provides the code of a simple component which you can install to demonstrate use of this API.

Joomla itself also has a specific way of designing form functionality, and this page includes tutorial material to help you understand and develop your component to align with these principles.

Overall Description

The diagram below shows the basic use of the Joomla Form class.

Firstly, you need to define your form in XML using Joomla Standard form field types. See the component code below for an example. In basic terms, each field element in your XML file maps to an HTML (mostly "input") element in the form, with the XML field attributes mapping to the (input) element attributes. Many of the possible field attributes are listed in Text form field type.

Step 1

The user clicks on the URL of your form, and Joomla routes the HTTP GET request through to your component code. You need to call Form::getInstance() passing the name of your XML file with your form definition. The Joomla Form code creates a Form instance, and then (in Form::loadFile()) reads the file into memory (as a PHP SimpleXMLElement) and parses the XML to ensure it's valid. The main parameters passed to getInstance() are:

• name – a string specifying the identity to give to this form – it just needs to be unique, so that it doesn't clash with any other Joomla forms on the same webpage
• data – the name of the XML file which has your form definition
• options – an array of options, with the "control" element specifying the name of the array which the POST parameters will be held in. For example, the sample code has array("control"=>"myform") which means that the HTML input elements will have name attributes set to "myform[message]", "myform[email]", etc,. They will be passed in POST parameters that way, and it's then very easy to get these into a PHP array.

Step 2

You provide values for any form element you wish. For example, if this form is being used to edit a record in the database, then you would pre-populate it with existing field values from the database. You can provide values by setting up an associative array $data and passing it to Form::bind($data) method, and Joomla Form then stores this data locally within the Form instance.

Step 3

You call renderField(fieldName) on the Form instance and you get returned the HTML which you can echo to the output. Joomla processes its XML representation of your form to obtain the section relating to the passed-in fieldName, generates the HTML for this HTML element and includes the "value" attribute based on the pre-populated data which you passed in step 2. When outputting the form you also need to surround the input elements in a <form> element and add a submit button.

Step 4

The user enters data into your HTML form and clicks on the submit button. The browser generates an HTTP POST request to the URL specified in the <form> element and passes to the server in POST parameters the values entered by the user; each parameter keyed by the "name" attribute of the HTML input element.

Joomla routes this POST through to your component. As this is a new HTTP request the previous Form instance no longer exists, so you have to again call Form::getInstance(), passing the filename of your form XML, and Joomla (as before) creates a Form instance and reads this file into memory.

Step 5

In this step you process the submitted data. This involves:

1. Getting the POST data using Factory::getApplication->input->get(). Usually the "name" attributes of the input elements are defined so that the POST parameters appear as an array, and you can use the ARRAY filter from Retrieving_request_data_using_JInput to read these directly into a PHP array. However, this means that the individual elements are not filtered at all.
2. Filtering. This applies filtering on each of the input values. The filter applied to a field is governed by the "filter=..." attribute on that field in your form XML file, or if not present then the default filter will remove HTML tags etc from your data values. The possible filters are in the filterField() method of the Form class (and see https://joomla.stackexchange.com/questions/5764/what-are-possible-filters-in-joomla-form-fields). Note that these form field filters are different from the jinput filters.
3. Validation. You validate the data which the user has entered by calling validate($data) on your Form instance, passing an associative array of the (filtered) user data. Joomla compares the user-entered data with the validation you defined in your form XML file, and generates errors for fields which fail the validation.

If there are validation errors then you should display those errors to the user, and redisplay the form, pre-populating the fields with the (filtered) data which the user entered previously.

If there are no errors then you can confirm this to the user, and show the next web page.