Difference between revisions of "Basic form guide"

From Joomla! Documentation

m (Include link to advanced guide)
(Several markup changes.)
 
Line 2: Line 2:
 
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 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.  
+
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. A companion guide [[Advanced form guide|Advanced Form Guide]] deals with more advanced aspects of the Joomla Form class.  
+
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. A companion guide [[Advanced form guide|Advanced Form Guide]] deals with more advanced aspects of the Joomla Form class.
  
 
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.
 
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.
Line 11: Line 11:
 
The diagram below shows the basic use of the Joomla Form class.
 
The diagram below shows the basic use of the Joomla Form class.
  
[[File:basicform.jpg|Using Joomla Forms]]  
+
[[File:basicform.jpg|Using Joomla Forms]]
  
 
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]].
 
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 Loading the Form ===
 
=== Step 1 Loading the Form ===
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 <tt>Form::getInstance()</tt> passing the name of your XML file with your form definition. The Joomla Form code creates a Form instance, and then (in <tt>Form::loadFile()</tt>) reads the file into memory (as a PHP <tt>SimpleXMLElement</tt>) and parses the XML to ensure it's valid. The main parameters passed to <tt>getInstance()<tt> are:
+
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
 
* 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
 
* 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 <tt>array("control"=>"myform")</tt> 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.
+
* 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 Providing Pre-fill Data ===
 
=== Step 2 Providing Pre-fill Data ===
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 <tt>$data</tt> and passing it to <tt>Form::bind($data)</tt> method, and Joomla Form then stores this data locally within the Form instance.
+
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 Outputting the Form in HTML ===
 
=== Step 3 Outputting the Form in HTML ===
You call <tt>renderField(fieldName)</tt> 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.
+
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 <tt><form></tt> element and add a submit button.  
+
When outputting the form you also need to surround the input elements in a ''<form>'' element and add a submit button.
  
 
=== Step 4 User Submitting the Form ===
 
=== Step 4 User Submitting the Form ===
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 <tt><form></tt> 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.
+
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 <tt>Form::getInstance()</tt>, passing the filename of your form XML, and Joomla (as before) creates a Form instance and reads this file into memory.
+
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 Handling the HTTP POST Data ===
 
=== Step 5 Handling the HTTP POST Data ===
 
In this step you process the submitted data. This involves:
 
In this step you process the submitted data. This involves:
# Getting the POST data using <tt>Factory::getApplication->input->get()<tt>. 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.  
+
# 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.
# 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 <tt>filterField()</tt> 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.  
+
# 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.
 
# 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.
 
# 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.
  
Line 44: Line 44:
  
 
== Sample Form 1 ==
 
== Sample Form 1 ==
Below is the code for a small component which you can install to demonstrate basic use of Joomla forms. Place the following 3 files into a folder called "com_sample_form1". Then zip up the folder to create <tt>com_sample_form1.zip</tt> and install this as a component on your Joomla instance.
+
Below is the code for a small component which you can install to demonstrate basic use of Joomla forms. Place the following 3 files into a folder called "com_sample_form1". Then zip up the folder to create ''com_sample_form1.zip'' and install this as a component on your Joomla instance.
  
<tt>com_sample_form1.xml</tt> Manifest file for the component
+
''com_sample_form1.xml'' Manifest file for the component
<source lang="xml">
+
<syntaxhighlight lang="xml">
 
<?xml version="1.0" encoding="utf-8"?>
 
<?xml version="1.0" encoding="utf-8"?>
 
<extension type="component" version="3.1.0" method="upgrade">
 
<extension type="component" version="3.1.0" method="upgrade">
Line 54: Line 54:
 
<version>1.0.0</version>
 
<version>1.0.0</version>
 
<description>Sample form 1</description>
 
<description>Sample form 1</description>
+
 
 
<administration>
 
<administration>
 
</administration>
 
</administration>
Line 63: Line 63:
 
</files>
 
</files>
 
</extension>
 
</extension>
</source>
+
</syntaxhighlight>
  
<tt>sample_form.xml</tt> File containing the XML for the form definition
+
''sample_form.xml'' File containing the XML for the form definition
<source lang="xml">
+
<syntaxhighlight lang="xml">
 
<?xml version="1.0" encoding="utf-8"?>
 
<?xml version="1.0" encoding="utf-8"?>
 
<form>
 
<form>
Line 76: Line 76:
 
class="inputbox"
 
class="inputbox"
 
required="true" />
 
required="true" />
<field name="email"  
+
<field name="email"
 
type="email"
 
type="email"
 
label="Enter email"
 
label="Enter email"
Line 82: Line 82:
 
size="40"
 
size="40"
 
class="inputbox" />
 
class="inputbox" />
<field name="telephone"  
+
<field name="telephone"
 
type="tel"
 
type="tel"
 
label="Enter telephone number"
 
label="Enter telephone number"
Line 90: Line 90:
 
validate="tel" />
 
validate="tel" />
 
</form>
 
</form>
</source>
+
</syntaxhighlight>
  
