Template Toolkit(русская редакция) |
|
||
|
|||
Template::Context |
|
КРАТКИЙ ОБЗОР |
[ Индекс ] [ Модули ] [ Наверх ] |
use Template::Context; # конструктор
$context = Template::Context->new(\%config)
|| die $Template::Context::ERROR;
# загрузить и скомпилировать шаблон
$template = $context->template($template_name);
# загрузить и активировать плагин
$plugin = $context->plugin($name, \@args);
# возвратить или создать функцию-фильтр
$filter = $context->filter($name, \@args, $alias);
# обработать/включить шаблон, ошибки инициируют die()
$output = $context->process($template, \%vars);
$output = $context->include($template, \%vars);
# сгенерировать исключение через die()
$context->throw($error_type, $error_message, \$output_buffer);
# перехватить исключение, очистить его и восстанавливает выходной буфер
$exception = $context->catch($exception, \$output_buffer);
# сохранить/восстановить хранилище для локализации переменных
$new_stash = $context->localise(\%vars);
$old_stash = $context->delocalise();
# добавить новые определения BLOCK или FILTER
$context->define_block($name, $block);
$context->define_filter($name, \&filtersub, $is_dynamic);
# очистить окружение, очистка всех импортированных определений BLOCK
$context->reset();
# методы доступа к внутренним переменным
$stash = $context->stash();
$tflag = $context->trim();
$epflag = $context->eval_perl();
$providers = $context->templates();
$providers = $context->plugins();
$providers = $context->filters();
... |
ОПИСАНИЕ |
[ Индекс ] [ Модули ] [ Наверх ] |
Модуль Template::Context определяет класс для представления текущего окружения, в котором обрабатываются шаблоны. Он предоставляет интерфейс к основным функциям парсера Template Toolkit через которые скомпилированный шаблон (т.е. построенный из шаблона perl-код) может обрабатывать шаблоны, загружать плагины и фильтры, генерировать исключения и т.д. Объект Template::Context по умолчанию создается модулем Template. Любые опции Template::Context могут передаваться конструктору new() Template и будут переданы конструктору Template::Context. use Template;
my $template = Template->new({
TRIM => 1,
EVAL_PERL => 1,
BLOCKS => {
header => 'Это заголовок',
footer => 'Это подвал',
},
});
Таким же образом, конструктор Template::Context передаст все параметры конфигурации в другие объекты по умолчанию (например, Template::Provider, Template::Plugins, Template::Filters и т.д.), которые ему может потребоваться создать. $context = Template::Context->new({
INCLUDE_PATH => '/home/abw/templates', # опция объекта Template::Provider
TAG_STYLE => 'html', # опция парсера
});
Объект Template::Context (или производный класс) можно создать явно и передать конструктору Template new() как элемент CONTEXT. use Template;
use Template::Context;
my $context = Template::Context->new({ TRIM => 1 });
my $template = Template->new({ CONTEXT => $context });
Модуль Template производящий метод context() модуля Template::Config для того чтобы создать при необходимости контекстный объект по умолчанию. Можно установить переменную пакета $Template::Config::CONTEXT, чтобы указать альтернативный контекстный модуль. Он будет загружаться автоматически и его конструктор new() будет вызываться производящим методом context() при необходимости создать объект контекста по умолчанию. use Template; $Template::Config::CONTEXT = 'MyOrg::Template::Context'; my $template = Template->new({
EVAL_PERL => 1,
EXTRA_MAGIC => 'red hot', # ваши дополнительные опции конфигурации
...
}); |
МЕТОДЫ |
[ Индекс ] [ Модули ] [ Наверх ] |
new(\%params)Метод-конструктор new() вызывается для создания объекта Template::Context. Параметры конфигурации можно передать как ссылку на хеш или как массив пар (имя => значение). my $context = Template::Context->new({
INCLUDE_PATH => 'header',
POST_PROCESS => 'footer',
});
my $context = Template::Context->new( EVAL_PERL => 1 ); Метод new() возвращает объект Template::Context (или производный класс) или undef в случае ошибки. В последнем случае соответсвующее сообщение об ошибке можно получить вызвав метод класса error() или прямо из переменной пакета $Template::Context::ERROR. my $context = Template::Context->new(\%config) || die Template::Context->error(); my $context = Template::Context->new(\%config) || die $Template::Context::ERROR; Можно указать следующие опции конфигурации.
template($name)Возвращает скомпилированный шаблон, опрашивая по очереди поставщиков LOAD_TEMPLATES (ссылки на объекты Template::Provider или производных классов). $template = $context->template('header');
В случае ошибки исключение типа 'file' (объект Template::Exception) будет сгенерировано через die(). Оно может быть перехвачено, если поместить вызов template() в блок eval с последующей проверкой $@. eval {
$template = $context->template('header');
};
if ($@) {
print "failed to fetch template: $@\n";
}
plugin($name, \@args)Создает экземпляр объекта-плагина, опрашивая поставщиков LOAD_PLUGINS. По умолчанию поставщик LOAD_PLUGINS - объект Template::Plugins, который пытается загрузить модули плагинов в соответствии с различными опциями конфигурации (PLUGIN_BASE, LOAD_PERL, и т.д.), и затем создает экземпляр класса с помощью new(). В качестве второго параметра можно передать ссылку на список аргументов конструктора. Этот список передается конструктору плагина. Возвращает ссылку на плагин (который обычно является объектом, хотя и не обязан им быть). Ошибки возбуждаются как объекты-исключения Template::Exception типа 'plugin'. $plugin = $context->plugin('DBI', 'dbi:msql:mydbname');
filter($name, \@args, $alias)Создает функцию-фильтр, опрашивая поставщиков LOAD_FILTERS. Поставщик LOAD_FILTERS по умолчанию - объект Template::Filters. Можно передать дополнительные аргументы через ссылку на массив вместе с дополнительным именем, под которым фильтр будет закеширован для последующих вызовов. Если $alias неопределен, фильтр кешируется под его собственным именем $name. Последующие вызовы filter($name) вернут закешированную копию, если она определена. Указанные дополнительные аргументы передаются кеширующему механизму и всегда приводят к созданию нового фильтра. Ошибки генерируют исключение-объект Template::Exception типа 'filter'. # статический фильтр (без аргументов)
$filter = $context->filter('html');
# динамический фильтр (есть аргументы) с псевдонимом 'padright'
$filter = $context->filter('format', '%60s', 'padright');
# получаем предыдущий фильтр через псевдоним 'padright'
$filter = $context->filter('padright');
process($template, \%vars)Обрабатывает шаблон, определенный именем или ссылкой, переданной в качестве первого аргумента, и возвращает сгенерированный вывод. В качестве второго аргумента можно передать ссылку на хеш, содержащий определения переменных, которые будут установлены перед обработкой шаблона. Шаблон обрабатывается в текущем окружении без локализации переменных. Ошибки генерируют через die() исключение-объект Template::Exception. $output = $context->process('header', { title => 'Hello World' });
include($template, \%vars)Аналогичен описанному выше методу process(), но использует локализацию переменных. Изменения любых переменных будут действовать только до завершения метода include(). $output = $context->include('header', { title => 'Hello World' });
throw($error_type, $error_message, \\)Возбуждает исключение в виде объекта Template::Exception, вызывая die(). Методу можно передать ссылку на существующий объект Template::Exception; единичное значение, содержащее сообщение об ошибке, используемое для создания объекта Template::Exception типа 'undef'; или пару значений (тип исключения и информация об ошибке), из которых будет создан объект Template::Exception. Например, $context->throw($exception);
$context->throw("I'm sorry Dave, I can't do that");
$context->throw('denied', "I'm sorry Dave, I can't do that");
В качестве необязательного третьего параметра можно передать ссылку на текущий буфер вывода. Она сохраняется при создании объекта исключения, позволяя перехватчику получить и использовать вывод до точки, в которой произошло исключение. $output .= 'blah blah blah';
$output .= 'more rhubarb';
$context->throw('yack', 'Too much yacking', \$output);
catch($exception, \\)Перехватывает возбужденное исключение, или как ссылку на объект Template::Exception, или как некоторое другое значение. В последнем случае сообщение об ошибке преобразуется в объект Template::Exception типа 'undef'. Этот метод также принимает ссылку на текущий буфер вывода, которая передается конструктору Template::Exception, или добавляется к буферу вывода, сохраненному в существующем объекте Template::Exception, если эти буферы не совпадают (то есть это не одна и та же ссылка). С помощью этого механизма можно восстановить правильное состояние буфера вывода для простых или вложенных исключений. define_block($name, $block)Добавляет новое определение блока во внутренний кеш BLOCKS. Первый аргумент должен содержать имя блока, а второй - ссылку на объект Template::Document или функцию шаблона, или текст шаблона, который автоматически компилируется в функцию шаблона. Возвращает истинное значение (ссылку на функцию или объект Template::Document) в случае удачного выполнения или undef в случае ошибки. Соответствующее сообщение об ошибке можно получить вызвав метод error(). define_filter($name, \&filter, $is_dynamic)Добавляет новое определение фильтра через вызовы метода store() для каждого из поставщиков LOAD_FILTERS до тех пор пока определение не будет принято (обычно, определение принимается сразу же первым и единственным поставщиком Template::Filters). Первый аргумент должен содержать имя шаблона, а второй ссылку на функцию фильтра. Необязательный третий параметр может быть установлен в любое истинное значение, чтобы указать, что функция - является производящей для динамических фильтров. Возвращает истинное значение или возбуждает исключение 'filter' в случае ошибки. localise(\%vars)Копирует хранилище переменных, чтобы создать окружение с локализованными переменными. Возвращает ссылку на новый объект-хранилище, который также сохраняется внутри. $stash = $context->localise(); delocalise()Восстанавливает хранилище в состояние до локализации. $stash = $context->delocalise(); visit(\%blocks)Метод вызывается объектами Template::Document непосредственно перед обработкой их содержимого. Он вызывается для того, чтобы зарегистрировать в объекте контекста все локальные определения BLOCK, чтобы позже они были доступны по запросам. leave()Метод, завершающий описанный выше visit(). Вызывается объектами Template::Document сразу после обработки их содержимого. reset()Очищает локальный кеш BLOCKS от всех определений BLOCK. Начальный набор, определенный в опции конфигурации конструктора BLOCKS, будет инициализирован заново. AUTOLOADМетод AUTOLOAD предоставляет доступ к опциям конфигурации контекста. $stash = $context->stash();
$tflag = $context->trim();
$epflag = $context->eval_perl();
...
|
АВТОР |
[ Индекс ] [ Модули ] [ Наверх ] |
Энди Уардли (Andy Wardley <abw@andywardley.com>) |
ВЕРСИЯ |
[ Индекс ] [ Модули ] [ Наверх ] |
2.91, поставляется в составе 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::Document, Template::Exception, Template::Filters, Template::Plugins, Template::Provider, Template::Service, Template::Stash |