J1.5:Template parameters

The "J1.5" namespace is an archived namespace. This page contains information for a Joomla! version which is no longer supported. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

The template system has always been one of Joomla's most powerful features, but prior to Joomla 1.5 it was difficult for web design companies to ship templates with much in the way of built-in flexibility. For example, a template available in a variety of different colour schemes would often be supplied as a suite of separate template files. Some web design companies created their own methods for allowing the site administrator to change colour schemes and other template features in the Administrator, but these methods were not standardised and often involved the site administrator in editing configuration files by hand, or installing a custom component to manage the template.

This all changed with the advent of Joomla 1.5 which supported the idea of template parameters. Actually it would be more accurate to call them extension parameters as the implementation is generic for all extension types: components, modules, plugins and templates. In this chapter you will learn about how to create and use parameters in your template designs. Each of the wide range of parameter types directly supported by the Joomla Framework is described in detail, but you will also learn how to create your own custom parameter types to suit your particular needs. There is also a short reference on regular expressions as they are used in some of the template parameter types.

Introduction to template parameters

To see an example of template parameters in action, go into Extensions → Template Manager and click on the rhuk_milkyway template. You will see, on the Template: [Edit] screen that there is a Parameters group containing a couple of fields called Colour Variation and Background Variation. See illustration below. These are typical template parameters and in this case they control the colour scheme of the template.

Template parameters allow the administrator to adjust the behaviour of a template using a form in the Administrator. What parameters are available and what they do is down to the template designer, but designers now have a set of easy-to-use tools for building flexibility into their templates. For the designer, this involves making changes to three elements:

• Adding a <param> element to the <params> section of the templateDetails.xml file.
• Adding a line to a params.ini file which will hold the current value of the parameter.
• Adding code to the template PHP file to retrieve the current value of the parameter and act on it.

Defining a parameter in templateDetails.xml

The templateDetails.xml file is always located in the root directory for the template. For example, for the Beez template the full path will look like:

[path-to-Joomla]/templates/beez/templateDetails.xml

Note that letter case is important on case-sensitive operating systems such as Linux. You can use a standard text editor (not a word processor) or an XML editor to make changes to this file.

Locate the <params> element, generally towards the end of the file. If there is no <params> element you will need to add one. This must be immediately beneath the <install> element in the XML element hierarchy. Don't forget to close the element with a </params> tag. Note that for Joomla 1.6 onwards the <install> tag is deprecated in favour of <extension>.

• See Creating a basic templateDetails.xml file for an introduction to creating a templateDetails.xml file from scratch.
• See Specification of templateDetails.xml for a detailed specification of this file.

For each parameter that you want to define, add a <param> element. This element takes a number of mandatory and optional arguments that depend on the type argument. The only truly mandatory argument is type, but name, default, description and label are common to most parameter types and name is mandatory whenever it occurs. These mandatory/common arguments are:

• type specifies the type of HTML form control used in the Template Parameters screen in the Administrator to allow the user to change the value of the parameter.
• name is the unique name of the parameter. You will refer to this name when retrieving the parameter value in the template code.

The following arguments are optional but are common to almost all parameter types:

• default is the default value of the parameter.
• description is text that will be displayed as a tooltip for the field in the Template Parameters screen in the Administrator. This is a translatable string; see Template Translations for information on how to add language translations of this string.
• label is the descriptive title of the field which will be shown to the user in the Template Parameters screen in the Administrator. This is a translatable string; see Template Translations for information on how to add language translations of this string. If the label argument is omitted it will default to the value given by the name argument.

The optional arguments depend on the parameter type. Each of the parameter types is described in detail in J1.5:Standard parameter types. If you are a developer it is also possible to create your own custom parameter types; see J1.5:Creating_custom_template_parameter_types for more information.

For example, the following extract shows a <params> section defining two parameters; one for a drop-down list of template colour variations, the other for a radio button which will allow the user to show or hide an author copyright message.

<params>
    <param name="templateColour" type="list" default="blue" 
            label="Template Colour" description="Choose the template colour.">
        <option value="blue">Blue</option>
        <option value="red">Red</option>
        <option value="green">Green</option>
        <option value="black">Black</option>
    </param>
    <param name="authorCopyright" type="radio" default="1" 
            label="Author Copyright" description="Show/Hide author copyright.">
        <option value="0">hide</option>
        <option value="1">show</option>
    </param>
