.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Template::Manual::Syntax 3pm"
.TH Template::Manual::Syntax 3pm "2018-11-02" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Template::Manual::Syntax \- Directive syntax, structure and semantics
.SH "Tag Styles"
.IX Header "Tag Styles"
Template directives are embedded between start and end markers tags.
By default these tag markers are \f(CW\*(C`[%\*(C'\fR and \f(CW\*(C`%]\*(C'\fR.
.PP
.Vb 1
\& [% PROCESS header %]
\&
\& Hello World!
\& 
\&
\& [% PROCESS footer %]
.Ve
.PP
You can change the tag characters using the \f(CW\*(C`START_TAG\*(C'\fR, \f(CW\*(C`END_TAG\*(C'\fR and
\&\f(CW\*(C`TAG_STYLE\*(C'\fR configuration options. You can also use the \f(CW\*(C`TAGS\*(C'\fR directive to
define a new tag style for the current template file.
.PP
You can also set the \f(CW\*(C`INTERPOLATE\*(C'\fR option to allow simple variable references
to be embedded directly in templates, prefixed by a \f(CW\*(C`$\*(C'\fR.
.PP
.Vb 3
\& # INTERPOLATE = 0
\& [% name %] |
\& [% email %] |
\&
\& # INTERPOLATE = 1
\& $name |
\& $email |
.Ve
.PP
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.
.PP
.Vb 4
\& [% INCLUDE header
\& title = \*(AqHello World\*(Aq
\& bgcol = \*(Aq#ffffff\*(Aq
\& %]
\&
\& [%INCLUDE menu align=\*(Aqright\*(Aq%]
\&
\& Name: [% name %] ([%id%])
.Ve
.SH "Outline Tags"
.IX Header "Outline Tags"
As of version 2.26, the Template Toolkit supports \*(L"outline\*(R" tags. These have
a designated marker at the start of a line (\f(CW\*(C`%%\*(C'\fR by default) and continue to
the end of a line. The newline character at the end of the line is discarded
(aka \*(L"chomped\*(R").
.PP
So rather than writing something like this:
.PP
.Vb 7
\& [% IF some.list.size \-%]
\&
\& [% FOREACH item IN some.list \-%]
\& - [% item.html %]
\& [% END \-%]
\&
\& [% END \-%]
.Ve
.PP
You can write it like this instead:
.PP
.Vb 7
\& %% IF some.list.size
\&
\& %% FOREACH item IN some.list
\& - [% item.html %]
\& %% END
\&
\& %% END
.Ve
.PP
Outline tags aren't enabled by default. There are a numbers of ways you can
enable them. The first is to use the \f(CW\*(C`TAGS\*(C'\fR directive to set the tag style
to \f(CW\*(C`outline\*(C'\fR in any templates where you want to use them. This will enable
outline tags from that point on.
.PP
.Vb 2
\& [% TAGS outline \-%]
\& %% INCLUDE header
.Ve
.PP
You can set the \f(CW\*(C`TAGS\*(C'\fR back to the \f(CW\*(C`default\*(C'\fR value at some point later in the
template if you want to disable them:
.PP
.Vb 1
\& [% TAGS default \-%]
.Ve
.PP
You can set the \f(CW\*(C`TAG_STYLE\*(C'\fR configuration option if you want then enabled in
all templates by default. You can always use the \f(CW\*(C`[% TAGS default %]\*(C'\fR
directive to disable them in any templates or parts of templates if necessary.
.PP
.Vb 3
\& my $tt = Template\->new({
\& TAG_STYLE => \*(Aqoutline\*(Aq,
\& });
.Ve
.PP
The \f(CW\*(C`OUTLINE_TAG\*(C'\fR 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.
.PP
.Vb 3
\& my $tt = Template\->new({
\& OUTLINE_TAG => \*(Aq>>\*(Aq,
\& });
.Ve
.PP
You can also use the \f(CW\*(C`TAGS\*(C'\fR directive to define your own custom tags (start,
end and now optionally, outline) for a template or part of a template.
.PP
.Vb 3
\& [% TAGS <* *> >> %]
\& >> INCLUDE header # outline tag
\& Hello <* name *> # inline tag
.Ve
.PP
If you only specify a start and end tag then outline tags will be disabled.
.PP
.Vb 1
\& [% TAGS <* *> %] # no outline tags
.Ve
.SH "Comments"
.IX Header "Comments"
The \f(CW\*(C`#\*(C'\fR 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.
.PP
.Vb 3
\& [%# this entire directive is ignored no
\& matter how many lines it wraps onto
\& %]
.Ve
.PP
In any other position, it causes the remainder of the current line to
be treated as a comment.
.PP
.Vb 4
\& [% # this is a comment
\& theta = 20 # so is this
\& rho = 30 # me too!
\& %]
.Ve
.SH "Chomping Whitespace"
.IX Header "Chomping Whitespace"
You can add \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`+\*(C'\fR to the immediate start or end of a directive
tag to control the whitespace chomping options. See the \f(CW\*(C`PRE_CHOMP\*(C'\fR and
\&\f(CW\*(C`POST_CHOMP\*(C'\fR options for further details.
.PP
.Vb 3
\& [% BLOCK foo \-%] # remove trailing newline
\& This is block foo
\& [%\- END %] # remove leading newline
.Ve
.SH "Implicit Directives: GET and SET"
.IX Header "Implicit Directives: GET and SET"
The simplest directives are \f(CW\*(C`GET\*(C'\fR and \f(CW\*(C`SET\*(C'\fR which retrieve and update
variable values respectively. The \f(CW\*(C`GET\*(C'\fR and \f(CW\*(C`SET\*(C'\fR 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:
.PP
.Vb 2
\& [% SET foo = 10 %]
\& [% GET foo %]
.Ve
.PP
written as:
.PP
.Vb 2
\& [% foo = 10 %]
\& [% foo %]
.Ve
.PP
You can also express simple logical statements as implicit \f(CW\*(C`GET\*(C'\fR directives:
.PP
.Vb 1
\& [% title or template.title or \*(AqDefault Title\*(Aq %]
\&
\& [% mode == \*(Aqgraphics\*(Aq ? "Graphics Mode Enabled" : "Text Mode" %]
.Ve
.PP
All other directives should start with a keyword specified in \s-1UPPER
CASE\s0 (but see the \f(CW\*(C`ANYCASE\*(C'\fR option). All directives keywords are in
\&\s-1UPPER CASE\s0 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 \f(CW\*(C`stop\*(C'\fR which is
entirely separate from the \f(CW\*(C`STOP\*(C'\fR directive.
.PP
.Vb 1
\& [% stop = \*(AqClackett Lane Bus Depot\*(Aq %]
\&
\& The bus will next stop at [% stop %] # variable
\&
\& [% STOP %] # directive
.Ve
.SH "Block Directives"
.IX Header "Block Directives"
Directives such as \f(CW\*(C`FOREACH\*(C'\fR, \f(CW\*(C`WHILE\*(C'\fR, \f(CW\*(C`BLOCK\*(C'\fR, \f(CW\*(C`FILTER\*(C'\fR, etc., mark the
start of a block which may contain text or other directives up to the matching
\&\f(CW\*(C`END\*(C'\fR directive. Blocks may be nested indefinitely. The \f(CW\*(C`IF\*(C'\fR, \f(CW\*(C`UNLESS\*(C'\fR,
\&\f(CW\*(C`ELSIF\*(C'\fR and \f(CW\*(C`ELSE\*(C'\fR directives also define blocks and may be grouped together
in the usual manner.
.PP
.Vb 3
\& [% FOREACH item = [ \*(Aqfoo\*(Aq \*(Aqbar\*(Aq \*(Aqbaz\*(Aq ] %]
\& * 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 %]
.Ve
.PP
Block directives can also be used in a convenient side-effect notation.
.PP
.Vb 1
\& [% INCLUDE userinfo FOREACH user = userlist %]
\&
\& [% INCLUDE debugtxt msg="file: $error.info"
\& IF debugging %]
\&
\& [% "Danger Will Robinson" IF atrisk %]
.Ve
.PP
versus:
.PP
.Vb 3
\& [% FOREACH user = userlist %]
\& [% INCLUDE userinfo %]
\& [% END %]
\&
\& [% IF debugging %]
\& [% INCLUDE debugtxt msg="file: $error.info" %]
\& [% END %]
\&
\& [% IF atrisk %]
\& Danger Will Robinson
\& [% END %]
.Ve
.SH "Capturing Block Output"
.IX Header "Capturing Block Output"
The output of a directive can be captured by simply assigning the directive
to a variable.
.PP
.Vb 1
\& [% headtext = PROCESS header title="Hello World" %]
\&
\& [% people = PROCESS userinfo FOREACH user = userlist %]
.Ve
.PP
This can be used in conjunction with the \f(CW\*(C`BLOCK\*(C'\fR directive for defining large
blocks of text or other content.
.PP
.Vb 6
\& [% 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 %]
.Ve
.PP
Note one important caveat of using this syntax in conjunction with side-effect
notation. The following directive does not behave as might be expected:
.PP
.Vb 1
\& [% var = \*(Aqvalue\*(Aq IF some_condition %] # does not work
.Ve
.PP
In this case, the directive is interpreted as (spacing added for clarity)
.PP
.Vb 3
\& [% var = IF some_condition %]
\& value
\& [% END %]
.Ve
.PP
rather than
.PP
.Vb 3
\& [% IF some_condition %]
\& [% var = \*(Aqvalue\*(Aq %]
\& [% END %]
.Ve
.PP
The variable is assigned the output of the \f(CW\*(C`IF\*(C'\fR block which returns
\&\f(CW\*(Aqvalue\*(Aq\fR if true, but nothing if false. In other words, the following
directive will always cause 'var' to be cleared.
.PP
.Vb 1
\& [% var = \*(Aqvalue\*(Aq IF 0 %]
.Ve
.PP
To achieve the expected behaviour, the directive should be written as:
.PP
.Vb 1
\& [% SET var = \*(Aqvalue\*(Aq IF some_condition %]
.Ve
.SH "Chaining Filters"
.IX Header "Chaining Filters"
Multiple \f(CW\*(C`FILTER\*(C'\fR 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.
.PP
.Vb 1
\& [% PROCESS somefile FILTER truncate(100) FILTER html %]
.Ve
.PP
The pipe character, \f(CW\*(C`|\*(C'\fR, can also be used as an alias for \f(CW\*(C`FILTER\*(C'\fR.
.PP
.Vb 1
\& [% PROCESS somefile | truncate(100) | html %]
.Ve
.SH "Multiple Directive Blocks"
.IX Header "Multiple Directive Blocks"
Multiple directives can be included within a single tag when delimited
by semi-colons. Note however that the \f(CW\*(C`TAGS\*(C'\fR directive must always
be specified in a tag by itself.
.PP
.Vb 6
\& [% IF title;
\& INCLUDE header;
\& ELSE;
\& INCLUDE other/header title="Some Other Title";
\& END
\& %]
.Ve
.PP
versus
.PP
.Vb 5
\& [% IF title %]
\& [% INCLUDE header %]
\& [% ELSE %]
\& [% INCLUDE other/header title="Some Other Title" %]
\& [% END %]
.Ve