[%#
  # IMPORTANT NOTE
  #   This documentation is generated automatically from source
  #   templates.  Any changes you make here may be lost.
  # 
  #   The 'docsrc' documentation source bundle is available for download
  #   from http://www.template-toolkit.org/docs.html and contains all
  #   the source templates, XML files, scripts, etc., from which the
  #   documentation for the Template Toolkit is built.
-%]
[% META book = 'Modules'
        page = 'Plugin_Filter'
%]
[%  WRAPPER toc;
	PROCESS tocitem 
	        title ="SYNOPSIS"
                subs  = [];
	PROCESS tocitem 
	        title ="DESCRIPTION"
                subs  = [];
	PROCESS tocitem 
	        title ="EXAMPLE"
                subs  = [];
	PROCESS tocitem 
	        title ="AUTHOR"
                subs  = [];
	PROCESS tocitem 
	        title ="VERSION"
                subs  = [];
	PROCESS tocitem 
	        title ="COPYRIGHT"
                subs  = [];
	PROCESS tocitem 
	        title ="SEE ALSO"
                subs  = [];
    END
%]
<!-- Pod to HTML conversion by the Template Toolkit version 2 -->
[% WRAPPER section
    title="SYNOPSIS"
-%]<pre>    package MyOrg::Template::Plugin::MyFilter;</pre>
<pre>    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );</pre>
<pre>    sub filter {
	my ($self, $text) = @_;</pre>
<pre>	# ...mungify $text...</pre>
<pre>	return $text;
    }</pre>
<pre>    # now load it...
    [% tt_start_tag %] USE MyFilter [% tt_end_tag %]</pre>
<pre>    # ...and use the returned object as a filter
    [% tt_start_tag %] FILTER $MyFilter [% tt_end_tag %]
      ...
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
[%- END %]
[% WRAPPER section
    title="DESCRIPTION"
-%]<p>
This module implements a base class for plugin filters.  It hides
the underlying complexity involved in creating and using filters
that get defined and made available by loading a plugin.
</p>
<p>
To use the module, simply create your own plugin module that is 
inherited from the Template::Plugin::Filter class.
</p>
<pre>    package MyOrg::Template::Plugin::MyFilter;</pre>
<pre>    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );</pre>
<p>
Then simply define your filter() method.  When called, you get
passed a reference to your plugin object ($self) and the text
to be filtered.
</p>
<pre>    sub filter {
	my ($self, $text) = @_;</pre>
<pre>	# ...mungify $text...</pre>
<pre>	return $text;
    }</pre>
<p>
To use your custom plugin, you have to make sure that the Template
Toolkit knows about your plugin namespace.
</p>
<pre>    my $tt2 = Template-&gt;new({
	PLUGIN_BASE =&gt; 'MyOrg::Template::Plugin',
    });</pre>
<p>
Or for individual plugins you can do it like this:
</p>
<pre>    my $tt2 = Template-&gt;new({
	PLUGINS =&gt; {
	    MyFilter =&gt; 'MyOrg::Template::Plugin::MyFilter',
	},
    });</pre>
<p>
Then you USE your plugin in the normal way.
</p>
<pre>    [% tt_start_tag %] USE MyFilter [% tt_end_tag %]</pre>
<p>
The object returned is stored in the variable of the same name,
'MyFilter'.  When you come to use it as a FILTER, you should add
a dollar prefix.  This indicates that you want to use the filter 
stored in the variable 'MyFilter' rather than the filter named 
'MyFilter', which is an entirely different thing (see later for 
information on defining filters by name).
</p>
<pre>    [% tt_start_tag %] FILTER $MyFilter [% tt_end_tag %]
       ...text to be filtered...
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
You can, of course, assign it to a different variable.
</p>
<pre>    [% tt_start_tag %] USE blat = MyFilter [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] FILTER $blat [% tt_end_tag %]
       ...text to be filtered...
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
Any configuration parameters passed to the plugin constructor from the
USE directive are stored internally in the object for inspection by
the filter() method (or indeed any other method).  Positional
arguments are stored as a reference to a list in the _ARGS item while
named configuration parameters are stored as a reference to a hash
array in the _CONFIG item.
</p>
<p>
For example, loading a plugin as shown here:
</p>
<pre>    [% tt_start_tag %] USE blat = MyFilter 'foo' 'bar' baz = 'blam' [% tt_end_tag %]</pre>
<p>
would allow the filter() method to do something like this:
</p>
<pre>    sub filter {
	my ($self, $text) = @_;</pre>
<pre>	my $args = $self-&gt;{ _ARGS   };  # [ 'foo', 'bar' ]
	my $conf = $self-&gt;{ _CONFIG };  # { baz =&gt; 'blam' }</pre>
<pre>	# ...munge $text...</pre>
<pre>	return $text;
    }</pre>
<p>
By default, plugins derived from this module will create static
filters.  A static filter is created once when the plugin gets 
loaded via the USE directive and re-used for all subsequent
FILTER operations.  That means that any argument specified with
the FILTER directive are ignored.
</p>
<p>
Dynamic filters, on the other hand, are re-created each time 
they are used by a FILTER directive.  This allows them to act
on any parameters passed from the FILTER directive and modify
their behaviour accordingly.  
</p>
<p>
There are two ways to create a dynamic filter.  The first is to
define a $DYNAMIC class variable set to a true value.
</p>
<pre>    package MyOrg::Template::Plugin::MyFilter;</pre>
<pre>    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );
    use vars qw( $DYNAMIC );</pre>
