Page 1 of 2
Parameters are a key idea in Joomla development. It is almost an understatement to say that they are used to customise modules, components, plug-ins and templates. In many cases parameters provide the basic data that makes the add-in function.
In the case of modules parameters are used to create multiple instances of a single module to do different jobs and in this case they are fundamental to the operation of a module. Parameters are also automatically stored in the site's database and provides some of the easiest-to-use data persistence facilities in Joomla and they provide an almost automatic user interface - with little extra work.
You can also create custom Joomla parameters complete with custom user interfaces using the same framework - but this is the subject of another article - for now let's take a look at how to use the standard Joomla parameters.
Joomla provides 21 different types of standard controls or widgets that can be displayed in an administrative or back-end editor and you can use these in modules, components, plug-ins and even templates.
All you have to do is add some XML to the installation manifest and you can start to use them in either the back-end or the front-end PHP code. They are automatically created and the database is used to persist their values.
If there isn't a control that suits your application then creating a custom control is fairly easy as well. This makes building complicated add-ons, complete with customisable parameters, much easier than you might think.
All of the standard controls are listed as standard parameter types. but they fall into a small number of basic categories, some of which should be familiar from HTML, and is worth just indicating what is available.
First we have the general input types:
- text - a text box
- textarea - multi-line text entry
- password - password entry text box
- radio - radio buttons to select different options.
- hidden - a hidden field for saving a parameter
There are a great many very useful drop-down lists that are provided ready populated or fully customisable:
- list - custom-defined entries
- category - sections in a specific category
- editors - available editors
- filelist - files from a specified directory.
- folderlist - folders from a specified directory.
- helpsites - help sites for your Joomla installation.
- imagelist - image files in a specified directory.
- languages - installed languages
- menu - available menus
- menuitem - menu items
- section - sections
- sql - list of entries returned from a sql query
- timezones - time zones.
- usergroup - user groups.
There is also one date entry widget:
and a spacer widget that can be used for layout:
- spacer - no parameter value is stored
All of these controls can be created in the add-ons editing page in the admin site simply by placing the appropriate XML into the manifest, i.e. the XML file included in the installation. At the end of the XML file you can add as many control specifications as you need between:
list of controls
Each control corresponds to at least one <param> tag and a set of attributes - at least a name and a value but for a standard parameter also a type attribute which defines the control. The other attributes that you can use depend on the control selected and you can look these up at:standard parameter types.
For example, lets add a message parameter to the simple module created in More Advanced Joomla Modules with PHP and Eclipse - although the same method will work if the XML is added to the simple component created in A Simple Joomla Module with PHP and Eclipse or indeed any XML installation file.
To do this you need to add a text box using the following XML:
<param name="mygreeting" type="text"
label="Set the greeting"
description="To set the greeting"
If you now uninstall the component and reinstall it using the new XML file within the ZIP then when you navigate to the module's editing page you will see a new textbox with the specifications you have provided.
If you want you can add parameters to the advanced, legacy or other group by adding the attribute group="advanced". group="legacy" or group="other" to the params tag. If you want to create your own groups you will have to modify the admin.modules.html.php template which is usually not worth the small gain in presentation.