1Template::Manual::SyntaUxs(e3r)Contributed Perl DocumentTaetmipolnate::Manual::Syntax(3)
2
6 Template::Manual::Syntax - Directive syntax, structure and semantics
7
9 Template directives are embedded between start and end markers tags.
10 By default these tag markers are "[%" and "%]".
11 [% PROCESS header %]
13 <h1>Hello World!</h1>
15 <a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
16 [% PROCESS footer %]
18 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 You can also set the "INTERPOLATE" option to allow simple variable
24 references to be embedded directly in templates, prefixed by a "$".
25 # INTERPOLATE = 0
27 <td>[% name %]</td>
28 <td>[% email %]</td>
29 # INTERPOLATE = 1
31 <td>$name</td>
32 <td>$email</td>
33 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 [% INCLUDE header
39 title = 'Hello World'
40 bgcol = '#ffffff'
41 %]
42 [%INCLUDE menu align='right'%]
44 Name: [% name %] ([%id%])
46
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 So rather than writing something like this:
54 [% IF some.list.size -%]
56 <ul>
57 [% FOREACH item IN some.list -%]
58 <li>[% item.html %]</li>
59 [% END -%]
60 </ul>
61 [% END -%]
62 You can write it like this instead:
64 %% IF some.list.size
66 <ul>
67 %% FOREACH item IN some.list
68 <li>[% item.html %]</li>
69 %% END
70 </ul>
71 %% END
72 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 [% TAGS outline -%]
79 %% INCLUDE header
80 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 [% TAGS default -%]
85 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 my $tt = Template->new({
92 TAG_STYLE => 'outline',
93 });
94 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 my $tt = Template->new({
100 OUTLINE_TAG => '>>',
101 });
102 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 [% TAGS <* *> >> %]
108 >> INCLUDE header # outline tag
109 Hello <* name *> # inline tag
110 If you only specify a start and end tag then outline tags will be
112 disabled.
113 [% TAGS <* *> %] # no outline tags
115
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 [%# this entire directive is ignored no
122 matter how many lines it wraps onto
123 %]
124 In any other position, it causes the remainder of the current line to
126 be treated as a comment.
127 [% # this is a comment
129 theta = 20 # so is this
130 rho = 30 # <aol>me too!</aol>
131 %]
132
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 [% BLOCK foo -%] # remove trailing newline
139 This is block foo
140 [%- END %] # remove leading newline
141
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 [% SET foo = 10 %]
150 [% GET foo %]
151 written as:
153 [% foo = 10 %]
155 [% foo %]
156 You can also express simple logical statements as implicit "GET"
158 directives:
159 [% title or template.title or 'Default Title' %]
161 [% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]
163 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 [% stop = 'Clackett Lane Bus Depot' %]
172 The bus will next stop at [% stop %] # variable
174 [% STOP %] # directive
176
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 [% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
185 * Item: [% item %]
186 [% END %]
187 [% BLOCK footer %]
189 Copyright 2000 [% me %]
190 [% INCLUDE company/logo %]
191 [% END %]
192 [% 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 Block directives can also be used in a convenient side-effect notation.
204 [% INCLUDE userinfo FOREACH user = userlist %]
206 [% INCLUDE debugtxt msg="file: $error.info"
208 IF debugging %]
209 [% "Danger Will Robinson" IF atrisk %]
211 versus:
213 [% FOREACH user = userlist %]
215 [% INCLUDE userinfo %]
216 [% END %]
217 [% IF debugging %]
219 [% INCLUDE debugtxt msg="file: $error.info" %]
220 [% END %]
221 [% IF atrisk %]
223 Danger Will Robinson
224 [% END %]
225
227 The output of a directive can be captured by simply assigning the
228 directive to a variable.
229 [% headtext = PROCESS header title="Hello World" %]
231 [% people = PROCESS userinfo FOREACH user = userlist %]
233 This can be used in conjunction with the "BLOCK" directive for defining
235 large blocks of text or other content.
236 [% 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 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 [% var = 'value' IF some_condition %] # does not work
249 In this case, the directive is interpreted as (spacing added for
251 clarity)
252 [% var = IF some_condition %]
254 value
255 [% END %]
256 rather than
258 [% IF some_condition %]
260 [% var = 'value' %]
261 [% END %]
262 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 [% var = 'value' IF 0 %]
268 To achieve the expected behaviour, the directive should be written as:
270 [% SET var = 'value' IF some_condition %]
272
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 [% PROCESS somefile FILTER truncate(100) FILTER html %]
279 The pipe character, "|", can also be used as an alias for "FILTER".
281 [% PROCESS somefile | truncate(100) | html %]
283
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 [% IF title;
290 INCLUDE header;
291 ELSE;
292 INCLUDE other/header title="Some Other Title";
293 END
294 %]
295 versus
297 [% IF title %]
299 [% INCLUDE header %]
300 [% ELSE %]
301 [% INCLUDE other/header title="Some Other Title" %]
302 [% END %]
303perl v5.36.0 2022-07-22 Template::Manual::Syntax(3)