<pre>    $DYNAMIC = 1;</pre>
<p>
The other way is to set the internal _DYNAMIC value within the init()
method which gets called by the new() constructor.
</p>
<pre>    sub init {
	my $self = shift;
	$self-&gt;{ _DYNAMIC } = 1;
	return $self;
    }</pre>
<p>
When this is set to a true value, the plugin will automatically
create a dynamic filter.  The outcome is that the filter() method
will now also get passed a reference to an array of postional
arguments and a reference to a hash array of named parameters.
</p>
<p>
So, using a plugin filter like this:
</p>
<pre>    [% tt_start_tag %] FILTER $blat 'foo' 'bar' baz = 'blam' [% tt_end_tag %]</pre>
<p>
would allow the filter() method to work like this:
</p>
<pre>    sub filter {
	my ($self, $text, $args, $conf) = @_;</pre>
<pre>	# $args = [ 'foo', 'bar' ]
	# $conf = { baz =&gt; 'blam' }</pre>
<pre>    }</pre>
<p>
In this case can pass parameters to both the USE and FILTER directives,
so your filter() method should probably take that into account.  
</p>
<pre>    [% tt_start_tag %] USE MyFilter 'foo' wiz =&gt; 'waz' [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] FILTER $MyFilter 'bar' biz =&gt; 'baz' [% tt_end_tag %]
       ...
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
You can use the merge_args() and merge_config() methods to do a quick
and easy job of merging the local (e.g. FILTER) parameters with the
internal (e.g. USE) values and returning new sets of conglomerated
data.
</p>
<pre>    sub filter {
	my ($self, $text, $args, $conf) = @_;</pre>
<pre>	$args = $self-&gt;merge_args($args); 
	$conf = $self-&gt;merge_config($conf);</pre>
<pre>	# $args = [ 'foo', 'bar' ]	
	# $conf = { wiz =&gt; 'waz', biz =&gt; 'baz' }	
	...
    }</pre>
<p>
You can also have your plugin install itself as a named filter by
calling the install_filter() method from the init() method.  You 
should provide a name for the filter, something that you might 
like to make a configuration option.
</p>
<pre>    sub init {
	my $self = shift;
	my $name = $self-&gt;{ _CONFIG }-&gt;{ name } || 'myfilter';
	$self-&gt;install_filter($name);
	return $self;
    }</pre>
<p>
This allows the plugin filter to be used as follows:
</p>
<pre>    [% tt_start_tag %] USE MyFilter [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] FILTER myfilter [% tt_end_tag %] 
       ... 
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
or			
</p>
<pre>    [% tt_start_tag %] USE MyFilter name = 'swipe' [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] FILTER swipe [% tt_end_tag %] 
       ... 
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
Alternately, you can allow a filter name to be specified as the 
first positional argument.
</p>
<pre>    sub init {
	my $self = shift;
	my $name = $self-&gt;{ _ARGS }-&gt;[0] || 'myfilter';
	$self-&gt;install_filter($name);
	return $self;
    }</pre>
<pre>    [% tt_start_tag %] USE MyFilter 'swipe' [% tt_end_tag %]
    
    [% tt_start_tag %] FILTER swipe [% tt_end_tag %]
       ...
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
[%- END %]
[% WRAPPER section
    title="EXAMPLE"
-%]<p>
Here's a complete example of a plugin filter module.
</p>
<pre>    package My::Template::Plugin::Change;
    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );</pre>
<pre>    sub init {
    	my $self = shift;</pre>
<pre>	$self-&gt;{ _DYNAMIC } = 1;</pre>
<pre>	# first arg can specify filter name
	$self-&gt;install_filter($self-&gt;{ _ARGS }-&gt;[0] || 'change');</pre>
<pre>	return $self;
    }</pre>
<pre>    sub filter {
	my ($self, $text, $args, $config) = @_;</pre>
<pre>	$config = $self-&gt;merge_config($config);
	my $regex = join('|', keys %$config);</pre>
<pre>	$text =~ s/($regex)/$config-&gt;{ $1 }/ge;</pre>
<pre>	return $text;
    }</pre>
<pre>    1;</pre>
[%- END %]
[% WRAPPER section
    title="AUTHOR"
-%]<p>
Andy Wardley &lt;abw@wardley.org&gt;
</p>
<p>
[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
    title="VERSION"
-%]<p>
1.36, distributed as part of the
Template Toolkit version 2.19, released on 27 April 2007.
</p>
[%- END %]
[% WRAPPER section
    title="COPYRIGHT"
-%]<pre>  Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.</pre>
<p>
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
</p>
[%- END %]
[% WRAPPER section
    title="SEE ALSO"
-%]<p>
[% ttlink('Template::Plugin', 'Template::Plugin') -%], [% ttlink('Template::Filters', 'Template::Filters') -%], [% ttlink('Template::Manual::Filters', 'Template::Manual::Filters') -%]
</p>
[%- END %]