Template Toolkit

Этот раздел содержит список всех стандартных фильтров для постпроцессорной обработки, входящих в состав 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)%] # рекомендуется

    [% PROCESS something/cool
           FILTER stdout(1)%]         # альтернативная форма

Фильтр '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/

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.