Using the core parameter types
| This recently added article requires a review |
Parameters are one way in which data may be stored for a Joomla! Extension. Each parameter consists of two parts: a simple text string of the form {NAME} = {VALUE}, in which the parameter value is recorded (usually concatenated into a single string with other parameter values, and stored in a table field); and a form field in the Extension backend, which allows a user to enter the parameter value, and which is defined by an xml <param> element.
Joomla! defines 20 different core parameter types, each of which gives a predefined behviour and appearance in the backend. This makes it very easy for developers to implement a range of different form data entry types (text boxes, radio buttons, calendar selectors, etc) with a minimum of effort. This behaviour and appearance is determined by the type attribute of the <param> element, as detailed below.
Contents |
Calendar
Description: This provides a text box for entry of a date. If the parameter has a value saved, this value is shown in the text box. If not, the default value (if any) is displayed. An icon next to the text box provides a link to a pop-up calendar, which can also be used to enter the date value.
Screen shot:
XML definition:
<param name="mycalendar" type="Calendar" default="5-10-2008" label="Select a date" description="" format="%d-%m-%Y" />- Name: The name under which the parameter value is stored.
- Default: The default date.
- Label: A label displayed next to the text box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
- Format: The date format to be used.
Category
Description: This provides a drop down list of categories from a given section. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="mycategory" type="Category" label="Select a category" description="" section="3" />- Name: The name under which the parameter value is stored.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
- Section: The section ID number from which the categories should be selected. (This can be found in the Section Manager.)
Editors
Description: This provides a drop down list of the available WYSIWYG editors. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="myeditor" type="Editors" default="" label="Select an editor" description="" />- Name: The name under which the parameter value is stored.
- Default: The default editor.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
File list
Description: This provides a drop down list of files from a certain directory. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="myfile" type="Filelist" default="" label="Select a file"
description="" directory="administrator" filter="" exclude="" stripext="" />- Name: The name under which the parameter value is stored.
- Default: The default file name.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
- Directory: The directory containing the files to be listed.
- Filter: A text string which is used to filter the list of files shown. Only those files whose names contain the string will be shown.
- Exclude: Similarly, a text string which is used to exclude files from the list.
- Stripext: Strip these characters.
Folder list
Description: This provides a drop down list of folders from a certain directory. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="my folder" type="Folderlist" default="" label="Select a folder" description=""
directory="administrator" filter="" exclude="" stripext="" />- Name: The name under which the parameter value is stored.
- Default: The default folder name.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
- Directory: The directory containing the folders to be listed.
- Filter: A text string which is used to filter the list of folders shown. Only those folders whose names contain the string will be shown.
- Exclude: Similarly, a text string which is used to exclude folders from the list.
- Stripext: Strip these characters.
Help sites
Description: This provides a drop down list of the help sites in your Joomla! installation. These can be found at administrator\help\helpsites-15.xml. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="myhelpsite" type="Helpsites" default="" label="Select a help site" description="" />- Name: The name under which the parameter value is stored.
- Default: The default help site.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
Hidden
Description: This provides a hidden text box for recording system information at the time the parameters are (last) saved. If the parameter has a value saved, this value is entered in the text box. If not, the default value (if any) is entered.
Screen shot: As the name says, this parameter is a hidden one. No output will be displayed.
XML definition:
<param name="mysecretvariable" type="Hidden" value="" />- Name: The name under which the parameter value is stored.
- Value: The data which needs to be collected.
- Two examples:
- The ID of the user:
value="<?php echo $this->user->get('id'); ?>" - The date on which the parameters were saved:
value="<?php echo date( 'j M Y' ); ?>"
- The ID of the user:
- Two examples:
Image list
Description: This provides a drop down list of images: .png, .gif, .jpg, .bmp and .ico. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="myimage" type="Imagelist" default="" label="Select an image" description="" directory="" exclude="" stripext="" />- Name: The name under which the parameter value is stored.
- Default: The default image.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
- Directory: The directory containing the images to be listed.
- Exclude: A text string which is used to exclude certain images from the list. Any images whose names contain the string will be excluded.
- Stripext: Strip these characters.
Language
Description: This provides a drop down list of the installed languages for the Front-end or Back-end. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="mylanguage" type="Languages" client="site" default="" label="Select a language" description="" />- Name: The name under which the parameter value is stored.
- Client: Use 'site' when you want to display the Front-end languages, and 'administrator' when you want to display the Back-end languages.
- Default: The default language.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
List
Description: This provides a drop down list of custom-defined entries. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="mylistvalue" type="List" default="" label="Select an option" description="" > <option value="0">Option 1</option> <option value="1">Option 2</option> </param>
- Name: The name under which the parameter value is stored.
- Default: The default list option.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
- Option: A list entry. The text between the
<option>...</option>tags is what is shown in the drop down list. - Option value: The value that will be saved for the parameter when a given option is selected.
- N.B. Don't forget to close the parameter with
</param>!
- N.B. Don't forget to close the parameter with
Menu
Description: This provides a drop down list of the available menus from your Joomla! site. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="mymenu" type="Menu" default="" label="Select a menu" description="" />- Name: The name under which the parameter value is stored.
- Default: The default menu.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
Menu item
Description: This provides a drop down list of the available menu items from your Joomla! site.
Screen shot:
XML definition:
<param name="mymenuitem" type="MenuItem" default="" label="Select a menu item" description="" />- Name: The name under which the parameter value is stored.
- Default: The default menu item.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
Password
Description: This provides a text box for entry of a password. The password characters will be obscured as they are entered. If the parameter has a value saved, this value is entered (in obscured form) into the text box. If not, the default value (if any) is entered.
Screen shot:
XML definition:
<param name="mypassword" type="Password" default="" label="Enter a password" description="" size="5" />- Name: The name under which the parameter value is stored.
- Default: The default password.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
- Size: The width of the text box in characters.
Radio
Description: This provides radio buttons to select different options. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="myradiovalue" type="Radio" default="0" label="Select an option" description="" > <option value="0">1</option> <option value="1">2</option> </param>
- Name: The name under which the parameter value is stored.
- Default: The default radio option.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
- Option: A radio option. The text between the
<option>...</option>tags is shown as the label for the radio button. - Option value: The value that will be saved for the parameter when a given option is selected.
- N.B. Don't forget to close the parameter with
</param>!
- N.B. Don't forget to close the parameter with
Section
Description: This provides a drop down list of the sections from your Joomla! site. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="mysection" type="Section" default="" label="Select a section" description="" />- Name: The name under which the parameter value is stored.
- Default: The default section.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
Spacer
Description:' This provides a separator between parameter entry elements.
Screen shot:
XML definition:
<param type="Spacer" />
SQL
Description: This provides a drop down list of entries obtained by running a query on the Joomla! database. The first results column returned by the query provides the values for the drop down box. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
Screen shot:
XML definition:
<param name="title" type="SQL" default="" label="Select an article" description="" query="SELECT id, title FROM #__content" />- Name: The name under which the parameter value is stored. This should be the same as the query results column that you want to be displayed in the drop-down box.
- Default: The default value.
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
- Query: The MySQL query which provides the data for the drop down box.
Text
Description: This provides a text box for data entry.
Screen shot:
XML definition:
<param name="mytextvalue" type="Text" default="" label="Enter some text" description="" size="10" />- Name: The name under which the parameter value is stored.
- Default: The default text.
- Label: A label displayed next to the text box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
- Size: The width of the text box in characters.
Text area
Description: This provides a text area for entry of multi-line text.
Screen shot:
XML definition:
<param name="mytextarea" type="Textarea" default="default" label="Enter some text" description="" rows="10" cols="5" />- Name: The name under which the parameter value is stored.
- Default: The default text.
- Label: A label displayed next to the text area to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the text area.
- Rows: The height of the visible text area, in lines.
- Cols: The width of the visible text area, in characters.
Time zones
Description: This provides a drop down list of time zones.
Screen shot:
XML definition:
<param name="mytimezone" type="Timezones" default="-10" label="Select a timezone" description="" />- Name: The name under which the parameter value is stored.
- Default: The default time zone. Use for example '-10' for UTC -10:00
- Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
- Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.















