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       By default, template directives are embedded within the character
10       sequences "[%" 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

Comments

48       The "#" character is used to indicate comments within a directive.
49       When placed immediately inside the opening directive tag, it causes the
50       entire directive to be ignored.
51
52           [%# this entire directive is ignored no
53               matter how many lines it wraps onto
54           %]
55
56       In any other position, it causes the remainder of the current line to
57       be treated as a comment.
58
59           [% # this is a comment
60              theta = 20      # so is this
61              rho   = 30      # <aol>me too!</aol>
62           %]
63

Chomping Whitespace

65       You can add "-" or "+" to the immediate start or end of a directive tag
66       to control the whitespace chomping options.  See the "PRE_CHOMP" and
67       "POST_CHOMP" options for further details.
68
69           [% BLOCK foo -%]    # remove trailing newline
70           This is block foo
71           [%- END %]          # remove leading newline
72

Implicit Directives: GET and SET

74       The simplest directives are "GET" and "SET" which retrieve and update
75       variable values respectively. The "GET" and "SET" keywords are actually
76       optional as the parser is smart enough to see them for what they really
77       are (but note the caveat below on using side-effect notation). Thus,
78       you'll generally see:
79
80           [% SET foo = 10 %]
81           [% GET foo %]
82
83       written as:
84
85           [% foo = 10 %]
86           [% foo %]
87
88       You can also express simple logical statements as implicit "GET"
89       directives:
90
91           [% title or template.title or 'Default Title' %]
92
93           [% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]
94
95       All other directives should start with a keyword specified in UPPER
96       CASE (but see the "ANYCASE" option).  All directives keywords are in
97       UPPER CASE to make them visually distinctive and to distinguish them
98       from variables of the same name but different case.  It is perfectly
99       valid, for example, to define a variable called "stop" which is
100       entirely separate from the "STOP" directive.
101
102           [% stop = 'Clackett Lane Bus Depot' %]
103
104           The bus will next stop at [% stop %]    # variable
105
106           [% STOP %]                              # directive
107

Block Directives

109       Directives such as "FOREACH", "WHILE", "BLOCK", "FILTER", etc., mark
110       the start of a block which may contain text or other directives up to
111       the matching "END" directive. Blocks may be nested indefinitely. The
112       "IF", "UNLESS", "ELSIF" and "ELSE" directives also define blocks and
113       may be grouped together in the usual manner.
114
115           [% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
116              * Item: [% item %]
117           [% END %]
118
119           [% BLOCK footer %]
120              Copyright 2000 [% me %]
121              [% INCLUDE company/logo %]
122           [% END %]
123
124           [% IF foo %]
125              [% FOREACH thing = foo.things %]
126                 [% thing %]
127              [% END %]
128           [% ELSIF bar %]
129              [% INCLUDE barinfo %]
130           [% ELSE %]
131              do nothing...
132           [% END %]
133
134       Block directives can also be used in a convenient side-effect notation.
135
136           [% INCLUDE userinfo FOREACH user = userlist %]
137
138           [% INCLUDE debugtxt msg="file: $error.info"
139                IF debugging %]
140
141           [% "Danger Will Robinson" IF atrisk %]
142
143       versus:
144
145           [% FOREACH user = userlist %]
146              [% INCLUDE userinfo %]
147           [% END %]
148
149           [% IF debugging %]
150              [% INCLUDE debugtxt msg="file: $error.info" %]
151           [% END %]
152
153           [% IF atrisk %]
154           Danger Will Robinson
155           [% END %]
156

Capturing Block Output

158       The output of a directive can be captured by simply assigning the
159       directive to a variable.
160
161           [% headtext = PROCESS header title="Hello World" %]
162
163           [% people = PROCESS userinfo FOREACH user = userlist %]
164
165       This can be used in conjunction with the "BLOCK" directive for defining
166       large blocks of text or other content.
167
168           [% poem = BLOCK %]
169              The boy stood on the burning deck,
170              His fleece was white as snow.
171              A rolling stone gathers no moss,
172              And Keith is sure to follow.
173           [% END %]
174
175       Note one important caveat of using this syntax in conjunction with
176       side-effect notation.  The following directive does not behave as might
177       be expected:
178
179           [% var = 'value' IF some_condition %]   # does not work
180
181       In this case, the directive is interpreted as (spacing added for
182       clarity)
183
184           [% var = IF some_condition %]
185              value
186           [% END %]
187
188       rather than
189
190           [% IF some_condition %]
191              [% var = 'value' %]
192           [% END %]
193
194       The variable is assigned the output of the "IF" block which returns
195       'value' if true, but nothing if false.  In other words, the following
196       directive will always cause 'var' to be cleared.
197
198           [% var = 'value' IF 0 %]
199
200       To achieve the expected behaviour, the directive should be written as:
201
202           [% SET var = 'value' IF some_condition %]
203

Chaining Filters

205       Multiple "FILTER" directives can be chained together in sequence.  They
206       are called in the order defined, piping the output of one into the
207       input of the next.
208
209           [% PROCESS somefile FILTER truncate(100) FILTER html %]
210
211       The pipe character, "|", can also be used as an alias for "FILTER".
212
213           [% PROCESS somefile | truncate(100) | html %]
214

Multiple Directive Blocks

216       Multiple directives can be included within a single tag when delimited
217       by semi-colons.  Note however that the "TAGS" directive must always be
218       specified in a tag by itself.
219
220           [% IF title;
221                 INCLUDE header;
222              ELSE;
223                 INCLUDE other/header  title="Some Other Title";
224              END
225           %]
226
227       versus
228
229           [% IF title %]
230              [% INCLUDE header %]
231           [% ELSE %]
232              [% INCLUDE other/header  title="Some Other Title" %]
233           [% END %]
234
235
236
237perl v5.12.0                      2008-11-13       Template::Manual::Syntax(3)