Template Toolkit: Модули: Template

Template Toolkit

(русская редакция)

[ Пособия ] [ Руководство ] [ Модули ] [ Библиотеки ] [ Утилиты ] [ Вопросы ] [ Релиз ] [ Perl-ресурсы ] Форум ]
 
Поиск
Template Toolkit | Модули | Template

Template

[ Template::Base ► ]
Внешний интерфейс Template Toolkit.

Оглавление

ОБЗОР

Индекс ] [ Модули ] [ Наверх ]

  use Template;
  # некоторые полезные опции (полный список приводится ниже)
  my $config = {
      INCLUDE_PATH => '/search/path',  # или ссылка на список
      INTERPOLATE  => 1,               # интерполяция "$var" в обычном тексте
      POST_CHOMP   => 1,               # чистка пробельных символов
      PRE_PROCESS  => 'header',        # префикс любого шаблона
      EVAL_PERL    => 1,               # вычислять блоки кода Perl
  };
  # создаем объект Template
  my $template = Template->new($config);
  # определяем переменные шаблона для подстановки
  my $vars = {
      var1  => $value,
      var2  => \%hash,
      var3  => \@list,
      var4  => \&code,
      var5  => $object,
  };
  # указываем имя входного файла, или файловый дескриптор, ссылку на текст и т.д.
  my $input = 'myfile.html';
  # обрабатываем входной шаблон, подставляя переменные
  $template->process($input, $vars)
      || die $template->error();

ОПИСАНИЕ

Индекс ] [ Модули ] [ Наверх ]

Этот документ описывает модуль Template, который является прямым интерфейсом Perl к Template Toolkit. Он содержит описание использования модуля и краткую сводку опций конфигурации и директив шаблонов. Полное справочное руководство, содержащее более глубокий обзор возможностей использования Template Toolkit можно найти в Template::Manual. Также в качестве вводного курса по использованию Template Toolkit можно изучить Template::Tutorial.

МЕТОДЫ

Индекс ] [ Модули ] [ Наверх ]

new(\%config)

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

    my $tt = Template->new({
	INCLUDE_PATH => '/usr/local/templates',
	EVAL_PERL    => 1,
    }) || die $Template::ERROR, "\n";

Возвращается новый объект Template, или в случае ошибки undef. В последнем случае, сообщение об ошибке можно получить вызвав error() как метод класса (например, 'Template->error()') или непосредственно из переменной пакета $ERROR (например, '$Template::ERROR').

    my $tt = Template->new(\%config)
        || die Template->error(), "\n";
    my $tt = Template->new(\%config)
        || die $Template::ERROR, "\n";

Для удобства опции конфигурации также можно указать в виде списка вместо ссылки на хеш. Конструктор автоматически соберет их в хеш.

    my $tt = Template->new(INCLUDE_PATH => '/tmp', POST_CHOMP => 1)
	|| die $Template::ERROR, "\n";

process($template, \%vars, $output, %options)

Метод process() вызывается для обработки шаблона. Первый аргумент, указывающий входной шаблон может быть: именем файла относительно INCLUDE_PATH, если эта опция определена; ссылкой на текстовую строку, содержащую текст шаблона; или ссылкой на дескриптор файла (например, IO::Handle или объект производного класса) или GLOB (например, \*STDIN), из которого можно прочитать шаблон. В качестве второго аргумента можно передать ссылку на хеш, содержащий определения перемнных шаблона.

    $text = "[% INCLUDE header %]\nHello world!\n[% INCLUDE footer %]";
    # имя файла
    $tt->process('welcome.tt2')
        || die $tt->error(), "\n";
    # ссылка на текст
    $tt->process(\$text)
        || die $tt->error(), "\n";
    # GLOB
    $tt->process(\*DATA)
        || die $tt->error(), "\n";
    __END__
    [% INCLUDE header %]
    Это шаблон определенный в разделе __END__, доступный
    через "файловый дескриптор" DATA.
    [% INCLUDE footer %]