</params>

The Template Parameters screen for this example will look like this:

Note: Parameter groups are not currently supported in template parameters.

Tip: To include HTML tags in XML arguments you must encode certain special characters as follows:

Character	Description	Encoding
&	Ampersand	&
“	Double quote	"
'	Single quote	'
<	Less than	&lt;
>	Greater than	&gt;

Standard parameter types

There are 21 different standard parameter types supported in the Joomla Framework for all extension types (templates, components, modules and plugins). This section gives a brief description of each parameter type, in alphabetical order. Full details of each parameter type are given on the following pages.

• calendar provides a text box for entry of a date. 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.
• category provides a drop down list of categories from a given section.
• editors provides a drop down list of the available WYSIWYG editors.
• filelist provides a drop down list of files from a specified directory.
• folderlist provides a drop down list of folders from a specified directory.
• helpsites provides a drop down list of the help sites for your Joomla installation.
• hidden provides a hidden field for saving a parameter whose value cannot be altered directly by a user in the Administrator (it can be altered in code or by editing the params.ini file).
• imagelist provides a drop down list of image files in a specified directory.
• languages provides a drop down list of the installed languages for the Front-end or Back-end.
• list provides a drop down list of custom-defined entries.
• menu provides a drop down list of the available menus from your Joomla site.
• menuitem provides a drop down list of the available menu items from your Joomla site.
• password provides a text box for entry of a password. The password characters will be obscured as they are entered.
• radio provides radio buttons to select different options.
• spacer provides a visual separator between parameter field elements. It is purely a visual aid and no parameter value is stored.
• sql 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.
• text provides a text box for data entry.
• textarea provides a text area for entry of multi-line text.
• timezones provides a drop down list of time zones.
• usergroup provides a drop down list of user groups.

Standard parameter types in detail

Calendar parameter type

The calendar parameter type provides a text box for entry of a date. 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. If the parameter has a saved value this is shown in the text box. Otherwise the default value, if any, is displayed.

• type (mandatory) must be calendar.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default date. This must be given in the same format as specified by the format argument. You can put "NOW" to have current time.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the text box.
• format (optional) is the date format to be used. This is in the format used by PHP to specify date string formats (see below). If no format argument is given, '%Y-%m-%d' is assumed (giving dates like '2008-04-16').
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.

Example XML parameter definition:

<param name="mycalendar" type="calendar" default="5-10-2008" label="Select a date" description="" format="%d-%m-%Y" />

The format field specifies the format that the date string will be saved in. It is also the format that manually entered dates need to be enterered in; except that the punctuation character is ignored. The coding scheme used to specify date formats is the same as the PHP date string format, full details of which can be found on http://www.php.net/manual/en/function.date.php. The following are some of the most frequently used date string codes:

Character	Description	Example
d	Day of the month, 2 digits with leading zeros	01 to 31
D	A textual representation of a day, three letters	Mon through Sun
j	Day of the month without leading zeros	1 to 31
l	A full textual representation of the day of the week	Monday through Sunday
N	ISO-8601 numeric representation of the day of the week (only supported on servers running PHP 5.1.0 or later)	1 (for Monday) through 7 (for Sunday)
S	English ordinal suffix for the day of the month, 2 characters	st, nd, rd or th. Works well with j
w	Numeric representation of the day of the week	0 (for Sunday) through 6 (for Saturday)
z	The day of the year (starting from 0)	0 through 365
W	ISO-8601 week number of year, weeks starting on Monday	42 (42nd week in the year)
F	A full textual representation of a month	January through December
m	Numeric representation of a month, with leading zeros	01 through 12
M	A short textual representation of a month, three letters	Jan through Dec
n	Numeric representation of a month, without leading zeros	1 through 12
t	Number of days in the given month	28 through 31
o	ISO-8601 year number. Same value as Y except that if the ISO week number (W) belongs to the previous or next year, that year is used instead (only supported on servers running PHP 5.1.0 or later)	1999 or 2003
Y	A full numeric representation of a year, 4 digits	1999 or 2003
y	A two-digit representation of a year	99 or 03
a	Lowercase Ante Meridiem or Post Meridiem	am or pm
A	Uppercase Ante Meridiem or Post Meridiem	AM or PM