<tt>sample_form1.php</tt> Component code.
+
''sample_form1.php'' Component code.
<source lang="php">
+
<syntaxhighlight lang="php">
 
<?php
 
<?php
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
Line 103: Line 103:
 
$prefillData = array("email" => ".@.");
 
$prefillData = array("email" => ".@.");
  
if ($_SERVER['REQUEST_METHOD'] === 'POST')  
+
if ($_SERVER['REQUEST_METHOD'] === 'POST')
 
{
 
{
 
$app  = JFactory::getApplication();
 
$app  = JFactory::getApplication();
 
$data = $app->input->post->get('myform', array(), "array");
 
$data = $app->input->post->get('myform', array(), "array");
echo "Message was " . $data["message"] .  
+
echo "Message was " . $data["message"] .
", email was " . $data["email"] .  
+
", email was " . $data["email"] .
 
", and telephone was " . $data["telephone"] . "<br>";
 
", and telephone was " . $data["telephone"] . "<br>";
 
$filteredData = $form->filter($data);
 
$filteredData = $form->filter($data);
Line 135: Line 135:
  
 
<?php echo $form->renderField('message');  ?>
 
<?php echo $form->renderField('message');  ?>
+
 
 
<?php echo $form->renderField('email');  ?>
 
<?php echo $form->renderField('email');  ?>
+
 
 
<?php echo $form->renderField('telephone');  ?>
 
<?php echo $form->renderField('telephone');  ?>
+
 
 
<button type="submit">Submit</button>
 
<button type="submit">Submit</button>
 
</form>
 
</form>
</source>
+
</syntaxhighlight>
  
Once installed navigate to your site and add the following parameter to the URL:  
+
Once installed navigate to your site and add the following parameter to the URL:
<tt>&option=com_sample_form1<tt>. You should then see the form displayed with 3 required fields:
+
''&option=com_sample_form1''. You should then see the form displayed with 3 required fields:
 
* a general text input field for a message
 
* a general text input field for a message
 
* an email input field, pre-populated with the string ".@."
 
* an email input field, pre-populated with the string ".@."
 
* a telephone number input field.
 
* a telephone number input field.
and using your browser's development tools you can compare the html attributes with the attributes in your XML form definition.  
+
and using your browser's development tools you can compare the HTML attributes with the attributes in your XML form definition.
  
 
Note that modern browsers will do some validation on the values you enter, specifically they will validate the email address and will force you to enter something into fields with the "required" attribute set, but don't (currently) do validation on telephone number fields.
 
Note that modern browsers will do some validation on the values you enter, specifically they will validate the email address and will force you to enter something into fields with the "required" attribute set, but don't (currently) do validation on telephone number fields.
Line 155: Line 155:
 
Once you enter valid data into the fields and press Submit, then the data will be sent to the server and the POST leg of the sample code will be run. This runs the filtering and validation routines. If there are validation errors then the code outputs the error messages, and prefills the form with the data which the user entered before redisplaying it.
 
Once you enter valid data into the fields and press Submit, then the data will be sent to the server and the POST leg of the sample code will be run. This runs the filtering and validation routines. If there are validation errors then the code outputs the error messages, and prefills the form with the data which the user entered before redisplaying it.
  
== MVC and other considerations ==
+
== MVC and Other Considerations ==
 
The way that the code above is written isn't the best approach if you are developing a genuine Joomla component. Instead you should follow the way that the Joomla core code is designed, in particular splitting your component into controllers, models, views and layouts, and the revised component code in the section after this follows this approach. The remainder of this section describes these and other design decisions, which should make the sample code easier to understand.
 
The way that the code above is written isn't the best approach if you are developing a genuine Joomla component. Instead you should follow the way that the Joomla core code is designed, in particular splitting your component into controllers, models, views and layouts, and the revised component code in the section after this follows this approach. The remainder of this section describes these and other design decisions, which should make the sample code easier to understand.
  
=== Joomla MVC split ===
+
=== Joomla MVC Split ===
 
In general terms Joomla splits components into separate types of functionality:
 
In general terms Joomla splits components into separate types of functionality:
 
* the controller contains the "business logic" of the application, including deciding what view and model to use
 
* the controller contains the "business logic" of the application, including deciding what view and model to use
* the model provides access to the data  
+
* the model provides access to the data
 
* the view decides what data is necessary for outputting on the web page and obtains this data from the model
 
* the view decides what data is necessary for outputting on the web page and obtains this data from the model
* the layout outputs the HTML, and includes in the output the data which has been collated by the view. The layout runs within the context of the view, and so has direct access to the variables of the view code.  
+
* the layout outputs the HTML, and includes in the output the data which has been collated by the view. The layout runs within the context of the view, and so has direct access to the variables of the view code.
  
=== Post/Request/Get pattern ===
+
=== Post/Request/Get Pattern ===
In Joomla all of the HTML output (such as the display of a form) is performed in response to an HTTP GET, following the https://en.wikipedia.org/wiki/Post/Redirect/Get pattern. The sample code above doesn't follow this pattern, but instead outputs the validation errors and re-displays the form in the response to the HTTP POST request.  
+
In Joomla all of the HTML output (such as the display of a form) is performed in response to an HTTP GET, following the https://en.wikipedia.org/wiki/Post/Redirect/Get pattern. The sample code above doesn't follow this pattern, but instead outputs the validation errors and re-displays the form in the response to the HTTP POST request.
  
 
To follow the Joomla pattern, in the code which handles the POST we should include a HTTP GET redirect to the form URL. As that GET will then be a new HTTP request/response we must store in the user session the data to be shown when the form is redisplayed:
 
To follow the Joomla pattern, in the code which handles the POST we should include a HTTP GET redirect to the form URL. As that GET will then be a new HTTP request/response we must store in the user session the data to be shown when the form is redisplayed:
* the validation error messages are stored and output using the <tt>enqueueMessage()</tt> method (which stores data in the user session automatically for us)
+
* the validation error messages are stored and output using the ''enqueueMessage()'' method (which stores data in the user session automatically for us)
* the user-entered data is stored using <tt>setUserState()</tt> and retrieved using <tt>getUserState()</tt>, and keyed by a <tt>context</tt> which should be unique to this form. The code which provides the data for the form <tt>bind()</tt> operation must first check using <tt>getUserState()<tt> if there is any prefill data in the session. And if the user enters data which successfully passes validation then <tt>setUserState()<tt> should be called to clear this prefill data in the session, otherwise it will appear whenever the user next displays the form.
+
* the user-entered data is stored using ''setUserState()'' and retrieved using ''getUserState()'', and keyed by a ''context'' which should be unique to this form. The code which provides the data for the form ''bind()'' operation must first check using ''getUserState()'' if there is any prefill data in the session. And if the user enters data which successfully passes validation then ''setUserState()'' should be called to clear this prefill data in the session, otherwise it will appear whenever the user next displays the form.
  
 
=== Separate Controllers ===
 
=== Separate Controllers ===
In response to a GET or POST, Joomla always runs the same component file, sample_form1.php in the sample component example above and the top-level sample_form2.php in the example below. The sample_form2.php code below follows the example of the core Joomla components, and has code which passes control to different methods in different controllers based on the value of the HTTP parameter <tt>task</tt>. This parameter is set by Joomla core javascript based on the submit button, eg in the example below:
+
In response to a GET or POST, Joomla always runs the same component file, sample_form1.php in the sample component example above and the top-level sample_form2.php in the example below. The sample_form2.php code below follows the example of the core Joomla components, and has code which passes control to different methods in different controllers based on the value of the HTTP parameter ''task''. This parameter is set by Joomla core javascript based on the submit button, e.g. in the example below:
  
 
onclick="Joomla.submitbutton('myform.submit')"
 
onclick="Joomla.submitbutton('myform.submit')"
  
The task parameter is in this example set to "myform.submit". In general the task parameter is of the form "firstpart.secondpart" and for a component called "com_example" Joomla will try to run an instance method called <tt>secondpart()</tt> of a controller class <tt>ExampleControllerFirstpart</tt> in a file <tt>firstpart.php</tt> in the <tt>controllers</tt> directory.
+
The task parameter is in this example set to "myform.submit". In general the task parameter is of the form "firstpart.secondpart" and for a component called "com_example" Joomla will try to run an instance method called ''secondpart()'' of a controller class ''ExampleControllerFirstpart'' in a file ''firstpart.php'' in the ''controllers'' directory.
  
If the task parameter is not set then Joomla will try to run the <tt>display()</tt> method of the <tt>ExampleController</tt> class which it will expect to find in <tt>controller.php</tt>.  
+
If the task parameter is not set then Joomla will try to run the ''display()'' method of the ''ExampleController'' class which it will expect to find in ''controller.php''.
  
 
In terms of code:
 
In terms of code:
  
<tt>$controller = JControllerLegacy::getInstance('Sample_form2');</tt>
+
''$controller = JControllerLegacy::getInstance('Sample_form2');''
  
uses the <tt>task</tt> parameter to identify the appropriate controller file to include, and then creates an instance of that controller class.
+
uses the ''task'' parameter to identify the appropriate controller file to include, and then creates an instance of that controller class.
  
<tt>$controller->execute($input->getCmd('task'));</tt>
+
''$controller->execute($input->getCmd('task'));''
  
executes the appropriate method (<tt>secondpart()</tt> - or in the case below, <tt>submit()</tt> - or <tt>display()</tt>) of that class.  
+
executes the appropriate method (''secondpart()'' - or in the case below, ''submit()'' - or ''display()'') of that class.
  
In this way controller functionality handling GETs (generally in the file <tt>controller.php</tt>) is separated from that handling POSTs (generally in the files in the <tt>controllers</tt> folder).
+
In this way controller functionality handling GETs (generally in the file ''controller.php'') is separated from that handling POSTs (generally in the files in the ''controllers'' folder).
  
=== Joomla MVC classes ===  
+
=== Joomla MVC Classes ===
  
Joomla provides feature-rich controller, view and model classes from which your component controllers, views and models can inherit. The model code below inherits from <tt>FormModel</tt> which shields somewhat the Joomla <tt>Form</tt> API. In this case our model calls <tt>FormModel::loadForm()</tt>, and this then executes a callback to our <tt>loadFormData()</tt> to provide the data to <tt>bind()</tt> to the form.  
+
Joomla provides feature-rich controller, view and model classes from which your component controllers, views and models can inherit. The model code below inherits from ''FormModel'' which shields somewhat the Joomla ''Form'' API. In this case our model calls ''FormModel::loadForm()'', and this then executes a callback to our ''loadFormData()'' to provide the data to ''bind()'' to the form.
  
You can also use <tt>FormController</tt> and <tt>AdminController</tt> classes, but these assume that your component is using a database table to store the data. The Joomla MVC Component Development tutorial takes this approach in [[J3.x:Developing an MVC Component/Adding backend actions]].
+
You can also use ''FormController'' and ''AdminController'' classes, but these assume that your component is using a database table to store the data. The Joomla MVC Component Development tutorial takes this approach in [[J3.x:Developing an MVC Component/Adding backend actions]].
  
 
=== Security Token ===
 
=== Security Token ===
Joomla uses a security token on forms to prevent CSRF attacks (see https://en.wikipedia.org/wiki/Cross-site_request_forgery). The token is output in the layout file  
+
Joomla uses a security token on forms to prevent CSRF attacks (see https://en.wikipedia.org/wiki/Cross-site_request_forgery). The token is output in the layout file
  
<tt><?php echo JHtml::_('form.token'); ?></tt>
+
''<?php echo JHtml::_('form.token'); ?>''
  
 
and checked within the controller handling the POST:
 
and checked within the controller handling the POST:
  
<tt>$this->checkToken();</tt>
+
''$this->checkToken();''
  
If the token is found to be invalid then <tt>checkToken()</tt> outputs a warning and redirects the user back to the previous page.  
+
If the token is found to be invalid then ''checkToken()'' outputs a warning and redirects the user back to the previous page.
  
 
=== Client-side Validation ===
 
=== Client-side Validation ===
In addition to the server-side validation included through the form XML definition, Joomla also provides a way of including javascript which performs client-side validation on the browser. This is NOT included below, as it's deemed beyond the scope of this tutorial, but you can find details of it in [[J3.x:Developing an MVC Component/Adding verifications]] and [[Client-side_form_validation|Client-side form validation]].
+
In addition to the server-side validation included through the form XML definition, Joomla also provides a way of including JavaScript which performs client-side validation on the browser. This is NOT included below, as it's deemed beyond the scope of this tutorial, but you can find details of it in [[J3.x:Developing an MVC Component/Adding verifications]] and [[Client-side_form_validation|Client-side form validation]].
  
 
== Sample Form 2 ==
 
== Sample Form 2 ==
Line 220: Line 220:
 
Starting at the bottom of this diagram and going upwards the file contents are:
 
Starting at the bottom of this diagram and going upwards the file contents are:
  
<tt>com_sample_form2/sample_form2.php</tt> Entry point for the component. This is the first file which Joomla runs.  
+
''com_sample_form2/sample_form2.php'' Entry point for the component. This is the first file which Joomla runs.
<source lang="php">
+
<syntaxhighlight lang="php">
 
<?php
 
<?php
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
Line 230: Line 230:
 
// Run the task method, or display() if no task parameter
 
// Run the task method, or display() if no task parameter
 
$controller->execute($input->getCmd('task'));
 
$controller->execute($input->getCmd('task'));
+
 
 
$controller->redirect();
 
$controller->redirect();
</source>
+
</syntaxhighlight>
  
<tt>com_sample_form2/controller.php</tt> The controller for handling HTTP GET requests
+
''com_sample_form2/controller.php'' The controller for handling HTTP GET requests
<source lang="php">
+
<syntaxhighlight lang="php">
 
<?php
 
<?php
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
Line 245: Line 245:
 
// It will (usually) call the display() method, and will find this is in the BaseController class
 
// It will (usually) call the display() method, and will find this is in the BaseController class
 
}
 
}
</source>
+
</syntaxhighlight>
  
<tt>com_sample_form2/sample_form2.xml</tt> Manifest file for the component.
+
''com_sample_form2/sample_form2.xml'' Manifest file for the component.
<source lang="xml">
+
<syntaxhighlight lang="xml">
 
<?xml version="1.0" encoding="utf-8"?>
 
<?xml version="1.0" encoding="utf-8"?>
 
<extension type="component" version="3.1.0" method="upgrade">
 
<extension type="component" version="3.1.0" method="upgrade">
Line 255: Line 255:
 
<version>1.0.0</version>
 
<version>1.0.0</version>
 
<description>Sample form 2</description>
 
<description>Sample form 2</description>
+
 
 
<administration>
 
<administration>
 
</administration>
 
</administration>
Line 267: Line 267:
 
</files>
 
</files>
 
</extension>
 
</extension>
</source>
+
</syntaxhighlight>
  
<tt>com_sample_form2/views/form/view.html.php</tt> View file for displaying the form. The controller <tt>display()</tt> function will create instances of the model and view, and call the view <tt>display()</tt> function below.  
+
''com_sample_form2/views/form/view.html.php'' View file for displaying the form. The controller ''display()'' function will create instances of the model and view, and call the view ''display()'' function below.
<source lang="php">
+
<syntaxhighlight lang="php">
 
<?php
 
<?php
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
Line 289: Line 289:
 
}
 
}
 
}
 
}
</source>
+
</syntaxhighlight>
  
