Actions

J1.5

Difference between revisions of "Using the core parameter types"

From Joomla! Documentation

m (images)
(50% done)
Line 1: Line 1:
 
{{inuse}}
 
{{inuse}}
I will implement from this GHOP - document:
+
 
http://code.google.com/p/google-highly-open-participation-joomla/issues/detail?id=95
+
When you create an extension (component, module, plugin or template) you can implement parameters in the .XML file. With this parameters you can set options, and use them in the main file, the .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]]
 +
 
 +
== XML file ==
 +
You need an XML file for every extension. It is used mainly to install the extension. A
 +
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:'''
  
 
[[Image:Params.calendar.jpg]]
 
[[Image:Params.calendar.jpg]]
 +
 +
'''XML file:''' Use the following code in the XML file to create a parameter like this.
 +
<source lang=xml><param name="calendar" type="Calendar" default="5-10-2008" label="Calendar"
 +
description="" format="%d-%m-%Y" /></source>
 +
*Name: The name used to implement in the PHP file.
 +
*Type: For a calendar parameter, use 'Calendar'.
 +
*Default: The default date.
 +
*Label: The name displayed at the output of the parameter.
 +
*Description: The description displayed as a tool tip.
 +
*Format: The format of the date.
 +
 +
'''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====
 +
'''Description:''' This parameter shows a drop down list of categories from a section.
 +
 +
'''Screen shot:'''
 +
 
[[Image:Params.category.jpg]]
 
[[Image:Params.category.jpg]]
 +
 +
'''XML file:''' Use the following code in the XML file to create a parameter like this.
 +
<source lang=xml><param name="category" type="Category" label="Category" description="" section="3" />
 +
</source>
 +
*Name: The name used to implement in the PHP file.
 +
*Type: For a category parameter, use 'Category'.
 +
*Label: The name displayed at the output of the parameter.
 +
*Description: The description displayed as a tool tip.
 +
*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====
 +
'''Description:''' This parameter shows a drop down list of the available WYSIWYG editors.
 +
'''Screen shot:'''
 +
 
[[Image:Params.editors.jpg]]
 
[[Image:Params.editors.jpg]]
 +
 +
'''XML file:''' Use the following code in the XML file to create a parameter like this.
 +
<source lang=xml><param name="editors" type="Editors" default="" label="Editors" description="" /></source>
 +
*Name: The name used to implement in the PHP file.
 +
*Type: For an editor parameter, use 'Editor'.
 +
*Default: The default editor.
 +
*Label: The name displayed at the output of the parameter.
 +
*Description: The description displayed as a tool tip.
 +
'''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.
 +
'''Screen shot:'''
 +
 
[[Image:Params.filelist.jpg]]
 
[[Image:Params.filelist.jpg]]
 +
 +
'''XML file:''' Use the following code in the XML file to create a parameter like this.
 +
<source lang=xml><param name="filelist" type="Filelist" default="" label="File list"
 +
description="" directory="" filter="" exclude="" stripext="" /></source>
 +
*Name: The name used to implement in the PHP file.
 +
*Type: For a file list parameter, use 'Filelist'.
 +
*Default: The default file.
 +
*Label: The name displayed at the output of the parameter.
 +
*Description: The description displayed as a tool tip.
 +
*Directory: The directory from which the files should be showed.
 +
**For example “administrator”.
 +
*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.
 +
'''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.
 +
'''Screen shot:'''
 +
 
[[Image:Params.folderlist.jpg]]
 
[[Image:Params.folderlist.jpg]]
[[Image:Params.helpsites.jpg]]
 
[[Image:Params.imagelist.jpg]]
 
[[Image:Params.language.jpg]]
 
[[Image:Params.list.jpg]]
 
[[Image:Params.menu.jpg]]
 
[[Image:Params.menuitem.jpg]]
 
[[Image:Params.password.jpg]]
 
[[Image:Params.radio.jpg]]
 
[[Image:Params.section.jpg]]
 
[[Image:Params.spacer.jpg]]
 
[[Image:Params.sql.jpg]]
 
[[Image:Params.text.jpg]]
 
[[Image:Params.textarea.jpg]]
 
[[Image:Params.timezones.jpg]]
 
  
 +
'''XML file:''' Use the following code in the XML file to create a parameter like this.
 +
<source lang=xml><param name="folderlist" type="Folderlist" default="" label="Folder list" description=""
 +
