1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
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<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
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.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
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
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
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'
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 \
129 .\" ========================================================================
131 .IX Title "Template::Plugin::Filter 3"
132 .TH Template::Plugin::Filter 3 "2009-07-04" "perl v5.8.7" "User Contributed Perl Documentation"
134 Template::Plugin::Filter \- Base class for plugin filters
136 .IX Header "SYNOPSIS"
138 \& package MyOrg::Template::Plugin::MyFilter;
142 \& use Template::Plugin::Filter;
143 \& use base qw( Template::Plugin::Filter );
148 \& my ($self, $text) = @_;
152 \& # ...mungify $text...
162 \& [% USE MyFilter %]
166 \& # ...and use the returned object as a filter
167 \& [% FILTER $MyFilter %]
172 .IX Header "DESCRIPTION"
173 This module implements a base class for plugin filters. It hides
174 the underlying complexity involved in creating and using filters
175 that get defined and made available by loading a plugin.
177 To use the module, simply create your own plugin module that is
178 inherited from the \f(CW\*(C`Template::Plugin::Filter\*(C'\fR class.
181 \& package MyOrg::Template::Plugin::MyFilter;
185 \& use Template::Plugin::Filter;
186 \& use base qw( Template::Plugin::Filter );
189 Then simply define your \f(CW\*(C`filter()\*(C'\fR method. When called, you get
190 passed a reference to your plugin object (\f(CW$self\fR) and the text
195 \& my ($self, $text) = @_;
199 \& # ...mungify $text...
207 To use your custom plugin, you have to make sure that the Template
208 Toolkit knows about your plugin namespace.
211 \& my $tt2 = Template\->new({
212 \& PLUGIN_BASE => 'MyOrg::Template::Plugin',
216 Or for individual plugins you can do it like this:
219 \& my $tt2 = Template\->new({
221 \& MyFilter => 'MyOrg::Template::Plugin::MyFilter',
226 Then you \f(CW\*(C`USE\*(C'\fR your plugin in the normal way.
229 \& [% USE MyFilter %]
232 The object returned is stored in the variable of the same name,
233 \&'\f(CW\*(C`MyFilter\*(C'\fR'. When you come to use it as a \f(CW\*(C`FILTER\*(C'\fR, you should add
234 a dollar prefix. This indicates that you want to use the filter
235 stored in the variable '\f(CW\*(C`MyFilter\*(C'\fR' rather than the filter named
236 \&'\f(CW\*(C`MyFilter\*(C'\fR', which is an entirely different thing (see later for
237 information on defining filters by name).
240 \& [% FILTER $MyFilter %]
241 \& ...text to be filtered...
245 You can, of course, assign it to a different variable.
248 \& [% USE blat = MyFilter %]
252 \& [% FILTER $blat %]
253 \& ...text to be filtered...
257 Any configuration parameters passed to the plugin constructor from the
258 \&\f(CW\*(C`USE\*(C'\fR directive are stored internally in the object for inspection by
259 the \f(CW\*(C`filter()\*(C'\fR method (or indeed any other method). Positional
260 arguments are stored as a reference to a list in the \f(CW\*(C`_ARGS\*(C'\fR item while
261 named configuration parameters are stored as a reference to a hash
262 array in the \f(CW\*(C`_CONFIG\*(C'\fR item.
264 For example, loading a plugin as shown here:
267 \& [% USE blat = MyFilter 'foo' 'bar' baz = 'blam' %]
270 would allow the \f(CW\*(C`filter()\*(C'\fR method to do something like this:
274 \& my ($self, $text) = @_;
278 \& my $args = $self\->{ _ARGS }; # [ 'foo', 'bar' ]
279 \& my $conf = $self\->{ _CONFIG }; # { baz => 'blam' }
283 \& # ...munge $text...
291 By default, plugins derived from this module will create static
292 filters. A static filter is created once when the plugin gets
293 loaded via the \f(CW\*(C`USE\*(C'\fR directive and re-used for all subsequent
294 \&\f(CW\*(C`FILTER\*(C'\fR operations. That means that any argument specified with
295 the \f(CW\*(C`FILTER\*(C'\fR directive are ignored.
297 Dynamic filters, on the other hand, are re-created each time
298 they are used by a \f(CW\*(C`FILTER\*(C'\fR directive. This allows them to act
299 on any parameters passed from the \f(CW\*(C`FILTER\*(C'\fR directive and modify
300 their behaviour accordingly.
302 There are two ways to create a dynamic filter. The first is to
303 define a \f(CW$DYNAMIC\fR class variable set to a true value.
306 \& package MyOrg::Template::Plugin::MyFilter;
307 \& use base 'Template::Plugin::Filter';
311 The other way is to set the internal \f(CW\*(C`_DYNAMIC\*(C'\fR value within the \f(CW\*(C`init()\*(C'\fR
312 method which gets called by the \f(CW\*(C`new()\*(C'\fR constructor.
317 \& $self\->{ _DYNAMIC } = 1;
322 When this is set to a true value, the plugin will automatically
323 create a dynamic filter. The outcome is that the \f(CW\*(C`filter()\*(C'\fR method
324 will now also get passed a reference to an array of postional
325 arguments and a reference to a hash array of named parameters.
327 So, using a plugin filter like this:
330 \& [% FILTER $blat 'foo' 'bar' baz = 'blam' %]
333 would allow the \f(CW\*(C`filter()\*(C'\fR method to work like this:
337 \& my ($self, $text, $args, $conf) = @_;
341 \& # $args = [ 'foo', 'bar' ]
342 \& # $conf = { baz => 'blam' }
346 In this case can pass parameters to both the \s-1USE\s0 and \s-1FILTER\s0 directives,
347 so your \fIfilter()\fR method should probably take that into account.
350 \& [% USE MyFilter 'foo' wiz => 'waz' %]
354 \& [% FILTER $MyFilter 'bar' biz => 'baz' %]
359 You can use the \f(CW\*(C`merge_args()\*(C'\fR and \f(CW\*(C`merge_config()\*(C'\fR methods to do a quick
360 and easy job of merging the local (e.g. \f(CW\*(C`FILTER\*(C'\fR) parameters with the
361 internal (e.g. \f(CW\*(C`USE\*(C'\fR) values and returning new sets of conglomerated
366 \& my ($self, $text, $args, $conf) = @_;
370 \& $args = $self\->merge_args($args);
371 \& $conf = $self\->merge_config($conf);
375 \& # $args = [ 'foo', 'bar' ]
376 \& # $conf = { wiz => 'waz', biz => 'baz' }
381 You can also have your plugin install itself as a named filter by
382 calling the \f(CW\*(C`install_filter()\*(C'\fR method from the \f(CW\*(C`init()\*(C'\fR method. You
383 should provide a name for the filter, something that you might
384 like to make a configuration option.
389 \& my $name = $self\->{ _CONFIG }\->{ name } || 'myfilter';
390 \& $self\->install_filter($name);
395 This allows the plugin filter to be used as follows:
398 \& [% USE MyFilter %]
402 \& [% FILTER myfilter %]
410 \& [% USE MyFilter name = 'swipe' %]
414 \& [% FILTER swipe %]
419 Alternately, you can allow a filter name to be specified as the
420 first positional argument.
425 \& my $name = $self\->{ _ARGS }\->[0] || 'myfilter';
426 \& $self\->install_filter($name);
432 \& [% USE MyFilter 'swipe' %]
436 \& [% FILTER swipe %]
442 Here's a complete example of a plugin filter module.
445 \& package My::Template::Plugin::Change;
446 \& use Template::Plugin::Filter;
447 \& use base qw( Template::Plugin::Filter );
456 \& $self\->{ _DYNAMIC } = 1;
460 \& # first arg can specify filter name
461 \& $self\->install_filter($self\->{ _ARGS }\->[0] || 'change');
471 \& my ($self, $text, $args, $config) = @_;
475 \& $config = $self\->merge_config($config);
476 \& my $regex = join('|', keys %$config);
480 \& $text =~ s/($regex)/$config\->{ $1 }/ge;
493 Andy Wardley <abw@wardley.org> <http://wardley.org/>
495 .IX Header "COPYRIGHT"
496 Copyright (C) 1996\-2007 Andy Wardley. All Rights Reserved.
498 This module is free software; you can redistribute it and/or
499 modify it under the same terms as Perl itself.
501 .IX Header "SEE ALSO"
502 Template::Plugin, Template::Filters, Template::Manual::Filters