Note: The format in which dates are stored in the params.ini file is that specified by the format argument. Since there can be language-dependent elements to this format (for example, the '%F' specifier), you need to be careful not to use such elements if there is a possibility that the front-end and back-end languages may be different.

Note: The calendar parameter type does not support non-Gregorian calendars. If you need to support non-Gregorian calendars then you will need to create a custom parameter type to support your calendar.

Category parameter type

The category parameter type provides a drop down list of published categories from a given section. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected. The first option on the list is always '- Select Category -' (which is a translatable string) and is given the value 0.

Note that categories will still be shown in the drop-down list even if the section they belong to is not published. This is to make it possible to build draft content areas without having to first publish a section.

• type (mandatory) must be category.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• section (optional) is the ID number of the section from which the categories in the list are drawn. The section ID number can be found in the Section Manager. If omitted, all published categories in all sections will be listed.
• scope (optional) is an alias for section.
• default (optional) is the default category ID number.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.

Example XML parameter definition:

<param name="mycategory" type="category" label="Select a category" description="" section="3" />

Editors parameter type

The editors parameter type provides a drop down list of the available and enabled WYSIWYG editors. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

The first option on the list is always '- Select Editor -' (which is a translatable string) and is given the value 0.

• type (mandatory) must be editors.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default editor name. This is the name listed in the File column in the Plugin Manager screen.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<param name="myeditor" type="editors" default="none" label="Select an editor" />

Filelist parameter type

The filelist parameter type provides a drop down list of files from a specified directory. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

By default, the first item on the list is '- Do not use -' (which is translatable) and is given the value '-1' and this is followed by '- Use default -' (also translatable) given the value '0'.

• type (mandatory) must be filelist.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• directory (optional) is the filesystem path to the directory containing the files to be listed. If omitted the directory given by JPATH_ROOT is assumed.
• default (optional) is the default file name.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• filter (optional) is a regular expression string which is used to filter the list of files selected for inclusion in the drop-down list. If omitted, all files in the directory are included. The filter argument expression is applied before the exclude argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• exclude (optional) is a regular expression string which is used to exclude files from the list. The exclude argument expression is applied after the filter argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• stripext (optional) is a Boolean argument. If true then file name extensions will be stripped from the file names listed. Also note that the file name will be saved without the extension too.
• hide_none (optional) is a Boolean argument. If true, the '- Do not use -' item is omitted from the drop-down list.
• hide_default (optional) is a Boolean argument. If true, the '- Use default -' item is omitted from the drop-down list.

Example XML parameter definition:

<param name="myfile" type="filelist" default="" label="Select a file" description="" directory="administrator" filter="" exclude="" stripext="" />

Folderlist parameter type

The folderlist parameter type provides a drop down list of folders from a specfied directory. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

By default, the first item on the list is '- Do not use -' (which is translatable) and is given the value '-1' and this is followed by '- Use default -' (also translatable) given the value '0'.

• type (mandatory) must be folderlist.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• directory (mandatory) is the filesystem path to the directory containing the folders to be listed.
• default (optional) is the default folder name.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• filter (optional) is a regular expression string which is used to filter the list of folders selected for inclusion in the drop-down list. If omitted, all folders in the directory are included. The filter argument expression is applied before the exclude argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• exclude (optional) is a regular expression string which is used to exclude folders from the list. The exclude argument expression is applied after the filter argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• hide_none (optional) is a Boolean argument. If true, the '- Do not use -' item is omitted from the drop-down list.
• hide_default (optional) is a Boolean argument. If true, the '- Use default -' item is omitted from the drop-down list.

Example XML parameter definition:

<param name="myfolder" type="folderlist" default="" label="Select a folder" directory="administrator" filter="" exclude="" stripext="" />

Helpsites parameter type

The helpsites parameter type provides a drop down list of the help sites in your Joomla installation. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected. With the exception of the “Local” entry, which is always added, the list of help sites is generated from the file:

[path-to-Joomla]/administrator/help/helpsites-15.xml

The 'local' string is translatable. The 'local' URL returned is an empty string.

• type (mandatory) must be helpsites.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default help site URL (not the visible help site name).
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<param name="myhelpsite" type="helpsites" default="" label="Select a help site" description="" />

