1Template::Manual::SyntaUxs(e3r)Contributed Perl DocumentTaetmipolnate::Manual::Syntax(3)
2
3
4

NAME

6       Template::Manual::Syntax - Directive syntax, structure and semantics
7

Tag Styles

9       Template directives are embedded between start and end markers tags.
10       By default these tag markers are "[%" and "%]".
11
12           [% PROCESS header %]
13
14           <h1>Hello World!</h1>
15           <a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
16
17           [% PROCESS footer %]
18
19       You can change the tag characters using the "START_TAG", "END_TAG" and
20       "TAG_STYLE" configuration options. You can also use the "TAGS"
21       directive to define a new tag style for the current template file.
22
23       You can also set the "INTERPOLATE" option to allow simple variable
24       references to be embedded directly in templates, prefixed by a "$".
25
26           # INTERPOLATE = 0
27           <td>[% name %]</td>
28           <td>[% email %]</td>
29
30           # INTERPOLATE = 1
31           <td>$name</td>
32           <td>$email</td>
33
34       Directives may be embedded anywhere in a line of text and can be split
35       across several lines.  Insignificant whitespace is generally ignored
36       within the directive.
37
38           [% INCLUDE header
39                title = 'Hello World'
40                bgcol = '#ffffff'
41           %]
42
43           [%INCLUDE menu align='right'%]
44
45           Name: [% name %]  ([%id%])
46

Outline Tags

48       As of version 2.26, the Template Toolkit supports "outline" tags.
49       These have a designated marker at the start of a line ("%%" by default)
50       and continue to the end of a line.  The newline character at the end of
51       the line is discarded (aka "chomped").
52
53       So rather than writing something like this:
54
55           [% IF some.list.size -%]
56             <ul>
57           [%   FOREACH item IN some.list -%]
58               <li>[% item.html %]</li>
59           [%   END -%]
60             </ul>
61           [% END -%]
62
63       You can write it like this instead:
64
65           %% IF some.list.size
66             <ul>
67           %%   FOREACH item IN some.list
68               <li>[% item.html %]</li>
69           %%   END
70             </ul>
71           %% END
72
73       Outline tags aren't enabled by default.  There are a numbers of ways
74       you can enable them.  The first is to use the "TAGS" directive to set
75       the tag style to "outline" in any templates where you want to use them.
76       This will enable outline tags from that point on.
77
78           [% TAGS outline -%]
79           %% INCLUDE header
80
81       You can set the "TAGS" back to the "default" value at some point later
82       in the template if you want to disable them:
83
84           [% TAGS default -%]
85
86       You can set the "TAG_STYLE" configuration option if you want then
87       enabled in all templates by default.  You can always use the "[% TAGS
88       default %]" directive to disable them in any templates or parts of
89       templates if necessary.
90
91           my $tt = Template->new({
92               TAG_STYLE => 'outline',
93           });
94
95       The "OUTLINE_TAG" option allows you to set the outline tag marker to
96       something else if you're not a fan of percent signs.  Setting this
97       option will automatically enable outline tags.
98
99           my $tt = Template->new({
100               OUTLINE_TAG => '>>',
101           });
102
103       You can also use the "TAGS" directive to define your own custom tags
104       (start, end and now optionally, outline) for a template or part of a
105       template.
106
107           [% TAGS <* *> >> %]
108           >> INCLUDE header       # outline tag
109           Hello <* name *>        # inline tag
110
111       If you only specify a start and end tag then outline tags will be
112       disabled.
113
114           [% TAGS <* *> %]        # no outline tags
115

Comments

117       The "#" character is used to indicate comments within a directive.
118       When placed immediately inside the opening directive tag, it causes the
119       entire directive to be ignored.
120
121           [%# this entire directive is ignored no
122               matter how many lines it wraps onto
123           %]
124
125       In any other position, it causes the remainder of the current line to
126       be treated as a comment.
127
128           [% # this is a comment
129              theta = 20      # so is this
130              rho   = 30      # <aol>me too!</aol>
131           %]
132

Chomping Whitespace

134       You can add "-" or "+" to the immediate start or end of a directive tag
135       to control the whitespace chomping options.  See the "PRE_CHOMP" and
136       "POST_CHOMP" options for further details.
137
138           [% BLOCK foo -%]    # remove trailing newline
139           This is block foo
140           [%- END %]          # remove leading newline
141

Implicit Directives: GET and SET

