Template Toolkit

    use Template::Filters;

    $filters = Template::Filters->new(\%config);

    ($filter, $error) = $filters->fetch($name, \@args, $context);

Модуль Template::Filters реализует поставщика для создания и/или возвращения функций, реализующих стандартные фильтры. Дополнительные пользовательские фильтры можно добавить через опции FILTERS.

Метод конструктора, который создает и возвращает ссылку на объект Template::Filters. В качестве параметра можно передать ссылку на хеш с опциями конфигурации. Они описаны ниже.

    my $filters = Template::Filters->new({
        FILTERS => { ... },
    });

    my $template = Template->new({
        LOAD_FILTERS => [ $filters ],
    });

Модуль по умолчанию Template::Filters создается модулем Template.pm, если не указана опция LOAD_FILTERS. Все параметры конфигурации передаются конструктору.

    $template = Template->new({
        FILTERS => { ... },
    });

Запрашивает фильтр с указанным именем. Имя фильтра передается в качестве первого параметра. Это должно быть имя одного из стандартных фильтров или одного из фильтров, определенных в конфигурационном хеше FILTERS. Второй аргумент должен быть ссылкой на массив, содержащий параметры конфигурации фильтра. Можно передать 0 или undef, если таких параметров нет. Третий аргумент должен быть ссылкой на текущий объект Template::Context.

В случае успеха метод возвращает ссылку на функцию фильтра. Он также может вернуть (undef, STATUS_DECLINE) в случае отклонения запроса, чтобы разрешить обращение к другим поставщикам фильтров, определенных в цепочке ответственности LOAD_FILTERS. В случае ошибки метод возвращает ($error, STATUS_ERROR), где $error - сообщение об ошибке или объект Template::Exception, обозначающие произошедшую ошибку.

Если установлена опция TOLERANT, ошибки автоматически подавляются и ответ преобразуется в STATUS_DECLINE.

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

• FILTERS
  

  Опция FILTERS может быть использована, чтобы определить пользовательские фильтры, которые затем можно использовать в директиве FILTER как и любые другие. Они добавляются к стандартным фильтрам, которые доступны по умолчанию. Фильтры, определенные через эту опцию переопределяют любые из стандартных фильтров с тем же именем.

  Опция FILTERS должна быть ссылкой на хеш, в которой каждый ключ представляет имя фильтра. Соответсвующее значение должно быть ссылкой на массив, содержащий ссылку на функцию и флаг, обозначающий является ли фильтр статическим (0) или динамическим (1). Фильтр также может быть указан как одиночная ссылка на функцию, при этом предполагается, что фильтр статический.

      $filters = Template::Filters->new({
          FILTERS => {
              'sfilt1' =>   \&static_filter,      # статический
              'sfilt2' => [ \&static_filter, 0 ], # то же, что и выше
              'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
          },
      });

  Дополнительные фильтры можно определять в любое время, вызывая метод define_filter() текущего объекта Template::Context. Метод принимает имя фильтра, ссылку на функцию фильтра и необязательный флаг, обозначающий что фильтр динамический.

      my $context = $template->context();
      $context->define_filter('new_html', \&new_html);
      $context->define_filter('new_repeat', \&new_repeat, 1);

  Статические фильтры используют ссылку на одну функцию для всех вызовов. Фильтры, которые не принимают параметров конфигурации (например, 'html') могут быть реализованы статически. Когда такой фильтр запрашивается, просто возвращается ссылка на функцию. Эта функция вызывается, чтобы обработать вывод блока шаблона, который передается в качестве единственного аргумента. Функция должна вернуть модифицированный текст.

      sub static_filter {
          my $text = shift;
          # $text модифицируется...
          return $text;
      }

  Следующий фрагмент шаблона:

      [% FILTER sfilt1 %]
      Blah blah blah.
      [% END %]

  примерно эквивалентен следующему:

      &static_filter("\nBlah blah blah.\n");

  Фильтры, которые могут принимать параметры (например, 'truncate') должны быть реализованы динамически. В этом случае, функция должна быть 'фабрикой' фильтров, которая вызывается, чтобы создать уникальную функцию фильтра при каждом запросе. Фабрика фильтров получает в качестве первого аргумента ссылку на текущий объект Template::Context, следом идут любые указанные дополнительные параметры. Функция должна вернуть ссылку на другую функцию (как правило, замыкание), которая реализует фильтр.

      sub dynamic_filter_factory {
          my ($context, @args) = @_;

          return sub {
              my $text = shift;
              # $text модифицируется...
              return $text;
          }
      }

  Следующий фрагмент шаблона:

      [% FILTER dfilt1(123, 456) %]
      Blah blah blah
      [% END %]              

  примерно эквивалентен следующему:

      my $filter = &dynamic_filter_factory($context, 123, 456);
      &$filter("\nBlah blah blah.\n");

  Другие примеры можно найти в описании директивы FILTER.