Hidden parameter type

The hidden parameter type provides a hidden field for saving a parameter whose value cannot be altered directly by a user in the Administrator (it can be altered in code or by editing the params.ini file). If the parameter has a saved value this is entered in the text box. If not, the default value (if any) is entered. As the field is hidden there is no visible field in the Administrator.

• type (mandatory) must be hidden.
• name (mandatory) is the unique name of the parameter.
• default (mandatory) is the data which needs to be collected.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.

Example XML parameter definition:

<param name="mysecretvariable" type="hidden" default="" />

Imagelist parameter type

The imagelist parameter type provides a drop down list of image files in a specified directory. Only files with .png, .gif, .jpg, .bmp, .ico extensions are listed. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

By default, the first item on the list is '- Do not use -' (which is translatable) and is given the value '-1' and this is followed by '- Use default -' (also translatable) given the value '0'.

• type (mandatory) must be imagelist.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• directory (optional) is the filesystem path to the directory containing the image files to be listed. If omitted the directory given by JPATH_ROOT is assumed.
• default (optional) is the default image file name.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• filter (optional) is a regular expression string which is used to filter the list of image files selected for inclusion in the drop-down list. If omitted, all image files in the directory are included. The filter argument expression is applied before the exclude argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• exclude (optional) is a regular expression string which is used to exclude image files from the list. The exclude argument expression is applied after the filter argument expression. For information on constructing regular expressions see Regular expressions in parameter arguments.
• stripext (optional) is a Boolean argument. If true then file name extensions will be stripped from the image file names listed. Also note that the file name will be saved without the extension too.
• hide_none (optional) is a Boolean argument. If true, the '- Do not use -' item is omitted from the drop-down list.
• hide_default (optional) is a Boolean argument. If true, the '- Use default -' item is omitted from the drop-down list.

Example XML parameter definition:

<param name="myimage" type="imagelist" default="" label="Select an image" description="" directory="" exclude="" stripext="" />

Languages parameter type

The languages parameter type provides a drop down list of the installed languages for the Front-end or Back-end. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected. The value saved is the language tag. For example, for English (United Kingdom) this will be 'en-GB'.

The first option on the list is always '- Select Language -' (which is a translatable string) and is given the value 0.

• type (mandatory) must be languages.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• client (mandatory) is the application whose installed languages will be listed. Use site when you want to list the Front-end languages or administrator when you want to list the Back-end languages.
• default (optional) is the default language tag. For example, 'en-GB'.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<param name="mylanguage" type="languages" client="site" default="en-GB" label="Select a language" description="" />

List parameter type

The list parameter type provides a drop down list of custom-defined entries. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be list.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default list item value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.

The XML <param> element must include one or more <option> elements which define the list items. The text between the <option> and </option> tags is what will be shown in the drop down list and is a translatable string. The <option> tag takes the following argument:

• value (mandatory) is the value that will be saved for the parameter if this item is selected.

Tip: Don't forget to close the parameter definition with </param>.

Example XML parameter 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>

Menu parameter type

The menu parameter type provides a drop down list of the available menus from your Joomla site. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

The first option on the list is always '- Select Menu -' (which is a translatable string) and is given the value 0.

• type (mandatory) must be menu.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default menu. Note that this is the name of the menu shown in the Type column on the Menu Manager screen and not the menu ID number.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<param name="mymenu" type="menu" default="mainmenu" label="Select a menu" description="Select a menu" />

Menuitem parameter type

The menuitem parameter type provides a drop down list of the available menu items from your Joomla site.

The first option on the list is always '- Select Item -' (which is a translatable string) and is given the value 0.

The first item on the list will always have the ' - Top' (which is a translatable string) appended to it.

• type (mandatory) must be menuitem.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default menu item. Note that this is the ItemID number of the menu item.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• state (optional) determines whether all menu items are listed or only published menu items. If state is '0' then all menu items will be listed. If state is '1' then only published menu items will be listed.

Example XML parameter definition:

<param name="mymenuitem" type="menuitem" default="45" label="Select a menu item" description="Select a menu item" />

Password parameter type

The password parameter type provides a text box for entry of a password. The password characters will be obscured as they are entered. If the parameter has a saved value this is entered (in obscured form) into the text box. If not, the default value (if any) is entered.