<tt>com_sample_form2/views/form/tmpl/edit.php</tt> Layout file for displaying the form
+
''com_sample_form2/views/form/tmpl/edit.php'' Layout file for displaying the form
<source lang="php">
+
<syntaxhighlight lang="php">
 
<?php
 
<?php
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
Line 300: Line 300:
  
 
<?php echo $this->form->renderField('message');  ?>
 
<?php echo $this->form->renderField('message');  ?>
+
 
 
<?php echo $this->form->renderField('email');  ?>
 
<?php echo $this->form->renderField('email');  ?>
+
 
 
<?php echo $this->form->renderField('telephone');  ?>
 
<?php echo $this->form->renderField('telephone');  ?>
  
 
<button type="button" class="btn btn-primary" onclick="Joomla.submitbutton('myform.submit')">Submit</button>
 
<button type="button" class="btn btn-primary" onclick="Joomla.submitbutton('myform.submit')">Submit</button>
+
 
 
<input type="hidden" name="task" />
 
<input type="hidden" name="task" />
 
<?php echo JHtml::_('form.token'); ?>
 
<?php echo JHtml::_('form.token'); ?>
 
</form>
 
</form>
</source>
+
</syntaxhighlight>
  
<tt>com_sample_form2/models/form.php</tt> Model associated with displaying the form. The view <tt>get('form')</tt> gets mapped to the model <tt>getForm()</tt> method call.  
+
''com_sample_form2/models/form.php'' Model associated with displaying the form. The view ''get('form')'' gets mapped to the model ''getForm()'' method call.
<source lang="php">
+
<syntaxhighlight lang="php">
 