• TOLERANT
  

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

• DEBUG
  

  Опция DEBUG может быть использована для включения отладочных сообщений модуля Template::Filters, если биты DEBUG_FILTERS установлены.

      use Template::Constants qw( :debug );

      my $template = Template->new({
  	DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
      });

The following standard filters are distributed with the Template Toolkit.

Фильтр 'format' принимает в качестве параметра строку описания формата вывода (как в printf()) и форматирует в соответствие с ней каждую строку текста.

    [% FILTER format('<!-- %-40s -->') %]
    This is a block of text filtered
    through the above format.
    [% END %]

вывод:

    <!-- This is a block of text filtered        -->
    <!-- through the above format.               -->

Переводит вывод в ВЕРХНИЙ РЕГИСТР.

    [% "hello world" FILTER upper %]

вывод:

    HELLO WORLD

Переводит вывод в нижний регистр.

    [% "Hello World" FILTER lower %]

вывод:

    hello world

Переводит в ВЕРХНИЙ РЕГИСТР первый символ вывода.

    [% "hello" FILTER ucfirst %]

вывод:

    Hello

Переводит в нижний регистр первый символ вывода.

    [% "HELLO" FILTER lcfirst %]

вывод:

    hELLO

Обрезает начальные и/или завершающие пробельные символы в тексте вывода. Особенно полезен в сочетании с INCLUDE, PROCESS, и т.п., оказывая такой же эффект как и опция конфигурации TRIM.

    [% INCLUDE myfile | trim %]

Сокращает пробельные последовательности внутри текста вывода в единственный пробел. Начальные и/или завершающие пробельные символы (которые будут сжаты в один пробел) удаляются, как и в фильтре trim.

    [% FILTER collapse %]

       The   cat

       sat    on

       the   mat

    [% END %]

вывод:

    The cat sat on the mat

Заменяет символы '<', '>' и '&' на '&lt;', '&gt;' и '&amp;' соответственно, предохраняя от интерпретации их как части HTML тегов или сущностей.

    [% FILTER html %]
    Binary "<=>" returns -1, 0, or 1 depending on...
    [% END %]

вывод:

    Binary "<=>" returns -1, 0, or 1 depending on...

Фильтр html быстрый и простой, но он не кодирует весь спектр HTML сущностей, который может содержать текст. Фильтр html_entity использует либо модуль Apache::Util (который написан на C и поэтому более быстр), либо модуль HTML::Entities (написанный на Perl, но столь же всеобъемлющий), для того чтобы выполнить перекодирование. Если на вашей системе установлен один из этих модулей, текст будет перекодирован (посредством функций escape_html() или encode_entities() соответственно) - все символы из расширенного диапазона будут переведены в соответствующие HTML сущности (например, 'é' будет заменен на '&eacute;'). Если ни один из модулей не доступен, будет возбуждено исключение 'html_entity' с соответствующим сообщением.

Более подробно о кодировании HTML сущностей смотрите http://www.w3.org/TR/REC-html40/sgml/entities.html.

Этот фильтр форматирует блок текста в параграфы HTML. Последовательность из двух и более символов новой строки используется в качестве разделителя параграфов, которые затем заворачиваются в HTML теги <p>...</p>.

    [% FILTER html_para %]
    The cat sat on the mat.

    Mary had a little lamb.
    [% END %]

вывод:

    <p>
    The cat sat on the mat.
    </p>

    <p>
    Mary had a little lamb.
    </p>

Аналогичен описанному выше фильтру html_para, но для связывания параграфов использует последовательность HTML-тегов <br><br>.

    [% FILTER html_break %]
    The cat sat on the mat.

    Mary had a little lamb.
    [% END %]

