1Template::Manual::FilteUrsse(r3)Contributed Perl DocumenTteamtpiloante::Manual::Filters(3)
2
3
4

NAME

6       Template::Manual::Filters - Standard filters
7

format(format)

9       The "format" filter takes a format string as a parameter (as per
10       "printf()") and formats each line of text accordingly.
11
12           [% FILTER format('<!-- %-40s -->') %]
13           This is a block of text filtered
14           through the above format.
15           [% END %]
16
17       Output:
18
19           <!-- This is a block of text filtered        -->
20           <!-- through the above format.               -->
21

upper

23       Folds the input to UPPER CASE.
24
25           [% "hello world" FILTER upper %]
26
27       Output:
28
29           HELLO WORLD
30

lower

32       Folds the input to lower case.
33
34           [% "Hello World" FILTER lower %]
35
36       Output:
37
38           hello world
39

ucfirst

41       Folds the first character of the input to UPPER CASE.
42
43           [% "hello" FILTER ucfirst %]
44
45       Output:
46
47           Hello
48

lcfirst

50       Folds the first character of the input to lower case.
51
52           [% "HELLO" FILTER lcfirst %]
53
54       Output:
55
56           hELLO
57

trim

59       Trims any leading or trailing whitespace from the input text.
60       Particularly useful in conjunction with "INCLUDE", "PROCESS", etc.,
61       having the same effect as the "TRIM" configuration option.
62
63           [% INCLUDE myfile | trim %]
64

collapse

66       Collapse any whitespace sequences in the input text into a single
67       space.  Leading and trailing whitespace (which would be reduced to a
68       single space) is removed, as per trim.
69
70           [% FILTER collapse %]
71
72              The   cat
73
74              sat    on
75
76              the   mat
77
78           [% END %]
79
80       Output:
81
82           The cat sat on the mat
83

html

85       Converts the characters "<", ">", "&" and """ to "&lt;", "&gt;",
86       "&amp;", and "&quot;" respectively, protecting them from being
87       interpreted as representing HTML tags or entities.
88
89           [% FILTER html %]
90           Binary "<=>" returns -1, 0, or 1 depending on...
91           [% END %]
92
93       Output:
94
95           Binary "&lt;=&gt;" returns -1, 0, or 1 depending on...
96

html_entity

98       The "html" filter is fast and simple but it doesn't encode the full
99       range of HTML entities that your text may contain.  The "html_entity"
100       filter uses either the "Apache::Util" module (which is written in C and
101       is therefore faster) or the "HTML::Entities" module (written in Perl
102       but equally as comprehensive) to perform the encoding.
103
104       If one or other of these modules are installed on your system then the
105       text will be encoded (via the "escape_html()" or "encode_entities()"
106       subroutines respectively) to convert all extended characters into their
107       appropriate HTML entities (e.g. converting '"?"' to '"&eacute;"'). If
108       neither module is available on your system then an '"html_entity"'
109       exception will be thrown reporting an appropriate message.
110
111       If you want to force TT to use one of the above modules in preference
112       to the other, then call either of the Template::Filters class methods:
113       use_html_entities() or use_apache_util().
114
115           use Template::Filters;
116           Template::Filters->use_html_entities;
117
118       For further information on HTML entity encoding, see
119       <http://www.w3.org/TR/REC-html40/sgml/entities.html>.
120

xml

122       Same as the "html" filter, but adds "&apos;" which is the fifth XML
123       built-in entity.
124

html_para

126       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
130           [% FILTER html_para %]
131           The cat sat on the mat.
132
133           Mary had a little lamb.
134           [% END %]
135
136       Output:
137
138           <p>
139           The cat sat on the mat.
140           </p>
141
142           <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
148       sequence "<br><br>" to join paragraphs.
149
150           [% FILTER html_break %]
151           The cat sat on the mat.
152
153           Mary had a little lamb.
154           [% END %]
155
156       Output:
157
158           The cat sat on the mat.
159           <br>
160           <br>
161           Mary had a little lamb.
162

html_line_break

164       This filter replaces any newlines with "<br>" HTML tags, thus
165       preserving the line breaks of the original text in the HTML output.
166
167           [% FILTER html_line_break %]
168           The cat sat on the mat.
169           Mary had a little lamb.
170           [% END %]
171
172       Output:
173
174           The cat sat on the mat.<br>
175           Mary had a little lamb.<br>
176

uri

178       This filter URI escapes the input text, converting any characters
179       outside of the permitted URI character set (as defined by RFC 3986)
180       into a %nn hex escape.
181
182           [% 'my file.html' | uri %]
183
184       Output:
185
186           my%20file.html
187
188       The uri filter correctly encodes all reserved characters, including
189       "&", "@", "/", ";", ":", "=", "+", "?" and "$".  This filter is
190       typically used to encode parameters in a URL that could otherwise be
191       interpreted as part of the URL.  Here's an example:
192
193           [% path  = 'http://tt2.org/example'
194              back  = '/other?foo=bar&baz=bam'
195              title = 'Earth: "Mostly Harmless"'
196           %]
197           <a href="[% path %]?back=[% back | uri %]&title=[% title | uri %]">
198
199       The output generated is rather long so we'll show it split across two
200       lines:
201
202           <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26
203           baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22">
204
205       Without the uri filter the output would look like this (also split
206       across two lines).
207
208           <a href="http://tt2.org/example?back=/other?foo=bar
209           &baz=bam&title=Earth: "Mostly Harmless"">
210
211       In this rather contrived example we've manage to generate both a broken
212       URL (the repeated "?" is not allowed) and a broken HTML element (the
213       href attribute is terminated by the first """ after "Earth: " leaving
214       "Mostly Harmless"" dangling on the end of the tag in precisely the way
215       that harmless things shouldn't dangle). So don't do that. Always use
216       the uri filter to encode your URL parameters.
217
218       However, you should not use the uri filter to encode an entire URL.
219
220          <a href="[% page_url | uri %]">   # WRONG!
221
222       This will incorrectly encode any reserved characters like ":" and "/"
223       and that's almost certainly not what you want in this case.  Instead
224       you should use the url (note spelling) filter for this purpose.
225
226          <a href="[% page_url | url %]">   # CORRECT
227
228       Please note that this behaviour was changed in version 2.16 of the
229       Template Toolkit.  Prior to that, the uri filter did not encode the
230       reserved characters, making it technically incorrect according to the
231       RFC 2396 specification (since superceded by RFC2732 and RFC3986).  So
232       we fixed it in 2.16 and provided the url filter to implement the old
233       behaviour of not encoding reserved characters.
234
235       As of version 2.28 of the Template Toolkit, the "uri" and url filters
236       use the unsafe character set defined by RFC3986.  This means that
237       certain characters ("(", ")", "*", "!", "'", and '"') are now deemed
238       unsafe and will be escaped as hex character sequences.
239
240       The ability to use the RFC3986 character set was added in 2.26 but not
241       enabled by default; double quote was incorrectly deemed safe in 2.26
242       but correctly escaped in 2.27.
243
244       If you want to enable the old behaviour then call the "use_rfc2732()"
245       method in Template::Filters
246
247           use Template::Filters
248           Template::Filters->use_rfc2732;
249

