Template Toolkit

    use Template::Plugins;

    $plugin_provider = Template::Plugins->new(\%options);

    ($plugin, $error) = $plugin_provider->fetch($name, @args);

Модуль Template::Plugins определяет класс-провайдер, который можно использовать для загрузки и инициализации модулей-плагинов Template Toolkit.

Конструктор создает и возвращает ссылку на объект Template::Plugins. В качестве параметра может примать ссылку на хеш конфигурации. Это описано ниже.

Учтите, что модуль-фронтенд Template.pm создает провайдера Template::Plugins, передавая ему все элементы конфигурации. Так приведенный ниже пример:

    $plugprov = Template::Plugins->new({
        PLUGIN_BASE => 'MyTemplate::Plugin',
        LOAD_PERL   => 1,
        ...
    });

также может быть реализован через модуль Template:

    $ttengine = Template->new({
        PLUGIN_BASE => 'MyTemplate::Plugin',
        LOAD_PERL   => 1,
        ...
    });

а также в более ясной форме:

    $plugprov = Template::Plugins->new({
        PLUGIN_BASE => 'MyTemplate::Plugin',
        LOAD_PERL   => 1,
        ...
    });

    $ttengine = Template->new({
        LOAD_PLUGINS => [ $plugprov ],
    });

Вызывается по запросу на предоставление плагина с указанным именем. Вначале загружается подходящий модуль (если необходимо) и вызывается метод класса load(), который возвращает имя производящего класса (обычно это имя пакета) или производящий объект (прототип). Затем вызывается метод new() производящего класса или объекта с передачей ему всех оставшихся параметров.

Возвращает ссылку на новый объект плагина или в случае ошибки пару ($error, STATUS_ERROR). Также может возвратить (undef, STATUS_DECLINED) в случае отказа от обслуживания запроса. Если установлена опция TOLERANT вместо ошибок будет возвращаться отказ от обслуживания.

Следующий список содержит детальное описание опций конфигурации, которые можно передать конструктору new() Template::Plugins.

• PLUGINS
  

  Опция PLUGINS используется для определения ссылки на хеш, связывающий имена плагинов с названиями модулей Perl. Ряд плагинов (например, 'table', 'cgi', 'dbi' и т.д.) уже определены и связаны с соответсвующими модулями Template::Plugin::*. Они могут быть переопределены в хеше PLUGINS.

      my $plugins = Template::Plugins->new({
          PLUGINS => {
              cgi => 'MyOrg::Template::Plugin::CGI',
              foo => 'MyOrg::Template::Plugin::Foo',
              bar => 'MyOrg::Template::Plugin::Bar',
          },
      });

  Директива USE используется для создания объектов плагинов и делает это посредством вызова метода plugin() текущего объекта Template::Context. Если имя плагина определено в хеше PLUGINS, соответствующий модуль Perl загружается посредством require(). Затем объект контекста вызывает метод класса load(), который должен вернуть имя класса (в общем случае и по умолчанию) или объект-прототип, вызов метода new() которого можно использовать для создания индивидуальных объектов плагинов.

  Если имя плагина не определено в хеше PLUGINS, вступают в силу опции PLUGIN_BASE и/или LOAD_PERL.

• PLUGIN_BASE
  

  Если плагин не определен в хеше PLUGINS, опция PLUGIN_BASE используется для конструирования правильного имени perl-модуля, который может быть удачно загружен.

  PLUGIN_BASE может быть определена как единичное значение или как ссылка на массив значений. Значение PLUGIN_BASE по умолчанию 'Template::Plugin' всегда добавляется в конец списка PLUGIN_BASE (единичное значение перед этим преобразуется в список). Каждое значение должно содержать пространство имен Perl, к которому добавляется запрашиваемое имя плагина.

  Пример 1:

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

      [% USE Foo %]    # => MyOrg::Template::Plugin::Foo
                         или       Template::Plugin::Foo

  Пример 2:

      my $template = Template->new({
  	PLUGIN_BASE => [   'MyOrg::Template::Plugin',
  			 'YourOrg::Template::Plugin'  ],
      });

      [% USE Foo %]    # =>    MyOrg::Template::Plugin::Foo
                         или YourOrg::Template::Plugin::Foo
                         или          Template::Plugin::Foo 

