local-lib5/man/man3/Template::Manual::Plugins.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Manual::Plugins 3"
 132 .TH Template::Manual::Plugins 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Manual::Plugins \- Standard plugins
 135 .SH "TEMPLATE TOOLKIT PLUGINS"
 136 .IX Header "TEMPLATE TOOLKIT PLUGINS"
 137 The following plugin modules are distributed with the Template
 138 Toolkit.  Some of the plugins interface to external modules (detailed
 139 below) which should be downloaded from any \s-1CPAN\s0 site and installed
 140 before using the plugin.
 141 .Sh "Assert"
 142 .IX Subsection "Assert"
 143 New in 2.20!  The Assert plugin adds an
 144 \&\f(CW\*(C`assert\*(C'\fR virtual method that you can use to catch undefined values.
 145 .PP
 146 For example, consider this dotop:
 147 .PP
 148 .Vb 1
 149 \&    [% user.name %]
 150 .Ve
 151 .PP
 152 If \f(CW\*(C`user.name\*(C'\fR is an undefined value then \s-1TT\s0 will silently ignore the
 153 fact and print nothing.  If you \f(CW\*(C`USE\*(C'\fR the \f(CW\*(C`assert\*(C'\fR plugin then you
 154 can add the \f(CW\*(C`assert\*(C'\fR vmethod between the \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`name\*(C'\fR elements,
 155 like so:
 156 .PP
 157 .Vb 1
 158 \&    [% user.assert.name %]
 159 .Ve
 160 .PP
 161 Now, if \f(CW\*(C`user.name\*(C'\fR is an undefined value, an exception will be thrown:
 162 .PP
 163 .Vb 1
 164 \&    assert error \- undefined value for name
 165 .Ve
 166 .Sh "Autoformat"
 167 .IX Subsection "Autoformat"
 168 The Autoformat plugin is an interface to
 169 Damian Conway's Text::Autoformat Perl module which provides advanced text
 170 wrapping and formatting. See Template::Plugin::Autoformat and
 171 Text::Autoformat for further details.
 172 .PP
 173 .Vb 3
 174 \&    [% USE autoformat(left=10, right=20) %]
 175 \&    [% autoformat(mytext) %]        # call autoformat sub
 176 \&    [% mytext FILTER autoformat %]  # or use autoformat filter
 177 .Ve
 178 .PP
 179 The Text::Autoformat module is available from \s-1CPAN:\s0
 180 .PP
 181 .Vb 1
 182 \&    L<http://www.cpan.org/modules/by\-module/Text/>
 183 .Ve
 184 .Sh "\s-1CGI\s0"
 185 .IX Subsection "CGI"
 186 The \s-1CGI\s0 plugin is a wrapper around Lincoln Stein's
 187 \&\s-1CGI\s0.pm module. The plugin is distributed with the Template Toolkit (see
 188 Template::Plugin::CGI) and the \s-1CGI\s0 module itself is distributed with
 189 recent versions Perl, or is available from \s-1CPAN\s0.
 190 .PP
 191 .Vb 6
 192 \&    [% USE CGI %]
 193 \&    [% CGI.param('param_name') %]
 194 \&    [% CGI.start_form %]
 195 \&    [% CGI.popup_menu( Name   => 'color',
 196 \&                       Values => [ 'Green', 'Brown' ] ) %]
 197 \&    [% CGI.end_form %]
 198 .Ve
 199 .Sh "Datafile"
 200 .IX Subsection "Datafile"
 201 Provides an interface to data stored in a plain text file in a simple
 202 delimited format.  The first line in the file specifies field names
 203 which should be delimiter by any non-word character sequence.
 204 Subsequent lines define data using the same delimiter as in the first
 205 line.  Blank lines and comments (lines starting '#') are ignored.  See
 206 Template::Plugin::Datafile for further details.
 207 .PP
 208 /tmp/mydata:
 209 .PP
 210 .Vb 5
 211 \&    # define names for each field
 212 \&    id : email : name : tel
 213 \&    # here's the data
 214 \&    fred : fred@here.com : Fred Smith : 555\-1234
 215 \&    bill : bill@here.com : Bill White : 555\-5678
 216 .Ve
 217 .PP
 218 example:
 219 .PP
 220 .Vb 1
 221 \&    [% USE userlist = datafile('/tmp/mydata') %]
 222 .Ve
 223 .PP
 224 .Vb 3
 225 \&    [% FOREACH user = userlist %]
 226 \&       [% user.name %] ([% user.id %])
 227 \&    [% END %]
 228 .Ve
 229 .Sh "Date"
 230 .IX Subsection "Date"
 231 The Date plugin provides an easy way to generate
 232 formatted time and date strings by delegating to the \s-1POSIX\s0 \f(CW\*(C`strftime()\*(C'\fR
 233 routine. See Template::Plugin::Date and \s-1POSIX\s0 for further details.
 234 .PP
 235 .Vb 2
 236 \&    [% USE date %]
 237 \&    [% date.format %]           # current time/date
 238 .Ve
 239 .PP
 240 .Vb 1
 241 \&    File last modified: [% date.format(template.modtime) %]
 242 .Ve
 243 .Sh "Directory"
 244 .IX Subsection "Directory"
 245 The Directory plugin provides a simple
 246 interface to a directory and the files within it. See
 247 Template::Plugin::Directory for further details.
 248 .PP
 249 .Vb 7
 250 \&    [% USE dir = Directory('/tmp') %]
 251 \&    [% FOREACH file = dir.files %]
 252 \&        # all the plain files in the directory
 253 \&    [% END %]
 254 \&    [% FOREACH file = dir.dirs %]
 255 \&        # all the sub\-directories
 256 \&    [% END %]
 257 .Ve
 258 .Sh "\s-1DBI\s0"
 259 .IX Subsection "DBI"
 260 The \f(CW\*(C`DBI\*(C'\fR plugin is no longer distributed as part of the Template Toolkit
 261 (as of version 2.15).  It is now available as a separate Template::DBI
 262 distribution from \s-1CPAN\s0.
 263 .Sh "Dumper"
 264 .IX Subsection "Dumper"
 265 The Dumper plugin provides an interface to the
 266 Data::Dumper module. See Template::Plugin::Dumper and Data::Dumper for
 267 futher details.
 268 .PP
 269 .Vb 2
 270 \&    [% USE dumper(indent=0, pad="<br>") %]
 271 \&    [% dumper.dump(myvar, yourvar) %]
 272 .Ve
 273 .Sh "File"
 274 .IX Subsection "File"
 275 The File plugin provides a general abstraction for
 276 files and can be used to fetch information about specific files within a
 277 filesystem. See Template::Plugin::File for further details.
 278 .PP
 279 .Vb 4
 280 \&    [% USE File('/tmp/foo.html') %]
 281 \&    [% File.name %]     # foo.html
 282 \&    [% File.dir %]      # /tmp
 283 \&    [% File.mtime %]    # modification time
 284 .Ve
 285 .Sh "Filter"
 286 .IX Subsection "Filter"
 287 This module implements a base class plugin which can be subclassed
 288 to easily create your own modules that define and install new filters.
 289 .PP
 290 .Vb 1
 291 \&    package MyOrg::Template::Plugin::MyFilter;
 292 .Ve
 293 .PP
 294 .Vb 2
 295 \&    use Template::Plugin::Filter;
 296 \&    use base qw( Template::Plugin::Filter );
 297 .Ve
 298 .PP
 299 .Vb 5
 300 \&    sub filter {
 301 \&        my ($self, $text) = @_;
 302 \&        # ...mungify $text...
 303 \&        return $text;
 304 \&    }
 305 .Ve
 306 .PP
 307 Example of use:
 308 .PP
 309 .Vb 2
 310 \&    # now load it...
 311 \&    [% USE MyFilter %]
 312 .Ve
 313 .PP
 314 .Vb 4
 315 \&    # ...and use the returned object as a filter
 316 \&    [% FILTER $MyFilter %]
 317 \&      ...
 318 \&    [% END %]
 319 .Ve
 320 .PP
 321 See Template::Plugin::Filter for further details.
 322 .Sh "Format"
 323 .IX Subsection "Format"
 324 The Format plugin provides a simple way to format
 325 text according to a \f(CW\*(C`printf()\*(C'\fR\-like format. See Template::Plugin::Format for
 326 further details.
 327 .PP
 328 .Vb 2
 329 \&    [% USE bold = format('<b>%s</b>') %]
 330 \&    [% bold('Hello') %]
 331 .Ve
 332 .Sh "\s-1GD\s0"
 333 .IX Subsection "GD"
 334 The \f(CW\*(C`GD\*(C'\fR plugins are no longer part of the core Template Toolkit distribution.
 335 They are now available from \s-1CPAN\s0 in a separate Template::GD distribution.
 336 .Sh "\s-1HTML\s0"
 337 .IX Subsection "HTML"
 338 The \s-1HTML\s0 plugin is very basic, implementing a few
 339 useful methods for generating \s-1HTML\s0. It is likely to be extended in the future
 340 or integrated with a larger project to generate \s-1HTML\s0 elements in a generic way.
 341 .PP
 342 .Vb 4
 343 \&    [% USE HTML %]
 344 \&    [% HTML.escape("if (a < b && c > d) ..." %]
 345 \&    [% HTML.attributes(border => 1, cellpadding => 2) %]
 346 \&    [% HTML.element(table => { border => 1, cellpadding => 2 }) %]
 347 .Ve
 348 .PP
 349 See Template::Plugin::HTML for further details.
 350 .Sh "Iterator"
 351 .IX Subsection "Iterator"
 352 The Iterator plugin provides a way to create a
 353 Template::Iterator object to iterate over a data set. An iterator is
 354 created automatically by the \f(CW\*(C`FOREACH\*(C'\fR directive and is aliased to the \f(CW\*(C`loop\*(C'\fR
 355 variable. This plugin allows an iterator to be explicitly created with a given
 356 name, or the default plugin name, \f(CW\*(C`iterator\*(C'\fR. See
 357 Template::Plugin::Iterator for further details.
 358 .PP
 359 .Vb 1
 360 \&    [% USE iterator(list, args) %]
 361 .Ve
 362 .PP
 363 .Vb 5
 364 \&    [% FOREACH item = iterator %]
 365 \&       [% '<ul>' IF iterator.first %]
 366 \&       <li>[% item %]
 367 \&       [% '</ul>' IF iterator.last %]
 368 \&    [% END %]
 369 .Ve
 370 .Sh "Pod"
 371 .IX Subsection "Pod"
 372 This plugin provides an interface to the Pod::POM module
 373 which parses \s-1POD\s0 documents into an internal object model which can
 374 then be traversed and presented through the Template Toolkit.
 375 .PP
 376 .Vb 1
 377 \&    [% USE Pod(podfile) %]
 378 .Ve
 379 .PP
 380 .Vb 6
 381 \&    [% FOREACH head1 = Pod.head1;
 382 \&         FOREACH head2 = head1/head2;
 383 \&           ...
 384 \&         END;
 385 \&       END
 386 \&    %]
 387 .Ve
 388 .Sh "Scalar"
 389 .IX Subsection "Scalar"
 390 The Template Toolkit calls user-defined subroutines and object methods
 391 using Perl's array context by default.
 392 .PP
 393 .Vb 2
 394 \&    # TT2 calls object methods in array context by default
 395 \&    [% object.method %]
 396 .Ve
 397 .PP
 398 This plugin module provides a way for you to call subroutines and methods
 399 in scalar context.
 400 .PP
 401 .Vb 1
 402 \&    [% USE scalar %]
 403 .Ve
 404 .PP
 405 .Vb 2
 406 \&    # force it to use scalar context
 407 \&    [% object.scalar.method %]
 408 .Ve
 409 .PP
 410 .Vb 2
 411 \&    # also works with subroutine references
 412 \&    [% scalar.my_sub_ref %]
 413 .Ve
 414 .Sh "String"
 415 .IX Subsection "String"
 416 The String plugin implements an object-oriented
 417 interface for manipulating strings. See Template::Plugin::String for
 418 further details.
 419 .PP
 420 .Vb 2
 421 \&    [% USE String 'Hello' %]
 422 \&    [% String.append(' World') %]
 423 .Ve
 424 .PP
 425 .Vb 2
 426 \&    [% msg = String.new('Another string') %]
 427 \&    [% msg.replace('string', 'text') %]
 428 .Ve
 429 .PP
 430 .Vb 1
 431 \&    The string "[% msg %]" is [% msg.length %] characters long.
 432 .Ve
 433 .Sh "Table"
 434 .IX Subsection "Table"
 435 The Table plugin allows you to format a list of
 436 data items into a virtual table by specifying a fixed number of rows or
 437 columns, with an optional overlap. See Template::Plugin::Table for further
 438 details.
 439 .PP
 440 .Vb 1
 441 \&    [% USE table(list, rows=10, overlap=1) %]
 442 .Ve
 443 .PP
 444 .Vb 3
 445 \&    [% FOREACH item = table.col(3) %]
 446 \&       [% item %]
 447 \&    [% END %]
 448 .Ve
 449 .Sh "\s-1URL\s0"
 450 .IX Subsection "URL"
 451 The \s-1URL\s0 plugin provides a simple way of contructing
 452 URLs from a base part and a variable set of parameters. See
 453 Template::Plugin::URL for further details.
 454 .PP
 455 .Vb 1
 456 \&    [% USE mycgi = url('/cgi\-bin/bar.pl', debug=1) %]
 457 .Ve
 458 .PP
 459 .Vb 2
 460 \&    [% mycgi %]
 461 \&       # ==> /cgi/bin/bar.pl?debug=1
 462 .Ve
 463 .PP
 464 .Vb 2
 465 \&    [% mycgi(mode='submit') %]
 466 \&       # ==> /cgi/bin/bar.pl?mode=submit&debug=1
 467 .Ve
 468 .Sh "Wrap"
 469 .IX Subsection "Wrap"
 470 The Wrap plugin uses the Text::Wrap module to
 471 provide simple paragraph formatting. See Template::Plugin::Wrap and
 472 Text::Wrap for further details.
 473 .PP
 474 .Vb 3
 475 \&    [% USE wrap %]
 476 \&    [% wrap(mytext, 40, '* ', '  ') %]  # use wrap sub
 477 \&    [% mytext FILTER wrap(40) \-%]       # or wrap FILTER
 478 .Ve
 479 .PP
 480 The \f(CW\*(C`Text::Wrap\*(C'\fR module is available from \s-1CPAN:\s0
 481 .PP
 482 .Vb 1
 483 \&    http://www.cpan.org/modules/by\-module/Text/
 484 .Ve
 485 .Sh "\s-1XML\s0"
 486 .IX Subsection "XML"
 487 The \f(CW\*(C`XML::DOM\*(C'\fR, \f(CW\*(C`XML::RSS\*(C'\fR, \f(CW\*(C`XML::Simple\*(C'\fR and \f(CW\*(C`XML::XPath\*(C'\fR plugins are no
 488 longer distributed with the Template Toolkit as of version 2.15
 489 .PP
 490 They are now available in a separate Template::XML distribution.