Actions

J1.5

Difference between revisions of "Template parameters"

From Joomla! Documentation

m (1 revision(s))
m
Line 7: Line 7:
 
{{:Retrieving parameter data in a template file|Retrieving parameter data in a template file}}
 
{{:Retrieving parameter data in a template file|Retrieving parameter data in a template file}}
  
<noinclude>[[Category:Templates]]</noinclude>
+
<noinclude>[[Category:Templates]]
<noinclude>[[Category:Tutorials]]</noinclude>
+
[[Category:Tutorials]]
 +
[[Category:Parameters]]</noinclude>

Revision as of 05:57, 29 April 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.

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;


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

<translate> Joomla 1.5 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.</translate>

<translate>

Type</translate>

<translate>

Description</translate>

<translate>

Availability</translate>

<translate>

accesslevel</translate>

<translate>

provides a drop down list of viewing access levels.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

cachehandler</translate>

<translate>

provides a list of available cache handling options.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

calendar</translate>

<translate>

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

Joomla 2.5 <translate>

and newer</translate>

<translate>

captcha</translate>

<translate>

provides a drop down list of the captcha plugins.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

category</translate>

<translate>

provides a drop down list of categories for an extension.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

checkbox</translate>

<translate>

provides a single checkbox to be checked or unchecked</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

checkboxes</translate>

<translate>

provides unlimited checkboxes that can be used for multi-select.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

Chrome Style</translate>

<translate>

provides a list of template chrome style options grouped by template.</translate>

Joomla 3.0 <translate>

and newer</translate>

<translate>

color</translate>

<translate>

provides a color picker when clicking the input box.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

Content Language</translate>

<translate>

Provides a list of content languages.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

Content Type</translate>

<translate>

Provides a list of content types.</translate>

Joomla 3.1 <translate>

and newer</translate>

<translate>

combo</translate>

<translate>

provides a combo box field.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

componentlayout</translate>

<translate>

provides a grouped list of core and template alternate layouts for a component item.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

contentlanguage</translate>

<translate>

provides a list of installed content languages for use in conjunction with the language switcher plugin.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

Database Connection</translate>

<translate>

Provides a list of available database connections, optionally limiting to a given list.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

editor</translate>

<translate>

provides an editor area field.</translate>

Joomla 1.6 <translate>

and newer</translate>

<translate>

editors</translate>

<translate>

Provides a drop down list of the available WYSIWYG editors. Since Joomla 2.5 use plugins form field instead.</translate>

Joomla 1.6
<translate>

email</translate>

<translate>

provides an email field.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

file</translate>

<translate>

Provides an input field for files</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

filelist</translate>

<translate>

provides a drop down list of files from a specified directory.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

folderlist</translate>

<translate>

provides a drop down list of folders from a specified directory.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

groupedlist</translate>

<translate>

provides a drop down list of items organized into groups.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

header tag</translate>

<translate>

provides a drop down list of the header tags (h1-h6)</translate>.

Joomla 3.0 <translate>

and newer</translate>

<translate>

helpsite</translate>

<translate>

provides a drop down list of the help sites for your Joomla installation.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

hidden</translate>

<translate>

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).</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

imagelist</translate>

<translate>

provides a drop down list of image files in a specified directory.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

integer</translate>

<translate>

provides a drop down list of integers between a minimum and maximum.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

language</translate>

<translate>

provides a drop down list of the installed languages for the Front-end or Back-end.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

list</translate>

<translate>

provides a drop down list of custom-defined entries.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

media</translate>

<translate>

provides modal access to the media manager for insertion of images with upload for users with appropriate permissions.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

menu</translate>

<translate>

provides a drop down list of the available menus from your Joomla site.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

Menu Item</translate>

<translate>

provides a drop down list of the available menu items from your Joomla site.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate> meter</translate> <translate>

Provides a meter to show value in a range.</translate>

Joomla 3.2 <translate>

and newer</translate>

<translate>

Module Layout</translate>

<translate>

provides a list of alternative layout for a module grouped by core and template.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

Module Order</translate>

<translate>

Provides a drop down to set the ordering of module in a given position</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

Module Position</translate>

<translate>

provides a text input to set the position of a module.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

Module Tag</translate>

<translate>

provides a list of html5 elements (used to wrap a module in).</translate>

Joomla 3.0 <translate>

and newer</translate>

<translate>

note</translate>

<translate>

supports a one line text field.</translate>

Joomla 3.1 <translate>

and newer</translate>

<translate>

number</translate>

<translate>

Provides a one line text box with up-down handles to set a number in the field.</translate>

Joomla 3.2 <translate>

and newer</translate>

<translate>

password</translate>

<translate>

provides a text box for entry of a password. The password characters will be obscured as they are entered.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

plugins</translate>

<translate>

provides a list of plugins from a given folder.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

predefinedlist</translate>

<translate>

Form Field to load a list of predefined values.</translate>

Joomla 3.2 <translate>

and newer</translate>

<translate>

radio</translate>

<translate>

provides radio buttons to select different options.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

range</translate>

<translate>

Provides a horizontal scroll bar to specify a value in a range.</translate>

Joomla 3.2 <translate>

and newer</translate>

<translate>

repeatable</translate>

<translate>

Allows form fields which can have as many options as the user desires.</translate>

Joomla 3.2 <translate>

and newer</translate>

<translate>

rules</translate>

<translate>

provides a matrix of group by action options for managing access control. Display depends on context.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

sessionhandler</translate>

<translate>

provides a drop down list of session handler options.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

spacer</translate>

<translate>

provides a visual separator between form fields. It is purely a visual aid and no value is stored.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

sql</translate>

<translate>

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

Joomla 2.5 <translate>

and newer</translate>

<translate>

tag</translate>

<translate>

provides an entry point for tags (either AJAX or Nested).</translate>

Joomla 3.1 <translate>

and newer</translate>

<translate>

tel</translate>

<translate>

provides an input field for a telephone number.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

templatestyle</translate>

<translate>

provides a drop down list of template styles.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

text</translate>

<translate>

provides a text box for data entry.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

textarea</translate>

<translate>

provides a text area for entry of multi-line text.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

timezone</translate>

<translate>

provides a drop down list of time zones.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

URL</translate>

<translate>

provides a URL text input field.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

user</translate>

<translate>

Field to select a user from a modal list. Displays User Name and stores User ID</translate>

Joomla 1.6 <translate>

and newer</translate>

<translate>

useractive</translate>

<translate>

Field to show a list of available user active statuses.</translate>

Joomla 3.2 <translate>

and newer</translate>

<translate>

usergroup</translate>

<translate>

provides a drop down list of user groups. Since Joomla 3.2 use usergrouplist instead.</translate>

Joomla 2.5 <translate>

and newer</translate>

<translate>

usergrouplist</translate>

<translate>

Field to load a drop down list of available user groups. Replaces usergroup form field type.</translate>

Joomla 3.2 <translate>

and newer</translate>

<translate>

userstate</translate>

<translate>

Field to load a list of available users statuses.</translate>

Joomla 3.2 <translate>

and newer</translate>


Page for each parameter type

Retrieving parameter data in a template file