1Template::Manual::PlugiUnsse(r3)Contributed Perl DocumenTteamtpiloante::Manual::Plugins(3)
2
3
4

NAME

6       Template::Manual::Plugins - Standard plugins
7

TEMPLATE TOOLKIT PLUGINS

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