1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html>
<head>
<title>Template::Manual::Syntax</title>
<link rel="stylesheet" type="text/css" href="../css/blue.css" title="Clear Blue">
<link rel="alternate stylesheet" type="text/css" href="../css/orange.css" title="Clear Orange">
<link rel="alternate stylesheet" type="text/css" href="../css/green.css" title="Clear Green">
<link rel="alternate stylesheet" type="text/css" href="../css/purple.css" title="Clear Purple">
<link rel="alternate stylesheet" type="text/css" href="../css/grey.css" title="Clear Grey">
<link rel="alternate stylesheet" type="text/css" href="../css/print.css" title="Print">
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../css/ie6.css" />
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="../css/ie7.css" />
<![endif]-->
<link rel="stylesheet" type="text/css" href="../css/print.css" media="print">
<script type="text/javascript" src="../js/tt2.js"></script>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="author" content="Andy Wardley">
</head>
<body id="body">
<div id="layout">
<div id="header">
<a href="../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
<ul id="trail">
<li><a href="../manual/index.html">Manual</a></li>
<li class="last"><a href="../manual/Syntax.html">Syntax</a></li>
</ul>
<div class="controls">
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
<span class="about">Click to view the menu. It's very nice.</span>
</a>
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
<span class="about">Click to hide the menu and go all widescreen!</span>
</a>
<div class="pager">
<a href="../manual/Intro.html" title="Template::Manual::Intro" class="go back">Back<span class="about"><h4>Template::Manual::Intro</h4>Introduction to the Template Toolkit</span></a>
<a href="../manual/index.html" title="Template::Manual" class="go up">Up<span class="about"><h4>Template::Manual</h4>Template Toolkit User Manual</span></a>
<a href="../manual/Directives.html" title="Template::Manual::Directives" class="go next">Next<span class="about"><h4>Template::Manual::Directives</h4>Template directives</span></a>
</div>
</div>
<h1 class="headline">Template::Manual::Syntax</h1>
<h2 class="subhead">Directive syntax, structure and semantics</h1>
</div>
<div id="page">
<div id="sidebar">
<a href="../index.html" id="logo"></a>
<div id="menu">
<ul class="menu">
<li class="l0 first"><a href="../manual/index.html" class="warm">Manual</a></li>
<li class="l1"><a href="../manual/Intro.html">Intro</a></li>
<li class="l1"><a href="../manual/Syntax.html" class="warm">Syntax</a></li>
<li class="l1"><a href="../manual/Directives.html">Directives</a></li>
<li class="l1"><a href="../manual/Variables.html">Variables</a></li>
<li class="l1"><a href="../manual/VMethods.html">VMethods</a></li>
<li class="l1"><a href="../manual/Config.html">Config</a></li>
<li class="l1"><a href="../manual/Filters.html">Filters</a></li>
<li class="l1"><a href="../manual/Plugins.html">Plugins</a></li>
<li class="l1"><a href="../manual/Internals.html">Internals</a></li>
<li class="l1"><a href="../manual/Views.html">Views</a></li>
<li class="l1"><a href="../manual/Credits.html">Credits</a></li>
<li class="l0"><a href="../modules/index.html">Modules</a></li>
<li class="l0"><a href="../tools/index.html">Tools</a></li>
<li class="l0"><a href="../tutorial/index.html">Tutorial</a></li>
<li class="l0 last"><a href="../faq/index.html">FAQ</a></li>
</ul>
<div class="foot"></div>
</div>
</div>
<div id="content">
<div class="section">
<div class="head">
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<ul class="toc">
<li class=""><a href="#Tag_Styles">Tag Styles</a></li>
<li class=""><a href="#Comments">Comments</a></li>
<li class=""><a href="#Chomping_Whitespace">Chomping Whitespace</a></li>
<li class=""><a href="#Implicit_Directives_GET_and_SET">Implicit Directives: GET and SET</a></li>
<li class=""><a href="#Block_Directives">Block Directives</a></li>
<li class=""><a href="#Capturing_Block_Output">Capturing Block Output</a></li>
<li class=""><a href="#Chaining_Filters">Chaining Filters</a></li>
<li class=""><a href="#Multiple_Directive_Blocks">Multiple Directive Blocks</a></li>
</ul>
</div>
</div>
<div class="pod">
<div class="section">
<div class="head">
<h1 id="Tag_Styles" onclick="switch_section(this)" title="Click title to show/hide section content.">Tag Styles</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
By default, template directives are embedded within the character
sequences <code>[%</code> and <code>%]</code>.
</p>
<pre><span class="tt">[% PROCESS header %]</span>
<h1>Hello World!</h1>
<a href="<span class="tt">[% page.next %]</span>"><img src="<span class="tt">[% icon.next %]</span>.gif"></a>
<span class="tt">[% PROCESS footer %]</span></pre>
<p>
You can change the tag characters using the <code>START_TAG</code>,
<code>END_TAG</code> and <code>TAG_STYLE</code> configuration options.
You can also use the <code>TAGS</code> directive to define a new tag
style for the current template file.
</p>
<p>
You can also set the <code>INTERPOLATE</code> option to allow simple
variable references to be embedded directly in templates, prefixed by a
<code>$</code>.
</p>
<pre># INTERPOLATE = 0
<td><span class="tt">[% name %]</span></td>
<td><span class="tt">[% email %]</span></td>
# INTERPOLATE = 1
<td>$name</td>
<td>$email</td></pre>
<p>
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.
</p>
<pre><span class="tt">[% INCLUDE header
title = 'Hello World'
bgcol = '#ffffff'
%]</span>
<span class="tt">[%INCLUDE menu align='right'%]</span>
Name: <span class="tt">[% name %]</span> (<span class="tt">[%id%]</span>)</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Comments" onclick="switch_section(this)" title="Click title to show/hide section content.">Comments</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>#</code> 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.
</p>
<pre><span class="tt">[%# this entire directive is ignored no
matter how many lines it wraps onto
%]</span></pre>
<p>
In any other position, it causes the remainder of the current line to be
treated as a comment.
</p>
<pre><span class="tt">[% # this is a comment
theta = 20 # so is this
rho = 30 # <aol>me too!</aol>
%]</span></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Chomping_Whitespace" onclick="switch_section(this)" title="Click title to show/hide section content.">Chomping Whitespace</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
You can add <code>-</code> or <code>+</code> to the immediate start or
end of a directive tag to control the whitespace chomping options. See
the <code>PRE_CHOMP</code> and <code>POST_CHOMP</code> options for
further details.
</p>
<pre><span class="tt">[% BLOCK foo -%]</span> # remove trailing newline
This is block foo
<span class="tt">[%- END %]</span> # remove leading newline</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Implicit_Directives_GET_and_SET" onclick="switch_section(this)" title="Click title to show/hide section content.">Implicit Directives: GET and SET</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The simplest directives are <code>GET</code> and <code>SET</code> which
retrieve and update variable values respectively. The <code>GET</code>
and <code>SET</code> 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:
</p>
<pre><span class="tt">[% SET foo = 10 %]</span>
<span class="tt">[% GET foo %]</span></pre>
<p>
written as:
</p>
<pre><span class="tt">[% foo = 10 %]</span>
<span class="tt">[% foo %]</span></pre>
<p>
You can also express simple logical statements as implicit
<code>GET</code> directives:
</p>
<pre><span class="tt">[% title or template.title or 'Default Title' %]</span>
<span class="tt">[% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]</span></pre>
<p>
All other directives should start with a keyword specified in UPPER CASE
(but see the <code>ANYCASE</code> 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 <code>stop</code> which is entirely
separate from the <code>STOP</code> directive.
</p>
<pre><span class="tt">[% stop = 'Clackett Lane Bus Depot' %]</span>
The bus will next stop at <span class="tt">[% stop %]</span> # variable
<span class="tt">[% STOP %]</span> # directive</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Block_Directives" onclick="switch_section(this)" title="Click title to show/hide section content.">Block Directives</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Directives such as <code>FOREACH</code>, <code>WHILE</code>,
<code>BLOCK</code>, <code>FILTER</code>, etc., mark the start of a block
which may contain text or other directives up to the matching
<code>END</code> directive. Blocks may be nested indefinitely. The
<code>IF</code>, <code>UNLESS</code>, <code>ELSIF</code> and
<code>ELSE</code> directives also define blocks and may be grouped
together in the usual manner.
</p>
<pre><span class="tt">[% FOREACH item = [ 'foo' 'bar' 'baz' ] %]</span>
* Item: <span class="tt">[% item %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% BLOCK footer %]</span>
Copyright 2000 <span class="tt">[% me %]</span>
<span class="tt">[% INCLUDE company/logo %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% IF foo %]</span>
<span class="tt">[% FOREACH thing = foo.things %]</span>
<span class="tt">[% thing %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% ELSIF bar %]</span>
<span class="tt">[% INCLUDE barinfo %]</span>
<span class="tt">[% ELSE %]</span>
do nothing...
<span class="tt">[% END %]</span></pre>
<p>
Block directives can also be used in a convenient side-effect notation.
</p>
<pre><span class="tt">[% INCLUDE userinfo FOREACH user = userlist %]</span>
<span class="tt">[% INCLUDE debugtxt msg="file: $error.info"
IF debugging %]</span>
<span class="tt">[% "Danger Will Robinson" IF atrisk %]</span></pre>
<p>
versus:
</p>
<pre><span class="tt">[% FOREACH user = userlist %]</span>
<span class="tt">[% INCLUDE userinfo %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% IF debugging %]</span>
<span class="tt">[% INCLUDE debugtxt msg="file: $error.info" %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% IF atrisk %]</span>
Danger Will Robinson
<span class="tt">[% END %]</span></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Capturing_Block_Output" onclick="switch_section(this)" title="Click title to show/hide section content.">Capturing Block Output</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The output of a directive can be captured by simply assigning the
directive to a variable.
</p>
<pre><span class="tt">[% headtext = PROCESS header title="Hello World" %]</span>
<span class="tt">[% people = PROCESS userinfo FOREACH user = userlist %]</span></pre>
<p>
This can be used in conjunction with the <code>BLOCK</code> directive for
defining large blocks of text or other content.
</p>
<pre><span class="tt">[% poem = BLOCK %]</span>
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.
<span class="tt">[% END %]</span></pre>
<p>
Note one important caveat of using this syntax in conjunction with
side-effect notation. The following directive does not behave as might be
expected:
</p>
<pre><span class="tt">[% var = 'value' IF some_condition %]</span> # does not work</pre>
<p>
In this case, the directive is interpreted as (spacing added for clarity)
</p>
<pre><span class="tt">[% var = IF some_condition %]</span>
value
<span class="tt">[% END %]</span></pre>
<p>
rather than
</p>
<pre><span class="tt">[% IF some_condition %]</span>
<span class="tt">[% var = 'value' %]</span>
<span class="tt">[% END %]</span></pre>
<p>
The variable is assigned the output of the <code>IF</code> block which
returns <code>'value'</code> if true, but nothing if false. In other
words, the following directive will always cause 'var' to be cleared.
</p>
<pre><span class="tt">[% var = 'value' IF 0 %]</span></pre>
<p>
To achieve the expected behaviour, the directive should be written as:
</p>
<pre><span class="tt">[% SET var = 'value' IF some_condition %]</span></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Chaining_Filters" onclick="switch_section(this)" title="Click title to show/hide section content.">Chaining Filters</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Multiple <code>FILTER</code> 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.
</p>
<pre><span class="tt">[% PROCESS somefile FILTER truncate(100) FILTER html %]</span></pre>
<p>
The pipe character, <code>|</code>, can also be used as an alias for
<code>FILTER</code>.
</p>
<pre><span class="tt">[% PROCESS somefile | truncate(100) | html %]</span></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Multiple_Directive_Blocks" onclick="switch_section(this)" title="Click title to show/hide section content.">Multiple Directive Blocks</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Multiple directives can be included within a single tag when delimited by
semi-colons. Note however that the <code>TAGS</code> directive must
always be specified in a tag by itself.
</p>
<pre><span class="tt">[% IF title;
INCLUDE header;
ELSE;
INCLUDE other/header title="Some Other Title";
END
%]</span></pre>
<p>
versus
</p>
<pre><span class="tt">[% IF title %]</span>
<span class="tt">[% INCLUDE header %]</span>
<span class="tt">[% ELSE %]</span>
<span class="tt">[% INCLUDE other/header title="Some Other Title" %]</span>
<span class="tt">[% END %]</span></pre>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
<a href="http://template-toolkit.org/docs/manual/Syntax.html">http://template-toolkit.org/docs/manual/Syntax.html</a>
</div>
</div>
<div id="footer">
<a href="http://opensource.org/" class="osi"></a>
<div class="controls">
<div class="pager">
<a href="../manual/Intro.html" title="Template::Manual::Intro" class="go back">Back<span class="about"><h4>Template::Manual::Intro</h4></span></a>
<a href="../manual/index.html" title="Template::Manual" class="go up">Up<span class="about"><h4>Template::Manual</h4></span></a>
<a href="../manual/Directives.html" title="Template::Manual::Directives" class="go next">Next<span class="about"><h4>Template::Manual::Directives</h4></span></a>
</div>
</div>
<div class="copyright">
Copyright © 1996-2012 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
</div>
<div class="licence">
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
</div>
</div>
<div id="palette">
<ul>
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
</ul>
</div>
</div> </body>
</html>
|