<?php
 
<?php
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
Line 353: Line 353:
 
return $data;
 
return $data;
 
}
 
}
+
 
 
}
 
}
</source>
+
</syntaxhighlight>
  
<tt>com_sample_form2/models/forms/sample_form.xml</tt> XML file containing the form definition
+
''com_sample_form2/models/forms/sample_form.xml'' XML file containing the form definition
<source lang="xml">
+
<syntaxhighlight lang="xml">
 
<?xml version="1.0" encoding="utf-8"?>
 
<?xml version="1.0" encoding="utf-8"?>
 
<form>
 
<form>
Line 368: Line 368:
 
class="inputbox"
 
class="inputbox"
 
required="true" />
 
required="true" />
<field name="email"  
+
<field name="email"
 
type="email"
 
type="email"
 
label="Enter email"
 
label="Enter email"
Line 374: Line 374:
 
size="40"
 
size="40"
 
class="inputbox" />
 
class="inputbox" />
<field name="telephone"  
+
<field name="telephone"
 
type="tel"
 
type="tel"
 
label="Enter telephone number"
 
label="Enter telephone number"
Line 382: Line 382:
 
validate="tel" />
 
validate="tel" />
 
</form>
 
</form>
</source>
+
</syntaxhighlight>
  
<tt>com_sample_form2/controllers/Myform.php</tt> Controller which handles the HTTP POST
+
''com_sample_form2/controllers/Myform.php'' Controller which handles the HTTP POST
<source lang="php">
+
<syntaxhighlight lang="php">
 
