Templat...:Filter(3)

okay so we're in Templat...:Filter(3) from the User Contributed Perl Documentation, and this page is literally the base-class blueprint for plugin filters. bestie, it's giving “make your own filter without crying.” 💅

💖 NAME 💖

Template::Plugin::Filter — base class for plugin filters. periodt.

✨ SYNOPSIS ✨

here's the exact code vibe, no cap:

           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 is a base class for plugin filters. It hides all the underlying complexity of creating and using filters that get defined and made available by loading a plugin. lowkey iconic.

To use it, you just create your own plugin module that inherits from the Template::Plugin::Filter class:

           package MyOrg::Template::Plugin::MyFilter;

           use Template::Plugin::Filter;
           use base qw( Template::Plugin::Filter );

Then you define your filter() method. When it's called, you get a reference to your plugin object ($self) and the text to be filtered. easy.

           sub filter {
               my ($self, $text) = @_;

               # ...mungify $text...

               return $text;
           }

To use your custom plugin, make sure Template Toolkit knows about your plugin namespace. like this:

           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, add a dollar prefix. That indicates you want the filter stored in the variable "MyFilter" rather than the filter named "MyFilter" — those are an entirely different thing (see later for info 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 so the filter() method (or literally any other method) can inspect them. 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 like this:

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

would let the filter() method 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 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 any argument specified with the FILTER directive are ignored. 🫠

Dynamic filters, on the other hand, are re-created each time they're used by a FILTER directive. That lets them act on any parameters passed from the FILTER directive and modify their behaviour accordingly.

There are two ways to create a dynamic filter. First way: 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 inside 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 automatically creates 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 let the filter() method work like this:

           sub filter {
               my ($self, $text, $args, $conf) = @_;

               # $args = [ 'foo', 'bar' ]
               # $conf = { baz => 'blam' }
           }

In this case you 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 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 like this:

           [% 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. slay:

           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/> — bestie authored the whole thing.

🎀 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

---

okay bye bestie 💖 this page is from perl v5.42.0, dated 2024-06-23 — mwah, go make a filter and eat 💅✨