143       The simplest directives are "GET" and "SET" which retrieve and update
144       variable values respectively. The "GET" and "SET" keywords are actually
145       optional as the parser is smart enough to see them for what they really
146       are (but note the caveat below on using side-effect notation). Thus,
147       you'll generally see:
148
149           [% SET foo = 10 %]
150           [% GET foo %]
151
152       written as:
153
154           [% foo = 10 %]
155           [% foo %]
156
157       You can also express simple logical statements as implicit "GET"
158       directives:
159
160           [% title or template.title or 'Default Title' %]
161
162           [% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]
163
164       All other directives should start with a keyword specified in UPPER
165       CASE (but see the "ANYCASE" option).  All directives keywords are in
166       UPPER CASE to make them visually distinctive and to distinguish them
167       from variables of the same name but different case.  It is perfectly
168       valid, for example, to define a variable called "stop" which is
169       entirely separate from the "STOP" directive.
170
171           [% stop = 'Clackett Lane Bus Depot' %]
172
173           The bus will next stop at [% stop %]    # variable
174
175           [% STOP %]                              # directive
176

Block Directives

178       Directives such as "FOREACH", "WHILE", "BLOCK", "FILTER", etc., mark
179       the start of a block which may contain text or other directives up to
180       the matching "END" directive. Blocks may be nested indefinitely. The
181       "IF", "UNLESS", "ELSIF" and "ELSE" directives also define blocks and
182       may be grouped together in the usual manner.
183
184           [% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
185              * Item: [% item %]
186           [% END %]
187
188           [% BLOCK footer %]
189              Copyright 2000 [% me %]
190              [% INCLUDE company/logo %]
191           [% END %]
192
193           [% IF foo %]
194              [% FOREACH thing = foo.things %]
195                 [% thing %]
196              [% END %]
197           [% ELSIF bar %]
198              [% INCLUDE barinfo %]
199           [% ELSE %]
200              do nothing...
201           [% END %]
202
203       Block directives can also be used in a convenient side-effect notation.
204
205           [% INCLUDE userinfo FOREACH user = userlist %]
206
207           [% INCLUDE debugtxt msg="file: $error.info"
208                IF debugging %]
209
210           [% "Danger Will Robinson" IF atrisk %]
211
212       versus:
213
214           [% FOREACH user = userlist %]
215              [% INCLUDE userinfo %]
216           [% END %]
217
218           [% IF debugging %]
219              [% INCLUDE debugtxt msg="file: $error.info" %]
220           [% END %]
221
222           [% IF atrisk %]
223           Danger Will Robinson
224           [% END %]
225

Capturing Block Output

227       The output of a directive can be captured by simply assigning the
228       directive to a variable.
229
230           [% headtext = PROCESS header title="Hello World" %]
231
232           [% people = PROCESS userinfo FOREACH user = userlist %]
233
234       This can be used in conjunction with the "BLOCK" directive for defining
235       large blocks of text or other content.
236
237           [% poem = BLOCK %]
238              The boy stood on the burning deck,
239              His fleece was white as snow.
240              A rolling stone gathers no moss,
241              And Keith is sure to follow.
242           [% END %]
243
244       Note one important caveat of using this syntax in conjunction with
245       side-effect notation.  The following directive does not behave as might
246       be expected:
247
248           [% var = 'value' IF some_condition %]   # does not work
249
250       In this case, the directive is interpreted as (spacing added for
251       clarity)
252
253           [% var = IF some_condition %]
254              value
255           [% END %]
256
257       rather than
258
259           [% IF some_condition %]
260              [% var = 'value' %]
261           [% END %]
262
263       The variable is assigned the output of the "IF" block which returns
264       'value' if true, but nothing if false.  In other words, the following
265       directive will always cause 'var' to be cleared.
266
267           [% var = 'value' IF 0 %]
268
269       To achieve the expected behaviour, the directive should be written as:
270
271           [% SET var = 'value' IF some_condition %]
272

Chaining Filters

274       Multiple "FILTER" directives can be chained together in sequence.  They
275       are called in the order defined, piping the output of one into the
276       input of the next.
277
278           [% PROCESS somefile FILTER truncate(100) FILTER html %]
279
280       The pipe character, "|", can also be used as an alias for "FILTER".
281
282           [% PROCESS somefile | truncate(100) | html %]
283

Multiple Directive Blocks

285       Multiple directives can be included within a single tag when delimited
286       by semi-colons.  Note however that the "TAGS" directive must always be
287       specified in a tag by itself.
288
289           [% IF title;
290                 INCLUDE header;
291              ELSE;
292                 INCLUDE other/header  title="Some Other Title";
293              END
294           %]
295
296       versus
297
298           [% IF title %]
299              [% INCLUDE header %]
300           [% ELSE %]
301              [% INCLUDE other/header  title="Some Other Title" %]
302           [% END %]
303
304
305
306perl v5.36.0                      2022-07-22       Template::Manual::Syntax(3)
Impressum