• LOAD_PERL
  

  Если не удается загрузить плагин с помощью PLUGINS или PLUGIN_BASE, поставщик плагинов пытается загрузить модуль без использования добавочного префикса в пути модуля. Это позволяет загружать и использовать в качестве плагинов обычные perl-модули (т.е. те модули, которые не находятся внутри Template::Plugin или других подобных пространств имен).

  По умолчанию, опция LOAD_PERL установлена в 0 и Template Toolkit не пытается загрузить модули, которые явно не определены в хеше PLUGINS или не находятся внутри пакетов, определенных в PLUGIN_BASE.

  Плагины, загружаемые с помощью PLUGINS или PLUGIN_BASE, получают ссылку на объект текущего контекста в качестве первого аргумента конструктора new(). Для модулей, загружаемых с помощью LOAD_PERL, предполагается, что они не следуют интерфейсу плагина. Они должны предоставлять метод new() для создания объектов, но ссылка на объект текущего контекста им в качестве первого аргумента не передается. Модули-плагины должны содержать метод класса load() (или унаследовать метод по умолчанию от базового класса Template::Plugin), который вызывается при первой загрузке плагина. Обычные модули Perl могут не содержать такого метода. Во всем остальном обычные perl-модули и плагины Template Toolkit идентичны.

  Если какой-то perl-модуль не следует общему, но не обязательному, соглашению о конструкторе new(), можно написать простой плагин-обертку, предоставляющий интерфейс для работы с этим модулем.

• TOLERANT
  

  Флаг TOLERANT используется различными модулями-поставщиками Template Toolkit (Template::Provider, Template::Plugins, Template::Filters) для управления их поведением при возникновении ошибок. По умолчанию, о любых ошибках как таковых генерируется отчет, с одновременным запретом доступа к их источнику (шаблон, плагин, фильтр) и возбуждением исключения. Когда флаг TOLERANT установлен в любое истинное значение, ошибки будут без уведомления игнорироваться, а поставщик вместо этого вернет отказ от обслуживания (STATUS_DECLINED). Это позволяет вместо неудачного завершения после запроса поставщику, передать ответственность за предоставление источника следующему поставщику. Если все поставщики отклонят запрос на обслуживание либо по причине возникновения ошибки, либо из-за невозможности его выполнить, возбуждается исключение '<resource> not found'.

• DEBUG
  

  Чтобы разрешить вывод отладочных сообщений от модуля Template::Plugins можно включить (логическое ИЛИ) значение DEBUG_PLUGINS в опцию DEBUG.

      use Template::Constants qw( :debug );
      my $template = Template->new({
          DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
      });

Следующие модули-плагины поставляются в составе Template Toolkit. Некоторые из плагинов являются интерфейсами к внешним модулям (описанным ниже), которые необходимо загрузить с CPAN и установить перед использованием соответсвующих плагинов.

Плагин Autoformat - интерфейс к модулю Демиана Конвея (Damian Conway) Text::Autoformat, который предоставляет широкие возможности по переносу и форматированию текста. Детальное описание смотрите в Template::Plugin::Autoformat и Text::Autoformat.

    [% USE autoformat(left=10, right=20) %]
    [% autoformat(mytext) %]	    # вызов функции autoformat
    [% mytext FILTER autoformat %]  # использование фильтра autoformat

Модуль Text::Autoformat доступен на CPAN:

    http://www.cpan.org/modules/by-module/Text/

