Template::Manual::Syntax(3pm)

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

NAME

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

DESCRIPTION

9       Tag Styles
10
11       By default, template directives are embedded within the character
12       sequences '[%' and '%]'.  e.g.
13
14           [% PROCESS header %]
15
16           <h1>Hello World!</h1>
17           <a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
18
19           [% PROCESS footer %]
20
21       You can change the tag characters using the START_TAG, END_TAG and
22       TAG_STYLE configuration options.  You can also use the TAGS directive
23       to define a new tag style for the current template file.
24
25       You can also set the INTERPOLATE option to allow simple variable refer‐
26       ences to be embedded directly in templates, prefixed by a '$'.
27
28           # INTERPOLATE => 0
29           <td>[% name %]</td>  <td>[% email %]</td>
30
31           # INTERPOLATE => 1
32           <td>$name</td>  <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
47       Comments
48
49       The '#' character is used to indicate comments within a directive.
50       When placed immediately inside the opening directive tag, it causes the
51       entire directive to be ignored.
52
53           [%# this entire directive is ignored no
54               matter how many lines it wraps onto
55           %]
56
57       In any other position, it causes the remainder of the current line to
58       be treated as a comment.
59
60           [% # this is a comment
61              theta = 20      # so is this
62              rho   = 30      # <aol>me too!</aol>
63           %]
64
65       Chomping Whitespace
66
67       You can add '-' or '+' to the immediate start or end of a directive tag
68       to control the whitespace chomping options.  See the PRE_CHOMP and
69       POST_CHOMP options for further details.
70
71           [% BLOCK foo -%]            # remove trailing newline
72           This is block foo
73           [%- END %]                  # remove leading newline
74
75       Implicit Directives: GET and SET
76
77       The simplest directives are GET and SET which retrieve and update vari‐
78       able values respectively.  The GET and SET keywords are actually
79       optional as the parser is smart enough to see them for what they really
80       are (but note the caveat below on using side-effect notation).  Thus,
81       you'll generally see:
82
83           [% SET foo = 10 %]
84           [% GET foo %]
85
86       written as:
87
88           [% foo = 10 %]
89           [% foo %]
90
91       You can also express simple logical statements as implicit GET direc‐
92       tives:
93
94           [% title or template.title or 'Default Title' %]
95
96           [% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]
97
98       All other directives should start with a keyword specified in UPPER
99       CASE (but see the ANYCASE option).  All directives keywords are in
100       UPPER CASE to make them visually distinctive and to distinguish them
101       from variables of the same name but different case.  It is perfectly
102       valid, for example, to define a variable called 'stop' which is
103       entirely separate from the STOP directive.
104
105           [% stop = 'Clackett Lane Bus Depot' %]
106
107           The bus will next stop at [% stop %]    # variable
108
109           [% STOP %]                              # directive
110
111       Block Directives
112
113       Directives such as FOREACH, WHILE, BLOCK, FILTER, etc., mark the start
114       of a block which may contain text or other directives up to the match‐
115       ing END directive.  Blocks may be nested indefinitely.  The IF, UNLESS,
116       ELSIF and ELSE directives also define blocks and may be grouped
117       together in the usual manner.
118
119           [% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
120              * Item: [% item %]
121           [% END %]
122
123           [% BLOCK footer %]
124              Copyright 2000 [% me %]
125              [% INCLUDE company/logo %]
126           [% END %]
127
128           [% IF foo %]
129              [% FOREACH thing = foo.things %]
130                 [% thing %]
131              [% END %]
132           [% ELSIF bar %]
133              [% INCLUDE barinfo %]
134           [% ELSE %]
135              do nothing...
136           [% END %]
137
138       Block directives can also be used in a convenient side-effect notation.
139
140           [% INCLUDE userinfo FOREACH user = userlist %]
141
142           [% INCLUDE debugtxt msg="file: $error.info"
143                IF debugging %]
144
145           [% "Danger Will Robinson" IF atrisk %]
146
147       versus:
148
149           [% FOREACH user = userlist %]
150              [% INCLUDE userinfo %]
151           [% END %]
152
153           [% IF debugging %]
154              [% INCLUDE debugtxt msg="file: $error.info" %]
155           [% END %]
156
157           [% IF atrisk %]
158           Danger Will Robinson
159           [% END %]
160
161       Capturing Block Output
162
163       The output of a directive can be captured by simply assigning the
164       directive to a variable.
165
166           [% headtext = PROCESS header title="Hello World" %]
167
168           [% people = PROCESS userinfo FOREACH user = userlist %]
169
170       This can be used in conjunction with the BLOCK directive for defining
171       large blocks of text or other content.
172
173           [% poem = BLOCK %]
174              The boy stood on the burning deck,
175              His fleece was white as snow.
176              A rolling stone gathers no moss,
177              And Keith is sure to follow.
178           [% END %]
179
180       Note one important caveat of using this syntax in conjunction with
181       side-effect notation.  The following directive does not behave as might
182       be expected:
183
184           [% var = 'value' IF some_condition %]
185
186       In this case, the directive is interpreted as (spacing added for clar‐
187       ity)
188
189           [% var = IF some_condition %]
190              value
191           [% END %]
192
193       rather than
194
195           [% IF some_condition %]
196              [% var = 'value' %]
197           [% END %]
198
199       The variable is assigned the output of the IF block which returns
200       'value' if true, but nothing if false.  In other words, the following
201       directive will always cause 'var' to be cleared.
202
203           [% var = 'value' IF 0 %]
204
205       To achieve the expected behaviour, the directive should be written as:
206
207           [% SET var = 'value' IF some_condition %]
208
209       Chaining Filters
210
211       Multiple FILTER directives can be chained together in sequence.  They
212       are called in the order defined, piping the output of one into the
213       input of the next.
214
215           [% PROCESS somefile FILTER truncate(100) FILTER html %]
216
217       The pipe character, '⎪', can also be used as an alias for FILTER.
218
219           [% PROCESS somefile ⎪ truncate(100) ⎪ html %]
220
221       Multiple Directive Blocks
222
223       Multiple directives can be included within a single tag when delimited
224       by semi-colons, ';'.  Note however that the TAGS directive must always
225       be specified in a tag by itself.
226
227           [% IF title;
228                 INCLUDE header;
229              ELSE;
230                 INCLUDE other/header  title="Some Other Title";
231              END
232           %]
233
234       versus
235
236           [% IF title %]
237              [% INCLUDE header %]
238           [% ELSE %]
239              [% INCLUDE other/header  title="Some Other Title" %]
240           [% END %]
241

AUTHOR

243       Andy Wardley <abw@wardley.org>
244
245       <http://wardley.org/⎪http://wardley.org/>
246

VERSION

248       Template Toolkit version 2.18, released on 09 February 2007.
249

COPYRIGHT

251         Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
252
253       This module is free software; you can redistribute it and/or modify it
254       under the same terms as Perl itself.
255
256
257
258perl v5.8.8                       2007-02-09       Template::Manual::Syntax(3)