<?php
 
<?php
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
Line 393: Line 393:
  
 
class Sample_form2ControllerMyform extends BaseController
 
class Sample_form2ControllerMyform extends BaseController
{  
+
{
 
public function submit($key = null, $urlVar = null)
 
public function submit($key = null, $urlVar = null)
 
{
 
{
 
$this->checkToken();
 
$this->checkToken();
+
 
 
$app  = JFactory::getApplication();
 
$app  = JFactory::getApplication();
 
$model = $this->getModel('form');
 
$model = $this->getModel('form');
Line 406: Line 406:
 
return false;
 
return false;
 
}
 
}
+
 
 
// name of array 'jform' must match 'control' => 'jform' line in the model code
 
// name of array 'jform' must match 'control' => 'jform' line in the model code
 
$data  = $this->input->post->get('jform', array(), 'array');
 
$data  = $this->input->post->get('jform', array(), 'array');
+
 
 
// This is validate() from the FormModel class, not the Form class
 
// This is validate() from the FormModel class, not the Form class
 
// FormModel::validate() calls both Form::filter() and Form::validate() methods
 
// FormModel::validate() calls both Form::filter() and Form::validate() methods
Line 439: Line 439:
 
$app->setUserState('com_sample_form2.sample', null);
 
$app->setUserState('com_sample_form2.sample', null);
 
}
 
}
+
 
 
// Redirect back to the form in all cases
 
