local-lib5/lib/perl5/i486-linux-gnu-thread-multi/Template/Manual/Filters.pod

   1 #============================================================= -*-perl-*-
   2 #
   3 # Template::Manual::Filters
   4 #
   5 # AUTHOR
   6 #   Andy Wardley  <abw@wardley.org>
   7 #
   8 # COPYRIGHT
   9 #   Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
  10 #
  11 #   This module is free software; you can redistribute it and/or
  12 #   modify it under the same terms as Perl itself.
  13 #
  14 #========================================================================
  15
  16 =head1 NAME
  17
  18 Template::Manual::Filters - Standard filters
  19
  20 =head1 format(format)
  21
  22 The C<format> filter takes a format string as a parameter (as per
  23 C<printf()>) and formats each line of text accordingly.
  24
  25     [% FILTER format('<!-- %-40s -->') %]
  26     This is a block of text filtered
  27     through the above format.
  28     [% END %]
  29
  30 Output:
  31
  32     <!-- This is a block of text filtered        -->
  33     <!-- through the above format.               -->
  34
  35 =head1 upper
  36
  37 Folds the input to UPPER CASE.
  38
  39     [% "hello world" FILTER upper %]
  40
  41 Output:
  42
  43     HELLO WORLD
  44
  45 =head1 lower
  46
  47 Folds the input to lower case.
  48
  49     [% "Hello World" FILTER lower %]
  50
  51 Output:
  52
  53     hello world
  54
  55 =head1 ucfirst
  56
  57 Folds the first character of the input to UPPER CASE.
  58
  59     [% "hello" FILTER ucfirst %]
  60
  61 Output:
  62
  63     Hello
  64
  65 =head1 lcfirst
  66
  67 Folds the first character of the input to lower case.
  68
  69     [% "HELLO" FILTER lcfirst %]
  70
  71 Output:
  72
  73     hELLO
  74
  75 =head1 trim
  76
  77 Trims any leading or trailing whitespace from the input text.  Particularly
  78 useful in conjunction with C<INCLUDE>, C<PROCESS>, etc., having the same effect
  79 as the C<TRIM> configuration option.
  80
  81     [% INCLUDE myfile | trim %]
  82
  83 =head1 collapse
  84
  85 Collapse any whitespace sequences in the input text into a single space.
  86 Leading and trailing whitespace (which would be reduced to a single space)
  87 is removed, as per trim.
  88
  89     [% FILTER collapse %]
  90
  91        The   cat
  92
  93        sat    on
  94
  95        the   mat
  96
  97     [% END %]
  98
  99 Output:
 100
 101     The cat sat on the mat
 102
 103 =head1 html
 104
 105 Converts the characters C<E<lt>>, C<E<gt>>, C<&> and C<"> to C<&lt;>,
 106 C<&gt;>, C<&amp;>, and C<&quot;> respectively, protecting them from being
 107 interpreted as representing HTML tags or entities.
 108
 109     [% FILTER html %]
 110     Binary "<=>" returns -1, 0, or 1 depending on...
 111     [% END %]
 112
 113 Output:
 114
 115     Binary "&lt;=&gt;" returns -1, 0, or 1 depending on...
 116
 117 =head1 html_entity
 118
 119 The C<html> filter is fast and simple but it doesn't encode the full
 120 range of HTML entities that your text may contain.  The C<html_entity>
 121 filter uses either the C<Apache::Util> module (which is written in C and
 122 is therefore faster) or the C<HTML::Entities> module (written in Perl but
 123 equally as comprehensive) to perform the encoding.
 124
 125 If one or other of these modules are installed on your system then the text
 126 will be encoded (via the C<escape_html()> or C<encode_entities()> subroutines
 127 respectively) to convert all extended characters into their appropriate HTML
 128 entities (e.g. converting 'C<é>' to 'C<&eacute;>'). If neither module is
 129 available on your system then an 'C<html_entity>' exception will be thrown
 130 reporting an appropriate message.
 131
 132 If you want to force TT to use one of the above modules in preference to
 133 the other, then call either of the L<Template::Filters> class methods:
 134 L<use_html_entities()|Template::Filters/use_html_entities()> or
 135 L<use_apache_util()|Template::Filters/use_apache_util()>.
 136
 137     use Template::Filters;
 138     Template::Filters->use_html_entities;
 139
 140 For further information on HTML entity encoding, see
 141 L<http://www.w3.org/TR/REC-html40/sgml/entities.html>.
 142
 143 =head1 xml
 144
 145 Same as the C<html> filter, but adds C<&apos;> which is the fifth XML
 146 built-in entity.
 147
 148 =head1 html_para
 149
 150 This filter formats a block of text into HTML paragraphs.  A sequence of
 151 two or more newlines is used as the delimiter for paragraphs which are
 152 then wrapped in HTML C<E<lt>pE<gt>>...C<E<lt>/pE<gt>> tags.
 153
 154     [% FILTER html_para %]
 155     The cat sat on the mat.
 156
 157     Mary had a little lamb.
 158     [% END %]
 159
 160 Output:
 161
 162     <p>
 163     The cat sat on the mat.
 164     </p>
 165
 166     <p>
 167     Mary had a little lamb.
 168     </p>
 169
 170 =head1 html_break / html_para_break
 171
 172 Similar to the html_para filter described above, but uses the HTML tag
 173 sequence C<E<lt>brE<gt>E<lt>brE<gt>> to join paragraphs.
 174
 175     [% FILTER html_break %]
 176     The cat sat on the mat.
 177
 178     Mary had a little lamb.
 179     [% END %]
 180
 181 Output:
 182
 183     The cat sat on the mat.
 184     <br>
 185     <br>
 186     Mary had a little lamb.
 187
 188 =head1 html_line_break
 189
 190 This filter replaces any newlines with C<E<lt>brE<gt>> HTML tags,
 191 thus preserving the line breaks of the original text in the
 192 HTML output.
 193
 194     [% FILTER html_line_break %]
 195     The cat sat on the mat.
 196     Mary had a little lamb.
 197     [% END %]
 198
 199 Output:
 200
 201     The cat sat on the mat.<br>
 202     Mary had a little lamb.<br>
 203
 204 =head1 uri
 205
 206 This filter URI escapes the input text, converting any characters
 207 outside of the permitted URI character set (as defined by RFC 2396)
 208 into a C<%nn> hex escape.
 209
 210     [% 'my file.html' | uri %]
 211
 212 Output:
 213
 214     my%20file.html
 215
 216 The uri filter correctly encodes all reserved characters, including
 217 C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>, C<?> and C<$>.  This filter
 218 is typically used to encode parameters in a URL that could otherwise
 219 be interpreted as part of the URL.  Here's an example:
 220
 221     [% path  = 'http://tt2.org/example'
 222        back  = '/other?foo=bar&baz=bam'
 223        title = 'Earth: "Mostly Harmless"'
 224     %]
 225     <a href="[% path %]?back=[% back | uri %]&title=[% title | uri %]">
 226
 227 The output generated is rather long so we'll show it split across two
 228 lines:
 229
 230     <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26
 231     baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22">
 232
 233 Without the uri filter the output would look like this (also split across
 234 two lines).
 235
 236     <a href="http://tt2.org/example?back=/other?foo=bar
 237     &baz=bam&title=Earth: "Mostly Harmless"">
 238
 239 In this rather contrived example we've manage to generate both a broken URL
 240 (the repeated C<?> is not allowed) and a broken HTML element (the href
 241 attribute is terminated by the first C<"> after C<Earth: > leaving C<Mostly
 242 Harmless"> dangling on the end of the tag in precisely the way that harmless
 243 things shouldn't dangle). So don't do that. Always use the uri filter to
 244 encode your URL parameters.
 245
 246 However, you should B<not> use the uri filter to encode an entire URL.
 247
 248    <a href="[% page_url | uri %]">   # WRONG!
 249
 250 This will incorrectly encode any reserved characters like C<:> and C</>
 251 and that's almost certainly not what you want in this case.  Instead
 252 you should use the B<url> (note spelling) filter for this purpose.
 253
 254    <a href="[% page_url | url %]">   # CORRECT
 255
 256 Please note that this behaviour was changed in version 2.16 of the
 257 Template Toolkit.  Prior to that, the uri filter did not encode the
 258 reserved characters, making it technically incorrect according to the
 259 RFC 2396 specification.  So we fixed it in 2.16 and provided the url
 260 filter to implement the old behaviour of not encoding reserved
 261 characters.
 262
 263 =head1 url
 264
 265 The url filter is a less aggressive version of the uri filter.  It encodes
 266 any characters outside of the permitted URI character set (as defined by RFC 2396)
 267 into C<%nn> hex escapes.  However, unlike the uri filter, the url filter does
 268 B<not> encode the reserved characters C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>,
 269 C<?> and C<$>.
 270
 271 =head1 indent(pad)
 272
 273 Indents the text block by a fixed pad string or width.  The 'C<pad>' argument
 274 can be specified as a string, or as a numerical value to indicate a pad
 275 width (spaces).  Defaults to 4 spaces if unspecified.
 276
 277     [% FILTER indent('ME> ') %]
 278     blah blah blah
 279     cabbages, rhubard, onions
 280     [% END %]
 281
 282 Output:
 283
 284     ME> blah blah blah
 285     ME> cabbages, rhubard, onions
 286
 287 =head1 truncate(length,dots)
 288
 289 Truncates the text block to the length specified, or a default length
 290 of 32.  Truncated text will be terminated with 'C<...>' (i.e. the 'C<...>'
 291 falls inside the required length, rather than appending to it).
 292
 293     [% FILTER truncate(21) %]
 294     I have much to say on this matter that has previously
 295     been said on more than one occasion.
 296     [% END %]
 297
 298 Output:
 299
 300     I have much to say...
 301
 302 If you want to use something other than 'C<...>' you can pass that as a
 303 second argument.
 304
 305     [% FILTER truncate(26, '&hellip;') %]
 306     I have much to say on this matter that has previously
 307     been said on more than one occasion.
 308     [% END %]
 309
 310 Output:
 311
 312     I have much to say&hellip;
 313
 314 =head1 repeat(iterations)
 315
 316 Repeats the text block for as many iterations as are specified (default: 1).
 317
 318     [% FILTER repeat(3) %]
 319     We want more beer and we want more beer,
 320     [% END %]
 321     We are the more beer wanters!
 322
 323 Output:
 324
 325     We want more beer and we want more beer,
 326     We want more beer and we want more beer,
 327     We want more beer and we want more beer,
 328     We are the more beer wanters!
 329
 330 =head1 remove(string)
 331
 332 Searches the input text for any occurrences of the specified string and
 333 removes them.  A Perl regular expression may be specified as the search
 334 string.
 335
 336     [% "The  cat  sat  on  the  mat" FILTER remove('\s+') %]
 337
 338 Output:
 339
 340     Thecatsatonthemat
 341
 342 =head1 replace(search, replace)
 343
 344 Similar to the remove filter described above, but taking a second parameter
 345 which is used as a replacement string for instances of the search string.
 346
 347     [% "The  cat  sat  on  the  mat" | replace('\s+', '_') %]
 348
 349 Output:
 350
 351     The_cat_sat_on_the_mat
 352
 353 =head1 redirect(file, options)
 354
 355 The C<redirect> filter redirects the output of the block into a separate
 356 file, specified relative to the C<OUTPUT_PATH> configuration item.
 357
 358     [% FOREACH user IN myorg.userlist %]
 359        [% FILTER redirect("users/${user.id}.html") %]
 360           [% INCLUDE userinfo %]
 361        [% END %]
 362     [% END %]
 363
 364 or more succinctly, using side-effect notation:
 365
 366     [%  FOREACH user IN myorg.userlist;
 367           INCLUDE userinfo
 368             FILTER redirect("users/${user.id}.html");
 369         END
 370     %]
 371
 372 A C<file> exception will be thrown if the C<OUTPUT_PATH> option is undefined.
 373
 374 An optional C<binmode> argument can follow the filename to explicitly set
 375 the output file to binary mode.
 376
 377     [% PROCESS my/png/generator
 378          FILTER redirect("images/logo.png", binmode=1) %]
 379
 380 For backwards compatibility with earlier versions, a single true/false
 381 value can be used to set binary mode.
 382
 383     [% PROCESS my/png/generator
 384          FILTER redirect("images/logo.png", 1) %]
 385
 386 For the sake of future compatibility and clarity, if nothing else, we
 387 would strongly recommend you explicitly use the named C<binmode> option
 388 as shown in the first example.
 389
 390 =head1 eval / evaltt
 391
 392 The C<eval> filter evaluates the block as template text, processing
 393 any directives embedded within it.  This allows template variables to
 394 contain template fragments, or for some method to be provided for
 395 returning template fragments from an external source such as a
 396 database, which can then be processed in the template as required.
 397
 398     my $vars  = {
 399         fragment => "The cat sat on the [% place %]",
 400     };
 401     $template->process($file, $vars);
 402
 403 The following example:
 404
 405     [% fragment | eval %]
 406
 407 is therefore equivalent to
 408
 409     The cat sat on the [% place %]
 410
 411 The C<evaltt> filter is provided as an alias for C<eval>.
 412
 413 =head1 perl / evalperl
 414
 415 The C<perl> filter evaluates the block as Perl code.  The C<EVAL_PERL>
 416 option must be set to a true value or a C<perl> exception will be
 417 thrown.
 418
 419     [% my_perl_code | perl %]
 420
 421 In most cases, the C<[% PERL %]> ... C<[% END %]> block should suffice for
 422 evaluating Perl code, given that template directives are processed
 423 before being evaluate as Perl.  Thus, the previous example could have
 424 been written in the more verbose form:
 425
 426     [% PERL %]
 427     [% my_perl_code %]
 428     [% END %]
 429
 430 as well as
 431
 432     [% FILTER perl %]
 433     [% my_perl_code %]
 434     [% END %]
 435
 436 The C<evalperl> filter is provided as an alias for C<perl> for backwards
 437 compatibility.
 438
 439 =head1 stdout(options)
 440
 441 The stdout filter prints the output generated by the enclosing block to
 442 C<STDOUT>.  The C<binmode> option can be passed as either a named parameter
 443 or a single argument to set C<STDOUT> to binary mode (see the
 444 binmode perl function).
 445
 446     [% PROCESS something/cool
 447            FILTER stdout(binmode=1) # recommended %]
 448
 449     [% PROCESS something/cool
 450            FILTER stdout(1)         # alternate %]
 451
 452 The C<stdout> filter can be used to force C<binmode> on C<STDOUT>, or also
 453 inside C<redirect>, C<null> or C<stderr> blocks to make sure that particular
 454 output goes to C<STDOUT>. See the C<null> filter below for an example.
 455
 456 =head1 stderr
 457
 458 The stderr filter prints the output generated by the enclosing block to
 459 C<STDERR>.
 460
 461 =head1 null
 462
 463 The C<null> filter prints nothing.  This is useful for plugins whose
 464 methods return values that you don't want to appear in the output.
 465 Rather than assigning every plugin method call to a dummy variable
 466 to silence it, you can wrap the block in a null filter:
 467
 468     [% FILTER null;
 469         USE im = GD.Image(100,100);
 470         black = im.colorAllocate(0,   0, 0);
 471         red   = im.colorAllocate(255,0,  0);
 472         blue  = im.colorAllocate(0,  0,  255);
 473         im.arc(50,50,95,75,0,360,blue);
 474         im.fill(50,50,red);
 475         im.png | stdout(1);
 476        END;
 477     -%]
 478
 479 Notice the use of the C<stdout> filter to ensure that a particular expression
 480 generates output to C<STDOUT> (in this case in binary mode).
 481
 482 =cut
 483
 484 # Local Variables:
 485 # mode: perl
 486 # perl-indent-level: 4
 487 # indent-tabs-mode: nil
 488 # End:
 489 #
 490 # vim: expandtab shiftwidth=4: