Provided by: libtemplate-perl_2.27-1build7_amd64 
NAME
Template::Manual::Syntax - Directive syntax, structure and semantics
Tag Styles
Template directives are embedded between start and end markers tags. By default these tag
markers are "[%" and "%]".
[% PROCESS header %]
<h1>Hello World!</h1>
<a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
[% PROCESS footer %]
You can change the tag characters using the "START_TAG", "END_TAG" and "TAG_STYLE"
configuration options. You can also use the "TAGS" directive to define a new tag style for
the current template file.
You can also set the "INTERPOLATE" option to allow simple variable references to be
embedded directly in templates, prefixed by a "$".
# INTERPOLATE = 0
<td>[% name %]</td>
<td>[% email %]</td>
# INTERPOLATE = 1
<td>$name</td>
<td>$email</td>
Directives may be embedded anywhere in a line of text and can be split across several
lines. Insignificant whitespace is generally ignored within the directive.
[% INCLUDE header
title = 'Hello World'
bgcol = '#ffffff'
%]
[%INCLUDE menu align='right'%]
Name: [% name %] ([%id%])
Outline Tags
As of version 2.26, the Template Toolkit supports "outline" tags. These have a designated
marker at the start of a line ("%%" by default) and continue to the end of a line. The
newline character at the end of the line is discarded (aka "chomped").
So rather than writing something like this:
[% IF some.list.size -%]
<ul>
[% FOREACH item IN some.list -%]
<li>[% item.html %]</li>
[% END -%]
</ul>
[% END -%]
You can write it like this instead:
%% IF some.list.size
<ul>
%% FOREACH item IN some.list
<li>[% item.html %]</li>
%% END
</ul>
%% END
Outline tags aren't enabled by default. There are a numbers of ways you can enable them.
The first is to use the "TAGS" directive to set the tag style to "outline" in any
templates where you want to use them. This will enable outline tags from that point on.
[% TAGS outline -%]
%% INCLUDE header
You can set the "TAGS" back to the "default" value at some point later in the template if
you want to disable them:
[% TAGS default -%]
You can set the "TAG_STYLE" configuration option if you want then enabled in all templates
by default. You can always use the "[% TAGS default %]" directive to disable them in any
templates or parts of templates if necessary.
my $tt = Template->new({
TAG_STYLE => 'outline',
});
The "OUTLINE_TAG" option allows you to set the outline tag marker to something else if
you're not a fan of percent signs. Setting this option will automatically enable outline
tags.
my $tt = Template->new({
OUTLINE_TAG => '>>',
});
You can also use the "TAGS" directive to define your own custom tags (start, end and now
optionally, outline) for a template or part of a template.
[% TAGS <* *> >> %]
>> INCLUDE header # outline tag
Hello <* name *> # inline tag
If you only specify a start and end tag then outline tags will be disabled.
[% TAGS <* *> %] # no outline tags
Comments
The "#" character is used to indicate comments within a directive. When placed
immediately inside the opening directive tag, it causes the entire directive to be
ignored.
[%# this entire directive is ignored no
matter how many lines it wraps onto
%]
In any other position, it causes the remainder of the current line to be treated as a
comment.
[% # this is a comment
theta = 20 # so is this
rho = 30 # <aol>me too!</aol>
%]
Chomping Whitespace
You can add "-" or "+" to the immediate start or end of a directive tag to control the
whitespace chomping options. See the "PRE_CHOMP" and "POST_CHOMP" options for further
details.
[% BLOCK foo -%] # remove trailing newline
This is block foo
[%- END %] # remove leading newline
Implicit Directives: GET and SET
The simplest directives are "GET" and "SET" which retrieve and update variable values
respectively. The "GET" and "SET" keywords are actually optional as the parser is smart
enough to see them for what they really are (but note the caveat below on using side-
effect notation). Thus, you'll generally see:
[% SET foo = 10 %]
[% GET foo %]
written as:
[% foo = 10 %]
[% foo %]
You can also express simple logical statements as implicit "GET" directives:
[% title or template.title or 'Default Title' %]
[% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]
All other directives should start with a keyword specified in UPPER CASE (but see the
"ANYCASE" option). All directives keywords are in UPPER CASE to make them visually
distinctive and to distinguish them from variables of the same name but different case.
It is perfectly valid, for example, to define a variable called "stop" which is entirely
separate from the "STOP" directive.
[% stop = 'Clackett Lane Bus Depot' %]
The bus will next stop at [% stop %] # variable
[% STOP %] # directive
Block Directives
Directives such as "FOREACH", "WHILE", "BLOCK", "FILTER", etc., mark the start of a block
which may contain text or other directives up to the matching "END" directive. Blocks may
be nested indefinitely. The "IF", "UNLESS", "ELSIF" and "ELSE" directives also define
blocks and may be grouped together in the usual manner.
[% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
* Item: [% item %]
[% END %]
[% BLOCK footer %]
Copyright 2000 [% me %]
[% INCLUDE company/logo %]
[% END %]
[% IF foo %]
[% FOREACH thing = foo.things %]
[% thing %]
[% END %]
[% ELSIF bar %]
[% INCLUDE barinfo %]
[% ELSE %]
do nothing...
[% END %]
Block directives can also be used in a convenient side-effect notation.
[% INCLUDE userinfo FOREACH user = userlist %]
[% INCLUDE debugtxt msg="file: $error.info"
IF debugging %]
[% "Danger Will Robinson" IF atrisk %]
versus:
[% FOREACH user = userlist %]
[% INCLUDE userinfo %]
[% END %]
[% IF debugging %]
[% INCLUDE debugtxt msg="file: $error.info" %]
[% END %]
[% IF atrisk %]
Danger Will Robinson
[% END %]
Capturing Block Output
The output of a directive can be captured by simply assigning the directive to a variable.
[% headtext = PROCESS header title="Hello World" %]
[% people = PROCESS userinfo FOREACH user = userlist %]
This can be used in conjunction with the "BLOCK" directive for defining large blocks of
text or other content.
[% poem = BLOCK %]
The boy stood on the burning deck,
His fleece was white as snow.
A rolling stone gathers no moss,
And Keith is sure to follow.
[% END %]
Note one important caveat of using this syntax in conjunction with side-effect notation.
The following directive does not behave as might be expected:
[% var = 'value' IF some_condition %] # does not work
In this case, the directive is interpreted as (spacing added for clarity)
[% var = IF some_condition %]
value
[% END %]
rather than
[% IF some_condition %]
[% var = 'value' %]
[% END %]
The variable is assigned the output of the "IF" block which returns 'value' if true, but
nothing if false. In other words, the following directive will always cause 'var' to be
cleared.
[% var = 'value' IF 0 %]
To achieve the expected behaviour, the directive should be written as:
[% SET var = 'value' IF some_condition %]
Chaining Filters
Multiple "FILTER" directives can be chained together in sequence. They are called in the
order defined, piping the output of one into the input of the next.
[% PROCESS somefile FILTER truncate(100) FILTER html %]
The pipe character, "|", can also be used as an alias for "FILTER".
[% PROCESS somefile | truncate(100) | html %]
Multiple Directive Blocks
Multiple directives can be included within a single tag when delimited by semi-colons.
Note however that the "TAGS" directive must always be specified in a tag by itself.
[% IF title;
INCLUDE header;
ELSE;
INCLUDE other/header title="Some Other Title";
END
%]
versus
[% IF title %]
[% INCLUDE header %]
[% ELSE %]
[% INCLUDE other/header title="Some Other Title" %]
[% END %]