Note that the password string is stored in params.ini in cleartext; the stored value is not obscured by any hash function. Since most web servers will, by default, serve a params.ini file if the URL is entered in a web browser, this cannot be considered a secure method of holding a password.

• type (mandatory) must be password.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• size (optional) is the width of the text box in characters. If omitted the width is determined by the browser. The value of size does not limit the number of characters that may be entered.
• default (optional) is the default password.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.

Example XML parameter definition:

<param name="mypassword" type="password" default="secret" label="Enter a password" description="" size="5" />

Radio parameter type

The radio parameter type provides radio buttons to select different options. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be radio.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) is the default radio button item value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

The XML <param> element must include one or more <option> elements which define the individual radio button items. The text between the <option> and </option> tags is shown as the label for the radio button and is a translatable string. The <option> tag takes the following argument:

• value (mandatory) is the value that will be saved for the parameter if this item is selected.

Tip: Don't forget to close the parameter definition with </param>.

Example XML parameter definition:

<param name="myradiovalue" type="radio" default="0" label="Select an option" description="">
  <option value="0">1</option>
  <option value="1">2</option>
</param>

Section parameter type

---

The section parameter type provides a drop down list of the published 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.

The first option on the list is always '- Select Section -' (which is a translatable string) and is given the value 0.

• type (mandatory) must be section.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) (translatable) is the default section ID number.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<param name="mysection" type="section" default="" label="Select a section" description="" />

Spacer parameter type

The spacer parameter type provides a visual separator between parameter field elements. It is purely a visual aid and no parameter value is stored.

• type (mandatory) must be spacer.
• default (optional) (translatable) is a string which will be used instead of the <hr /> that is inserted by default.

Example XML parameter definition:

<param type="spacer" />

You can replace the basic horizontal line with a title which can be used to group parameters. For example,

<param type="spacer" default="Advanced parameters" />

Note that you can also include HTML markup but it must be encoded. For example, to put the text into bold you can use:

<param type="spacer" default="&lt;b&gt;Advanced parameters&lt;/b&gt;" />

Sql parameter type

The sql parameter type provides a drop down list of entries obtained by running a query on the Joomla database. 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.

• type (mandatory) must be sql.
• name (mandatory) is the unique name of the parameter. This must match the name of the query results column that contains the values that will be shown to the user in the drop-down list, unless a different name is specified in the value_field attribute.
• label (mandatory) (translatable) is the descriptive title of the field.
• query (mandatory) is the SQL query which will provide the data for the drop-down list. The query must return two columns; one called 'value' (unless overridden by the key_field attribute) which will hold the values of the list items; the other called the same as the value of the name attribute (unless overridden by the value_field attribute) containing the text to be shown in the drop-down list.
• default (optional) is the default value. This is the value of the 'value' field, unless overridden by the key_field attribute.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• key_field (optional) is the name of the column that will contain values for the parameter. If omitted then the column called 'value' will be used, if it exists.
• value_field (optional) is the name of the column that will contain values to be shown to the user in the drop-down list. If omitted then the column with the same name as the name attribute will be used, if it exists.

Example XML parameter definition:

<param name="title" type="sql" default="10" label="Select an article" query="SELECT id AS value, title FROM #__content" />

Notice that an AS clause has been used in this example because the jos_content table does not have a column called 'value'. In fact very few tables in the Joomla database have a column called 'value'. Alternatively, you can use a key_field attribute to define the column to be instead of 'value':

<param name="title" type="sql" default="10" label="Select an article" query="SELECT id, title FROM #__content" key_field="id" />

This will give identical results to the previous example.

Both column names may need to be aliased. For example, suppose you want your field to be called 'myfield' instead of 'title' in the previous example. Then you can do this:

<param name="myfield" type="sql" default="10" label="Select an article" query="SELECT id AS value, title AS myfield FROM #__content" />

Or alternatively:

<param name="myfield" type="sql" default="10" label="Select an article" query="SELECT id, title FROM #__content" key_field="id" value_field="title" />

You can also assemble or calculate fields in the SQL statement. For example, suppose you wanted to append the created date/time of each article to the article title in the list. Then you could use this SQL statement:

SELECT id, concat( title, ' (', created, ')') AS title FROM #__content