По умолчанию, вывод обработаного шаблона идет на STDOUT. Метод process() после этого возвращает 1, обозначающую успешное завершение. Через третий аргумент метода process() можно указать другое место для вывода. Это значение может быть: строкой, указывающей имя файла (относительно OUTPUT_PATH, если опция определена), который будет открыт и в который будет сохранен вывод; открытым для вывода файловый GLOB; ссылкой на скаляр (например, текстовую строку), к которому вывод/ошибки будут добавлены; ссылкой на функцию, которая будет вызвана с выводом в качестве аргумента; или ссылкой на любой объект, который имеет метод 'print' (например, IO::Handle, Apache::Request и т.д.), который будет вызван с выводом в качестве аргумента.

Примеры:

    # имя файла для вывода
    $tt->process('welcome.tt2', $vars, 'welcome.html')
        || die $tt->error(), "\n";
    # ссылка на функцию, обрабатывающую вывод
    sub myout {
	my $output = shift;
	...
    }
    $tt->process('welcome.tt2', $vars, \&myout)
        || die $tt->error(), "\n";
    # ссылка на текстовую строку, к которой будет добавлен вывод
    my $output = '';
    $tt->process('welcome.tt2', $vars, \$output)
        || die $tt->error(), "\n";

    print "output: $output\n";

В обработчике Apache/mod_perl:

    sub handler {
	my $req = shift;
        ...
	# прямой вывод в Apache::Request через $req->print($output)
	$tt->process($file, $vars, $req) || do {
	    $req->log_reason($tt->error());
	    return SERVER_ERROR;
	};
	return OK;
    }

После необязательного третьего аргумента может идти дополнительная ссылка на хеш или массив пар (имя, значение), содержащие дополнительные опции вывода. Единственная поддерживаемая в настоящий момент опция "binmode", установленная в истинное значение, гарантирует, что создаваемые файлы (но не переданные в качестве аргументов открытые файловые дескрипторы) будут записаны в двоичном режиме (binmode).

    # или: ссылка на хеш опций
    $tt->process($infile, $vars, $outfile, { binmode => 1 })
        || die $tt->error(), "\n";
    # или: массив пар имя => значение
    $tt->process($infile, $vars, $outfile, binmode => 1)
        || die $tt->error(), "\n";

Дополнительно, аргумент binmode может определять особый слой ввода/вывода (IO layer), такой как ":utf8".

    $tt->process($infile, $vars, $outfile, binmode => ':utf8')
        || die $tt->error(), "\n";

Опцию конфигурации OUTPUT можно использовать для определения места вывода по умолчанию отличного от \*STDOUT. OUTPUT_PATH определяет каталог, в который будут сохранятся файлы при указании их в качестве места для вывода.

    my $tt = Template->new({
	OUTPUT      => sub { ... },       # по умолчанию
	OUTPUT_PATH => '/tmp',
	...
    }) || die Template->error(), "\n";
    # используется OUTPUT по умолчанию (вызывается функция)
    $tt->process('welcome.tt2', $vars)
        || die $tt->error(), "\n";
    # записывается в файл '/tmp/welcome.html'
    $tt->process('welcome.tt2', $vars, 'welcome.html')
        || die $tt->error(), "\n";

Метод process() возвращает в случае удачного завершения 1 или undef в случае ошибки. В последнем случае сообщение об ошибке можно получить вызвав метод error(). Смотри также раздел "СВОДКА ОПЦИЙ КОНФИГУРАЦИИ", в котором описывается как можно дополнительно настроить обработку ошибок.

error()

Когда вызывается как метод класса, возвращает значение переменной пакета $ERROR. Таким образом, следующие строки кода эквивалентны.

    my $tt = Template->new()
        || die Template->error(), "\n";
    my $tt = Template->new()
        || die $Template::ERROR, "\n";

Когда вызывается как метод объекта, возвращает значение внутренней переменной _ERROR, установленной в случае ошибки в предыдущем вызове process().

    $tt->process('welcome.tt2')
        || die $tt->error(), "\n";

