---
name: "Template::Plugin::Filter"
section: "3pm"
platform: "linux"
package: "perl-template-toolkit"
version: "3.106-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Template::Plugin::Filter"
---

# Template::Plugin::Filter(3pm)

Base class for plugin filters

## NAME

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

## SYNOPSIS

```
    package MyOrg::Template::Plugin::MyFilter;
    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );
    sub filter {
        my ($self, $text) = @_;
        # ...mungify $text...
        return $text;
    }
    # now load it...
    [% USE MyFilter %]
    # ...and use the returned object as a filter
    [% FILTER $MyFilter %]
      ...
    [% END %]
```

## DESCRIPTION

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.

To use the module, simply create your own plugin module that is inherited from the `"Template::Plugin::Filter"` class.

```
    package MyOrg::Template::Plugin::MyFilter;
    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );
```

Then simply define your `filter()` method.  When called, you get passed a reference to your plugin object (`$self`) and the text to be filtered.

```
    sub filter {
        my ($self, $text) = @_;
        # ...mungify $text...
        return $text;
    }
```

To use your custom plugin, you have to make sure that the Template Toolkit knows about your plugin namespace.

```
    my $tt2 = Template->new({
        PLUGIN_BASE => 'MyOrg::Template::Plugin',
    });
```

Or for individual plugins you can do it like this:

```
    my $tt2 = Template->new({
        PLUGINS => {
            MyFilter => 'MyOrg::Template::Plugin::MyFilter',
        },
    });
```

Then you `"USE"` your plugin in the normal way.

```
    [% USE MyFilter %]
```

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).

```
    [% FILTER $MyFilter %]
       ...text to be filtered...
    [% END %]
```

You can, of course, assign it to a different variable.

```
    [% USE blat = MyFilter %]
    [% FILTER $blat %]
       ...text to be filtered...
    [% END %]
```

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.

For example, loading a plugin as shown here:

```
    [% USE blat = MyFilter 'foo' 'bar' baz = 'blam' %]
```

would allow the `filter()` method to do something like this:

```
    sub filter {
        my ($self, $text) = @_;
        my $args = $self->{ _ARGS   };  # [ 'foo', 'bar' ]
        my $conf = $self->{ _CONFIG };  # { baz => 'blam' }
        # ...munge $text...
        return $text;
    }
```

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.

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.

There are two ways to create a dynamic filter.  The first is to define a `$DYNAMIC` class variable set to a true value.

```
    package MyOrg::Template::Plugin::MyFilter;
    use base 'Template::Plugin::Filter';
    our $DYNAMIC = 1;
```

The other way is to set the internal `"_DYNAMIC"` value within the `init()` method which gets called by the `new()` constructor.

```
    sub init {
        my $self = shift;
        $self->{ _DYNAMIC } = 1;
        return $self;
    }
```

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 positional arguments and a reference to a hash array of named parameters.

So, using a plugin filter like this:

```
    [% FILTER $blat 'foo' 'bar' baz = 'blam' %]
```

would allow the `filter()` method to work like this:

```
    sub filter {
        my ($self, $text, $args, $conf) = @_;
        # $args = [ 'foo', 'bar' ]
        # $conf = { baz => 'blam' }
    }
```

In this case can pass parameters to both the USE and FILTER directives, so your **filter()** method should probably take that into account.

```
    [% USE MyFilter 'foo' wiz => 'waz' %]
    [% FILTER $MyFilter 'bar' biz => 'baz' %]
       ...
    [% END %]
```

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.

```
    sub filter {
        my ($self, $text, $args, $conf) = @_;
        $args = $self->merge_args($args);
        $conf = $self->merge_config($conf);
        # $args = [ 'foo', 'bar' ]
        # $conf = { wiz => 'waz', biz => 'baz' }
        ...
    }
```

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.

```
    sub init {
        my $self = shift;
        my $name = $self->{ _CONFIG }->{ name } || 'myfilter';
        $self->install_filter($name);
        return $self;
    }
```

This allows the plugin filter to be used as follows:

```
    [% USE MyFilter %]
    [% FILTER myfilter %]
       ...
    [% END %]
```

or

```
    [% USE MyFilter name = 'swipe' %]
    [% FILTER swipe %]
       ...
    [% END %]
```

Alternately, you can allow a filter name to be specified as the first positional argument.

```
    sub init {
        my $self = shift;
        my $name = $self->{ _ARGS }->[0] || 'myfilter';
        $self->install_filter($name);
        return $self;
    }
    [% USE MyFilter 'swipe' %]
    [% FILTER swipe %]
       ...
    [% END %]
```

## EXAMPLE

Here's a complete example of a plugin filter module.

```
    package My::Template::Plugin::Change;
    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );
    sub init {
        my $self = shift;
        $self->{ _DYNAMIC } = 1;
        # first arg can specify filter name
        $self->install_filter($self->{ _ARGS }->[0] || 'change');
        return $self;
    }
    sub filter {
        my ($self, $text, $args, $config) = @_;
        $config = $self->merge_config($config);
        my $regex = join('|', keys %$config);
        $text =~ s/($regex)/$config->{ $1 }/ge;
        return $text;
    }
    1;
```

## AUTHOR

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

## COPYRIGHT

Copyright (C) 1996-2022 Andy Wardley.  All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

## SEE ALSO

Template::Plugin, Template::Filters, Template::Manual::Filters