Template::Plugin::Filter(3pm)

1Template::Plugin::FilteUrs(e3r)Contributed Perl DocumentTaetmipolnate::Plugin::Filter(3)
2
3
4

NAME

6       Template::Plugin::Filter - Base class for plugin filters
7

SYNOPSIS

9           package MyOrg::Template::Plugin::MyFilter;
10
11           use Template::Plugin::Filter;
12           use base qw( Template::Plugin::Filter );
13
14           sub filter {
15               my ($self, $text) = @_;
16
17               # ...mungify $text...
18
19               return $text;
20           }
21
22           # now load it...
23           [% USE MyFilter %]
24
25           # ...and use the returned object as a filter
26           [% FILTER $MyFilter %]
27             ...
28           [% END %]
29

DESCRIPTION

31       This module implements a base class for plugin filters.  It hides the
32       underlying complexity involved in creating and using filters that get
33       defined and made available by loading a plugin.
34
35       To use the module, simply create your own plugin module that is inher‐
36       ited from the Template::Plugin::Filter class.
37
38           package MyOrg::Template::Plugin::MyFilter;
39
40           use Template::Plugin::Filter;
41           use base qw( Template::Plugin::Filter );
42
43       Then simply define your filter() method.  When called, you get passed a
44       reference to your plugin object ($self) and the text to be filtered.
45
46           sub filter {
47               my ($self, $text) = @_;
48
49               # ...mungify $text...
50
51               return $text;
52           }
53
54       To use your custom plugin, you have to make sure that the Template
55       Toolkit knows about your plugin namespace.
56
57           my $tt2 = Template->new({
58               PLUGIN_BASE => 'MyOrg::Template::Plugin',
59           });
60
61       Or for individual plugins you can do it like this:
62
63           my $tt2 = Template->new({
64               PLUGINS => {
65                   MyFilter => 'MyOrg::Template::Plugin::MyFilter',
66               },
67           });
68
69       Then you USE your plugin in the normal way.
70
71           [% USE MyFilter %]
72
73       The object returned is stored in the variable of the same name, 'MyFil‐
74       ter'.  When you come to use it as a FILTER, you should add a dollar
75       prefix.  This indicates that you want to use the filter stored in the
76       variable 'MyFilter' rather than the filter named 'MyFilter', which is
77       an entirely different thing (see later for information on defining fil‐
78       ters by name).
79
80           [% FILTER $MyFilter %]
81              ...text to be filtered...
82           [% END %]
83
84       You can, of course, assign it to a different variable.
85
86           [% USE blat = MyFilter %]
87
88           [% FILTER $blat %]
89              ...text to be filtered...
90           [% END %]
91
92       Any configuration parameters passed to the plugin constructor from the
93       USE directive are stored internally in the object for inspection by the
94       filter() method (or indeed any other method).  Positional arguments are
95       stored as a reference to a list in the _ARGS item while named configu‐
96       ration parameters are stored as a reference to a hash array in the
97       _CONFIG item.
98
99       For example, loading a plugin as shown here:
100
101           [% USE blat = MyFilter 'foo' 'bar' baz = 'blam' %]
102
103       would allow the filter() method to do something like this:
104
105           sub filter {
106               my ($self, $text) = @_;
107
108               my $args = $self->{ _ARGS   };  # [ 'foo', 'bar' ]
109               my $conf = $self->{ _CONFIG };  # { baz => 'blam' }
110
111               # ...munge $text...
112
113               return $text;
114           }
115
116       By default, plugins derived from this module will create static fil‐
117       ters.  A static filter is created once when the plugin gets loaded via
118       the USE directive and re-used for all subsequent FILTER operations.
119       That means that any argument specified with the FILTER directive are
120       ignored.
121
122       Dynamic filters, on the other hand, are re-created each time they are
123       used by a FILTER directive.  This allows them to act on any parameters
124       passed from the FILTER directive and modify their behaviour accord‐
125       ingly.
126
127       There are two ways to create a dynamic filter.  The first is to define
128       a $DYNAMIC class variable set to a true value.
129
130           package MyOrg::Template::Plugin::MyFilter;
131
132           use Template::Plugin::Filter;
133           use base qw( Template::Plugin::Filter );
134           use vars qw( $DYNAMIC );
135
136           $DYNAMIC = 1;
137
138       The other way is to set the internal _DYNAMIC value within the init()
139       method which gets called by the new() constructor.
140
141           sub init {
142               my $self = shift;
143               $self->{ _DYNAMIC } = 1;
144               return $self;
145           }
146
147       When this is set to a true value, the plugin will automatically create
148       a dynamic filter.  The outcome is that the filter() method will now
149       also get passed a reference to an array of postional arguments and a
150       reference to a hash array of named parameters.
151
152       So, using a plugin filter like this:
153
154           [% FILTER $blat 'foo' 'bar' baz = 'blam' %]
155
156       would allow the filter() method to work like this:
157
158           sub filter {
159               my ($self, $text, $args, $conf) = @_;
160
161               # $args = [ 'foo', 'bar' ]
162               # $conf = { baz => 'blam' }
163
164           }
165
166       In this case can pass parameters to both the USE and FILTER directives,
167       so your filter() method should probably take that into account.
168
169           [% USE MyFilter 'foo' wiz => 'waz' %]
170
171           [% FILTER $MyFilter 'bar' biz => 'baz' %]
172              ...
173           [% END %]
174
175       You can use the merge_args() and merge_config() methods to do a quick
176       and easy job of merging the local (e.g. FILTER) parameters with the
177       internal (e.g. USE) values and returning new sets of conglomerated
178       data.
179
180           sub filter {
181               my ($self, $text, $args, $conf) = @_;
182
183               $args = $self->merge_args($args);
184               $conf = $self->merge_config($conf);
185
186               # $args = [ 'foo', 'bar' ]
187               # $conf = { wiz => 'waz', biz => 'baz' }
188               ...
189           }
190
191       You can also have your plugin install itself as a named filter by call‐
192       ing the install_filter() method from the init() method.  You should
193       provide a name for the filter, something that you might like to make a
194       configuration option.
195
196           sub init {
197               my $self = shift;
198               my $name = $self->{ _CONFIG }->{ name } ⎪⎪ 'myfilter';
199               $self->install_filter($name);
200               return $self;
201           }
202
203       This allows the plugin filter to be used as follows:
204
205           [% USE MyFilter %]
206
207           [% FILTER myfilter %]
208              ...
209           [% END %]
210
211       or
212
213           [% USE MyFilter name = 'swipe' %]
214
215           [% FILTER swipe %]
216              ...
217           [% END %]
218
219       Alternately, you can allow a filter name to be specified as the first
220       positional argument.
221
222           sub init {
223               my $self = shift;
224               my $name = $self->{ _ARGS }->[0] ⎪⎪ 'myfilter';
225               $self->install_filter($name);
226               return $self;
227           }
228
229           [% USE MyFilter 'swipe' %]
230
231           [% FILTER swipe %]
232              ...
233           [% END %]
234

EXAMPLE

236       Here's a complete example of a plugin filter module.
237
238           package My::Template::Plugin::Change;
239           use Template::Plugin::Filter;
240           use base qw( Template::Plugin::Filter );
241
242           sub init {
243               my $self = shift;
244
245               $self->{ _DYNAMIC } = 1;
246
247               # first arg can specify filter name
248               $self->install_filter($self->{ _ARGS }->[0] ⎪⎪ 'change');
249
250               return $self;
251           }
252
253           sub filter {
254               my ($self, $text, $args, $config) = @_;
255
256               $config = $self->merge_config($config);
257               my $regex = join('⎪', keys %$config);
258
259               $text =~ s/($regex)/$config->{ $1 }/ge;
260
261               return $text;
262           }
263
264           1;
265

AUTHOR

267       Andy Wardley <abw@wardley.org>
268
269       <http://wardley.org/⎪http://wardley.org/>
270

VERSION

272       1.36, distributed as part of the Template Toolkit version 2.18,
273       released on 09 February 2007.
274

COPYRIGHT

276         Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
277
278       This module is free software; you can redistribute it and/or modify it
279       under the same terms as Perl itself.
280