Documentation Menu

1.5 Template Project

The Joomla! Documentation Working Group is running a project to develop detailed reference and tutorial material on Joomla! 1.5 templates.  There is a project page on the documentation wiki where you can see the work in progress and help us by contributing your knowledge.

Who's Online

We have 3 guests online

Help Site License

The Joomla! Help Site content is copyright © 2005 - 2008 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution NonCommercial ShareAlike 2.5. Some parts of this website may be subject to other licenses.
Home arrow patTemplate arrow patTemplate Tags arrow Tmpl Tag

Tmpl Tag PDF Print E-mail
<patTemplate:tmpl>
  Pat is my best friend.
</patTemplate:tmpl>


This tag marks the beginning of a template. All text that follows will be appended to the template until a closing tag is found.

Attributes

The following attributes are supported:

name (optional but usually provided)

This attribute specifies the name of the template. The name must be unique as it is used to address the template with several API functions. If the name attribute is omitted than a unique name is generated interally for the template.

<patTemplate:tmpl name="body">
  This is my site.
</patTemplate:tmpl>

type (optional)

This attribute defines the type of the template and may be one of the following values:

Standard

(this is the default value if the type is omitted)

<patTemplate:tmpl name="body" type="standard">
  This is a vanilla flavoured template.
</patTemplate:tmpl>

OddEven

OddEven templates must two sub-templates with conditions for the odd and even cases. These sub-templates are alternated when the templated is repeated.

<patTemplate:tmpl name="row" type="oddeven">
    <patTemplate:sub condition="__odd">
<div style="background-color:#cccccc">{VALUE}</div>
    </patTemplate:sub>
    <patTemplate:sub condition="__even">
<div style="background-color:#ffffff">{VALUE}</div>
    </patTemplate:sub>
</patTemplate:tmpl>

Modulo

A modulo template allows you to define any number of sub-templates for alternating lists. It is similar to odd-even templates.

<patTemplate:tmpl name="row" type="modulo" modulo="3">
    <patTemplate:sub condition="0">
<div style="background-color:red">{VALUE}</div>
    </patTemplate:sub>
    <patTemplate:sub condition="1">
<div style="background-color:blue">{VALUE}</div>
    </patTemplate:sub>
    <patTemplate:sub condition="2">
<div style="background-color:green">{VALUE}</div>
    </patTemplate:sub>
</patTemplate:tmpl>


Two special system variables relate to the module type of template. These are:

PAT_MODULO
this is the calculated modulus value for the current sub-template. In the example above, it would cycle over 1, 2, and 0
PAT_MODULO_REP
this is the loop number or the number of times the whole template has been repeated, starting at one

Condition

Condition templates may contain as many subtemplates as you like. It emulates the switch statement in PHP.

SimpleCondition

SimpleCondition templates may define several variables that must be set to ensure that the template is displayed. They DO NOT contain any subtemplates. If all variables are set, the template is visible otherwise it is hidden.

Note: you have to use the requiredvars attribute to define the variables that have to be set, as a list of variables separated by commas.

addsystemvars

This attribute allows you to add special system variables, like the number of repetitions of a template.  The attribute may take the following values:

  • boolean - where appropriate, the textual boolean value of the system variable will be supplied, that is, 'true' or 'false'.
  • integer - where appropriate, the integer equivalent of boolean values will be supplied, that is, 0 for false and 1 for true.
  • any other text - in this case the text will be returned for a true case, or an empty string if false.

 

Example:

<patTemplate:tmpl name="tmpl-1" addSystemVars="boolean">
    <strong>System-variables:</strong><br />
    
    PAT_LOOPS    : {PAT_LOOPS}<br />
    PAT_IS_FIRST : {PAT_IS_FIRST}<br />
    PAT_IS_LAST  : {PAT_IS_LAST}<br />
    PAT_IS_ODD   : {PAT_IS_ODD}<br />
    PAT_IS_EVEN  : {PAT_IS_EVEN}<br />
    PATTEMPLATE_VERSION : {PATTEMPLATE_VERSION}<br />
    <hr />
</patTemplate:tmpl>

autoclear

If autoclear is set to yes, then the template will be reparsed each time it is displayed.

autoload

Allows you to dynamically include templates.

Example:

$tmpl->readTemplatesFromInput( 'example.tmpl' );
$tmpl->setAttribute( 'main', 'src', 'example_include.tmpl' );
$tmpl->displayParsedTemplate();
<mos:tmpl name="main" src="dynamic" autoload="off" parse="on" />

conditionvar (required for templates of type condition)

Sets the name of the variable that is used for the emulated switch statement.

Example: conditionvar="NAME"

Checking variables of other templates

Since version 2.4 it is also possible to use a variable of an other template as condition variable. To do this, we've implemented the dot syntax. Just use conditionvar="TEMPLATENAME.VARNAME" to use the variable of any template as conditionvar. But be careful when using variables of templates that are repeated as the iteration number of the template is also used.

requiredvars (required for templates of type simplecondition)

This can be a list of variables that have to be set for the template to be displayed. Each variable must be separated by a comma. It is very useful if you want to display error messages if one or more of the variables was not set. With version 2.4 you may also use the dot syntax for variables to check if vars in other templates are set.

Example: requiredvars="NAME,STREET,ZIPCODE"

useglobals (optional)

This atttibute can be used for templates of type Condition or "Simple Condition?" to tell patTemplate that the global variables should be used for conditions if the variable is not set locally.

The useglobals attribute does not need a value and thus can be used as flag.

Example: useglobals="yes" or just useglobals

loop (optional)

This forces the template to be repeated even if there are no values that need the repetition.

Example: loop="10"

visibility (optional)

Visibility can be set to either visible or hidden. If set to hidden, the template won't be outputted. It can be used to hide or display error messages, as attributes can be changed use setAttribute (see API Documentation).

Example: visibility="hidden"

placeholder (optional)

This should only be used by advanced users.

When placing a template into a template, the parser will extract the HTML of the child template and replace it with a certain placeholder (TMPL:templatename) to identify the position where it has to be placed when displaying the template. With this attribute you can force your own placeholder or tell the parser to use no placeholder at all (set it to none),

Example: placeholder="CONTENT"

parse (optional)

See src.

src (optional)

Use an external file as content for this template. This should be used in conjuntion with the parse="on|off" attribute to tell the parser if the external file should also be parsed (similar to external entities in XML) or if it contains plain HTML that just needs to be included.

unusedvars (optional)

This attribute is used to tell the parser how he should treat variables that have no value assigned. It can have one of the following values:

  • ignore  leave them like they are
  • strip  remove them from the html code
  • comment  use HTML comments to make them invisbible
  • nbsp  replace them with a non-breaking space
  • or any other string that they should be replaced with.

varscope (optional)

This can be used to import variables from another template into this template. Let's say you've got one template for the whole page and are adding all vars to this template. When inserting a new template into the page, the variables in this template would not be parsed as long as you do not add them. This is where the varscope attribute comes in. Just put varscope="NAMEOFPAGE" in your tmpl tag and the vars from the first template ar also available in this new template.

whitespace (optional)

Tells the parser, how it should treat whitespace in templates (trim, ltrim, rtrim, keep). It allows you to generate HTML output without any line breaks or tab stops, from templates that contain these layout elements.

Last Updated ( Tuesday, 01 November 2005 )
 
Next >