// Redirect back to the form in all cases
 
$this->setRedirect(JRoute::_('index.php?option=com_sample_form2&view=form&layout=edit', false));
 
$this->setRedirect(JRoute::_('index.php?option=com_sample_form2&view=form&layout=edit', false));
 
}
 
}
 
}
 
}
</source>
+
</syntaxhighlight>
 
 
After creating the files as described above, zip up the <tt>com_sample_form2</tt> folder to create com_sample_form2.zip and install this component. Then navigate to your Joomla site and add into the URL the parameters <tt>&option=com_sample_form2&view=form&layout=edit<tt>. This should display the form, and should work in a similar fashion to previous sample form, except that errors etc will appear in the message part of the Joomla display.
 
  
 +
After creating the files as described above, zip up the ''com_sample_form2'' folder to create com_sample_form2.zip and install this component. Then navigate to your Joomla site and add into the URL the parameters ''&option=com_sample_form2&view=form&layout=edit''. This should display the form, and should work in a similar fashion to previous sample form, except that errors etc. will appear in the message part of the Joomla display.
  
 
[[Category:Development]]
 
[[Category:Development]]

Latest revision as of 09:56, 27 September 2022

Introduction[edit]

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. A companion guide Advanced Form Guide deals with more advanced aspects of the Joomla Form class.

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[edit]

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

Using Joomla Forms

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 Loading the Form[edit]

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 Providing Pre-fill Data[edit]

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 Outputting the Form in HTML[edit]

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 User Submitting the Form[edit]

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 Handling the HTTP POST Data[edit]

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.

Sample Form 1[edit]

Below is the code for a small component which you can install to demonstrate basic use of Joomla forms. Place the following 3 files into a folder called "com_sample_form1". Then zip up the folder to create com_sample_form1.zip and install this as a component on your Joomla instance.

com_sample_form1.xml Manifest file for the component

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.1.0" method="upgrade">

	<name>com_sample_form1</name>
	<version>1.0.0</version>
	<description>Sample form 1</description>

	<administration>
	</administration>

	<files folder="site">
		<filename>sample_form1.php</filename>
		<filename>sample_form.xml</filename>
	</files>
</extension>

sample_form.xml File containing the XML for the form definition

<?xml version="1.0" encoding="utf-8"?>
<form>
	<field
		name="message"
		type="text"
		label="Enter message"
		size="40"
		class="inputbox"
		required="true" />
	<field name="email"
		type="email"
		label="Enter email"
		required="true"
		size="40"
		class="inputbox" />
	<field name="telephone"
		type="tel"
		label="Enter telephone number"
		required="true"
		size="40"
		class="inputbox"
		validate="tel" />
</form>

sample_form1.php Component code.

<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\Form\Form;
use Joomla\CMS\Factory;

$form = Form::getInstance("sample", __DIR__ . "/sample_form.xml", array("control" => "myform"));
$prefillData = array("email" => ".@.");

if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
	$app   = JFactory::getApplication();
	$data = $app->input->post->get('myform', array(), "array");
	echo "Message was " . $data["message"] .
		", email was " . $data["email"] .
		", and telephone was " . $data["telephone"] . "<br>";
	$filteredData = $form->filter($data);
	$result = $form->validate($filteredData);
	if ($result)
	{
		echo "Validation passed ok<br>";
	}
	else
	{
		echo "Validation failed<br>";
		$errors = $form->getErrors();
		foreach ($errors as $error)
		{
			echo $error->getMessage() . "<br>";
		}
		// in the redisplayed form show what the user entered (after data is filtered)
		$prefillData = $filteredData;
	}
}

$form->bind($prefillData);
?>
<form action="<?php echo JRoute::_('index.php?option=com_sample_form1'); ?>"
    method="post" name="sampleForm" id="adminForm" enctype="multipart/form-data">

	<?php echo $form->renderField('message');  ?>

	<?php echo $form->renderField('email');  ?>

	<?php echo $form->renderField('telephone');  ?>

	<button type="submit">Submit</button>
</form>

Once installed navigate to your site and add the following parameter to the URL: &option=com_sample_form1. You should then see the form displayed with 3 required fields:

  • a general text input field for a message
  • an email input field, pre-populated with the string ".@."
  • a telephone number input field.

and using your browser's development tools you can compare the HTML attributes with the attributes in your XML form definition.

Note that modern browsers will do some validation on the values you enter, specifically they will validate the email address and will force you to enter something into fields with the "required" attribute set, but don't (currently) do validation on telephone number fields.

Once you enter valid data into the fields and press Submit, then the data will be sent to the server and the POST leg of the sample code will be run. This runs the filtering and validation routines. If there are validation errors then the code outputs the error messages, and prefills the form with the data which the user entered before redisplaying it.

MVC and Other Considerations[edit]

The way that the code above is written isn't the best approach if you are developing a genuine Joomla component. Instead you should follow the way that the Joomla core code is designed, in particular splitting your component into controllers, models, views and layouts, and the revised component code in the section after this follows this approach. The remainder of this section describes these and other design decisions, which should make the sample code easier to understand.