Note: The SQL statements will need to be correct for the type and version of the underlying database that Joomla is running on. This will most likely be a version of MySQL, but it could be something else. There is no capability to query databases other than the one Joomla itself is running on.

Note: As shown in these examples, the database prefix can be entered in the form '#_' (hash-underscore), in which case it will automatically be replaced by the database prefix used by Joomla.

Text parameter type

The text parameter type provides a text box for data entry. If the parameter has a value saved, this value is displayed when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be text.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• size (optional) is the width of the text box in characters. If omitted the width is determined by the browser. The value of size does not limit the number of characters that may be entered.
• default (optional) (not translatable) is the default value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.

Example XML parameter definition:

<param name="mytextvalue" type="text" default="Some text" label="Enter some text" description="" size="10" />

Textarea parameter type

The textarea parameter type provides a text area for entry of multi-line text. If the parameter has a value saved, this value is displayed when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be textarea.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• rows (mandatory) is the height of the visible text area in lines. If omitted the width is determined by the browser. The value of rows does not limit the number of lines that may be entered.
• cols (mandatory) is the width of the visible text area in characters. If omitted the width is determined by the browser. The value of cols does not limit the number of characters that may be entered.
• default (optional) (not translatable) is the default value.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
• class (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.

Example XML parameter definition:

<param name="mytextarea" type="textarea" default="default" label="Enter some text" description="" rows="10" cols="5" />

Timezones parameter type

The timezones parameter type provides a drop down list of time zones. If the parameter has a value saved, this value is displayed when the page is first loaded. If not, the default value (if any) is selected.

• type (mandatory) must be timezones.
• name (mandatory) is the unique name of the parameter.
• label (mandatory) (translatable) is the descriptive title of the field.
• default (optional) (translatable) is the default time zone. For example, use '-10' for '(UTC -10:00) Hawaii'.
• description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.

Example XML parameter definition:

<param name="mytimezone" type="timezones" default="-10" label="Select a timezone" description="" />

Storing parameter values

The current values of the template parameters are stored in the file [path-to-Joomla]/templates/[template-name]/params.ini

If your template has parameters and you intend to create an installer package for it, then you should add this file to the <files> section of the templateDetails.xml file.

<files>
        ........

        <filename>params.ini</filename>

        ........

</files>

The installer will ensure that the params.ini file has the correct ownership and permissions and so is writeable.

The params.ini file distributed in a template installer package can actually be empty as the default values of the parameters can be set in the <param> elements in the templateDetails.xml file. The presence of the empty file during template installation just ensures that it is writeable. However, if you want to distribute a params.ini file with the default parameter values set in it, this is a simple procedure for creating one:

1. On your test system, create an empty params.ini file, making sure that it is writeable by the web server.
2. Log in to the Administrator back-end and go to the Template Parameters screen for your template.
3. Set all the parameters to the values that you want as the defaults.
4. Click Save.
5. Take a copy of your params.ini file to put into the template package. This now contains all the default parameter values.

Alternatively, as the format is very simple, you can create a params.ini file by hand. It is in standard INI file format with one parameter per line. The parameter name and its value are separated by an equals sign. For example:

templateColour=blue
authorCopyright=1

Retrieving parameter data in a template file

Having defined a parameter in the templateDetails.xml file and saved a value for it in the params.ini file, it remains to be seen how to retrieve the current value of the parameter so it can be used in the template code.

To retrieve the value of a parameter in your template code use the function call:

<?php $myParam = $this->params->get( 'parameterName' ); ?>

Note that the $this object in the template is always the current instance of the JDocument object. Also note that $this->params is an object of type JParameter.

For example, suppose your template has a parameter called templateColour which takes various string values which determine the colour scheme to be used. The colour schemes themselves are defined in CSS files which include the colour name as part of their file names. The following code retrieves the parameter then adds the appropriate stylesheet to render the page in the required colour scheme.

<?php
$tplColour = $this->params->get( 'templateColour' );
$this->addStyleSheet( $this->baseurl  . '/templates/'
                    . $this->template . '/css/' . $tplColour .'.css' );
?>

For another example, suppose your template has a parameter called authorCopyright which takes the value 0 to hide a copyright notice, or 1 to show it. The following code retrieves the parameter then outputs the copyright notice within a conditional PHP statement:

<?php if ($this->params->get( 'authorCopyright' )) : ?>   
     <div class="copyright">
         Copyright &copy; 2008 Fat Pigeon Templates
     </div>
<?php endif; ?>

Creating custom XML parameter types

It is possible to extend the parameter types that Joomla can support beyond the standard types available in a default installation. To understand how to do this, first look at how the standard types are implemented.

Location of standard parameter types code

The code for the standard parameter types can be found in the directory

[path-to-Joomla]/libraries/joomla/html/parameter/element/

Each parameter type is defined in a separate file which must have the same name as the parameter type. For example, the category type is coded in

[path-to-Joomla]/libraries/joomla/html/parameter/element/category.php

This file contains a single class, called JElementCategory which extends JElement. The naming of files and classes used here is not merely convention. The file must have the same name as the parameter type and it must contain a class called JElement<nowiki>[element-name] otherwise the Joomla Framework will not be able to recognise and support the parameter type.

Starting a new custom parameter type

To create a custom parameter type you first need to choose a name for it. Suppose you want to call it newparm. Then you will create a new file called newparm.php containing a single class, called JElementNewparm which extends JElement.

The code for the new parameter can exist almost anywhere but it should always be placed in a sub-directory on its own or with the code for other custom parameter types.

The new parameter type will most likely be associated with a particular extension, in which case you will want to bundle the code for the parameter type with the code for the extension.

Where you put this file is somewhat flexible and depends to some degree on the type of extension you are developing. For templates it is recommended that you place it here

path-to-Joomla]/templates/[template-name]/elements/newparm.php

