Actions

J1.5

Difference between revisions of "Using the core parameter types"

From Joomla! Documentation

m (Folder list)
m (Added category)
(3 intermediate revisions by 3 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 17: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.