Joomla! Programmers Documentation

This is an example component which you can download from com_exampleform.

Once you have downloaded the source, zip up the com_exampleform directory and install the component.

Then go to <your domain>/index.php/component/exampleform to run it on your Joomla instance.

It is an MVC component which demonstrates the following:

• using Joomla Forms to capture data in a form
• using several of the standard form fields
• writing a custom field
• writing a custom server-side validation rule
• writing a custom client-side validation rule
• writing a custom form filter

You can easily adapt it to experiment with other standard fields, simply by including the standard field in the form XML file.

There are comments throughout the code to help you understand it, and brief summaries of the main source files are provided below.

Administrator service provider¶

Path: administrator/components/com_exampleform/services/provider.php

This is boilerplate code for a basic MVC component. For components this file is placed under /administrator in the Joomla filesystem. If you want to understand it fully then read the Dependency Injection section.

From this file Joomla instantiates default Extension and Dispatcher classes, and an MVC Factory class which creates Model, View and Controller classes for our component.

Site Display Controller¶

Path: components/com_exampleform/src/Controller/DisplayController.php

This is what is run when you go to your site page which displays the form (ie navigate to the URL .../index.php/component/exampleform).

It gets the associated Model and View classes, and calls display() on the View instance.

Site Exampleform View¶

Path: components/com_exampleform/src/View/Exampleform/HtmlView.php

This calls the model to set up the form, then calls display() to run the tmpl file.

Site Exampleform Model¶

Path: components/com_exampleform/src/Model/ExampleformModel.php

This sets up the form as described in Forms.

Site Exampleform tmpl file¶

Path: components/com_exampleform/tmpl/exampleform/default.php

This uses the Web Asset Manager to set up the scripts for client-side validation.

Then it outputs the <form> html, and outputs the fields using renderFieldset.

The Submit button has an onclick listener which calls Joomla.submitbutton('exampleform.submit'). This function will initiate an HTTP POST to the server, with the field values as POST parameters, including the task parameter set to 'exampleform.submit'.

When the HTTP request reaches the server Joomla will examine the task parameter, and as a result will call the ExampleformController::submit() method, as described in Joomla MVC.

Example XML Form¶

Path: components/com_exampleform/forms/example_form.xml

Most of this involves simply using the Joomla Standard Form Fields.

You can easily add in other standard form fields to experiment with them.

In addition, the file includes:

Definition of a custom field:

addfieldprefix="My\Component\Exampleform\Site\Field"
name="time" 
type="mytime"

Definition of a custom filter:

addfilterprefix="My\Component\Exampleform\Site\Filter"
filter="lettersonly"

Definition of a custom client-side validation rule:

class="inputbox validate-noUppercase"
data-validation-text="Error: No uppercase letters are allowed"

Definition of a custom server-side validation rule:

addruleprefix="My\Component\Exampleform\Site\Rule"
validate="noasterisk"

Use of the showon attribute.

Site Exampleform Controller¶

Path: components/com_exampleform/src/Controller/ExampleformController.php

When the form data is sent to the server in an HTTP POST request, Joomla examines the task parameter, and as this will be set to 'exampleform.submit' Joomla will call the submit function of the ExampleformController class instance.

This function obtains the array of POST parameters and gets the model to set up the form again from the definition in example_form.xml.

It then initiates applying the filtering and validation rules of the fields.

If the data fails validation then the data entries are stored in the session, and a redirect back to the form is issued. When the HTTP GET request to redisplay the form is received then the loadFormData function in the ExampleformModel will retrieve the session data and prefill the fields with the previous entries.

If the data passes validation then the ExampleformReturn view is instantiated, and the raw data and filtered data passed to it.

Site ExampleformReturn View¶

Path: components/com_exampleform/src/View/ExampleformReturn/HtmlView.php

This simply has a function to accept the data from the Controller, which it stores locally.

Site ExampleformReturn tmpl file¶

Path: components/com_exampleform/tmpl/exampleformReturn/default.php

This simply outputs the raw and filtered data which was passed to the view.

Remember that the view and the tmpl file share the same function context, so variables set up in the view are accessible in the tmpl file.

Custom Field¶

Path: components/com_exampleform/src/Field/MytimeField.php

This is the source code for the mytime custom field.

Custom Filter¶

Path: components/com_exampleform/src/Filter/LettersonlyFilter.php

This is the source code for the lettersonly custom filter.

Custom Validation Rule¶

Path: components/com_exampleform/src/Rule/Noasterisk.php

This is the source code for the noasterisk custom server-side validation rule.

Media joomla.asset.json file¶

Path: media/com_exampleform/joomla.asset.json

This defines the component's javascript (and CSS) assets, together with their dependancies, as required by the Web Asset Manager.

For components this file is always automatically processed by Joomla.

Javascript client-side validation code¶

Path: media/com_exampleform/js/no-uppercase.js

This is javascript code for the custom client-side validation rule.