J1.5:Template parameters

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.

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 Standard parameter types. If you are a developer it is also possible to create your own custom parameter types; see Creating custom XML 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;

Numerous types of form field are built into Joomla!. The following table lists these standard types and their availability. Use the single-page reference if you want to print all existing form field documentation.

Please note that many of these fields are available as parameter types in Joomla! 1.5. For a list of parameter types, see J1.5:Standard parameter types. For a comparison between form field and parameter types, see Standard form field and parameter types.

Type	Description	Availability
accesslevel	provides a drop down list of viewing access levels.	and newer
cachehandler	provides a list of available cache handling options.	and newer
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.	and newer
captcha	provides a drop down list of the captcha plugins.	and newer
category	provides a drop down list of categories for an extension.	and newer
checkbox	provides a single checkbox to be checked or unchecked	and newer
checkboxes	provides unlimited checkboxes that can be used for multi-select.	and newer
Chrome Style	provides a list of template chrome style options grouped by template.	and newer
color	provides a color picker when clicking the input box.	and newer
Content Language	Provides a list of content languages.	and newer
Content Type	Provides a list of content types.	and newer
combo	provides a combo box field.	and newer
componentlayout	provides a grouped list of core and template alternate layouts for a component item.	and newer
contentlanguage	provides a list of installed content languages for use in conjunction with the language switcher plugin.	and newer
Database Connection	Provides a list of available database connections, optionally limiting to a given list.	and newer
editor	provides an editor area field.	and newer
editors	Provides a drop down list of the available WYSIWYG editors. Since use plugins form field instead.
email	provides an email field.	and newer
file		and newer
filelist	provides a drop down list of files from a specified directory.	and newer
folderlist	provides a drop down list of folders from a specified directory.	and newer
groupedlist	provides a drop down list of items organized into groups.	and newer
header tag	provides a drop down list of the header tags (h1-h6).	and newer
helpsite	provides a drop down list of the help sites for your Joomla installation.	and newer
hidden	provides a hidden field for saving a form field 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).	and newer
imagelist	provides a drop down list of image files in a specified directory.	and newer
integer	provides a drop down list of integers between a minimum and maximum.	and newer
language	provides a drop down list of the installed languages for the Front-end or Back-end.	and newer
list	provides a drop down list of custom-defined entries.	and newer
media	provides modal access to the media manager for insertion of images with upload for users with appropriate permissions.	and newer
menu	provides a drop down list of the available menus from your Joomla site.	and newer
Menu Item	provides a drop down list of the available menu items from your Joomla site.	and newer
Module Layout	provides a list of alternative layout for a module grouped by core and template.	and newer
Module Order	Provides a drop down to set the ordering of module in a given position	and newer
Module Position	provides a text input to set the position of a module.	and newer
Module Tag	provides a list of html5 elements (used to wrap a module in).	and newer
note	supports a one line text field.	and newer
password	provides a text box for entry of a password. The password characters will be obscured as they are entered.	and newer
plugins	provides a list of plugins from a given folder.	and newer
radio	provides radio buttons to select different options.	and newer
rules	provides a matrix of group by action options for managing access control. Display depends on context.	and newer
sessionhandler	provides a drop down list of session handler options.	and newer
spacer	provides a visual separator between form fields. It is purely a visual aid and no value is stored.	and newer
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.	and newer
tag	provides an entry point for tags (either AJAX or Nested).	and newer
tel	provides an input field for a telephone number.	and newer
templatestyle	provides a drop down list of template styles.	and newer
text	provides a text box for data entry.	and newer
textarea	provides a text area for entry of multi-line text.	and newer
timezone	provides a drop down list of time zones.	and newer
URL	provides a URL text input field.	and newer
user	provides a modal list of users.	and newer
usergroup	provides a drop down list of user groups.	and newer

Page for each parameter type

Retrieving parameter data in a template file