вывод:

    The cat sat on the mat.
    <br>
    <br>
    Mary had a little lamb.

Этот фильтр заменяет любой символ новой строки на HTML-тег <br>, сохраняя таким образом переносы в оригинальном тексте в выводе HTML.

    [% FILTER html_line_break %]
    The cat sat on the mat.
    Mary had a little lamb.
    [% END %]

вывод:

    The cat sat on the mat.<br>
    Mary had a little lamb.<br>

Фильтр выполняет URI-кодирование входного текста, преобразуя все символы, находящиеся вне диапазона разрешенных в URI (согласно RFC 2396), в их шестнадцатеричные представления в виде '%nn'.

    [% 'my file.html' | uri %]

вывод:

    my%20file.html

Учтите, что URI-кодирования часто недостаточно для генерации гиперссылок в HTML документе. Например, символ '&' входит в число разрешенных и не кодируется фильтром uri. В этом случае может понадобиться дополнительная обработка текста фильтром 'html'.

    <a href="[% filename | uri | html %]">click here</a>

Создает отступ у тестового блока либо подстановкой текстовой строки, либо подстановкой фиксированного количества пробелов. Аргумент 'отступ' может быть строкой или числовым значением, задающим ширину отступа (в пробелах). Если аргумент опущен используется значение по умолчанию 4.

    [% FILTER indent('ME> ') %]
    blah blah blah
    cabbages, rhubard, onions
    [% END %]

вывод:

    ME> blah blah blah
    ME> cabbages, rhubard, onions

Усекает текстовый блок до указанной длины или до длины по умолчанию (32 символа). Усеченный текст будет завершен последовательностью '...' (причем '...' входит в обрезанный текст, а не добавляется к нему после усечения).

    [% FILTER truncate(21) %]
    I have much to say on this matter that has previously
    been said on more than one occasion.
    [% END %]

вывод:

    I have much to say...

Повторяет текстовый блок указанное число раз (по умолчанию: 1).

    [% FILTER repeat(3) %]
    We want more beer and we want more beer,
    [% END %]
    We are the more beer wanters!

вывод:

    We want more beer and we want more beer,
    We want more beer and we want more beer,
    We want more beer and we want more beer,
    We are the more beer wanters!

Ищет во входном тексте вхождения указанной строки и удаляет их. В качестве строки для поиска можно использовать регулярное выражение Perl.

    [% "The  cat  sat  on  the  mat" FILTER remove('\s+') %]

вывод:

    Thecatsatonthemat

Аналогичен описанному выше фильтру remove, но принимает в качестве второго параметра строку, используемую для замены вхождений строки поиска.

    [% "The  cat  sat  on  the  mat" | replace('\s+', '_') %]

вывод:

    The_cat_sat_on_the_mat

Фильтр 'redirect' перенаправляет вывод блока в отдельный файл, указанный относительно пути, заданного опцией конфигурации OUTPUT_PATH.

    [% FOREACH user = myorg.userlist %]
       [% FILTER redirect("users/${user.id}.html") %]
          [% INCLUDE userinfo %]
       [% END %]
    [% END %]

или более лаконично с использованием обратной нотации:

    [% INCLUDE userinfo
         FILTER redirect("users/${user.id}.html")
	   FOREACH user = myorg.userlist
    %]

Если опция OUTPUT_PATH не определена будет сгенерировано исключение 'file'.

За именем файла может идти необзательный параметр 'binmode', явно определяющий вывод в файл в двоичном режиме.

    [% PROCESS my/png/generator
         FILTER redirect("images/logo.png", binmode=1) %]

В целях обратной совместимости с ранними версиями для установки двоичного режима можно использовать одиночное истинное значение.

    [% PROCESS my/png/generator
         FILTER redirect("images/logo.png", 1) %]

В целях будущей совместимости и ясности, если ничто не мешает, рекомендуется явно использовать именованную опцию 'binmode', как показано в первом примере.

Фильтр 'eval' вычисляет блок как текст шаблона, обрабатывая все директивы внутри него. Это позволяет переменным шаблона содержать фрагменты шаблона, а также предоставляет метод для обработки при необходимости фрагментов шаблона из внешних источников, таких как база данных.

    my $vars  = {
	fragment => "The cat sat on the [% place %]",
    };
    $template->process($file, $vars);