Changes to the XML file for custom parameter types

You need to make two specific amendments to the XML configuration file. First, you need to ensure that the file is included in the <files> list:

<files>
    ........
    <filename>elements/index.html</filename>
    <filename>elements/newparm.php</filename>
    ........
</files>

Tip: It is good practice to also include an empty index.html file in the elements directory as an extra security precaution to prevent directory listings being returned by the web server.

Alternatively, you can simply include the entire elements directory using a <folders> element:

<files>
    ........
    <folder>elements</folder>
    ........
</files>

The second amendment that you need to make to the XML configuration file is to let the Joomla Framework know that you have added a new parameter type and where to find the code to support it. To do this you add an addpath argument to the <params> tag:

<params addpath=”[path]/elements”>
   ...... list of <param> elements ......
</params>

Notice that you are adding a path to a directory containing the parameter type code, not to the code file itself. Notice also that you only have one addpath argument so if you are adding multiple parameter types you need to gather them into the same sub-directory and that sub-directory must contain only parameter type definition code.

For example, this would be a typical <params> element in a templeDetails.xml file:

<params addpath=”[path-Joomla]/templates/mytemplate/elements”>
    <param type=”newparm” name=”setting1” default=”12” />
    <param type=”text” name=”setting2” value=”Some text” />
</params>

Coding a custom parameter type

The easiest way to write the code for a new parameter type is to take the code for an existing parameter type that is similar to what you want to create and adapt it to suit your requirements. The base JElement class contains most of what you need and for most parameter types you will only need to override the fetchElement method in your extension class.

The fetchElement method returns the HTML code required to render the field that will be used to enter a value for the parameter. It takes four arguments:

fetchElement( $name, $value, &$node, $control_name )

where:

$name	is the unique name of the parameter, from the name argument.
$value	is the current value of the parameter.
$node	is a JSimpleXMLElement object representing the <param> element.
$control_name	is the parameter type from the type argument (eg. 'category' or 'newparm')

To obtain the value of an argument in the <param> element you use the attribute method of the JSimpleXMLElement object passed in $node. For example, to obtain the value of the class argument you could use code like this

$class = $node->attributes( 'class' );

For example, here is the fetchElement method for a simple version of the text parameter type (the actual version is more sophisticated):

function fetchElement( $name, $value, &$node, $control_name )
{ 
    $class = $node->attributes( 'class' ) ? $node->attributes( 'class' ) : "text_area";

    $return = '<input type="text"' .
                     'name="' . $control_name . '[' . $name . ']"' .
                     'id="'   . $control_name . '[' . $name . ']"' .
                     'value="' . $value . '"' .
                     'class="' . $class . '" />'; 
    return $return;
}

