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
36       inherited 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
44       a 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,
74       '"MyFilter"'.  When you come to use it as a "FILTER", you should add a
75       dollar prefix.  This indicates that you want to use the filter stored
76       in the variable '"MyFilter"' rather than the filter named '"MyFilter"',
77       which is an entirely different thing (see later for information on
78       defining filters 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
94       the "filter()" method (or indeed any other method).  Positional
95       arguments are stored as a reference to a list in the "_ARGS" item while
96       named configuration parameters are stored as a reference to a hash
97       array in the "_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
117       filters.  A static filter is created once when the plugin gets loaded
118       via the "USE" directive and re-used for all subsequent "FILTER"
119       operations.  That means that any argument specified with the "FILTER"
120       directive are 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
124       parameters passed from the "FILTER" directive and modify their
125       behaviour accordingly.
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           use base 'Template::Plugin::Filter';
132           our $DYNAMIC = 1;
133
134       The other way is to set the internal "_DYNAMIC" value within the
135       "init()" method which gets called by the "new()" constructor.
136
137           sub init {
138               my $self = shift;
139               $self->{ _DYNAMIC } = 1;
140               return $self;
141           }
142
143       When this is set to a true value, the plugin will automatically create
144       a dynamic filter.  The outcome is that the "filter()" method will now
145       also get passed a reference to an array of postional arguments and a
146       reference to a hash array of named parameters.
147
148       So, using a plugin filter like this:
149
150           [% FILTER $blat 'foo' 'bar' baz = 'blam' %]
151
152       would allow the "filter()" method to work like this:
153
154           sub filter {
155               my ($self, $text, $args, $conf) = @_;
156
157               # $args = [ 'foo', 'bar' ]
158               # $conf = { baz => 'blam' }
159           }
160
161       In this case can pass parameters to both the USE and FILTER directives,
162       so your filter() method should probably take that into account.
163
164           [% USE MyFilter 'foo' wiz => 'waz' %]
165
166           [% FILTER $MyFilter 'bar' biz => 'baz' %]
167              ...
168           [% END %]
169
170       You can use the "merge_args()" and "merge_config()" methods to do a
171       quick and easy job of merging the local (e.g. "FILTER") parameters with
172       the internal (e.g. "USE") values and returning new sets of
173       conglomerated data.
174
175           sub filter {
176               my ($self, $text, $args, $conf) = @_;
177
178               $args = $self->merge_args($args);
179               $conf = $self->merge_config($conf);
180
181               # $args = [ 'foo', 'bar' ]
182               # $conf = { wiz => 'waz', biz => 'baz' }
183               ...
184           }
185
186       You can also have your plugin install itself as a named filter by
187       calling the "install_filter()" method from the "init()" method.  You
188       should provide a name for the filter, something that you might like to
189       make a configuration option.
190
191           sub init {
192               my $self = shift;
193               my $name = $self->{ _CONFIG }->{ name } || 'myfilter';
194               $self->install_filter($name);
195               return $self;
196           }
197
198       This allows the plugin filter to be used as follows:
199
200           [% USE MyFilter %]
201
202           [% FILTER myfilter %]
203              ...
204           [% END %]
205
206       or
207
208           [% USE MyFilter name = 'swipe' %]
209
210           [% FILTER swipe %]
211              ...
212           [% END %]
213
214       Alternately, you can allow a filter name to be specified as the first
215       positional argument.
216
217           sub init {
218               my $self = shift;
219               my $name = $self->{ _ARGS }->[0] || 'myfilter';
220               $self->install_filter($name);
221               return $self;
222           }
223
224           [% USE MyFilter 'swipe' %]
225
226           [% FILTER swipe %]
227              ...
228           [% END %]
229

EXAMPLE

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

AUTHOR

262       Andy Wardley <abw@wardley.org> <http://wardley.org/>
263

COPYRIGHT

265       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
266
267       This module is free software; you can redistribute it and/or modify it
268       under the same terms as Perl itself.
269

NAME

SYNOPSIS

DESCRIPTION

EXAMPLE

AUTHOR

COPYRIGHT

SEE ALSO