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.

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.

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' ); ?>"
```

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>!

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>!

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.

Retrieved from "http://docs.joomla.org/Using_the_core_parameter_types"

Categories: Articles that require a review | Development

Using the core parameter types

Contents

Calendar

Category

Editors

File list

Folder list

Help sites

Hidden

Image list

Language

List

Menu

Menu item

Password

Radio

Section

Spacer

SQL

Text

Text area

Time zones

Views

Personal tools

Navigation

Joomla! Sites

Search

Toolbox