Notice that the parameter field must have an id attribute, with the value shown in this example, so that the <label> HTML element produced by the default fetchTooltip method will match with it correctly.

The only other method from JElement that you might conceivably want to override is the fetchTooltip method. This method returns the HTML code required to render a tooltip for the field. In most cases the default code will be entirely suitable and you will not need to override this method. It takes five arguments:

fetchTooltip( $label, $description, &$node, $control_name=,$name= )

where:

$label	is the string given in the label argument of the <param> definition. It should be passed through the language translation system before being used.
$description	is the string given in the description argument of the <param> definition. It should be passed through the language translation system before being used.
$node	is a JSimpleXMLElement object representing the <param> element.
$control_name	is the parameter type from the type argument (eg. 'category' or 'newparm').
$name	is the unique name of the parameter, from the name argument.

To pass a string through the language translation system you just need to use the JText static class like this

$output = JText::_( 'string to be translated' );

Regular expressions in parameter arguments

Some parameter arguments take regular expressions as values. For example, the filter and exclude arguments for the filelist and imagelist parameter types. This is enormously powerful, but it requires you to know at least a little regular expression syntax to be able to use it effectively.

Described here are some examples of simple regular expressions that you might want to use in the context of template parameters. A complete reference to regular expression syntax is beyond the scope of this book, but can be found online at http://www.php.net/manual/en/book.pcre.php

Simple filter string

Suppose you want to use the filelist parameter type to list the files in a given directory. There are many files in the directory but you only want those with a '.php' extension to be listed. Then you would use this argument in the <param> element

filter = “\.php”

The first thing to note is the leading backslash character. This is needed because the “.” character has a special meaning in regular expressions and that is not what is intended here. The backslash character tells the regular expression parser to treat the next character (which is the “.”) as just an ordinary character and not to give it the special meaning that it normally does.

The effect of this filter string is to only include those files that have the characters “.”, “p”, “h” and “p”, in that order, anywhere in the file name.

Anchoring to the end of the string

In the above example, if there is a file called configuration.php-dist then it would be included in the list because “.php” occurs in the middle of the string. Perhaps you don't want that, in which case you can use this instead

filter = “\.php$”

The “$” tells the regular expression parser that the string “.php” must occur at the end of the file name. So configuration.php will be included, but configuration.php-dist will not.

Anchoring to the start of the string

Suppose you want to list those files which start with the string “joomla” then you would use

filter = “^joomla”

The “^” tells the regular expression parser that the string following must occur at the start of the file name.

Anchoring to both ends of the string

Suppose you want to list all those files whose names begin with “joomla” and end with “.php”, but you don't care about what is in between. Then you can use

filter = “^joomla(.*)\.php$”

Here you will recognise the “^” character as anchoring the start of the string, and the “$” as anchoring the end of the string. The “(.*)” indicates that any number of characters, including no characters at all, are acceptable in that position. Breaking this down a little, the “.” will match any single character; the “*” indicates that the preceding character (in this case the “.”) can occur any number of times, including zero; and the brackets serve to separate the substring from the rest of the string.

Case sensitivity

It is important to note that regular expression strings are case sensitive. Suppose you have some file names that begin with “Joomla” instead of “joomla”. These would not be included if you used the string in the previous example. To allow for the first character of the file name to be either upper or lower case you can use

filter = “^[Jj]oomla”

Here the “[Jj]” indicates that either “J” or “j” should be matched. The brackets (“[]”) indicate a “character class” and should contain list of characters that are to be matched. If you want to include all filenames beginning with the letters “s”, “t”, “u” or “v” then you could use

filter = “^[stuv]”

Actually you can shorten this a little by using a range specification

filter = “^[s-v]”

If you want to make this case insensitive then use

filter = “^[s-vS-V]”

Filtering a list of extensions

Suppose you want to filter your list of files so that only those files with specific extensions are included. For a single extension you can just use

filter = “\.php$”

But what if you want to filter several different extensions? For example, to only include file names ending in “.php”, “.html” or “.txt” you can use

filter = “\.php$|\.html$|\.txt$”

The “|” character indicates an alternative, so “this|that” will match with “this” or “that”.

You might notice that the imagelist parameter type is exactly the same as the filelist parameter type with this filter string

filter = “\.png$|\.gif$|\.jpg$|\.bmp$|\.ico$”