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.)
Line 1: Line 1:
 
{{review}}
 
{{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 <code><param></code> element.
  
When you create an extension (component, module, plugin or template) you can implement parameters in the .XML file. You can use these parameters in the main PHP file. There are 20 extension parameter types available in Joomla! 1.5. You can use them easily and in this document you will find a description for all of them. You can also add your own parameters, you can find information about this specific part here: [[Creating_custom_XML_parameter_types]]
+
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.
  
== XML file ==
+
=== Calendar ===
You need an XML file for every extension. It is used mainly to install the extension. A
+
'''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.
particular XML file looks like this:
+
<source lang=xml>
+
<?xml version="1.0" encoding="utf-8"?>
+
<install version="1.5" type="extension type">
+
<name>Name of your extension</name>
+
<creationDate>Created Date</creationDate>
+
<author>Your name</author>
+
<authorEmail>Your e-mail address</authorEmail>
+
<authorUrl>Your website</authorUrl>
+
<copyright>Copyright</copyright>
+
<license>License, for example GNU/GPL</license>
+
<version>Version of the extension</version>
+
<description>Description of the extension</description>
+
<files>
+
<filename>add the files between those tags</filename>
+
</files>
+
<languages>
+
<language tag="en-GB">Language file</language>
+
</languages>
+
<params>
+
Place the parameters between these tags.
+
</params>
+
</install>
+
</source>
+
 
+
== Parameters ==
+
The parameters should be placed between the <code><params></code> and <code></params></code> tags. You can also
+
add groups. For example, the 'Advanced' group. This will look like this:
+
<source lang=xml>
+
<params>
+
'Normal' parameters
+
</params>
+
<params group="advanced">
+
Advanced parameters
+
</params></source>
+
Note: You can not add groups to templates.
+
 
+
=== Core Parameters ===
+
There are 20 parameter types available within your Joomla! 1.5 installation. These are:
+
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 and Time zones, and
+
will be described here in detail.
+
Each one is described in the following order:
+
*Description
+
*Screen shot of output
+
*XML file
+
*Implementation in PHP file
+
 
+
 
+
==== Calendar ====
+
'''Description:''' This parameter shows a text box where you can fill in the date. You can also choose
+
the date from a calendar, which pops up after you clicked on the icon next to the text
+
box.
+
  
 
'''Screen shot:'''  
 
'''Screen shot:'''  
Line 63: Line 11:
 
[[Image:Params.calendar.jpg]]
 
[[Image:Params.calendar.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml><param name="calendar" type="Calendar" default="5-10-2008" label="Calendar"  
+
<source lang=xml><param name="mycalendar" type="Calendar" default="5-10-2008" label="Select a date" description="" format="%d-%m-%Y" /></source>
description="" format="%d-%m-%Y" /></source>
+
*Name: The name under which the parameter value is stored.
*Name: The name used to implement in the PHP file.
+
*Type: For a calendar parameter, use 'Calendar'.
+
 
*Default: The default date.
 
*Default: The default date.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the text box to indicate the purpose of the parameter.
*Description: The description displayed as a tool tip.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
*Format: The format of the date.
+
*Format: The date format to be used.
  
'''PHP file:''' For example, get the parameter, named publish_up, like this:
 
<source lang=php>
 
$publish_up = new JDate($row->publish_up);
 
</source>
 
*Reference: administrator\components\com_content\admin.content.html.php, 122-168
 
  
 +
----
  
====Category====
+
===Category===
'''Description:''' This parameter shows a drop down list of categories from a section.
+
'''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:'''
 
'''Screen shot:'''
Line 87: Line 29:
 
[[Image:Params.category.jpg]]
 
[[Image:Params.category.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml><param name="category" type="Category" label="Category" description="" section="3" />
+
<source lang=xml><param name="mycategory" type="Category" label="Select a category" description="" section="3" />
 
</source>
 
</source>
*Name: The name used to implement in the PHP file.
+
*Name: The name under which the parameter value is stored.
*Type: For a category parameter, use 'Category'.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Label: The name displayed at the output of the parameter.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
*Description: The description displayed as a tool tip.
+
*Section: The section ID number from which the categories should be selected.  (This can be found in the Section Manager.)
*Section: The section ID number, can be found in the Section Manager.
+
 
'''PHP file:''' For example, get use the parameter, named category, like this:
+
<source lang=php>$category[$section->id][]
+
</source>
+
*Reference: administrator\components\com_content\controller.php, 452-530
+
  
 +
----
  
====Editors====
+
===Editors===
'''Description:''' This parameter shows a drop down list of the available WYSIWYG 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:'''
 
'''Screen shot:'''
Line 108: Line 47:
 
[[Image:Params.editors.jpg]]
 
[[Image:Params.editors.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml><param name="editors" type="Editors" default="" label="Editors" description="" /></source>
+
<source lang=xml><param name="myeditor" type="Editors" default="" label="Select an editor" description="" /></source>
*Name: The name used to implement in the PHP file.
+
*Name: The name under which the parameter value is stored.
*Type: For an editor parameter, use 'Editor'.
+
 
*Default: The default editor.
 
*Default: The default editor.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Description: The description displayed as a tool tip.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
'''PHP file:''' For example, get the parameter, named editors, like this:
+
<source lang=php>$this->lists['Editors']</source>
+
*Reference: administrator\components\com_config\controllers\application.php, 86
+
  
  
====File list====
+
----
'''Description:''' This parameter shows a drop down list of files from a certain directory.
+
 
 +
===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:'''
 
'''Screen shot:'''
Line 127: Line 64:
 
[[Image:Params.filelist.jpg]]
 
[[Image:Params.filelist.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml><param name="filelist" type="Filelist" default="" label="File list"  
+
<source lang=xml><param name="myfile" type="Filelist" default="" label="Select a file"  
description="" directory="" filter="" exclude="" stripext="" /></source>
+
description="" directory="administrator" filter="" exclude="" stripext="" /></source>
*Name: The name used to implement in the PHP file.
+
*Name: The name under which the parameter value is stored.
*Type: For a file list parameter, use 'Filelist'.
+
*Default: The default file name.
*Default: The default file.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Label: The name displayed at the output of the parameter.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
*Description: The description displayed as a tool tip.
+
*Directory: The directory containing the files to be listed.
*Directory: The directory from which the files should be showed.
+
*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.
**For example “administrator”.
+
*Exclude: Similarly, a text string which is used to exclude files from the list.
*Filter: Search in the files and only show the files containing this word or letter.
+
*Exclude: Exclude a certain file, file format or word from showing in the list.
+
 
*Stripext: Strip these characters.
 
*Stripext: Strip these characters.
'''PHP file:''' For example, get the parameter, named editors, like this:
 
<source lang=php>$params->get('ParameterName')</source>
 
  
====Folder list====
+
 
'''Description:''' This parameter shows a drop down list of folders from a certain directory.
+
----
 +
 
 +
===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:'''
 
'''Screen shot:'''
Line 150: Line 86:
 
[[Image:Params.folderlist.jpg]]
 
[[Image:Params.folderlist.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml><param name="folderlist" type="Folderlist" default="" label="Folder list" description=""  
+
<source lang=xml><param name="my folder" type="Folderlist" default="" label="Select a folder" description=""  
directory="" filter="" exclude="" stripext="" /></source>
+
directory="administrator" filter="" exclude="" stripext="" /></source>
*Name: The name used to implement in the PHP file.
+
*Name: The name under which the parameter value is stored.
*Type: For a folder list parameter, use 'Folderlist'.
+
*Default: The default folder name.
*Default: The default folder.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Label: The name displayed at the output of the parameter.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
*Description: The description displayed as a tool tip.
+
*Directory: The directory containing the folders to be listed.
*Directory: The directory from which the folders should be showed.
+
*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.
**For example “administrator”.
+
*Exclude: Similarly, a text string which is used to exclude folders from the list.
*Filter: Search within the folders and only show the folders containing this word or letter.
+
*Exclude: Exclude a certain folder or some folders containing a certain word from showing in the list.
+
 
*Stripext: Strip these characters.
 
*Stripext: Strip these characters.
'''PHP file:''' For example, get the parameter, named headerColor, like this:
 
<source lang=php>$this->params->get('headerColor','green')</source>
 
*Reference: administrator\templates\khepri\cpanel.php, 45
 
  
  
====Help sites====
+
----
'''Description:''' This parameter shows a drop down list of the help sites in your Joomla! installation. These can be found at administrator\help\helpsites-15.xml.
+
 
 +
===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:'''
 
'''Screen shot:'''
Line 175: Line 108:
 
[[Image:Params.helpsites.jpg]]
 
[[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.
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
 
<source lang=xml><param name="helpsites" type="Helpsites" default="local" label="Help sites" description="" /></source>
 
*Name: The name used to implement in the PHP file.
 
*Type: For a help site parameter, use 'Helpsites'.
 
*Default: The default editor.
 
*Label: The name displayed at the output of the parameter.
 
*Description: The description displayed as a tooltip.
 
'''PHP file:''' For example, get the parameter, named helpsites, like this:
 
<source lang=php>$this->params->get('helpsites','local')</source>
 
*Reference: administrator\components\com_config\controllers\application.php, 90-94
 
  
 +
----
  
====Hidden====
+
===Hidden===
'''Description:''' This parameter collects information about the user viewing the parameter section.
+
'''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.
+
'''Screen shot:''' As the name says, this parameter is a hidden one. No output will be displayed.
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml><param name="hidden" type="Hidden" value="" /></source>
+
<source lang=xml><param name="mysecretvariable" type="Hidden" value="" /></source>
*Name: The name used to implement in the PHP file.
+
*Name: The name under which the parameter value is stored.
*Type: For a hidden parameter, use 'Hidden'.
+
 
*Value: The data which needs to be collected.
 
*Value: The data which needs to be collected.
 
**Two examples:
 
**Two examples:
***Get ID of user: <source lang=xml>value="<?php echo $this->user->get('id'); ?>"</source>
+
***The ID of the user: <source lang=xml>value="<?php echo $this->user->get('id'); ?>"</source>
***Get filter order: <source lang=xml>value="<?php echo $this->lists['order']; ?>"</source>
+
***The date on which the parameters were saved: <source lang=xml>value="<?php echo date( 'j M Y' ); ?>"</source>
'''PHP file:''' For example, get the parameter, named id, like this:
+
 
<source lang=php>$user->get('id')</source>
+
*Reference: administrator\components\com_users\views\user\view.html.php, 52-76
+
  
 +
----
  
====Image list====
+
===Image list===
'''Description:''' This parameter shows a drop down list with images; .png, .gif, .jpg, .bmp and .ico.
+
'''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:'''
 
'''Screen shot:'''
Line 213: Line 141:
 
[[Image:Params.imagelist.jpg]]
 
[[Image:Params.imagelist.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param name="myimage" type="Imagelist" default="" label="Select an image" description="" directory="" exclude="" stripext="" /></source>
<param name="imagelist" type="Imagelist" default="" label="Image list"  
+
*Name: The name under which the parameter value is stored.
description="" directory="" exclude="" stripext="_" /></source>
+
*Name: The name used to implement in the PHP file.
+
*Type: For an image list parameter, use 'Imagelist'.
+
 
*Default: The default image.
 
*Default: The default image.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Description: The description displayed as a tooltip.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
*Directory: The directory from which the images should be showed.
+
*Directory: The directory containing the images to be listed.
**For example “images/stories”.
+
*Exclude: A text string which is used to exclude certain images from the list.  Any images whose names contain the string will be excluded.
*Exclude: Exclude a certain image name, format or word from showing in the list.
+
 
*Stripext: Strip these characters.
 
*Stripext: Strip these characters.
'''PHP file:''' For example, get the parameter, named image, like this:
 
<source lang=php>JHTML::_('list.images', 'image', $row->image );</source>
 
*Reference: administrator\components\com_categories\admin.categories.php, 386
 
  
  
====Language====
+
----
'''Description:''' This parameter shows a drop down list with the installed languages for the Front-end or Back-end.
+
 
 +
===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:'''
 
'''Screen shot:'''
Line 238: Line 161:
 
[[Image:Params.language.jpg]]
 
[[Image:Params.language.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param name="mylanguage" type="Languages" client="site" default="" label="Select a language" description="" /></source>
<param name="language" type="Languages" client="site" default="" label="Front-end Language" description="" />
+
*Name: The name under which the parameter value is stored.
</source>
+
*Client: Use 'site' when you want to display the Front-end languages, and 'administrator' when you want to display the Back-end languages.
*Name: The name used to implement in the PHP file.
+
*Type: For a language parameter, use 'Languages'.
+
*Client: Use 'site' when you want to display the Front-end languages, use 'administrator' when you want to display the Back-end languages.
+
 
*Default: The default language.
 
*Default: The default language.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Description: The description displayed as a tooltip.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
'''PHP file:''' For example, get the parameters like this:
+
<source lang=php>$params = $this->user->getParameters(true);
+
echo $params->render( 'params' );
+
</source>
+
*Reference: administrator\components\com_users\views\user\tmpl\form.php, 188-189
+
  
  
====List====
+
----
'''Description:''' This parameter shows a drop down list with options.
+
 
 +
===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:'''
 
'''Screen shot:'''
Line 262: Line 179:
 
[[Image:Params.list.jpg]]
 
[[Image:Params.list.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml><param name="list" type="List" default="" label="List"
+
<source lang=xml><param name="mylistvalue" type="List" default="" label="Select an option" description="" >
description="" >
+
  <option value="0">Option 1</option>
<option value="0">Label option 1</option>
+
  <option value="1">Option 2</option>
<option value="1">Label option 2</option>
+
</param></source>
</param>
+
*Name: The name under which the parameter value is stored.
</source>
+
*Name: The name used to implement in the PHP file.
+
*Type: For a list parameter, use 'List'.
+
 
*Default: The default list option.
 
*Default: The default list option.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Description: The description displayed as a tooltip.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
*Option: The option. Place the label beween <option> and </option>. You can add as many as you would like.
+
*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 name used to implement in the PHP file.
+
*Option value: The value that will be saved for the parameter when a given option is selected.
**Don not forget to close the parameter with </param>
+
**N.B. Don't forget to close the parameter with <code></param></code>!
'''PHP file:''' For example, get the parameter, named colorVariation, like this:
+
<source lang=php>$this->params->get('colorVariation')
+
</source>
+
*Reference: templates\rhuk_milkyway\index.php,
+
  
====Menu====
+
 
'''Description:''' This parameter shows a drop down list with the menus from your Joomla! site.
+
----
 +
 
 +
===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:'''
 
'''Screen shot:'''
Line 289: Line 202:
 
[[Image:Params.menu.jpg]]
 
[[Image:Params.menu.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml><param name="menu" type="Menu" default="" label="Menu" description="" />
+
<source lang=xml><param name="mymenu" type="Menu" default="" label="Select a menu" description="" /></source>
</source>
+
*Name: The name under which the parameter value is stored.
*Name: The name used to implement in the PHP file.
+
*Type: For a menu parameter, use 'Menu'.
+
 
*Default: The default menu.
 
*Default: The default menu.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Description: The description displayed as a tooltip.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
'''PHP file:''' For example, get the parameter, named menu, like this:
+
<source lang=php>$this->params->get('menu')
+
</source>
+
  
  
====Menu item====
+
----
'''Description:''' This parameter shows a drop down list with the menu-items from your Joomla! site.
+
 
 +
===Menu item===
 +
'''Description:''' This provides a drop down list of the available menu items from your Joomla! site.
  
 
'''Screen shot:'''
 
'''Screen shot:'''
Line 309: Line 219:
 
[[Image:Params.menuitem.jpg]]
 
[[Image:Params.menuitem.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml><param name="menuitem" type="MenuItem" default="" label="Menu-item" description="" />
+
<source lang=xml><param name="mymenuitem" type="MenuItem" default="" label="Select a menu item" description="" /></source>
</source>
+
*Name: The name under which the parameter value is stored.
*Name: The name used to implement in the PHP file.
+
*Default: The default menu item.
*Type: For a menu parameter, use 'MenuItem'.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Default: The default menu-item.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
*Label: The name displayed at the output of the parameter.
+
 
*Description: The description displayed as a tooltip.
+
 
'''PHP file:''' For example, get the parameter, named selections, like this:
+
----
<source lang=php>$lists['selections']
+
</source>
+
*Reference: administrator\components\com_templates\admin.templates.html.php,
+
lines 325 – 355 (create JavaScript) and 382
+
  
====Password====
+
===Password===
'''Description:''' This parameter shows a text box, where you can fill in a (hidden) 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:'''
 
'''Screen shot:'''
Line 330: Line 236:
 
[[Image:Params.password.jpg]]
 
[[Image:Params.password.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param name="mypassword" type="Password" default="" label="Enter a password" description="" size="5" /></source>
<param name="password" type="Password" default="" label="Password" description="" size="5" />
+
*Name: The name under which the parameter value is stored.
</source>
+
*Name: The name used to implement in the PHP file.
+
*Type: For a password parameter, use 'Password'.
+
 
*Default: The default password.
 
*Default: The default password.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Description: The description displayed as a tooltip.
+
*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.
+
*Size: The width of the text box in characters.
'''PHP file:''' For example, get the parameter, named password, like this:
+
<source lang=php>
+
$this->user->get('password')
+
</source>
+
*Reference: administrator\components\com_users\views\user\tmpl\form.php, 125
+
  
  
====Radio====
+
----
'''Description:''' This parameter shows radio buttons to select different options.
+
 
 +
===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:'''
 
'''Screen shot:'''
Line 354: Line 254:
 
[[Image:Params.radio.jpg]]
 
[[Image:Params.radio.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param name="myradiovalue" type="Radio" default="0" label="Select an option" description="" >
<param name="radio" type="Radio" default="0" label="Radio"
+
  <option value="0">1</option>
description="" >
+
  <option value="1">2</option>
<option value="0">1</option>
+
</param></source>
<option value="1">2</option>
+
*Name: The name under which the parameter value is stored.
</param>
+
</source>
+
*Name: The name used to implement in the PHP file.
+
*Type: For a radio parameter, use 'Radio'.
+
 
*Default: The default radio option.
 
*Default: The default radio option.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Description: The description displayed as a tooltip.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
*Option: The option. Place the label beween <option> and </option>. You can add as many as you would like.
+
*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 name used to implement in the PHP file.
+
*Option value: The value that will be saved for the parameter when a given option is selected.
**Don not forget to close the parameter with </param>
+
**N.B. Don't forget to close the parameter with <code></param></code>!
'''PHP file:''' For example, get the parameter, named smtpauth, like this:
+
<source lang=php>
+
$lists['smtpauth'] = JHTML::_('select.booleanlist', 'smtpauth', 'class="inputbox"', $row->smtpauth);
+
</source>
+
*Reference: administrator\components\com_config\controllers\application.php, 154
+
  
  
====Section====
+
----
'''Description:''' This parameter shows a drop down list with the sections from your Joomla! site.
+
 
 +
===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:'''
 
'''Screen shot:'''
Line 384: Line 277:
 
[[Image:Params.section.jpg]]
 
[[Image:Params.section.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param name="mysection" type="Section" default="" label="Select a section" description="" /></source>
<param name="section" type="Section" default="" label="Section" description="" />
+
*Name: The name under which the parameter value is stored.
</source>
+
*Name: The name used to implement in the PHP file.
+
*Type: For a section parameter, use 'Section'.
+
 
*Default: The default section.
 
*Default: The default section.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Description: The description displayed as a tooltip.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
'''PHP file:''' For example, get the parameter, named sectionid, like this:
+
<source lang=php>
+
$lists['sectionid'] = JHTML::_('select.genericlist', $sections, 'sectionid',
+
'class="inputbox" size="1" '.$javascript, 'id', 'title', intval($row->sectionid));
+
</source>
+
*Reference: administrator\components\com_content\controller.php, 462
+
  
  
====Spacer====
+
----
'''Description:'''' This parameter shows a separator between the other parameters.
+
 
 +
===Spacer===
 +
'''Description:'''' This provides a separator between parameter entry elements.
  
 
'''Screen shot:'''
 
'''Screen shot:'''
Line 408: Line 294:
 
[[Image:Params.spacer.jpg]]
 
[[Image:Params.spacer.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param type="Spacer" /></source>
<param type="Spacer" />
+
</source>
+
*Type: For a spacer parameter, use 'Spacer'.
+
'''PHP file:''' You can not implement this in your PHP file, it is just a separator, a single line.
+
  
  
====SQL====
+
----
'''Description:''' This parameter creates a drop down list based on the database.
+
 
 +
===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:'''
 
'''Screen shot:'''
Line 423: Line 307:
 
[[Image:Params.sql.jpg]]
 
[[Image:Params.sql.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param name="title" type="SQL" default="" label="Select an article" description="" query="SELECT id, title FROM #__content" /></source>
<param name="title" type="SQL" default="" label="SQL" 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.
</source>
+
*Default: The default value.
*Name: The name used to implement in the PHP file. This should be the same as the label of the query.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Type: For a sql parameter, use 'SQL'.
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
*Default: The default item, use the value from the query to define it.
+
*Query: The MySQL query which provides the data for the drop down box.
*Label: The name displayed at the output of the parameter.
+
 
*Description: The description displayed as a tooltip.
+
*Query: Use any query to the database you want. For example, use 'SELECT':
+
<source lang=xml>query="SELECT value, label FROM #__table"</source>
+
**Replace the 'value' and 'label' by existing columns of your database.
+
**Replace 'table' by a table from the database. Do not add the prefix. For example, jos_categories will become #_categories.
+
'''PHP file:''' For example, get the parameter, named title, like this:
+
<source lang=php>
+
$this->params->get('title')
+
</source>
+
  
 +
----
  
====Text====
+
===Text===
'''Description:''' This parameter shows a text box.
+
'''Description:''' This provides a text box for data entry.
  
 
'''Screen shot:'''
 
'''Screen shot:'''
Line 449: Line 325:
 
[[Image:Params.text.jpg]]
 
[[Image:Params.text.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param name="mytextvalue" type="Text" default="" label="Enter some text" description="" size="10" /></source>
<param name="text" type="Text" default="default" label="Text" description="" size="10" />
+
*Name: The name under which the parameter value is stored.
</source>
+
*Name: The name used to implement in the PHP file.
+
*Type: For a text parameter, use 'Text'.
+
 
*Default: The default text.
 
*Default: The default text.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the text box to indicate the purpose of the parameter.
*Description: The description displayed as a tool tip
+
*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.
+
*Size: The width of the text box in characters.
'''PHP file:''' For example, get the parameter, named count, like this:
+
<source lang=php>
+
$count = intval($params->get('count', 20));
+
</source>
+
*Reference: modules\mod_sections\helper.php, 28
+
  
  
====Text area====
+
----
'''Description:''' This parameter shows a text area.
+
 
 +
===Text area===
 +
'''Description:''' This provides a text area for entry of multi-line text.
  
 
'''Screen shot:'''
 
'''Screen shot:'''
Line 473: Line 343:
 
[[Image:Params.textarea.jpg]]
 
[[Image:Params.textarea.jpg]]
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param name="mytextarea" type="Textarea" default="default" label="Enter some text" description="" rows="10" cols="5" /></source>
<param name="textarea" type="Textarea" default="default"  
+
*Name: The name under which the parameter value is stored.
label="Text area" description="" rows="10" cols="5" />
+
</source>
+
*Name: The name used to implement in the PHP file.
+
*Type: For a text area parameter, use 'Textarea'.
+
 
*Default: The default text.
 
*Default: The default text.
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the text area to indicate the purpose of the parameter.
*Description: The description displayed as a tool tip
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the text area.
*Rows: The number of rows of the text area.
+
*Rows: The height of the visible text area, in lines.
*Cols: The number of columns of the text area.
+
*Cols: The width of the visible text area, in characters.
'''PHP file:''' For example, get the parameter, named area, like this:
+
<source lang=php>
+
$this->params->get('title')
+
</source>
+
  
  
====Time zones====
+
----
'''Description:''' This parameter shows a drop down list with all time zones.
+
 
 +
===Time zones===
 +
'''Description:''' This provides a drop down list of time zones.
  
 
'''Screen shot:'''
 
'''Screen shot:'''
Line 499: Line 363:
  
  
'''XML file:''' Use the following code in the XML file to create a parameter like this:
+
'''XML definition:'''  
<source lang=xml>
+
<source lang=xml><param name="mytimezone" type="Timezones" default="-10" label="Select a timezone" description="" /></source>
<param name="timezones" type="Timezones" default="-10" label="Timezones" description="" />
+
*Name: The name under which the parameter value is stored.
</source>
+
*Name: The name used to implement in the PHP file.
+
*Type: For a time zone parameter, use 'Timezones'.
+
 
*Default: The default time zone. Use for example '-10' for UTC -10:00
 
*Default: The default time zone. Use for example '-10' for UTC -10:00
*Label: The name displayed at the output of the parameter.
+
*Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
*Description: The description displayed as a tool tip
+
*Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
'''PHP file:''' For example, get this and other parameters like this:
+
<source lang=php>
+
$this->params->render( 'params' )
+
</source>
+
*Reference: components\com_user\views\user\tmpl\form.php, 86
+

Revision as of 17:05, 17 March 2008

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.
Copyedit.png
This Page Needs Your Help

This page is tagged because it NEEDS REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.


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:

Params.calendar.jpg

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:

Params.category.jpg

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:

Params.editors.jpg

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:

Params.filelist.jpg

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:

Params.folderlist.jpg

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:

Params.helpsites.jpg

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:

Params.imagelist.jpg

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:

Params.language.jpg

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:

Params.list.jpg

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

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:

Params.menu.jpg

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:

Params.menuitem.jpg

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:

Params.password.jpg

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:

Params.radio.jpg

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:

Params.section.jpg

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:

Params.spacer.jpg

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:

Params.sql.jpg

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:

Params.text.jpg

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:

Params.textarea.jpg

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:

Params.timezones.jpg


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.