Ошибки в Template Toolkit представляются объектами класса Template::Exception. Если метод process() возвращает ложное значение, можно вызвать метод error(), чтобы получить объект этого класса. У объекта можно вызвать методы type() и info(), которые возвращают тип ошибки и информационную строку соответственно. Метод as_string() можно вызвать, чтобы получить строку в виде "$type - $info". Этот метод также перегружает оператор "стрингификации" (stringification), позволяя печатать саму ссылку на объект в виде форматированного сообщения об ошибке.

    $tt->process('somefile') || do {
	my $error = $tt->error();
	print "error type: ", $error->type(), "\n";
	print "error info: ", $error->info(), "\n";
	print $error, "\n";
    };

service()

Модуль Template делегирует большую часть работы по обработке шаблонов лежашему в основе объекту Template::Service. Этот метод возвращает ссылку на этот объект.

context()

Модуль Template::Service использует основной объект Template::Context для обработки шаблонов во время исполнения. Этот метод возвращает ссылку на этот объект и эквивалентен $template->service->context();

СВОДКА ОПЦИЙ КОНФИГУРАЦИИ

Индекс ] [ Модули ] [ Наверх ]

Следующий список содержит краткий обзор каждой опции конфигурации Template Toolkit. Более подробное описание можно найти в Template::Manual::Config.

Стиль шаблонов и опции парсера

  • START_TAG, END_TAG

    Определяет символы, обозначающие начало и конец директив (по умолчанию: '[%' и '%]').

  • TAG_STYLE

    Устанавливает START_TAG и END_TAG в соответствие с предопределенным стилем (по умолчанию: 'template', как и выше).

  • PRE_CHOMP, POST_CHOMP

    Удаляет пробельные символы до/после директив (по умолчанию: 0/0).

  • TRIM

    Удаляет пробельные символы в начале и в конце вывода шаблона (по умолчанию: 0).

  • INTERPOLATE

    Интерполяция внедренных в текст переменных, подобных $this или ${this} (по умолчанию: 0).

  • ANYCASE

    Разрешает использование ключевых слов директив в нижнем регистре (по умолчанию: 0 - только в ВЕРХНЕМ регистре).

Файлы шаблонов и блоки

  • INCLUDE_PATH

    Одна или несколько директорий для поиска шаблонов.

  • DELIMITER

    Разделитель директорий в INCLUDE_PATH (по умолчанию: ':').

  • ABSOLUTE

    Разрешает использовать абсолютные имена файлов, например /foo/bar.html (по умолчанию: 0).

  • RELATIVE

    Разрешает использовать относительные имена файлов, например ../foo/bar.html (по умолчанию: 0).

  • DEFAULT

    Шаблон используемый по умолчанию, если не найден никакой другой.

  • BLOCKS

    Хеш предопределенных блоков-шаблонов.

  • AUTO_RESET

    Включенная по умолчанию приводит к сбрасыванию определений BLOCK при каждой новой обработке шаблона. Запрет разрешает сохранение определений BLOCK.

  • RECURSION

    Флаг разрешающий рекурсию в шаблонах (по умолчанию: 0).

Переменные шаблона

  • VARIABLES, PRE_DEFINE

    Хеш предопределенных переменных и значений в хранилище (stash).

Опции времени исполнения шаблонов

  • EVAL_PERL

    Флаг, указывающий на возможность обработки блоков PERL/RAWPERL (по умолчанию: 0).

  • PRE_PROCESS, POST_PROCESS

    Имена шаблона(ов), обрабатываемых до/после главного шаблона.

  • PROCESS

    Имена шаблона(ов), обрабатываемых вместо главного шаблона.

  • ERROR

    Имя шаблона ошибки или ссылка на хеш, связывающий типы ошибок с шаблонами.

  • OUTPUT

    Место назначения вывода или дескриптор по умолчанию.

  • OUTPUT_PATH

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

  • DEBUG

    Разрешает отладочные сообщения.