Joomla MVC Split[edit]

In general terms Joomla splits components into separate types of functionality:

  • the controller contains the "business logic" of the application, including deciding what view and model to use
  • the model provides access to the data
  • the view decides what data is necessary for outputting on the web page and obtains this data from the model
  • the layout outputs the HTML, and includes in the output the data which has been collated by the view. The layout runs within the context of the view, and so has direct access to the variables of the view code.

Post/Request/Get Pattern[edit]

In Joomla all of the HTML output (such as the display of a form) is performed in response to an HTTP GET, following the https://en.wikipedia.org/wiki/Post/Redirect/Get pattern. The sample code above doesn't follow this pattern, but instead outputs the validation errors and re-displays the form in the response to the HTTP POST request.

To follow the Joomla pattern, in the code which handles the POST we should include a HTTP GET redirect to the form URL. As that GET will then be a new HTTP request/response we must store in the user session the data to be shown when the form is redisplayed:

  • the validation error messages are stored and output using the enqueueMessage() method (which stores data in the user session automatically for us)
  • the user-entered data is stored using setUserState() and retrieved using getUserState(), and keyed by a context which should be unique to this form. The code which provides the data for the form bind() operation must first check using getUserState() if there is any prefill data in the session. And if the user enters data which successfully passes validation then setUserState() should be called to clear this prefill data in the session, otherwise it will appear whenever the user next displays the form.

Separate Controllers[edit]

In response to a GET or POST, Joomla always runs the same component file, sample_form1.php in the sample component example above and the top-level sample_form2.php in the example below. The sample_form2.php code below follows the example of the core Joomla components, and has code which passes control to different methods in different controllers based on the value of the HTTP parameter task. This parameter is set by Joomla core javascript based on the submit button, e.g. in the example below:

onclick="Joomla.submitbutton('myform.submit')"

The task parameter is in this example set to "myform.submit". In general the task parameter is of the form "firstpart.secondpart" and for a component called "com_example" Joomla will try to run an instance method called secondpart() of a controller class ExampleControllerFirstpart in a file firstpart.php in the controllers directory.

If the task parameter is not set then Joomla will try to run the display() method of the ExampleController class which it will expect to find in controller.php.

In terms of code:

$controller = JControllerLegacy::getInstance('Sample_form2');

uses the task parameter to identify the appropriate controller file to include, and then creates an instance of that controller class.

$controller->execute($input->getCmd('task'));

executes the appropriate method (secondpart() - or in the case below, submit() - or display()) of that class.

In this way controller functionality handling GETs (generally in the file controller.php) is separated from that handling POSTs (generally in the files in the controllers folder).

Joomla MVC Classes[edit]

Joomla provides feature-rich controller, view and model classes from which your component controllers, views and models can inherit. The model code below inherits from FormModel which shields somewhat the Joomla Form API. In this case our model calls FormModel::loadForm(), and this then executes a callback to our loadFormData() to provide the data to bind() to the form.

You can also use FormController and AdminController classes, but these assume that your component is using a database table to store the data. The Joomla MVC Component Development tutorial takes this approach in J3.x:Developing an MVC Component/Adding backend actions.

Security Token[edit]

