#============================================================= -*-Perl-*-
#
# Template::Plugin::Filter
#
# DESCRIPTION
# Template Toolkit module implementing a base class plugin
# object which acts like a filter and can be used with the
# FILTER directive.
#
# AUTHOR
# Andy Wardley
#
# COPYRIGHT
# Copyright (C) 2001-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.
#
#============================================================================
package Template::Plugin::Filter;
use strict;
use warnings;
use base 'Template::Plugin';
use Scalar::Util 'weaken', 'isweak';
our $VERSION = '3.106';
our $DYNAMIC = 0 unless defined $DYNAMIC;
sub new {
my ($class, $context, @args) = @_;
my $config = @args && ref $args[-1] eq 'HASH' ? pop(@args) : { };
# look for $DYNAMIC
my $dynamic;
{
no strict 'refs';
$dynamic = ${"$class\::DYNAMIC"};
}
$dynamic //= $DYNAMIC;
my $self = bless {
_CONTEXT => $context,
_DYNAMIC => $dynamic,
_ARGS => \@args,
_CONFIG => $config,
}, $class;
return $self->init($config)
|| $class->error($self->error());
}
sub init {
my ($self, $config) = @_;
return $self;
}
sub factory {
my $self = shift;
my $this = $self;
# avoid a memory leak
weaken( $this->{_CONTEXT} ) if ref $this->{_CONTEXT}
&& !isweak $this->{_CONTEXT};
if ($self->{ _DYNAMIC }) {
return [ sub {
my ($context, @args) = @_;
my $config = ref $args[-1] eq 'HASH' ? pop(@args) : { };
return sub {
$this->filter(shift, \@args, $config);
};
}, 1 ];
}
else {
return sub {
$this->filter(shift);
};
}
}
sub filter {
my ($self, $text, $args, $config) = @_;
return $text;
}
sub merge_config {
my ($self, $newcfg) = @_;
my $owncfg = $self->{ _CONFIG };
return $owncfg unless $newcfg;
return { %$owncfg, %$newcfg };
}
sub merge_args {
my ($self, $newargs) = @_;
my $ownargs = $self->{ _ARGS };
return $ownargs unless $newargs;
return [ @$ownargs, @$newargs ];
}
sub install_filter {
my ($self, $name) = @_;
$self->{ _CONTEXT }->define_filter( $name => $self->factory );
return $self;
}
1;
__END__
=head1 NAME
Template::Plugin::Filter - Base class for plugin filters
=head1 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 %]
=head1 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 C class.
package MyOrg::Template::Plugin::MyFilter;
use Template::Plugin::Filter;
use base qw( Template::Plugin::Filter );
Then simply define your C method. When called, you get
passed a reference to your plugin object (C<$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 C