Опции кеширования и компиляции

  • CACHE_SIZE

    Максимальное число скомпилированных шаблонов, кеширующихся в памяти (по умолчанию: undef - кешировать все).

  • COMPILE_EXT

    Расширение имени файла для файлов с скомпилированными шаблонами (по умолчанию: undef - скомпилированные шаблоны не сохраняются).

  • COMPILE_DIR

    Корневая директория, в которую будут сохранятся файлы скомпилированных шаблонов (по умолчанию: undef - скомпилированные шаблоны не сохраняются).

Плагины и фильтры

  • PLUGINS

    Ссылка на хеш, связывающий имена плагинов и пакеты Perl.

  • PLUGIN_BASE

    Один или несколько префиксов классов плагинов.

  • LOAD_PERL

    Флаг, указывающий нужно ли загружать обычные модули Perl, в случае неудачного поиска именнованных плагинов (по умолчанию: 0).

  • FILTERS

    Хеш связывающий имена фильтров с функциями-фильтрами или производящими функциями (factories).

Совместимость, настройка и расширение

  • V1DOLLAR

    Флаг обратной совместимости, включающий интерпретацию ведущего символа '$' перед переменными в стиле версии 1.*, т.е. игнорирование (по умолчанию: 0 - '$' обозначает интерполяцию при включенной опции INTERPOLATE).

  • LOAD_TEMPLATES

    Список поставщиков шаблонов.

  • LOAD_PLUGINS

    Список поставщиков плагинов.

  • LOAD_FILTERS

    Список поставщиков фильтров.

  • TOLERANT

    Устанавливает режим игнорирования ошибок в модулях поставщиков (по умолчанию: 0).

  • SERVICE

    Ссылка на переопределенный объект сервиса (по умолчанию: Template::Service).

  • CONTEXT

    Ссылка на переопределенный объект контекста (по умолчанию: Template::Context).

  • STASH

    Ссылка на переопредленный объект хранилища (по умолчанию: Template::Stash).

  • PARSER

    Ссылка на переопредленный объект парсера (по умолчанию: Template::Parser).

  • GRAMMAR

    Ссылка на переопредленный объект грамматики парсера (по умолчанию: Template::Grammar).

СВОДКА ДИРЕКТИВ

Индекс ] [ Модули ] [ Наверх ]

