Actions

J1.5

Difference between revisions of "Template parameters"

From Joomla! Documentation

(New page: {{:Defining a parameter in templateDetails.xml|Defining a parameter in templateDetails.xml}} {{:Parameter types supported|Parameter types supported}} Page for each parameter type {{:Ret...)
 
m (version tutorial template)
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{:Defining a parameter in templateDetails.xml|Defining a parameter in templateDetails.xml}}
+
{{version/tutor|1.5}}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.
  
{{:Parameter types supported|Parameter types supported}}
+
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.
  
Page for each parameter type
+
== Introduction to template parameters ==
 +
{{:Introduction to template parameters}}
 +
== Defining a parameter in templateDetails.xml ==
 +
{{:Defining a parameter in templateDetails.xml}}
 +
== Standard parameter types ==
 +
{{:Standard parameter types}}
 +
==Standard parameter types in detail==
 +
{{deprecated|when=1.5|from=1.6|link=Form field|old=Template Parameters|new=Form fields|only=yes}}
 +
===Calendar parameter type===
 +
{{:Calendar parameter type}}
 +
===Category parameter type===
 +
{{:Category parameter type}}
 +
===Editors parameter type===
 +
{{:Editors parameter type}}
 +
===Filelist parameter type===
 +
{{:Filelist parameter type}}
 +
===Folderlist parameter type===
 +
{{:Folderlist parameter type}}
 +
===Helpsites parameter type===
 +
{{:Helpsites parameter type}}
 +
===Hidden parameter type===
 +
{{:Hidden parameter type}}
 +
===Imagelist parameter type===
 +
{{:Imagelist parameter type}}
 +
===Languages parameter type===
 +
{{:Languages parameter type}}
 +
===List parameter type===
 +
{{:List parameter type}}
 +
===Menu parameter type===
 +
{{:Menu parameter type}}
 +
===Menuitem parameter type===
 +
{{:Menuitem parameter type}}
 +
===Password parameter type===
 +
{{:Password parameter type}}
 +
===Radio parameter type===
 +
{{:Radio parameter type}}
 +
===Section parameter type===
 +
{{:Section parameter type}}
 +
===Spacer parameter type===
 +
{{:Spacer parameter type}}
 +
===Sql parameter type===
 +
{{:Sql parameter type}}
 +
===Text parameter type===
 +
{{:Text parameter type}}
 +
===Textarea parameter type===
 +
{{:Textarea parameter type}}
 +
===Timezones parameter type===
 +
{{:Timezones parameter type}}
 +
===Usergroup parameter type===
 +
{{:Usergroups parameter type}}
  
{{:Retrieving parameter data in a template file|Retrieving parameter data in a template file}}
+
== Storing parameter values ==
 
+
{{:Storing parameter values}}
<noinclude>[[Category:Templates]]</noinclude>
+
== Retrieving parameter data in a template file ==
<noinclude>[[Category:Tutorials]]</noinclude>
+
{{:Retrieving parameter data in a template file}}
 +
== Creating custom XML parameter types ==
 +
{{:Creating custom XML parameter types}}
 +
== Regular expressions in parameter arguments ==
 +
{{:Regular expressions in parameter arguments}}
 +
<noinclude>[[Category:Template Development]][[Category:Tutorials]][[Category:Parameters]]</noinclude>

Revision as of 10:04, 18 September 2012

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

Contents

Introduction to template parameters

Introduction to template parameters

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

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:

Template-parameters-example.png

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 &amp;
Double quote &quot;
' Single quote &#039;
< Less than &lt;
> Greater than &gt;

Standard parameter types

Standard parameter types

Standard parameter types in detail

Calendar parameter type

Calendar parameter type

Category parameter type

Category parameter type

Editors parameter type

Editors parameter type

Filelist parameter type

Filelist parameter type

Folderlist parameter type

Folderlist parameter type

Helpsites parameter type

Helpsites parameter type

Hidden parameter type

Hidden parameter type

Imagelist parameter type

Imagelist parameter type

Languages parameter type

Languages parameter type

List parameter type

List parameter type

Menu parameter type

Menu parameter type

Menuitem parameter type

Menuitem parameter type

Password parameter type

Password parameter type

Radio parameter type

Radio parameter type

Section parameter type

Section parameter type

Spacer parameter type

Spacer parameter type

Sql parameter type

Sql parameter type

Text parameter type

Text parameter type

Textarea parameter type

Textarea parameter type

Timezones parameter type

Timezones parameter type

Usergroup parameter type

Usergroups parameter type

Storing parameter values

Storing parameter values

Retrieving parameter data in a template file

Retrieving parameter data in a template file

Creating custom XML parameter types

Creating custom XML parameter types

Regular expressions in parameter arguments

Regular expressions in parameter arguments