url

251       The url filter is a less aggressive version of the uri filter.  It
252       encodes any characters outside of the permitted URI character set (as
253       defined by RFC 2396) into %nn hex escapes.  However, unlike the uri
254       filter, the url filter does not encode the reserved characters "&",
255       "@", "/", ";", ":", "=", "+", "?" and "$".
256

indent(pad)

258       Indents the text block by a fixed pad string or width.  The '"pad"'
259       argument can be specified as a string, or as a numerical value to
260       indicate a pad width (spaces).  Defaults to 4 spaces if unspecified.
261
262           [% FILTER indent('ME> ') %]
263           blah blah blah
264           cabbages, rhubard, onions
265           [% END %]
266
267       Output:
268
269           ME> blah blah blah
270           ME> cabbages, rhubard, onions
271

truncate(length,dots)

273       Truncates the text block to the length specified, or a default length
274       of 32.  Truncated text will be terminated with '"..."' (i.e. the
275       '"..."'  falls inside the required length, rather than appending to
276       it).
277
278           [% FILTER truncate(21) %]
279           I have much to say on this matter that has previously
280           been said on more than one occasion.
281           [% END %]
282
283       Output:
284
285           I have much to say...
286
287       If you want to use something other than '"..."' you can pass that as a
288       second argument.
289
290           [% FILTER truncate(26, '&hellip;') %]
291           I have much to say on this matter that has previously
292           been said on more than one occasion.
293           [% END %]
294
295       Output:
296
297           I have much to say&hellip;
298

repeat(iterations)

300       Repeats the text block for as many iterations as are specified
301       (default: 1).
302
303           [% FILTER repeat(3) %]
304           We want more beer and we want more beer,
305           [% END %]
306           We are the more beer wanters!
307
308       Output:
309
310           We want more beer and we want more beer,
311           We want more beer and we want more beer,
312           We want more beer and we want more beer,
313           We are the more beer wanters!
314

remove(string)