Следующий пример:

    [% fragment | eval %]

следовательно эквивалентен:

    The cat sat on the [% place %]

Фильтр 'evaltt' является синонимом для 'eval'.

Фильтр 'perl' вычисляет блок как perl-код. Опция EVAL_PERL должна быть установлена в истинное значение или будет возбуждено исключение 'perl'.

    [% my_perl_code | perl %]

В большинстве случаев использование блока [% PERL %] ... [% END %] покрывает всю необходимость в вычислении perl-кода, учитывая то, что директивы обрабатываются до того, как блок вычисляется как код Perl. Так, предыдущий пример можно записать более подробно:

    [% PERL %]
    [% my_perl_code %]
    [% END %]

равносильно

    [% FILTER perl %]
    [% my_perl_code %]
    [% END %]

Фильтр 'evalperl' предоставляется как синоним 'perl' для обратной совместимости.

Фильтр 'stdout' отправляет вывод, сгенерированный окруженным им блоком, на STDOUT. Чтобы установить STDOUT в двоичный режим (смотри perl-функцию binmode), можно указать именованный параметр 'binmode' или одиночное истинное значение.

    [% PROCESS something/cool
           FILTER stdout(binmode=1) # recommended %]

    [% PROCESS something/cool
           FILTER stdout(1)         # alternate %]

Фильтр 'stdout' можно использовать для принудительной установки STDOUT в двоичный режим, а также для перенаправления отдельного вывода на STDOUT внутри null или stderr блоков. Смотри пример фильтра 'null' ниже.

Фильтр 'stderr' направляет вывод, сгенерированный окруженным им блоком, на STDERR.

Фильтр 'null' ничего не выводит. Это полезно при использовании плагинов, методы которых возвращают значения, которые не должны появиться в выводе. Вместо того, чтобы подавлять их присваиванием возвращаемых значений фиктивным переменным, можно заключить блок внутрь фильтра 'null':

    [% 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);
        im.png | stdout(1);
       END;
    -%]

Обратите внимание на использование фильтра 'stdout', обеспечивающего вывод частного выражения на stdout (в данном случае в двоичном режиме).

Передает текстовый блок на вход LaTeX и производит вывод в формате PDF, DVI или PostScript. Аргумент 'outputType' определяет формат вывода и должен быть установлен в одно из строковых значений: "pdf" (по умолчанию), "dvi" или "ps".

Блок текста должен быть завершенным исходным файлом LaTeX.

    [% FILTER latex("pdf") -%]
    \documentclass{article}

    \begin{document}

    \title{A Sample TT2 \LaTeX\ Source File}
    \author{Craig Barratt}
    \maketitle

    \section{Introduction}
    This is some text.

    \end{document}
    [% END -%]

Выводом будет файл PDF. Необходимо обратить внимание на то, чтобы вокруг блока не было посторонних символов или текста, так как этот текст будет добавлен к (двоичному) выводу фильтра 'latex'. Обратите внимание на использование в директиве END '-%]' в качестве END_TAG для удаления завершающего символа новой строки.

Один из примеров обоснованного использования предваряющего текста - вывод CGI-скрипта, который должен отдавать перед выводом latex заголовок Content-Type, например:

    Content-Type: application/pdf

    [% FILTER latex("pdf") -%]
    \documentclass{article}
    \begin{document}
    ...
    \end{document}
    [% END -%]

В других случаях следует использовать фильтр 'redirect', чтобы сохранить вывод в файл вместо отправки его на stdout. Это можно использовать в пакетных утилитах:

    [% output = FILTER latex("pdf") -%]
    \documentclass{article}
    \begin{document}
    ...
    \end{document}
    [% END; output | redirect("document.pdf", 1) -%]

(Обратите внимание второй аргумент принудительно устанавливает двоичный режим.)

Фильтр 'latex' запускает одну или две внешних программы, поэтому он не очень быстрый. Но для небольших документов производительность вполне приемлема, даже при использовании в интерактивных приложениях.

Если latex, pdflatex или dvips сообщат об ошибке, будет возбуждено исключение типа 'latex'.

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

http://www.andywardley.com/

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