Actions

J1.5

Difference between revisions of "Using the core parameter types"

From Joomla! Documentation

(Corrected some errors, and cleaned up. Removed references to reading parameter values as not relevant to XML definitions.)
m (Added category)
(5 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{review}}
+
Parameters are one way that data may be stored for a Joomla! Extension. Each parameter consists of two parts:
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 <code><param></code> element.
+
* A simple text string of the form {NAME} = {VALUE}, in which the parameter value is recorded. The strings are usually concatenated into a single string with other parameter values and stored in a table field.
 +
* A form field in the Extension backend that allows a user to enter the parameter value, and which is defined by an XML <code><param></code> 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 <code>type</code> attribute of the <code><param></code> element, as detailed below.
+
Joomla! defines 21 core parameter types, each of which gives a predefined behaviour and appearance in the back-end. This makes it very easy for developers to implement a range of form data entry types (text boxes, radio buttons, calendar selectors and so on) with a minimum of effort. This behaviour and appearance is determined by the <code>type</code> attribute of the <code><param></code> element. See [[Standard parameter types]] for a complete list and details of each type.
 
+
<noinclude>[[Category:Development]][[Category:Parameters]]</noinclude>
=== 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:'''
+
 
+
[[Image:Params.calendar.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mycalendar" type="Calendar" default="5-10-2008" label="Select a date" description="" format="%d-%m-%Y" /></source>
+
*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:'''
+
 
+
[[Image:Params.category.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mycategory" type="Category" label="Select a category" description="" section="3" />
+
</source>
+
*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:'''
+
 
+
[[Image:Params.editors.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="myeditor" type="Editors" default="" label="Select an editor" description="" /></source>
+
*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:'''
+
 
+
[[Image:Params.filelist.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="myfile" type="Filelist" default="" label="Select a file"
+
description="" directory="administrator" filter="" exclude="" stripext="" /></source>
+
*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:'''
+
 
+
[[Image:Params.folderlist.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="my folder" type="Folderlist" default="" label="Select a folder" description=""
+
directory="administrator" filter="" exclude="" stripext="" /></source>
+
*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:'''
+
 
+
[[Image:Params.helpsites.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="myhelpsite" type="Helpsites" default="" label="Select a help site" description="" /></source>
+
*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:'''
+
<source lang=xml><param name="mysecretvariable" type="Hidden" value="" /></source>
+
*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: <source lang=xml>value="<?php echo $this->user->get('id'); ?>"</source>
+
***The date on which the parameters were saved: <source lang=xml>value="<?php echo date( 'j M Y' ); ?>"</source>
+
 
+
 
+
----
+
 
+
===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:'''
+
 
+
[[Image:Params.imagelist.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="myimage" type="Imagelist" default="" label="Select an image" description="" directory="" exclude="" stripext="" /></source>
+
*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:'''
+
 
+
[[Image:Params.language.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mylanguage" type="Languages" client="site" default="" label="Select a language" description="" /></source>
+
*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:'''
+
 
+
[[Image:Params.list.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mylistvalue" type="List" default="" label="Select an option" description="" >
+
  <option value="0">Option 1</option>
+
  <option value="1">Option 2</option>
+
</param></source>
+
*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 <code><option>...</option></code> 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 <code></param></code>!
+
 
+
 
+
----
+
 
+
===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:'''
+
 
+
[[Image:Params.menu.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mymenu" type="Menu" default="" label="Select a menu" description="" /></source>
+
*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:'''
+
 
+
[[Image:Params.menuitem.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mymenuitem" type="MenuItem" default="" label="Select a menu item" description="" /></source>
+
*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:'''
+
 
+
[[Image:Params.password.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mypassword" type="Password" default="" label="Enter a password" description="" size="5" /></source>
+
*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:'''
+
 
+
[[Image:Params.radio.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="myradiovalue" type="Radio" default="0" label="Select an option" description="" >
+
  <option value="0">1</option>
+
  <option value="1">2</option>
+
</param></source>
+
*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 <code><option>...</option></code> 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 <code></param></code>!
+
 
+
 
+
----
+
 
+
===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:'''
+
 
+
[[Image:Params.section.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mysection" type="Section" default="" label="Select a section" description="" /></source>
+
*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:'''
+
 
+
[[Image:Params.spacer.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param type="Spacer" /></source>
+
 
+
 
+
----
+
 
+
===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:'''
+
 
+
[[Image:Params.sql.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="title" type="SQL" default="" label="Select an article" description="" query="SELECT id, title FROM #__content" /></source>
+
*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:'''
+
 
+
[[Image:Params.text.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mytextvalue" type="Text" default="" label="Enter some text" description="" size="10" /></source>
+
*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:'''
+
 
+
[[Image:Params.textarea.jpg]]
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mytextarea" type="Textarea" default="default" label="Enter some text" description="" rows="10" cols="5" /></source>
+
*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:'''
+
 
+
[[Image:Params.timezones.jpg]]
+
 
+
 
+
'''XML definition:'''
+
<source lang=xml><param name="mytimezone" type="Timezones" default="-10" label="Select a timezone" description="" /></source>
+
*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.
+

Revision as of 16:24, 22 November 2011

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

Parameters are one way that 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. The strings are usually concatenated into a single string with other parameter values and stored in a table field.
  • A form field in the Extension backend that allows a user to enter the parameter value, and which is defined by an XML <param> element.

Joomla! defines 21 core parameter types, each of which gives a predefined behaviour and appearance in the back-end. This makes it very easy for developers to implement a range of form data entry types (text boxes, radio buttons, calendar selectors and so on) with a minimum of effort. This behaviour and appearance is determined by the type attribute of the <param> element. See Standard parameter types for a complete list and details of each type.