Следующий список содержит короткую сводку всех директив Template Toolkit. Более подробно смотри Template::Manual::Directives.

  • GET

    Вычисляет и выводит переменную или значение.

        [%   GET variable %]    # ключевое слово 'GET' можно опустить
        [%       variable %]
        [%       hash.key %]
        [%         list.n %]
        [%     code(args) %]
        [% obj.meth(args) %]
        [%  "value: $var" %]
  • CALL

    То же что и GET, но без вывода результата (например, вызов кода)

        [%  CALL variable %]
  • SET

    Присвоить значения переменным.

        [% SET variable = value %]    # 'SET' также опционально
        [%     variable = other_variable
        	   variable = 'literal text @ $100'
        	   variable = "interpolated text: $var"
        	   list     = [ val, val, val, val, ... ]
        	   list     = [ val..val ]
        	   hash     = { var => val, var => val, ... }
        %]
  • DEFAULT

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

        [% DEFAULT variable = value %]
  • INSERT

    Вставляет содержимое файла без обработки его содержимого.

        [% INSERT legalese.txt %]
  • INCLUDE

    Обрабатывает другой файл шаблона или блок и включает результат в вывод. Переменные локализуются.

        [% INCLUDE template %]
        [% INCLUDE template  var = val, ... %]
  • PROCESS

    Как и приведенная выше директива INCLUDE, но локализация переменных не выполняется.

        [% PROCESS template %]
        [% PROCESS template  var = val, ... %]
  • WRAPPER

    Обрабатывает заключенный между WRAPPER ... END блок, затем включает именованный шаблон (INCLUDE), передавая результат обработки блока в виде переменной 'content'.

        [% WRAPPER template %]
           content...
        [% END %]
  • BLOCK

    Определяет именованный шаблонный блок для последующих директив INCLUDE, PROCESS и т.п.

        [% BLOCK template %]
           content
        [% END %]
  • FOREACH

    Повторяет заключенный между FOREACH ... END блок для каждого элемента списка.

        [% FOREACH variable = [ val, val, val ] %]	  # так
        [% FOREACH variable = list %]                 # или так
        [% FOREACH list %]                            # или так
           content...
           [% variable %]
        [% END %]
  • WHILE

    Заключенный между WHILE ... END блок обрабатывается, если условие истинно.

        [% WHILE condition %]
           content
        [% END %]
  • IF / UNLESS / ELSIF / ELSE

    Внутренний блок обрабатывается, если условие истинно.

        [% IF condition %]
           content
        [% ELSIF condition %]
    	 content
        [% ELSE %]
    	 content
        [% END %]
        [% UNLESS condition %]
           content
        [% # ELSIF/ELSE as per IF, above %]
           content
        [% END %]
  • SWITCH / CASE

    Выражение многовариантного условного выбора.

        [% SWITCH variable %]
        [% CASE val1 %]
           content
        [% CASE [ val2, val3 ] %]
           content
        [% CASE %]         # или [% CASE DEFAULT %]
           content
        [% END %]
  • MACRO

    Определяет именнованный макрос.

        [% MACRO name <directive> %]
        [% MACRO name(arg1, arg2) <directive> %]
        ...
        [% name %]
        [% name(val1, val2) %]
  • FILTER

    Обрабатывает блок между FILTER ... END, затем пропускает результат через фильтр.

        [% FILTER name %]			    # так
        [% FILTER name( params ) %]		    # или так
        [% FILTER alias = name( params ) %]	    # или так
           content
        [% END %]
  • USE

    Загружает модуль-"плагин", или любой обычный Perl-модуль, если установлена опция LOAD_PERL.

        [% USE name %]			    # так
        [% USE name( params ) %]		    # или так
        [% USE var = name( params ) %]	    # или так
        ...
        [% name.method %]
        [% var.method %]
  • PERL / RAWPERL

    Выполняет блок как perl-код (необходимо, чтобы опция EVAL_PERL была установлена).

        [% PERL %]
    	 # здесь находится perl-код
    	 $stash->set('foo', 10);
    	 print "set 'foo' to ", $stash->get('foo'), "\n";
    	 print $context->include('footer', { var => $val });
        [% END %]
        [% RAWPERL %]
           # здесь находится сырой perl-код, никакой магии, но быстро.
           $output .= 'some output';
        [% END %]
  • TRY / THROW / CATCH / FINAL

    Обрабатывает исключения.

        [% TRY %]
    	 content
           [% THROW type info %]
        [% CATCH type %]
    	 catch content
           [% error.type %] [% error.info %]
        [% CATCH %]	# or [% CATCH DEFAULT %]
    	 content
        [% FINAL %]
           this block is always processed
        [% END %]
  • NEXT

    Прямой переход к следующей итерации в циклах FOREACH/WHILE.

        [% NEXT %]
  • LAST

    Прерывание циклов FOREACH/WHILE.

        [% LAST %]
  • RETURN

    Остановка обработки текущего шаблона и возврат в вызывавший.

        [% RETURN %]
  • STOP

    Остановка обработки всех шаблонов и возврат в вызывавшую функцию.

        [% STOP %]
  • TAGS

    Определяет новый стиль или символы тегов (по умолчанию: [% %]).

        [% TAGS html %]
        [% TAGS <!-- --> %]
  • Комментарии

    Игнорируются и удаляются из вывода.

        [% # это комментарий до конца строки
           foo = 'bar'
        %]
        [%# символ '#' сразу за открывающим тегом директивы
            комментирует директиву целиком
        %]

АВТОР

Индекс ] [ Модули ] [ Наверх ]

Энди Уардли (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.