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

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

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

	# ...изменяем $text...

	return $text;
    }

    # теперь загружаем его...
    [% USE MyFilter %]

    # ...и используем возвращаемый объект как фильтр
    [% FILTER $MyFilter %]
      ...
    [% END %]

Этот модуль реализует базовый класс для плагинов-фильтров. Он скрывает в себе лежащие в основе сложности в создании и использовании фильтров, определяемых и доступных через загрузку плагина.

Чтобы использовать модуль, просто создайте свой собственный модуль-плагин, наследующий класс Template::Plugin::Filter.

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

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

Затем просто определите ваш метод filter(). При вызове он получает ссылку на объект плагина ($self) и текст, который нужно обработать фильтром.

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

	# ...изменяем $text...

	return $text;
    }

При использовании собственного плагина нужно убедиться, что Template Toolkit знает пространство имен вашего плагина.

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

Или для единичных плагинов можно сделать таким образом:

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

Затем можно использовать (USE) плагин обычным способом.

    [% USE MyFilter %]

Возвращаемый объект сохраняется в переменной с тем же именем 'MyFilter'. При использовании его в FILTER нужно добавить префикс '$', что означает что вы хотите использовать фильтр, хранящийся в переменной 'MyFilter', а не фильтр с именем 'MyFilter', что вообще говоря разные вещи (смотри далее информацию об определении имен фильтров).

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

Разумеется, можно назначить другое имя переменной.

    [% USE blat = MyFilter %]

    [% FILTER $blat %]
       ...текст который нужно обработать фильтром...
    [% END %]

Любые параметры конфигурации, передаваемые конструктору плагина через директиву USE, сохраняются внутри объекта, чтобы быть доступными из метода filter() (и разумеется из любого другого метода). Списковые (позиционные)аргументы сохраняются как ссылка на массив в элементе _ARGS, в то время как именованные параметры конфигурации сохраняются в виде ссылки на хеш в элементе _CONFIG.

Например, загружая плагин следующим образом:

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

мы позволяем методу filter() сделать что-то подобное:

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

	my $args = $self->{ _ARGS   };  # [ 'foo', 'bar' ]
	my $conf = $self->{ _CONFIG };  # { baz => 'blam' }

	# ...меняем текст $text...

	return $text;
    }

По умолчанию, плагины, производные от этого модуля, создают статические фильтры. Статический фильтр создается один раз при загрузке через директиву USE и повторно используется во всех последующих операциях FILTER. Это означает, что любые аргументы, передаваемые в директиве FILTER, игнорируются.

С другой стороны, динамические фильтры создаются заново при каждом вызове директивы FILTER. Это позволяет им реагировать на любые параметры, передаваемые от директивы FILTER и соответствующим образом изменять свое поведение.

Есть два способа создания динамического фильтра. Первый - определение переменной класса $DYNAMIC, установленной в истинное значение.

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

    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );
    use vars qw( $DYNAMIC );

    $DYNAMIC = 1;

Другой способ - установка значения внутренней переменной _DYNAMIC внутри метода init(), который вызывается конструктором new().

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

Когда это значение установлено в истинное значение, плагин автоматически создает динамический фильтр. В результате этого метод filter() теперь также будет получать ссылку на массив списковых (позиционных) аргументов и ссылку на хеш с именованными параметрами.

Таким образом, используя плагин-фильтр следующим образом:

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

мы позволяем методу filter() работать следующим образом:

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

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

    }

В этом случае можно передавать параметры как директиве USE, так и FILTER, и метод filter() вероятно должен это учитывать.

    [% USE MyFilter 'foo' wiz => 'waz' %]

    [% FILTER $MyFilter 'bar' biz => 'baz' %]
       ...
    [% END %]

Можно использовать методы merge_args() и merge_config(), чтобы быстро и легко выполнить работу по объединению локальных (т.е. полученных через FILTER) параметров с внутренними (т.е. полученными через USE) значениями и получением новых наборов объединенных данных.

    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' }
	...
    }

Также можно установить плагин как именованный фильтр, вызвав метод install_filter() в методе init(). Можно определить имя фильтра, в том числе через какую-нибудь опцию конфигурации.

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

Это позволяет использовать плагин-фильтр следующим образом:

    [% USE MyFilter %]

    [% FILTER myfilter %]
       ...
    [% END %]

или

    [% USE MyFilter name = 'swipe' %]

    [% FILTER swipe %]
       ...
    [% END %]

Как вариант, можно разрешить устанавливать имя фильтра через первый списочный (позиционный) аргумент.

    sub init {
	my $self = shift;
	my $name = $self->{ _ARGS }->[0] || 'myfilter';
	$self->install_filter($name);
	return $self;
    }

    [% USE MyFilter 'swipe' %]

    [% FILTER swipe %]
       ...
    [% END %]

Ниже приведен полный пример модуля плагина-фильтра.

    package My::Template::Plugin::Change;
    use Template::Plugin::Filter;
    use base qw( Template::Plugin::Filter );

    sub init {
    	my $self = shift;

	$self->{ _DYNAMIC } = 1;

	# первый аргумент может содержать имя фильтра
	$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;

Энди Уардли (Andy Wardley <abw@andywardley.com>)

http://www.andywardley.com/

1.31, поставляется в составе Template Toolkit версии 2.14, дата релиза - 4 октября 2004.

  Copyright (C) 1996-2004 Andy Wardley.  All Rights Reserved.
  Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.

Этот модуль является свободно-распространяемым программным обеспечением; вы можете распространять и/или модифицировать его на тех же условиях, что и Perl.

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