316       Searches the input text for any occurrences of the specified string and
317       removes them.  A Perl regular expression may be specified as the search
318       string.
319
320           [% "The  cat  sat  on  the  mat" FILTER remove('\s+') %]
321
322       Output:
323
324           Thecatsatonthemat
325

replace(search, replace)

327       Similar to the remove filter described above, but taking a second
328       parameter which is used as a replacement string for instances of the
329       search string.
330
331           [% "The  cat  sat  on  the  mat" | replace('\s+', '_') %]
332
333       Output:
334
335           The_cat_sat_on_the_mat
336

redirect(file, options)

338       The "redirect" filter redirects the output of the block into a separate
339       file, specified relative to the "OUTPUT_PATH" configuration item.
340
341           [% FOREACH user IN myorg.userlist %]
342              [% FILTER redirect("users/${user.id}.html") %]
343                 [% INCLUDE userinfo %]
344              [% END %]
345           [% END %]
346
347       or more succinctly, using side-effect notation:
348
349           [%  FOREACH user IN myorg.userlist;
350                 INCLUDE userinfo
351                   FILTER redirect("users/${user.id}.html");
352               END
353           %]
354
355       A "file" exception will be thrown if the "OUTPUT_PATH" option is
356       undefined.
357
358       An optional "binmode" argument can follow the filename to explicitly
359       set the output file to binary mode.
360
361           [% PROCESS my/png/generator
362                FILTER redirect("images/logo.png", binmode=1) %]
363
364       For backwards compatibility with earlier versions, a single true/false
365       value can be used to set binary mode.
366
367           [% PROCESS my/png/generator
368                FILTER redirect("images/logo.png", 1) %]
369
370       For the sake of future compatibility and clarity, if nothing else, we
371       would strongly recommend you explicitly use the named "binmode" option
372       as shown in the first example.
373

eval / evaltt

375       The "eval" filter evaluates the block as template text, processing any
376       directives embedded within it.  This allows template variables to
377       contain template fragments, or for some method to be provided for
378       returning template fragments from an external source such as a
379       database, which can then be processed in the template as required.
380
381           my $vars  = {
382               fragment => "The cat sat on the [% place %]",
383           };
384           $template->process($file, $vars);
385
386       The following example:
387
388           [% fragment | eval %]
389
390       is therefore equivalent to
391
392           The cat sat on the [% place %]
393
394       The "evaltt" filter is provided as an alias for "eval".
395

perl / evalperl

397       The "perl" filter evaluates the block as Perl code.  The "EVAL_PERL"
398       option must be set to a true value or a "perl" exception will be
399       thrown.
400
401           [% my_perl_code | perl %]
402
403       In most cases, the "[% PERL %]" ... "[% END %]" block should suffice
404       for evaluating Perl code, given that template directives are processed
405       before being evaluate as Perl.  Thus, the previous example could have
406       been written in the more verbose form:
407
408           [% PERL %]
409           [% my_perl_code %]
410           [% END %]
411
412       as well as
413
414           [% FILTER perl %]
415           [% my_perl_code %]
416           [% END %]
417
418       The "evalperl" filter is provided as an alias for "perl" for backwards
419       compatibility.
420

stdout(options)

422       The stdout filter prints the output generated by the enclosing block to
423       "STDOUT".  The "binmode" option can be passed as either a named
424       parameter or a single argument to set "STDOUT" to binary mode (see the
425       binmode perl function).
426
427           [% PROCESS something/cool
428                  FILTER stdout(binmode=1) # recommended %]
429
430           [% PROCESS something/cool
431                  FILTER stdout(1)         # alternate %]
432
433       The "stdout" filter can be used to force "binmode" on "STDOUT", or also
434       inside "redirect", "null" or "stderr" blocks to make sure that
435       particular output goes to "STDOUT". See the "null" filter below for an
436       example.
437

stderr

439       The stderr filter prints the output generated by the enclosing block to
440       "STDERR".
441

null

443       The "null" filter prints nothing.  This is useful for plugins whose
444       methods return values that you don't want to appear in the output.
445       Rather than assigning every plugin method call to a dummy variable to
446       silence it, you can wrap the block in a null filter:
447
448           [% FILTER null;
449               USE im = GD.Image(100,100);
450               black = im.colorAllocate(0,   0, 0);
451               red   = im.colorAllocate(255,0,  0);
452               blue  = im.colorAllocate(0,  0,  255);
453               im.arc(50,50,95,75,0,360,blue);
454               im.fill(50,50,red);
455               im.png | stdout(1);
456              END;
457           -%]
458
459       Notice the use of the "stdout" filter to ensure that a particular
460       expression generates output to "STDOUT" (in this case in binary mode).
461
462
463
464perl v5.30.1                      2020-01-30      Template::Manual::Filters(3)
Impressum