Плагин CGI - обертка вокруг модуля CGI.pm Линкольна Стейна (Lincoln Stein's <lstein@genome.wi.mit.edu>). Плагин содержится в составе Template Toolkit, а сам модуль CGI поставляется в составе последних версий Perl, а также доступен на CPAN.

    [% USE CGI %]
    [% CGI.param('param_name') %]
    [% CGI.start_form %]
    [% CGI.popup_menu( Name   => 'color',
                       Values => [ 'Green', 'Brown' ] ) %]
    [% CGI.end_form %]

Предоставляет интерфейс к данным, хранящимся в текстовом файле в простом формате с разделителями. Первая строка файла определяет названия полей, которые должны быть разделены любой последовательностью небуквенных символов. Следующие строки определяют данные, использующие те же разделители, что используются в первой строке. Пустые строки и комментарии (строки начинающиеся с '#') игнорируются. Более подробно смотрите Template::Plugin::Datafile.

/tmp/mydata:

    # определение имен полей
    id : email : name : tel
    # данные
    fred : fred@here.com : Fred Smith : 555-1234
    bill : bill@here.com : Bill White : 555-5678

Пример:

    [% USE userlist = datafile('/tmp/mydata') %]

    [% FOREACH user = userlist %]
       [% user.name %] ([% user.id %])
    [% END %]

Плагин Date предоставляет простой способ форматирования строк, содержащих даты и время с использованием POSIX функции strftime(). Более подробно смотрите Template::Plugin::Date и POSIX.

    [% USE date %]
    [% date.format %]		# текущее время/дата

    File last modified: [% date.format(template.modtime) %]

Плагин Directory предоставляет простой интерфейс для работы с каталогами и файлами внутри них. Более подробно смотрите Template::Plugin::Directory.

    [% USE dir = Directory('/tmp') %]
    [% FOREACH file = dir.files %]
        # все обычные файлы в каталоге
    [% END %]
    [% FOREACH file = dir.dirs %]
        # все подкаталоги
    [% END %]

Написанный Симоном Мэттьюсом (Simon Matthews <sam@knowledgepool.com>) плагин DBI предоставляет вашим шаблонам всю мощь модуля-интерфейса к базам данных DBI Тима Банса (Tim Bunce <Tim.Bunce@ig.co.uk>). Более подробно смотрите Template::Plugin::DBI и DBI.

    [% USE DBI('dbi:driver:database', 'user', 'pass') %]

    [% FOREACH user = DBI.query( 'SELECT * FROM users' ) %]
       [% user.id %] [% user.name %]
    [% END %]

DBI и соответсвующие модули DBD доступны на CPAN:

  http://www.cpan.org/modules/by-module/DBI/

Плагин Dumper предоставляет интерфейс к модулю Data::Dumper. Более подробно смотрите Template::Plugin::Dumper и Data::Dumper.

    [% USE dumper(indent=0, pad="<br>") %]
    [% dumper.dump(myvar, yourvar) %]

Плагин File предоставляет общюю абстракцию для файлов и может быть использован для получения информации о файлах внутри файловой системы. Более подробно смотрите Template::Plugin::File.

    [% USE File('/tmp/foo.html') %]
    [% File.name %]     # foo.html
    [% File.dir %]      # /tmp
    [% File.mtime %]    # время изменения (modification time)

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

    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.

Плагин Format предоставляет простой способ форматирования текста в формате printf(). Более подробно смотрите Template::Plugin::Format.

    [% USE bold = format('<b>%s</b>') %]
    [% bold('Hello') %]

Эти плагины предоставляют доступ к графической библиотеке GD через интерфейс GD.pm Линкольна Стейна (Lincoln D. Stein). Этот плагин позволяет генерировать PNG, JPEG и другие графические форматы.

    [% FILTER null;
        USE im = GD.Image(100,100);
        # назначить цвета
        black = im.colorAllocate(0, 0, 0);
        red   = im.colorAllocate(255, 0, 0);
        blue  = im.colorAllocate(0, 0, 255);
        # нарисовать голубой овал
        im.arc(50,50,95,75,0,360,blue);
        # залить его красным
        im.fill(50,50,red);
        # вывести картинку в формате PNG
        im.png | stdout(1);
       END;
    -%]

Более подробно смотрите Template::Plugin::GD::Image.

Эти плагины предоставляют доступ к модулям Мартина Вербрюггена (Martien Verbruggen) GD::Text, GD::Text::Align и GD::Text::Wrap. Эти плагины позволяют разместить, выровнять и перенести текст в картинках GD.

    [% FILTER null;
        USE gd  = GD.Image(200,400);
        USE gdc = GD.Constants;
        black = gd.colorAllocate(0,   0, 0);
        green = gd.colorAllocate(0, 255, 0);
        txt = "This is some long text. " | repeat(10);
        USE wrapbox = GD.Text.Wrap(gd,
         line_space  => 4,
         color       => green,
         text        => txt,
        );
        wrapbox.set_font(gdc.gdMediumBoldFont);
        wrapbox.set(align => 'center', width => 160);
        wrapbox.draw(20, 20);
        gd.png | stdout(1);
      END;
    -%]

Более подробно смотрите Template::Plugin::GD::Text, Template::Plugin::GD::Text::Alignи Template::Plugin::GD::Text::Wrap.

GD::Graph::lines, GD::Graph::bars, GD::Graph::points, GD::Graph::linespoints, GD::Graph::area, GD::Graph::mixed, GD::Graph::pie

Эти плагины предоставляют доступ к модулю Мартина Вербрюггена (Martien Verbruggen) GD::Graph, который позволяет создавать графики, диаграммы и схемы. Эти плагины позволяют выводить графики, диаграммы и схемы в PNG, JPEG и других графических форматах.

    [% FILTER null;
        data = [
            ["1st","2nd","3rd","4th","5th","6th"],
            [    4,    2,    3,    4,    3,  3.5]
        ];
        USE my_graph = GD.Graph.pie(250, 200);
        my_graph.set(
                title => 'A Pie Chart',
                label => 'Label',
                axislabelclr => 'black',
                pie_height => 36,
                transparent => 0,
        );
        my_graph.plot(data).png | stdout(1);
      END;
    -%]

Более подробно смотрите Template::Plugin::GD::Graph::lines, Template::Plugin::GD::Graph::bars, Template::Plugin::GD::Graph::points, Template::Plugin::GD::Graph::linespoints, Template::Plugin::GD::Graph::area, Template::Plugin::GD::Graph::mixed, Template::Plugin::GD::Graph::pie и GD::Graph.

Эти плагины предоставляют доступ к модулю GD::Graph3d Джереми Уадсака (Jeremy Wadsack). Это позволяет создавать 3-мерные гистограммы и линейные диаграммы.

    [% FILTER null;
        data = [
            ["1st","2nd","3rd","4th","5th","6th","7th", "8th", "9th"],
            [    1,    2,    5,    6,    3,  1.5,    1,     3,     4],
        ];
        USE my_graph = GD.Graph.bars3d();
        my_graph.set(
            x_label         => 'X Label',
            y_label         => 'Y label',
            title           => 'A 3d Bar Chart',
            y_max_value     => 8,
            y_tick_number   => 8,
            y_label_skip    => 2,
            # shadows
            bar_spacing     => 8,
            shadow_depth    => 4,
            shadowclr       => 'dred',
            transparent     => 0,
        my_graph.plot(data).png | stdout(1);
      END;
    -%]

Более подробно смотрите Template::Plugin::GD::Graph::lines3d, Template::Plugin::GD::Graph::bars3d и Template::Plugin::GD::Graph::pie3d.

Очень новый и простой плагин HTML предоставляет несколько полезных методов генерации HTML. Возможно в будущем он будет расширен или интегрирован в более крупный проект по генерации HTML элементов в общем виде (как это недавно обсуждалось в списке рассылки mod_perl).

    [% USE HTML %]
    [% HTML.escape("if (a < b && c > d) ..." %]
    [% HTML.attributes(border => 1, cellpadding => 2) %]
    [% HTML.element(table => { border => 1, cellpadding => 2 }) %]

Более подробно смотрите Template::Plugin::HTML.

Плагин Iterator предоставляет возможность создать объект Template::Iterator для использования в цикле обработки массива. Переменная-итератор с именем 'loop' создается автоматически директивой FOREACH. Этот плагин позволяет создать итератор явно с указанным именем или с именем по умолчанию 'iterator'. Более подробно смотрите Template::Plugin::Iterator.

    [% USE iterator(list, args) %]

    [% FOREACH item = iterator %]
       [% '<ul>' IF iterator.first %]
       <li>[% item %]
       [% '</ul>' IF iterator.last %]
    [% END %]

Плагин предоставляет интерфейс к модулю Pod::POM, который разбирает POD-документацию во внутреннюю объектную модель, которая затем может быть представлена с помощью Template Toolkit.

    [% USE Pod(podfile) %]

    [% FOREACH head1 = Pod.head1;
	 FOREACH head2 = head1/head2;
	   ...
         END;
       END
    %]

Плагин String реализует объектно-ориентированный интерфейс для манипулирования строками. Более подробно смотрите Template::Plugin::String.

    [% USE String 'Hello' %]
    [% String.append(' World') %]

    [% msg = String.new('Another string') %]
    [% msg.replace('string', 'text') %]

    The string "[% msg %]" is [% msg.length %] characters long.

Плагин Table позволяет сформатировать список данных в виртуальную таблицу с фиксированным числом строк или колонок, с частичным заполнением. Более подробно смотрите Template::Plugin::Table.

    [% USE table(list, rows=10, overlap=1) %]

    [% FOREACH item = table.col(3) %]
       [% item %]
    [% END %]

Плагин URL предоставляет простой способ построения URL из базовой части и переменного числа параметров. Более подробно смотрите Template::Plugin::URL.

    [% USE mycgi = url('/cgi-bin/bar.pl', debug=1) %]

    [% mycgi %]
       # ==> /cgi/bin/bar.pl?debug=1

    [% mycgi(mode='submit') %]
       # ==> /cgi/bin/bar.pl?mode=submit&debug=1

Плагин Wrap использует модуль Дэвида Мью Шарноффа (David Muir Sharnoff <muir@idiom.com>) Text::Wrap (при поддержке Тима Пирса (Tim Pierce) и многих-многих других) для простого форматирования параграфов. Более подробно смотрите Template::Plugin::Wrap и Text::Wrap.

    [% USE wrap %]
    [% wrap(mytext, 40, '* ', '  ') %]	# используем функцию wrap
    [% mytext FILTER wrap(40) -%]	# или фильтр wrap

Модуль Text::Wrap доступен на CPAN:

    http://www.cpan.org/modules/by-module/Text/

Плагин XML::DOM предоставляет доступ к объектной модели документа XML через модуль Кларка Купера (Clark Cooper <cooper@sch.ge.com>) и Энно Дерксена (Enno Derksen <enno@att.com>) XML::DOM. Более подробно смотрите Template::Plugin::XML::DOM и XML::DOM.

    [% USE dom = XML.DOM %]
    [% doc = dom.parse(filename) %]

    [% FOREACH node = doc.getElementsByTagName('CODEBASE') %]
       * [% node.getAttribute('href') %]
    [% END %]

Для работы плагина требуется установка модуля XML::DOM, доступного на CPAN:

    http://www.cpan.org/modules/by-module/XML/

Плагин XML::RSS это простой интерфейс к модулю Джонатана Эйзензопфа (Jonathan Eisenzopf <eisen@pobox.com>) XML::RSS. Файл RSS (Rich Site Summary) обычно используется для хранения коротких заголовков, описывающих различные ссылки на сайте. Этот плагин позволяет разбирать RSS-файлы и соответсвующим образом форматировать содержимое с использованием шаблонов. Более подробно смотрите Template::Plugin::XML::RSS и XML::RSS.

    [% USE news = XML.RSS(filename) %]

    [% FOREACH item = news.items %]
       <a href="[% item.link %]">[% item.title %]</a>
    [% END %]

Модуль XML::RSS доступен на CPAN:

    http://www.cpan.org/modules/by-module/XML/

Этот плагин реализует интерфейс к модулю XML::Simple.

    [% USE xml = XML.Simple(xml_file_or_text) %]

    [% xml.head.title %]

Более подробно смотрите Template::Plugin::XML::Simple.

Этот плагин определяет фильтр для выполнения простых преобразований XML на основе таблиц стилей.

    [% USE xmlstyle
           table = {
               attributes = {
                   border      = 0
                   cellpadding = 4
                   cellspacing = 1
               }
           }
    %]

    [% FILTER xmlstyle %]
    <table>
    <tr>
      <td>Foo</td> <td>Bar</td> <td>Baz</td>
    </tr>
    </table>
    [% END %]

Более подробно смотрите Template::Plugin::XML::Style.

Плагин XML::XPath предоставляет интерфейс к модулю Матта Серджинта (Matt Sergeant <matt@sergeant.org>) XML::XPath. Более подробно смотрите Template::Plugin::XML::XPath и XML::XPath.

    [% USE xpath = XML.XPath(xmlfile) %]
    [% FOREACH page = xpath.findnodes('/html/body/page') %]
       [% page.getAttribute('title') %]
    [% END %]

Для работы плагина требуется установка модуля XML::XPath, доступного на CPAN:

    http://www.cpan.org/modules/by-module/XML/

• Возможно есть смысл иметь возможность различать абсолютные имена модулей и относительные к каталогам PLUGIN_BASE. Например, использовать 'MyNamespace::MyModule' для обозначения абсолютных имен модулей (например, загружаемых при установленной опции LOAD_PERL), а 'MyNamespace.MyModule' для обозначения имен относительно PLUGIN_BASE.

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

http://www.andywardley.com/

2.71, поставляется в составе 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, Template::Plugin, Template::Context