directory="" filter="" exclude="" stripext="" /></source>
 +
*Name: The name used to implement in the PHP file.
 +
*Type: For a folder list parameter, use 'Folderlist'.
 +
*Default: The default folder.
 +
*Label: The name displayed at the output of the parameter.
 +
*Description: The description displayed as a tool tip.
 +
*Directory: The directory from which the folders should be showed.
 +
**For example “administrator”.
 +
*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.
 +
'''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 of your Joomla! Installation. These can be found at administrator\help\helpsites-15.xml
 +
'''Screen shot:'''
  
 +
[[Image:Params.helpsites.jpg]]
  
==Core XML Parameter Types==
 
XML parameter types allow the user to modify or change certain parts of a template, plugin, module, or component without having to edit any code - as long as these parameters are implemented by the developer of the Joomla! extension.
 
  
===The XML File===
+
'''XML file:''' Use the following code in the XML file to create a parameter like this.
Within every Joomla! extension, there is an XML file used for installation purposes. This file lists all the contents of the package, as well as various items used in the Joomla! extension.
+
<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
  
====Editing the XML File====
 
The XML file will have contents which look similar to this (except filled with the extension's details):
 
<pre>
 
<?xml version="1.0" encoding="utf-8"?>
 
<install type="module" version="1.5.0">
 
<name></name>
 
<author></author>
 
<creationDate></creationDate>
 
<copyright></copyright>
 
<license></license>
 
<authorEmail></authorEmail>
 
<authorUrl></authorUrl>
 
<version></version>
 
<description></description>
 
<files>
 
<filename module="mod_blog_calendar"></filename>
 
</files>
 
<languages>
 
                <language></language>
 
</languages>
 
<params>
 
</params>
 
</install>
 
</pre>
 
  
Find the <code><params></code> tag first. This will be the focus of XML parameters in Joomla!.
+
====Hidden====
 +
'''Description:''' This parameter collects information about the user viewing the parameter section.
 +
'''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.
 +
<source lang=xml><param name="hidden" type="Hidden" value="" /></source>
 +
*Name: The name used to implement in the PHP file.
 +
*Type: For a hidden parameter, use 'Hidden'.
 +
*Value: The data which needs to be collected.
 +
**Two examples:
 +
***Get ID of 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>
 +
