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

   1 #============================================================= -*-perl-*-
   2 #
   3 # Template::Manual::Plugins
   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::Plugins - Standard plugins
  19
  20 =head1 TEMPLATE TOOLKIT PLUGINS
  21
  22 The following plugin modules are distributed with the Template
  23 Toolkit.  Some of the plugins interface to external modules (detailed
  24 below) which should be downloaded from any CPAN site and installed
  25 before using the plugin.
  26
  27 =head2 Assert
  28
  29 New in 2.20!  The L<Assert|Template::Plugin::Assert> plugin adds an
  30 C<assert> virtual method that you can use to catch undefined values.
  31
  32 For example, consider this dotop:
  33
  34     [% user.name %]
  35
  36 If C<user.name> is an undefined value then TT will silently ignore the
  37 fact and print nothing.  If you C<USE> the C<assert> plugin then you
  38 can add the C<assert> vmethod between the C<user> and C<name> elements,
  39 like so:
  40
  41     [% user.assert.name %]
  42
  43 Now, if C<user.name> is an undefined value, an exception will be thrown:
  44
  45     assert error - undefined value for name
  46
  47 =head2 Autoformat
  48
  49 The L<Autoformat|Template::Plugin::Autoformat> plugin is an interface to
  50 Damian Conway's L<Text::Autoformat> Perl module which provides advanced text
  51 wrapping and formatting. See L<Template::Plugin::Autoformat> and
  52 L<Text::Autoformat> for further details.
  53
  54     [% USE autoformat(left=10, right=20) %]
  55     [% autoformat(mytext) %]        # call autoformat sub
  56     [% mytext FILTER autoformat %]  # or use autoformat filter
  57
  58 The L<Text::Autoformat> module is available from CPAN:
  59
  60     L<http://www.cpan.org/modules/by-module/Text/>
  61
  62 =head2 CGI
  63
  64 The L<CGI|Template::Plugin::CGI> plugin is a wrapper around Lincoln Stein's
  65 CGI.pm module. The plugin is distributed with the Template Toolkit (see
  66 L<Template::Plugin::CGI>) and the L<CGI> module itself is distributed with
  67 recent versions Perl, or is available from CPAN.
  68
  69     [% USE CGI %]
  70     [% CGI.param('param_name') %]
  71     [% CGI.start_form %]
  72     [% CGI.popup_menu( Name   => 'color',
  73                        Values => [ 'Green', 'Brown' ] ) %]
  74     [% CGI.end_form %]
  75
  76 =head2 Datafile
  77
  78 Provides an interface to data stored in a plain text file in a simple
  79 delimited format.  The first line in the file specifies field names
  80 which should be delimiter by any non-word character sequence.
  81 Subsequent lines define data using the same delimiter as in the first
  82 line.  Blank lines and comments (lines starting '#') are ignored.  See
  83 L<Template::Plugin::Datafile> for further details.
  84
  85 /tmp/mydata:
  86
  87     # define names for each field
  88     id : email : name : tel
  89     # here's the data
  90     fred : fred@here.com : Fred Smith : 555-1234
  91     bill : bill@here.com : Bill White : 555-5678
  92
  93 example:
  94
  95     [% USE userlist = datafile('/tmp/mydata') %]
  96
  97     [% FOREACH user = userlist %]
  98        [% user.name %] ([% user.id %])
  99     [% END %]
 100
 101 =head2 Date
 102
 103 The L<Date|Template::Plugin::Date> plugin provides an easy way to generate
 104 formatted time and date strings by delegating to the L<POSIX> C<strftime()>
 105 routine. See L<Template::Plugin::Date> and L<POSIX> for further details.
 106
 107     [% USE date %]
 108     [% date.format %]           # current time/date
 109
 110     File last modified: [% date.format(template.modtime) %]
 111
 112 =head2 Directory
 113
 114 The L<Directory|Template::Plugin::Directory> plugin provides a simple
 115 interface to a directory and the files within it. See
 116 L<Template::Plugin::Directory> for further details.
 117
 118     [% USE dir = Directory('/tmp') %]
 119     [% FOREACH file = dir.files %]
 120         # all the plain files in the directory
 121     [% END %]
 122     [% FOREACH file = dir.dirs %]
 123         # all the sub-directories
 124     [% END %]
 125
 126 =head2 DBI
 127
 128 The C<DBI> plugin is no longer distributed as part of the Template Toolkit
 129 (as of version 2.15).  It is now available as a separate L<Template::DBI>
 130 distribution from CPAN.
 131
 132 =head2 Dumper
 133
 134 The L<Dumper|Template::Plugin::Dumper> plugin provides an interface to the
 135 Data::Dumper module. See L<Template::Plugin::Dumper> and L<Data::Dumper> for
 136 futher details.
 137
 138     [% USE dumper(indent=0, pad="<br>") %]
 139     [% dumper.dump(myvar, yourvar) %]
 140
 141 =head2 File
 142
 143 The L<File|Template::Plugin::File> plugin provides a general abstraction for
 144 files and can be used to fetch information about specific files within a
 145 filesystem. See L<Template::Plugin::File> for further details.
 146
 147     [% USE File('/tmp/foo.html') %]
 148     [% File.name %]     # foo.html
 149     [% File.dir %]      # /tmp
 150     [% File.mtime %]    # modification time
 151
 152 =head2 Filter
 153
 154 This module implements a base class plugin which can be subclassed
 155 to easily create your own modules that define and install new filters.
 156
 157     package MyOrg::Template::Plugin::MyFilter;
 158
 159     use Template::Plugin::Filter;
 160     use base qw( Template::Plugin::Filter );
 161
 162     sub filter {
 163         my ($self, $text) = @_;
 164         # ...mungify $text...
 165         return $text;
 166     }
 167
 168 Example of use:
 169
 170     # now load it...
 171     [% USE MyFilter %]
 172
 173     # ...and use the returned object as a filter
 174     [% FILTER $MyFilter %]
 175       ...
 176     [% END %]
 177
 178 See L<Template::Plugin::Filter> for further details.
 179
 180 =head2 Format
 181
 182 The L<Format|Template::Plugin::Format> plugin provides a simple way to format
 183 text according to a C<printf()>-like format. See L<Template::Plugin::Format> for
 184 further details.
 185
 186     [% USE bold = format('<b>%s</b>') %]
 187     [% bold('Hello') %]
 188
 189 =head2 GD
 190
 191 The C<GD> plugins are no longer part of the core Template Toolkit distribution.
 192 They are now available from CPAN in a separate L<Template::GD> distribution.
 193
 194 =head2 HTML
 195
 196 The L<HTML|Template::Plugin::HTML> plugin is very basic, implementing a few
 197 useful methods for generating HTML. It is likely to be extended in the future
 198 or integrated with a larger project to generate HTML elements in a generic way.
 199
 200     [% USE HTML %]
 201     [% HTML.escape("if (a < b && c > d) ..." %]
 202     [% HTML.attributes(border => 1, cellpadding => 2) %]
 203     [% HTML.element(table => { border => 1, cellpadding => 2 }) %]
 204
 205 See L<Template::Plugin::HTML> for further details.
 206
 207 =head2 Iterator
 208
 209 The L<Iterator|Template::Plugin::Iterator> plugin provides a way to create a
 210 L<Template::Iterator> object to iterate over a data set. An iterator is
 211 created automatically by the C<FOREACH> directive and is aliased to the C<loop>
 212 variable. This plugin allows an iterator to be explicitly created with a given
 213 name, or the default plugin name, C<iterator>. See
 214 L<Template::Plugin::Iterator> for further details.
 215
 216     [% USE iterator(list, args) %]
 217
 218     [% FOREACH item = iterator %]
 219        [% '<ul>' IF iterator.first %]
 220        <li>[% item %]
 221        [% '</ul>' IF iterator.last %]
 222     [% END %]
 223
 224 =head2 Pod
 225
 226 This plugin provides an interface to the L<Pod::POM|Pod::POM> module
 227 which parses POD documents into an internal object model which can
 228 then be traversed and presented through the Template Toolkit.
 229
 230     [% USE Pod(podfile) %]
 231
 232     [% FOREACH head1 = Pod.head1;
 233          FOREACH head2 = head1/head2;
 234            ...
 235          END;
 236        END
 237     %]
 238
 239 =head2 Scalar
 240
 241 The Template Toolkit calls user-defined subroutines and object methods
 242 using Perl's array context by default.
 243
 244     # TT2 calls object methods in array context by default
 245     [% object.method %]
 246
 247 This plugin module provides a way for you to call subroutines and methods
 248 in scalar context.
 249
 250     [% USE scalar %]
 251
 252     # force it to use scalar context
 253     [% object.scalar.method %]
 254
 255     # also works with subroutine references
 256     [% scalar.my_sub_ref %]
 257
 258 =head2 String
 259
 260 The L<String|Template::Plugin::String> plugin implements an object-oriented
 261 interface for manipulating strings. See L<Template::Plugin::String> for
 262 further details.
 263
 264     [% USE String 'Hello' %]
 265     [% String.append(' World') %]
 266
 267     [% msg = String.new('Another string') %]
 268     [% msg.replace('string', 'text') %]
 269
 270     The string "[% msg %]" is [% msg.length %] characters long.
 271
 272 =head2 Table
 273
 274 The L<Table|Template::Plugin::Table> plugin allows you to format a list of
 275 data items into a virtual table by specifying a fixed number of rows or
 276 columns, with an optional overlap. See L<Template::Plugin::Table> for further
 277 details.
 278
 279     [% USE table(list, rows=10, overlap=1) %]
 280
 281     [% FOREACH item = table.col(3) %]
 282        [% item %]
 283     [% END %]
 284
 285 =head2 URL
 286
 287 The L<URL|Template::Plugin::URL> plugin provides a simple way of contructing
 288 URLs from a base part and a variable set of parameters. See
 289 L<Template::Plugin::URL> for further details.
 290
 291     [% USE mycgi = url('/cgi-bin/bar.pl', debug=1) %]
 292
 293     [% mycgi %]
 294        # ==> /cgi/bin/bar.pl?debug=1
 295
 296     [% mycgi(mode='submit') %]
 297        # ==> /cgi/bin/bar.pl?mode=submit&debug=1
 298
 299 =head2 Wrap
 300
 301 The L<Wrap|Template::Plugin::Wrap> plugin uses the L<Text::Wrap> module to
 302 provide simple paragraph formatting. See L<Template::Plugin::Wrap> and
 303 L<Text::Wrap> for further details.
 304
 305     [% USE wrap %]
 306     [% wrap(mytext, 40, '* ', '  ') %]  # use wrap sub
 307     [% mytext FILTER wrap(40) -%]       # or wrap FILTER
 308
 309 The C<Text::Wrap> module is available from CPAN:
 310
 311     http://www.cpan.org/modules/by-module/Text/
 312
 313 =head2 XML
 314
 315 The C<XML::DOM>, C<XML::RSS>, C<XML::Simple> and C<XML::XPath> plugins are no
 316 longer distributed with the Template Toolkit as of version 2.15
 317
 318 They are now available in a separate L<Template::XML> distribution.
 319
 320 =cut
 321
 322 # Local Variables:
 323 # mode: perl
 324 # perl-indent-level: 4
 325 # indent-tabs-mode: nil
 326 # End:
 327 #
 328 # vim: expandtab shiftwidth=4: