J1.5

Difference between revisions of "Defining a parameter in templateDetails.xml"

From Joomla! Documentation

m
(Fix red links)
 
(8 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
===== Defining a parameter in templateDetails.xml =====
+
{{version/tutor|1.5}}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:
 +
<tt>[path-to-Joomla]/templates/beez/templateDetails.xml</tt>
  
−
Template Parameters gives you the possibility to pass variables to the template. The <params> element contains sub-elements for each Parameter that is set for the template. The site administrator can change the values of Parameters from the "Template: [ Edit ]" page in the Back-end.
+
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.
  
−
For example, we set up two Parameters (Template color variation, show/hide Author Copyright).
+
Locate the <tt><params></tt> element, generally towards the end of the file.  If there is no <tt><params></tt> element you will need to add one.  This must be immediately beneath the <tt><install></tt> element in the XML element hierarchy.  Don't forget to close the element with a <tt></params></tt> tag.  Note that for Joomla 1.6 onwards the <tt><install></tt> tag is deprecated in favour of <tt><extension></tt>.
  
 +
* 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 <tt><param></tt> 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 <tt><params></tt> 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.
 
<source lang="xml">
 
<source lang="xml">
 
<params>
 
<params>
−
     <param name="templateColor" type="list" default="blue"  
+
     <param name="templateColour" type="list" default="blue"  
−
             label="Template Color" description="Choose the template color.">
+
             label="Template Colour" description="Choose the template colour.">
 
         <option value="blue">Blue</option>
 
         <option value="blue">Blue</option>
 
         <option value="red">Red</option>
 
         <option value="red">Red</option>
Line 22: Line 40:
 
</source>
 
</source>
  
−
In the Template Manager -> Template: [ Edit ] page you now see a block "Parameters" with the two Parameters we defined above. To retrieve the Parameters in your template index.php see [[Retrieving parameter data in a template file|Retrieving parameter data in a template file]]
+
The '''Template Parameters''' screen for this example will look like this:
  
−
Note: In order that the Parameters works you need a file called params.ini in your template root folder. This file is used by Joomla! to store the settings for the Parameters. It can be a blank file, but it must be writeable so changes can be made.
+
[[Image:template-parameters-example.png]]
  
−
For the example above the file looks like this.
+
Note: Parameter groups are not currently supported in template parameters.
  
−
<source lang="text">
+
Tip: To include HTML tags in XML arguments you must encode certain special characters as follows:
−
templateColor=blue
+
{| class="wikitable"
−
authorCopyright=1
+
!Character
−
</source>
+
!Description
 +
!Encoding
 +
|-
 +
|&
 +
|Ampersand
 +
|&amp;amp;
 +
|-
 +
|“
 +
|Double quote
 +
|&amp;quot;
 +
|-
 +
|'
 +
|Single quote
 +
|&amp;#039;
 +
|-
 +
|<
 +
|Less than
 +
|&amp;lt;
 +
|-
 +
|>
 +
|Greater than
 +
|&amp;gt;
 +
|}
 +
<noinclude> </noinclude>
  
−
<noinclude>[[Category:Intermediate]]
+
[[Category:Archived version Joomla! 1.5]]
−
[[Category:Templates]]
 
−
[[Category:Topics]]
 
−
[[Category:Parameters]]
 
−
</noinclude>
 

Latest revision as of 03:12, 11 June 2013

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.

This tutorial is for Joomla! CMS Version(s) Joomla 1.5

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;
Retrieved from "https://docs.joomla.org/index.php?title=J1.5:Defining_a_parameter_in_templateDetails.xml&oldid=100146"