'''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
  
==Adding Parameters==
 
After finding the <code><params></code> tag, place an opening (<code><param></code>) and closing (<code></param></code>) tag for the parameter in the Joomla! extension's XML file.
 
  
After placing the opening and closing tags, choose whether you want one of the following types of parameters:
+
====Image list====
 +
'''Description:''' This parameter shows a drop down list with images; .png, .gif, .jpg, .bmp and .ico.
 +
'''Screen shot:'''
  
*List Parameters (parameters are changed in a drop down list)
+
[[Image:Params.imagelist.jpg]]
*Radio Parameters (parameters are changed a check-box style input)
+
*Text Parameters (parameters are changed through direct text input)
+
  
===List Parameters===
+
'''XML file:''' Use the following code in the XML file to create a parameter like this.
List parameters are changed through a drop-down style list. List parameters are useful when there are multiple options or selections available to the end user of a Joomla! extension. To implement List parameters, use the following code in between the <code><params></code> and <code></params></code> tags in the Joomla! extension's XML file:
+
<source lang=xml>
<pre>
+
<param name="imagelist" type="Imagelist" default="" label="Image list"  
<param name="Enter the name of the parameter here" type="list" default="Set the default value for the parameter here" label="Label the parameter here" description="Put a description of the parameter here">
+
description="" directory="" exclude="" stripext="_" /></source>
<option value="Enter a string or integer here">Enter the title of the list item</option>
+
*Name: The name used to implement in the PHP file.
<option value="Enter a string or integer here">Enter the title of the list item</option>
+
*Type: For an image list parameter, use 'Imagelist'.
</param>
+
*Default: The default image.
</pre>
+
*Label: The name displayed at the output of the parameter.
Notice the <code><option></code> tags. These are the selectable items for the end user.
+
*Description: The description displayed as a tooltip.
 +
*Directory: The directory from which the images should be showed.
 +
**For example “images/stories”.
 +
*Exclude: Exclude a certain image name, format or word from showing in the list.
 +
*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
  
===Radio Parameters===
 
Radio parameters are changed through a check-box style selection mechanism. Place the following code in between the <code><params></code> and <code></params></code> tags in the Joomla! extension's XML file (make sure you replace the values with your own preferences):
 
<pre>
 
<param name="Enter the name of the parameter here" type="radio" default="Set the default value for the parameter here" label="Label the parameter here" description="Put a description of the parameter here">
 
    <option value="Enter a string or integer here">Enter the title of the item</option>
 
    <option value="Enter a string or integer here">Enter the title of the item</option>
 
    <option value="Enter a string or integer here">Enter the title of the item</option>
 
</param>
 
</pre>
 
===Text Parameters===
 
Text parameters allow the end user to directly input text instead of picking from pre-defined options. Look at the example below:
 
<pre>
 
<param name="Enter the name of the parameter here" type="text" default="Enter default value" label="Enter the label for the parameter" description="Enter the description of the parameter here" />
 
</pre>
 
  
==Utilizing Core Parameters==
 
Now that the parameters have been added, they need to be used in the Joomla! extension.
 
  
To return the parameter in PHP, use:
 
<pre>
 
$params->get('ParameterName')
 
</pre>
 
  
To return the parameter in html (specific to templates), use:
 
<pre>
 
<? php echo $this->params->get('ParameterName') ?>
 
</pre>
 
  
To use the parameter as a conditional in PHP, use the variable above above with PHP conditional statements as shown below:
 
<pre>
 
if($params->get('cPanelPermissions') == [insert string or integer here]) {
 
    [Do something]
 
};
 
</pre>
 
  
To use the parameter as a conditional in html (specific to templates), use the variable above above with PHP conditional statements as shown below:
+
 
<pre>
+
[[Image:Params.language.jpg]]
<?php
+
[[Image:Params.list.jpg]]
if($this->params->get('cPanelPermissions') == [insert string or integer here]) { ?>
+
[[Image:Params.menu.jpg]]
Do something   
+
[[Image:Params.menuitem.jpg]]
<?php }; ?>
+
[[Image:Params.password.jpg]]
</pre>
+
[[Image:Params.radio.jpg]]
 +
[[Image:Params.section.jpg]]
 +
[[Image:Params.spacer.jpg]]
 +
[[Image:Params.sql.jpg]]
 +
[[Image:Params.text.jpg]]
 +
[[Image:Params.textarea.jpg]]
 +
[[Image:Params.timezones.jpg]]

Revision as of 14:30, 11 February 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.
Quill icon.png
Page Actively Being Edited!

This j1.5 page is actively undergoing a major edit for a short while.
As a courtesy, please do not edit this page while this message is displayed. The user who added this notice will be listed in the page history. This message is intended to help reduce edit conflicts; please remove it between editing sessions to allow others to edit the page. If this page has not been edited for several hours, please remove this template, or replace it with {{underconstruction}} or {{incomplete}}.

When you create an extension (component, module, plugin or template) you can implement parameters in the .XML file. With this parameters you can set options, and use them in the main file, the .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

Contents

XML file

You need an XML file for every extension. It is used mainly to install the extension. A particular XML file looks like this:

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

Parameters

The parameters should be placed between the <params> and </params> tags. You can also add groups. For example, the 'Advanced' group. This will look like this:

<params>
'Normal' parameters
</params>
<params group="advanced">
Advanced parameters
</params>

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:

Params.calendar.jpg

XML file: Use the following code in the XML file to create a parameter like this.

<param name="calendar" type="Calendar" default="5-10-2008" label="Calendar" 
description="" format="%d-%m-%Y" />
  • Name: The name used to implement in the PHP file.
  • Type: For a calendar parameter, use 'Calendar'.
  • Default: The default date.
  • Label: The name displayed at the output of the parameter.
  • Description: The description displayed as a tool tip.
  • Format: The format of the date.

PHP file: For example, get the parameter, named publish_up, like this:

$publish_up = new JDate($row->publish_up);
  • Reference: administrator\components\com_content\admin.content.html.php, 122-168


Category

Description: This parameter shows a drop down list of categories from a section.

Screen shot:

Params.category.jpg

XML file: Use the following code in the XML file to create a parameter like this.

<param name="category" type="Category" label="Category" description="" section="3" />
  • Name: The name used to implement in the PHP file.
  • Type: For a category parameter, use 'Category'.
  • Label: The name displayed at the output of the parameter.
  • Description: The description displayed as a tool tip.
  • Section: The section ID number, can be found in the Section Manager.

PHP file: For example, get use the parameter, named category, like this:

$category[$section->id][]
  • Reference: administrator\components\com_content\controller.php, 452-530


Editors

Description: This parameter shows a drop down list of the available WYSIWYG editors. Screen shot:

Params.editors.jpg

XML file: Use the following code in the XML file to create a parameter like this.

<param name="editors" type="Editors" default="" label="Editors" description="" />
  • Name: The name used to implement in the PHP file.
  • Type: For an editor parameter, use 'Editor'.
  • Default: The default editor.
  • Label: The name displayed at the output of the parameter.
  • Description: The description displayed as a tool tip.

PHP file: For example, get the parameter, named editors, like this:

$this->lists['Editors']
  • 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. Screen shot:

Params.filelist.jpg

XML file: Use the following code in the XML file to create a parameter like this.

<param name="filelist" type="Filelist" default="" label="File list" 
description="" directory="" filter="" exclude="" stripext="" />
  • Name: The name used to implement in the PHP file.
  • Type: For a file list parameter, use 'Filelist'.
  • Default: The default file.
  • Label: The name displayed at the output of the parameter.
  • Description: The description displayed as a tool tip.
  • Directory: The directory from which the files should be showed.
    • For example “administrator”.
  • 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.

PHP file: For example, get the parameter, named editors, like this:

$params->get('ParameterName')

Folder list

Description: This parameter shows a drop down list of folders from a certain directory. Screen shot:

Params.folderlist.jpg

XML file: Use the following code in the XML file to create a parameter like this.

<param name="folderlist" type="Folderlist" default="" label="Folder list" description="" 
directory="" filter="" exclude="" stripext="" />
  • Name: The name used to implement in the PHP file.
  • Type: For a folder list parameter, use 'Folderlist'.
  • Default: The default folder.
  • Label: The name displayed at the output of the parameter.
  • Description: The description displayed as a tool tip.
  • Directory: The directory from which the folders should be showed.
    • For example “administrator”.
  • 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.

PHP file: For example, get the parameter, named headerColor, like this:

$this->params->get('headerColor','green')
  • Reference: administrator\templates\khepri\cpanel.php, 45


Help sites

Description: This parameter shows a drop down list of the help sites of your Joomla! Installation. These can be found at administrator\help\helpsites-15.xml Screen shot:

Params.helpsites.jpg


XML file: Use the following code in the XML file to create a parameter like this.

<param name="helpsites" type="Helpsites" default="local" label="Help sites" description="" />
  • 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:

$this->params->get('helpsites','local')
  • Reference: administrator\components\com_config\controllers\application.php, 90-94


Hidden

Description: This parameter collects information about the user viewing the parameter section. 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.

<param name="hidden" type="Hidden" value="" />
  • Name: The name used to implement in the PHP file.
  • Type: For a hidden parameter, use 'Hidden'.
  • Value: The data which needs to be collected.
    • Two examples:
      • Get ID of user:
        value="<?php echo $this->user->get('id'); ?>"
        
      • Get filter order:
        value="<?php echo $this->lists['order']; ?>"
        

PHP file: For example, get the parameter, named id, like this:

$user->get('id')
  • Reference: administrator\components\com_users\views\user\view.html.php, 52-76


Image list

Description: This parameter shows a drop down list with images; .png, .gif, .jpg, .bmp and .ico. Screen shot:

Params.imagelist.jpg

XML file: Use the following code in the XML file to create a parameter like this.

<param name="imagelist" type="Imagelist" default="" label="Image list" 
description="" directory="" exclude="" stripext="_" />
  • Name: The name used to implement in the PHP file.
  • Type: For an image list parameter, use 'Imagelist'.
  • Default: The default image.
  • Label: The name displayed at the output of the parameter.
  • Description: The description displayed as a tooltip.
  • Directory: The directory from which the images should be showed.
    • For example “images/stories”.
  • Exclude: Exclude a certain image name, format or word from showing in the list.
  • Stripext: Strip these characters.

PHP file: For example, get the parameter, named image, like this:

JHTML::_('list.images', 'image', $row->image );
  • Reference: administrator\components\com_categories\admin.categories.php, 386




Params.language.jpg Params.list.jpg Params.menu.jpg Params.menuitem.jpg Params.password.jpg Params.radio.jpg Params.section.jpg Params.spacer.jpg Params.sql.jpg Params.text.jpg Params.textarea.jpg Params.timezones.jpg