Joomla uses a security token on forms to prevent CSRF attacks (see https://en.wikipedia.org/wiki/Cross-site_request_forgery). The token is output in the layout file

<?php echo JHtml::_('form.token'); ?>

and checked within the controller handling the POST:

$this->checkToken();

If the token is found to be invalid then checkToken() outputs a warning and redirects the user back to the previous page.

Client-side Validation[edit]

In addition to the server-side validation included through the form XML definition, Joomla also provides a way of including JavaScript which performs client-side validation on the browser. This is NOT included below, as it's deemed beyond the scope of this tutorial, but you can find details of it in J3.x:Developing an MVC Component/Adding verifications and Client-side form validation.

Sample Form 2[edit]

This second sample component incorporates the design decisions described above and structures the code according to the Joomla paradigm. The overall file structure is shown in the diagram below.

Sample Form 2 file structure.

Starting at the bottom of this diagram and going upwards the file contents are:

com_sample_form2/sample_form2.php Entry point for the component. This is the first file which Joomla runs.

<?php
defined('_JEXEC') or die('Restricted access');
// Load the appropriate controller class
$controller = JControllerLegacy::getInstance('Sample_form2');

$input = JFactory::getApplication()->input;
// Run the task method, or display() if no task parameter
$controller->execute($input->getCmd('task'));

$controller->redirect();

com_sample_form2/controller.php The controller for handling HTTP GET requests

<?php
defined('_JEXEC') or die('Restricted access');
use Joomla\CMS\MVC\Controller\BaseController;

class Sample_form2Controller extends BaseController
{
	// Joomla will look for this class within the controller.php file
	// It will (usually) call the display() method, and will find this is in the BaseController class
}

com_sample_form2/sample_form2.xml Manifest file for the component.

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.1.0" method="upgrade">

	<name>com_sample_form2</name>
	<version>1.0.0</version>
	<description>Sample form 2</description>

	<administration>
	</administration>

	<files folder="site">
		<filename>sample_form2.php</filename>
		<filename>controller.php</filename>
		<folder>controllers</folder>
        <folder>views</folder>
        <folder>models</folder>
	</files>
</extension>

com_sample_form2/views/form/view.html.php View file for displaying the form. The controller display() function will create instances of the model and view, and call the view display() function below.

<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\MVC\View\HtmlView;
use Joomla\CMS\Factory;

class Sample_form2ViewForm extends HtmlView
{
	public function display($tpl = null)
	{
		if (!$this->form = $this->get('form'))
		{
			echo "Can't load form<br>";
			return;
		}
		parent::display($tpl);	// this will include the layout file edit.php
	}
}

com_sample_form2/views/form/tmpl/edit.php Layout file for displaying the form

<?php
defined('_JEXEC') or die('Restricted access');
?>
<form action="<?php echo JRoute::_('index.php?option=com_sample_form2&view=form&layout=edit'); ?>"
    method="post" name="adminForm" id="adminForm" enctype="multipart/form-data">

	<?php echo $this->form->renderField('message');  ?>

	<?php echo $this->form->renderField('email');  ?>

	<?php echo $this->form->renderField('telephone');  ?>

	<button type="button" class="btn btn-primary" onclick="Joomla.submitbutton('myform.submit')">Submit</button>

	<input type="hidden" name="task" />
	<?php echo JHtml::_('form.token'); ?>
</form>

com_sample_form2/models/form.php Model associated with displaying the form. The view get('form') gets mapped to the model getForm() method call.

<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\MVC\Model\FormModel;

class Sample_form2ModelForm extends FormModel
{

	public function getForm($data = array(), $loadData = true)
	{
		$form = $this->loadForm(
			'com_sample_form2.sample',  // just a unique name to identify the form
			'sample_form',				// the filename of the XML form definition
										// Joomla will look in the models/forms folder for this file
			array(
				'control' => 'jform',	// the name of the array for the POST parameters
				'load_data' => $loadData	// will be TRUE
			)
		);

		if (empty($form))
		{
            $errors = $this->getErrors();
			throw new Exception(implode("\n", $errors), 500);
		}

		return $form;
	}

    protected function loadFormData()
	{
		// Check the session for previously entered form data.
		$data = JFactory::getApplication()->getUserState(
			'com_sample_form2.sample',	// a unique name to identify the data in the session
			array("telephone" => "0")	// prefill data if no data found in session
		);

		return $data;
	}

}

com_sample_form2/models/forms/sample_form.xml XML file containing the form definition

<?xml version="1.0" encoding="utf-8"?>
<form>
	<field
		name="message"
		type="text"
		label="Enter message"
		size="40"
		class="inputbox"
		required="true" />
	<field name="email"
		type="email"
		label="Enter email"
		required="true"
		size="40"
		class="inputbox" />
	<field name="telephone"
		type="tel"
		label="Enter telephone number"
		required="true"
		size="40"
		class="inputbox"
		validate="tel" />
</form>

com_sample_form2/controllers/Myform.php Controller which handles the HTTP POST

<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\MVC\Controller\BaseController;
use Joomla\CMS\Factory;

class Sample_form2ControllerMyform extends BaseController
{
	public function submit($key = null, $urlVar = null)
	{
		$this->checkToken();

		$app   = JFactory::getApplication();
		$model = $this->getModel('form');
		$form = $model->getForm($data, false);
		if (!$form)
		{
			$app->enqueueMessage($model->getError(), 'error');
			return false;
		}

		// name of array 'jform' must match 'control' => 'jform' line in the model code
		$data  = $this->input->post->get('jform', array(), 'array');

		// This is validate() from the FormModel class, not the Form class
		// FormModel::validate() calls both Form::filter() and Form::validate() methods
		$validData = $model->validate($form, $data);

		if ($validData === false)
		{
			$errors = $model->getErrors();

			foreach ($errors as $error)
			{
				if ($error instanceof \Exception)
				{
					$app->enqueueMessage($error->getMessage(), 'warning');
				}
				else
				{
					$app->enqueueMessage($error, 'warning');
				}
			}

			// Save the form data in the session, using a unique identifier
			$app->setUserState('com_sample_form2.sample', $data);
		}
		else
		{
			$app->enqueueMessage("Data successfully validated", 'notice');
			// Clear the form data in the session
			$app->setUserState('com_sample_form2.sample', null);
		}

		// Redirect back to the form in all cases
		$this->setRedirect(JRoute::_('index.php?option=com_sample_form2&view=form&layout=edit', false));
	}
}

After creating the files as described above, zip up the com_sample_form2 folder to create com_sample_form2.zip and install this component. Then navigate to your Joomla site and add into the URL the parameters &option=com_sample_form2&view=form&layout=edit. This should display the form, and should work in a similar fashion to previous sample form, except that errors etc. will appear in the message part of the Joomla display.