Template Toolkit(русская редакция) |
|
||
|
|||
Template |
|
ОБЗОР |
[ Индекс ] [ Модули ] [ Наверх ] |
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() как метод класса (например, 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. Стиль шаблонов и опции парсера
Файлы шаблонов и блоки
Переменные шаблона
Опции времени исполнения шаблонов
Опции кеширования и компиляции
Плагины и фильтры
Совместимость, настройка и расширение
|
СВОДКА ДИРЕКТИВ |
[ Индекс ] [ Модули ] [ Наверх ] |
Следующий список содержит короткую сводку всех директив Template Toolkit. Более подробно смотри Template::Manual::Directives.
|
АВТОР |
[ Индекс ] [ Модули ] [ Наверх ] |
Энди Уардли (Andy Wardley <abw@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. |