1Template::Plugins(3) User Contributed Perl Documentation Template::Plugins(3)
2
6 Template::Plugins - Plugin provider module
7
9 use Template::Plugins;
10 $plugin_provider = Template::Plugins->new(\%options);
12 ($plugin, $error) = $plugin_provider->fetch($name, @args);
14
16 The Template::Plugins module defines a provider class which can be used
17 to load and instantiate Template Toolkit plugin modules.
18
20 new(\%params)
21 Constructor method which instantiates and returns a reference to a Tem‐
23 plate::Plugins object. A reference to a hash array of configuration
24 items may be passed as a parameter. These are described below.
25 Note that the Template.pm front-end module creates a Template::Plugins
27 provider, passing all configuration items. Thus, the examples shown
28 below in the form:
29 $plugprov = Template::Plugins->new({
31 PLUGIN_BASE => 'MyTemplate::Plugin',
32 LOAD_PERL => 1,
33 ...
34 });
35 can also be used via the Template module as:
37 $ttengine = Template->new({
39 PLUGIN_BASE => 'MyTemplate::Plugin',
40 LOAD_PERL => 1,
41 ...
42 });
43 as well as the more explicit form of:
45 $plugprov = Template::Plugins->new({
47 PLUGIN_BASE => 'MyTemplate::Plugin',
48 LOAD_PERL => 1,
49 ...
50 });
51 $ttengine = Template->new({
53 LOAD_PLUGINS => [ $plugprov ],
54 });
55 fetch($name, @args)
57 Called to request that a plugin of a given name be provided. The rele‐
59 vant module is first loaded (if necessary) and the load() class method
60 called to return the factory class name (usually the same package name)
61 or a factory object (a prototype). The new() method is then called as
62 a class or object method against the factory, passing all remaining
63 parameters.
64 Returns a reference to a new plugin object or ($error, STATUS_ERROR) on
66 error. May also return (undef, STATUS_DECLINED) to decline to serve
67 the request. If TOLERANT is set then all errors will be returned as
68 declines.
69
71 The following list details the configuration options that can be pro‐
72 vided to the Template::Plugins new() constructor.
73 PLUGINS
75 The PLUGINS options can be used to provide a reference to a hash
76 array that maps plugin names to Perl module names. A number of
77 standard plugins are defined (e.g. 'table', 'cgi', 'dbi', etc.)
78 which map to their corresponding Template::Plugin::* counterparts.
79 These can be redefined by values in the PLUGINS hash.
80 my $plugins = Template::Plugins->new({
82 PLUGINS => {
83 cgi => 'MyOrg::Template::Plugin::CGI',
84 foo => 'MyOrg::Template::Plugin::Foo',
85 bar => 'MyOrg::Template::Plugin::Bar',
86 },
87 });
88 The recommended convention is to specify these plugin names in
90 lower case. The Template Toolkit first looks for an exact case-
91 sensitive match and then tries the lower case conversion of the
92 name specified.
93 [% USE Foo %] # look for 'Foo' then 'foo'
95 If you define all your PLUGINS with lower case names then they will
97 be located regardless of how the user specifies the name in the USE
98 directive. If, on the other hand, you define your PLUGINS with
99 upper or mixed case names then the name specified in the USE direc‐
100 tive must match the case exactly.
101 The USE directive is used to create plugin objects and does so by
103 calling the plugin() method on the current Template::Context
104 object. If the plugin name is defined in the PLUGINS hash then the
105 corresponding Perl module is loaded via require(). The context
106 then calls the load() class method which should return the class
107 name (default and general case) or a prototype object against which
108 the new() method can be called to instantiate individual plugin
109 objects.
110 If the plugin name is not defined in the PLUGINS hash then the
112 PLUGIN_BASE and/or LOAD_PERL options come into effect.
113 PLUGIN_BASE
115 If a plugin is not defined in the PLUGINS hash then the PLUGIN_BASE
116 is used to attempt to construct a correct Perl module name which
117 can be successfully loaded.
118 The PLUGIN_BASE can be specified as a reference to an array of mod‐
120 ule namespaces, or as a single value which is automatically con‐
121 verted to a list. The default PLUGIN_BASE value ('Template::Plug‐
122 in') is then added to the end of this list.
123 example 1:
125 my $plugins = Template::Plugins->new({
127 PLUGIN_BASE => 'MyOrg::Template::Plugin',
128 });
129 [% USE Foo %] # => MyOrg::Template::Plugin::Foo
131 or Template::Plugin::Foo
132 example 2:
134 my $plugins = Template::Plugins->new({
136 PLUGIN_BASE => [ 'MyOrg::Template::Plugin',
137 'YourOrg::Template::Plugin' ],
138 });
139 [% USE Foo %] # => MyOrg::Template::Plugin::Foo
141 or YourOrg::Template::Plugin::Foo
142 or Template::Plugin::Foo
143 If you don't want the default Template::Plugin namespace added to
145 the end of the PLUGIN_BASE, then set the $Template::Plugins::PLUG‐
146 IN_BASE variable to a false value before calling the Tem‐
147 plate::Plugins new() constructor method. This is shown in the
148 example below where the 'Foo' is located as 'My::Plugin::Foo' or
149 'Your::Plugin::Foo' but not as 'Template::Plugin::Foo'.
150 example 3:
152 use Template::Plugins;
154 $Template::Plugins::PLUGIN_BASE = '';
155 my $plugins = Template::Plugins->new({
157 PLUGIN_BASE => [ 'My::Plugin',
158 'Your::Plugin' ],
159 });
160 [% USE Foo %] # => My::Plugin::Foo
162 or Your::Plugin::Foo
163 LOAD_PERL
165 If a plugin cannot be loaded using the PLUGINS or PLUGIN_BASE
166 approaches then the provider can make a final attempt to load the
167 module without prepending any prefix to the module path. This
168 allows regular Perl modules (i.e. those that don't reside in the
169 Template::Plugin or some other such namespace) to be loaded and
170 used as plugins.
171 By default, the LOAD_PERL option is set to 0 and no attempt will be
173 made to load any Perl modules that aren't named explicitly in the
174 PLUGINS hash or reside in a package as named by one of the PLUG‐
175 IN_BASE components.
176 Plugins loaded using the PLUGINS or PLUGIN_BASE receive a reference
178 to the current context object as the first argument to the new()
179 constructor. Modules loaded using LOAD_PERL are assumed to not
180 conform to the plugin interface. They must provide a new() class
181 method for instantiating objects but it will not receive a refer‐
182 ence to the context as the first argument. Plugin modules should
183 provide a load() class method (or inherit the default one from the
184 Template::Plugin base class) which is called the first time the
185 plugin is loaded. Regular Perl modules need not. In all other
186 respects, regular Perl objects and Template Toolkit plugins are
187 identical.
188 If a particular Perl module does not conform to the common, but not
190 unilateral, new() constructor convention then a simple plugin wrap‐
191 per can be written to interface to it.
192 TOLERANT
194 The TOLERANT flag is used by the various Template Toolkit provider
195 modules (Template::Provider, Template::Plugins, Template::Filters)
196 to control their behaviour when errors are encountered. By
197 default, any errors are reported as such, with the request for the
198 particular resource (template, plugin, filter) being denied and an
199 exception raised. When the TOLERANT flag is set to any true val‐
200 ues, errors will be silently ignored and the provider will instead
201 return STATUS_DECLINED. This allows a subsequent provider to take
202 responsibility for providing the resource, rather than failing the
203 request outright. If all providers decline to service the request,
204 either through tolerated failure or a genuine disinclination to
205 comply, then a '<resource> not found' exception is raised.
206 DEBUG
208 The DEBUG option can be used to enable debugging messages from the
209 Template::Plugins module by setting it to include the DEBUG_PLUGINS
210 value.
211 use Template::Constants qw( :debug );
213 my $template = Template->new({
215 DEBUG => DEBUG_FILTERS ⎪ DEBUG_PLUGINS,
216 });
217
219 The following plugin modules are distributed with the Template Toolkit.
220 Some of the plugins interface to external modules (detailed below)
221 which should be downloaded from any CPAN site and installed before
222 using the plugin.
223 Autoformat
225 The Autoformat plugin is an interface to Damian Conway's Text::Autofor‐
227 mat Perl module which provides advanced text wrapping and formatting.
228 See Template::Plugin::Autoformat and Text::Autoformat for further
229 details.
230 [% USE autoformat(left=10, right=20) %]
232 [% autoformat(mytext) %] # call autoformat sub
233 [% mytext FILTER autoformat %] # or use autoformat filter
234 The Text::Autoformat module is available from CPAN:
236 http://www.cpan.org/modules/by-module/Text/
238 CGI
240 The CGI plugin is a wrapper around Lincoln Stein's
242 <lstein@genome.wi.mit.edu> CGI.pm module. The plugin is distributed
243 with the Template Toolkit (see Template::Plugin::CGI) and the CGI mod‐
244 ule itself is distributed with recent versions Perl, or is available
245 from CPAN.
246 [% USE CGI %]
248 [% CGI.param('param_name') %]
249 [% CGI.start_form %]
250 [% CGI.popup_menu( Name => 'color',
251 Values => [ 'Green', 'Brown' ] ) %]
252 [% CGI.end_form %]
253 Datafile
255 Provides an interface to data stored in a plain text file in a simple
257 delimited format. The first line in the file specifies field names
258 which should be delimiter by any non-word character sequence. Subse‐
259 quent lines define data using the same delimiter as in the first line.
260 Blank lines and comments (lines starting '#') are ignored. See Tem‐
261 plate::Plugin::Datafile for further details.
262 /tmp/mydata:
264 # define names for each field
266 id : email : name : tel
267 # here's the data
268 fred : fred@here.com : Fred Smith : 555-1234
269 bill : bill@here.com : Bill White : 555-5678
270 example:
272 [% USE userlist = datafile('/tmp/mydata') %]
274 [% FOREACH user = userlist %]
276 [% user.name %] ([% user.id %])
277 [% END %]
278 Date
280 The Date plugin provides an easy way to generate formatted time and
282 date strings by delegating to the POSIX strftime() routine. See Tem‐
283 plate::Plugin::Date and POSIX for further details.
284 [% USE date %]
286 [% date.format %] # current time/date
287 File last modified: [% date.format(template.modtime) %]
289 Directory
291 The Directory plugin provides a simple interface to a directory and the
293 files within it. See Template::Plugin::Directory for further details.
294 [% USE dir = Directory('/tmp') %]
296 [% FOREACH file = dir.files %]
297 # all the plain files in the directory
298 [% END %]
299 [% FOREACH file = dir.dirs %]
300 # all the sub-directories
301 [% END %]
302 DBI
304 The DBI plugin is no longer distributed as part of the Template Toolkit
306 (as of version 2.15). It is now available as a separate Template-Plug‐
307 in-DBI distribution from CPAN.
308 Dumper
310 The Dumper plugin provides an interface to the Data::Dumper module.
312 See Template::Plugin::Dumper and Data::Dumper for futher details.
313 [% USE dumper(indent=0, pad="<br>") %]
315 [% dumper.dump(myvar, yourvar) %]
316 File
318 The File plugin provides a general abstraction for files and can be
320 used to fetch information about specific files within a filesystem.
321 See Template::Plugin::File for further details.
322 [% USE File('/tmp/foo.html') %]
324 [% File.name %] # foo.html
325 [% File.dir %] # /tmp
326 [% File.mtime %] # modification time
327 Filter
329 This module implements a base class plugin which can be subclassed to
331 easily create your own modules that define and install new filters.
332 package MyOrg::Template::Plugin::MyFilter;
334 use Template::Plugin::Filter;
336 use base qw( Template::Plugin::Filter );
337 sub filter {
339 my ($self, $text) = @_;
340 # ...mungify $text...
342 return $text;
344 }
345 # now load it...
347 [% USE MyFilter %]
348 # ...and use the returned object as a filter
350 [% FILTER $MyFilter %]
351 ...
352 [% END %]
353 See Template::Plugin::Filter for further details.
355 Format
357 The Format plugin provides a simple way to format text according to a
359 printf()-like format. See Template::Plugin::Format for further
360 details.
361 [% USE bold = format('<b>%s</b>') %]
363 [% bold('Hello') %]
364 GD
366 The GD plugins are no longer part of the core Template Toolkit distri‐
368 bution. They are now available in a separate Template-GD distribution.
369 HTML
371 The HTML plugin is very basic, implementing a few useful methods for
373 generating HTML. It is likely to be extended in the future or inte‐
374 grated with a larger project to generate HTML elements in a generic way
375 (as discussed recently on the mod_perl mailing list).
376 [% USE HTML %]
378 [% HTML.escape("if (a < b && c > d) ..." %]
379 [% HTML.attributes(border => 1, cellpadding => 2) %]
380 [% HTML.element(table => { border => 1, cellpadding => 2 }) %]
381 See Template::Plugin::HTML for further details.
383 Iterator
385 The Iterator plugin provides a way to create a Template::Iterator
387 object to iterate over a data set. An iterator is created automati‐
388 cally by the FOREACH directive and is aliased to the 'loop' variable.
389 This plugin allows an iterator to be explicitly created with a given
390 name, or the default plugin name, 'iterator'. See Template::Plug‐
391 in::Iterator for further details.
392 [% USE iterator(list, args) %]
394 [% FOREACH item = iterator %]
396 [% '<ul>' IF iterator.first %]
397 <li>[% item %]
398 [% '</ul>' IF iterator.last %]
399 [% END %]
400 Pod
402 This plugin provides an interface to the Pod::POM module which parses
404 POD documents into an internal object model which can then be traversed
405 and presented through the Template Toolkit.
406 [% USE Pod(podfile) %]
408 [% FOREACH head1 = Pod.head1;
410 FOREACH head2 = head1/head2;
411 ...
412 END;
413 END
414 %]
415 String
417 The String plugin implements an object-oriented interface for manipu‐
419 lating strings. See Template::Plugin::String for further details.
420 [% USE String 'Hello' %]
422 [% String.append(' World') %]
423 [% msg = String.new('Another string') %]
425 [% msg.replace('string', 'text') %]
426 The string "[% msg %]" is [% msg.length %] characters long.
428 Table
430 The Table plugin allows you to format a list of data items into a vir‐
432 tual table by specifying a fixed number of rows or columns, with an
433 optional overlap. See Template::Plugin::Table for further details.
434 [% USE table(list, rows=10, overlap=1) %]
436 [% FOREACH item = table.col(3) %]
438 [% item %]
439 [% END %]
440 URL
442 The URL plugin provides a simple way of contructing URLs from a base
444 part and a variable set of parameters. See Template::Plugin::URL for
445 further details.
446 [% USE mycgi = url('/cgi-bin/bar.pl', debug=1) %]
448 [% mycgi %]
450 # ==> /cgi/bin/bar.pl?debug=1
451 [% mycgi(mode='submit') %]
453 # ==> /cgi/bin/bar.pl?mode=submit&debug=1
454 Wrap
456 The Wrap plugin uses the Text::Wrap module by David Muir Sharnoff
458 <muir@idiom.com> (with help from Tim Pierce and many many others) to
459 provide simple paragraph formatting. See Template::Plugin::Wrap and
460 Text::Wrap for further details.
461 [% USE wrap %]
463 [% wrap(mytext, 40, '* ', ' ') %] # use wrap sub
464 [% mytext FILTER wrap(40) -%] # or wrap FILTER
465 The Text::Wrap module is available from CPAN:
467 http://www.cpan.org/modules/by-module/Text/
469 XML::Style
471 This plugin defines a filter for performing simple stylesheet based
473 transformations of XML text.
474 [% USE xmlstyle
476 table = {
477 attributes = {
478 border = 0
479 cellpadding = 4
480 cellspacing = 1
481 }
482 }
483 %]
484 [% FILTER xmlstyle %]
486 <table>
487 <tr>
488 <td>Foo</td> <td>Bar</td> <td>Baz</td>
489 </tr>
490 </table>
491 [% END %]
492 See Template::Plugin::XML::Style for further details.
494 XML
496 The XML::DOM, XML::RSS, XML::Simple and XML::XPath plugins are no
498 longer distributed with the Template Toolkit as of version 2.15
499 They are now available in a separate Template-XML distribution.
501
503 · It might be worthwhile being able to distinguish between absolute
504 module names and those which should be applied relative to PLUG‐
505 IN_BASE directories. For example, use 'MyNamespace::MyModule' to
506 denote absolute module names (e.g. LOAD_PERL), and 'MyNames‐
507 pace.MyModule' to denote relative to PLUGIN_BASE.
508
510 Andy Wardley <abw@wardley.org>
511 <http://wardley.org/⎪http://wardley.org/>
513
515 2.77, distributed as part of the Template Toolkit version 2.18,
516 released on 09 February 2007.
517
519 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
520 This module is free software; you can redistribute it and/or modify it
522 under the same terms as Perl itself.
523
525 Template, Template::Plugin, Template::Context
526perl v5.8.8 2007-02-09 Template::Plugins(3)