1Template::Manual::FilteUrsse(r3)Contributed Perl DocumenTteamtpiloante::Manual::Filters(3)
2
6 Template::Manual::Filters - Standard filters
7
10 format(format)
11 The 'format' filter takes a format string as a parameter (as per
13 printf()) and formats each line of text accordingly.
14 [% FILTER format('<!-- %-40s -->') %]
16 This is a block of text filtered
17 through the above format.
18 [% END %]
19 output:
21 <!-- This is a block of text filtered -->
23 <!-- through the above format. -->
24 upper
26 Folds the input to UPPER CASE.
28 [% "hello world" FILTER upper %]
30 output:
32 HELLO WORLD
34 lower
36 Folds the input to lower case.
38 [% "Hello World" FILTER lower %]
40 output:
42 hello world
44 ucfirst
46 Folds the first character of the input to UPPER CASE.
48 [% "hello" FILTER ucfirst %]
50 output:
52 Hello
54 lcfirst
56 Folds the first character of the input to lower case.
58 [% "HELLO" FILTER lcfirst %]
60 output:
62 hELLO
64 trim
66 Trims any leading or trailing whitespace from the input text. Particu‐
68 larly useful in conjunction with INCLUDE, PROCESS, etc., having the
69 same effect as the TRIM configuration option.
70 [% INCLUDE myfile ⎪ trim %]
72 collapse
74 Collapse any whitespace sequences in the input text into a single
76 space. Leading and trailing whitespace (which would be reduced to a
77 single space) is removed, as per trim.
78 [% FILTER collapse %]
80 The cat
82 sat on
84 the mat
86 [% END %]
88 output:
90 The cat sat on the mat
92 html
94 Converts the characters '<', '>', '&' and '"' to '<', '>',
96 '&', and '"' respectively, protecting them from being inter‐
97 preted as representing HTML tags or entities.
98 [% FILTER html %]
100 Binary "<=>" returns -1, 0, or 1 depending on...
101 [% END %]
102 output:
104 Binary "<=>" returns -1, 0, or 1 depending on...
106 html_entity
108 The html filter is fast and simple but it doesn't encode the full range
110 of HTML entities that your text may contain. The html_entity filter
111 uses either the Apache::Util module (which is written in C and is
112 therefore faster) or the HTML::Entities module (written in Perl but
113 equally as comprehensive) to perform the encoding. If one or other of
114 these modules are installed on your system then the text will be
115 encoded (via the escape_html() or encode_entities() subroutines respec‐
116 tively) to convert all extended characters into their appropriate HTML
117 entities (e.g. converting 'é' to 'é'). If neither module is
118 available on your system then an 'html_entity' exception will be thrown
119 reporting an appropriate message.
120 For further information on HTML entity encoding, see
122 http://www.w3.org/TR/REC-html40/sgml/entities.html.
123 html_para
125 This filter formats a block of text into HTML paragraphs. A sequence
127 of two or more newlines is used as the delimiter for paragraphs which
128 are then wrapped in HTML <p>...</p> tags.
129 [% FILTER html_para %]
131 The cat sat on the mat.
132 Mary had a little lamb.
134 [% END %]
135 output:
137 <p>
139 The cat sat on the mat.
140 </p>
141 <p>
143 Mary had a little lamb.
144 </p>
145 html_break / html_para_break
147 Similar to the html_para filter described above, but uses the HTML tag
149 sequence <br><br> to join paragraphs.
150 [% FILTER html_break %]
152 The cat sat on the mat.
153 Mary had a little lamb.
155 [% END %]
156 output:
158 The cat sat on the mat.
160 <br>
161 <br>
162 Mary had a little lamb.
163 html_line_break
165 This filter replaces any newlines with <br> HTML tags, thus preserving
167 the line breaks of the original text in the HTML output.
168 [% FILTER html_line_break %]
170 The cat sat on the mat.
171 Mary had a little lamb.
172 [% END %]
173 output:
175 The cat sat on the mat.<br>
177 Mary had a little lamb.<br>
178 uri
180 This filter URI escapes the input text, converting any characters out‐
182 side of the permitted URI character set (as defined by RFC 2396) into a
183 %nn hex escape.
184 [% 'my file.html' ⎪ uri %]
186 output:
188 my%20file.html
190 Note that as of TT version 2.16, the uri filter now correctly encodes
192 all reserved characters. This includes "&", "@", "/", ";", ":", "=",
193 "+", "?" and "$" which were not escaped (incorrectly) by the uri filter
194 in versions 2.15 and earlier. See RFC 2396 for further details.
195 indent(pad)
197 Indents the text block by a fixed pad string or width. The 'pad' argu‐
199 ment can be specified as a string, or as a numerical value to indicate
200 a pad width (spaces). Defaults to 4 spaces if unspecified.
201 [% FILTER indent('ME> ') %]
203 blah blah blah
204 cabbages, rhubard, onions
205 [% END %]
206 output:
208 ME> blah blah blah
210 ME> cabbages, rhubard, onions
211 truncate(length,dots)
213 Truncates the text block to the length specified, or a default length
215 of 32. Truncated text will be terminated with '...' (i.e. the '...'
216 falls inside the required length, rather than appending to it).
217 [% FILTER truncate(21) %]
219 I have much to say on this matter that has previously
220 been said on more than one occasion.
221 [% END %]
222 output:
224 I have much to say...
226 If you want to use something other than '...' you can pass that as a
228 second argument.
229 [% FILTER truncate(26, '…') %]
231 I have much to say on this matter that has previously
232 been said on more than one occasion.
233 [% END %]
234 output:
236 I have much to say…
238 repeat(iterations)
240 Repeats the text block for as many iterations as are specified
242 (default: 1).
243 [% FILTER repeat(3) %]
245 We want more beer and we want more beer,
246 [% END %]
247 We are the more beer wanters!
248 output:
250 We want more beer and we want more beer,
252 We want more beer and we want more beer,
253 We want more beer and we want more beer,
254 We are the more beer wanters!
255 remove(string)
257 Searches the input text for any occurrences of the specified string and
259 removes them. A Perl regular expression may be specified as the search
260 string.
261 [% "The cat sat on the mat" FILTER remove('\s+') %]
263 output:
265 Thecatsatonthemat
267 replace(search, replace)
269 Similar to the remove filter described above, but taking a second
271 parameter which is used as a replacement string for instances of the
272 search string.
273 [% "The cat sat on the mat" ⎪ replace('\s+', '_') %]
275 output:
277 The_cat_sat_on_the_mat
279 redirect(file, options)
281 The 'redirect' filter redirects the output of the block into a separate
283 file, specified relative to the OUTPUT_PATH configuration item.
284 [% FOREACH user = myorg.userlist %]
286 [% FILTER redirect("users/${user.id}.html") %]
287 [% INCLUDE userinfo %]
288 [% END %]
289 [% END %]
290 or more succinctly, using side-effect notation:
292 [% INCLUDE userinfo
294 FILTER redirect("users/${user.id}.html")
295 FOREACH user = myorg.userlist
296 %]
297 A 'file' exception will be thrown if the OUTPUT_PATH option is unde‐
299 fined.
300 An optional 'binmode' argument can follow the filename to explicitly
302 set the output file to binary mode.
303 [% PROCESS my/png/generator
305 FILTER redirect("images/logo.png", binmode=1) %]
306 For backwards compatibility with earlier versions, a single true/false
308 value can be used to set binary mode.
309 [% PROCESS my/png/generator
311 FILTER redirect("images/logo.png", 1) %]
312 For the sake of future compatibility and clarity, if nothing else, we
314 would strongly recommend you explicitly use the named 'binmode' option
315 as shown in the first example.
316 eval / evaltt
318 The 'eval' filter evaluates the block as template text, processing any
320 directives embedded within it. This allows template variables to con‐
321 tain template fragments, or for some method to be provided for return‐
322 ing template fragments from an external source such as a database,
323 which can then be processed in the template as required.
324 my $vars = {
326 fragment => "The cat sat on the [% place %]",
327 };
328 $template->process($file, $vars);
329 The following example:
331 [% fragment ⎪ eval %]
333 is therefore equivalent to
335 The cat sat on the [% place %]
337 The 'evaltt' filter is provided as an alias for 'eval'.
339 perl / evalperl
341 The 'perl' filter evaluates the block as Perl code. The EVAL_PERL
343 option must be set to a true value or a 'perl' exception will be
344 thrown.
345 [% my_perl_code ⎪ perl %]
347 In most cases, the [% PERL %] ... [% END %] block should suffice for
349 evaluating Perl code, given that template directives are processed
350 before being evaluate as Perl. Thus, the previous example could have
351 been written in the more verbose form:
352 [% PERL %]
354 [% my_perl_code %]
355 [% END %]
356 as well as
358 [% FILTER perl %]
360 [% my_perl_code %]
361 [% END %]
362 The 'evalperl' filter is provided as an alias for 'perl' for backwards
364 compatibility.
365 stdout(options)
367 The stdout filter prints the output generated by the enclosing block to
369 STDOUT. The 'binmode' option can be passed as either a named parameter
370 or a single argument to set STDOUT to binary mode (see the binmode perl
371 function).
372 [% PROCESS something/cool
374 FILTER stdout(binmode=1) # recommended %]
375 [% PROCESS something/cool
377 FILTER stdout(1) # alternate %]
378 The stdout filter can be used to force binmode on STDOUT, or also
380 inside redirect, null or stderr blocks to make sure that particular
381 output goes to stdout. See the null filter below for an example.
382 stderr
384 The stderr filter prints the output generated by the enclosing block to
386 STDERR.
387 null
389 The null filter prints nothing. This is useful for plugins whose meth‐
391 ods return values that you don't want to appear in the output. Rather
392 than assigning every plugin method call to a dummy variable to silence
393 it, you can wrap the block in a null filter:
394 [% FILTER null;
396 USE im = GD.Image(100,100);
397 black = im.colorAllocate(0, 0, 0);
398 red = im.colorAllocate(255,0, 0);
399 blue = im.colorAllocate(0, 0, 255);
400 im.arc(50,50,95,75,0,360,blue);
401 im.fill(50,50,red);
402 im.png ⎪ stdout(1);
403 END;
404 -%]
405 Notice the use of the stdout filter to ensure that a particular expres‐
407 sion generates output to stdout (in this case in binary mode).
408 latex(outputType)
410 The latex() filter is no longer part of the core Template Toolkit dis‐
412 tribution as of version 2.15. You can download it as a separate Tem‐
413 plate-Latex distribution from CPAN.
414
416 Andy Wardley <abw@wardley.org>
417 <http://wardley.org/⎪http://wardley.org/>
419
421 Template Toolkit version 2.18, released on 09 February 2007.
422
424 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
425 This module is free software; you can redistribute it and/or modify it
427 under the same terms as Perl itself.
428perl v5.8.8 2007-02-09 Template::Manual::Filters(3)