Template Toolkit: Модули: Template::Context

Template Toolkit

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

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

Template::Context

[ ◄ Template::Constants ] [ Template::Document ► ]
Текущий контекст, в котором обрабатываются шаблоны.

Оглавление

КРАТКИЙ ОБЗОР

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

    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;

Можно указать следующие опции конфигурации.

  • VARIABLES, PRE_DEFINE

    Опция VARIABLES (или PRE_DEFINE - они эквивалентны) используется для указания хеша переменных шаблона, которые будут использоваться для инициализации хранилища переменных при его создании. Эти элементы игнорируются, если определена опция STASH.

        my $context = Template::Context->new({
    	VARIABLES => {
    	    title   => 'A Demo Page',
    	    author  => 'Joe Random Hacker',
    	    version => 3.14,
    	},
        };

    или

        my $context = Template::Context->new({
    	PRE_DEFINE => {
    	    title   => 'A Demo Page',
    	    author  => 'Joe Random Hacker',
    	    version => 3.14,
    	},
        };
  • BLOCKS

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

        my $context = Template::Context->new({
    	BLOCKS => {
    	    header  => 'The Header.  [% title %]',
    	    footer  => sub { return $some_output_text },
    	    another => Template::Document->new({ ... }),
    	},
        }); 
  • TRIM

    Опцию TRIM можно использовать для автоматического удаления из вывода всех шаблонов и блоков BLOCK начальных и завершающих пробельных символов.

    Например, следующее определение BLOCK

        [% BLOCK foo %]
        Line 1 of foo
        [% END %]

    будет обработано как "\nLine 1 of foo\n". При включении директивой INCLUDE, окружающие символы новой строки также будут добавлены.

        before
        [% INCLUDE foo %]
        after

    Вывод:

        before
        Line 1 of foo
        after

    Если опция TRIM установлена в любое истинное значение, ведущие и завершающие переносы (которые также относятся к пробельным символам) будут удалены из вывода BLOCK.

        before
        Line 1 of foo
        after

    Опция TRIM по умолчанию запрещена (0).

  • EVAL_PERL

    Этот флаг используется для указания будут ли вычисляться блоки PERL и/или RAWPERL. По умолчанию опция запрещена и любой встретившийся блок PERL или RAWPERL приведет к возникновению исключения типа 'perl' с сообщением 'EVAL_PERL not set'. Тем не менее имейте в виду, что любой блок RAWPERL должен всегда содержать корректный perl-код, вне зависимости от флага EVAL_PERL. Парсер не сможет скомпилировать шаблоны, содержащие код с ошибками в блоках RAWPERL и возбудит исключение типа 'file'.

    При использовании скомпилированных шаблонов (смотри COMPILE_EXT и COMPILE_DIR), EVAL_PERL оказывает влияние на результат компиляции, и позже, когда шаблоны снова обрабатываются, возможно, в контексте, отличном от того, в котором они были скомпилированы.

    Если опция EVAL_PERL установлена при компиляции шаблона, то все блоки PERL и RAWPERL будут включены в скомпилированный шаблон. Если опция EVAL_PERL не установлена, будет сгенерирован perl-код, который всегда возбуждает исключение 'perl' с сообщением 'EVAL_PERL not set', когда бы и в каком контексте код шаблона ни исполнялся.

    Поэтому, вам необходимо устанавливать EVAL_PERL, если вы хотите, чтобы скомпилированные шаблоны включали блоки PERL и RAWPERL.

    Впоследствии, используя другой вызов Template Toolkit, вы можете обработать такой предкомпилированный шаблон. Если при компиляции опция EVAL_PERL была установлена, вывод всех блоков RAWPERL будет будет включен в скомпилированный шаблон и будет выполнен при обработке шаблона вне зависимости от текущей установки EVAL_PERL.

    Тем не менее, стандартные блоки PERL немного более требовательные. Если опция EVAL_PERL не установлена в текущем контексте, то попытка обработки такого скомпилированного шаблона приведет к генерации знакомого исключения 'perl' с сообщением 'EVAL_PERL not set'.

    Таким образом, вы можете скомпилировать шаблоны с блоками PERL, но при последующей обработке выборочно запрещать их выполнение. Не забывайте тем не менее, что блок PERL может содержать perl-код "BEGIN { # здесь что-то делается }", который всегда будет выполнен независимо от текущей установки EVAL_PERL. Таким образом, предполагается, что уставливая при компиляции опцию EVAL_PERL, вы доверяете шаблонам. В противном случае вам придется смириться с тем фактом, что не существует надежного способа помещать включенному коду нанести ущерб текущему окружению и стать настоящей проблемой. Если вам эта идея не нравится, используйте всегда установку EVAL_PERL по умолчанию (запрещено).

  • RECURSION

    Процессор шаблонов возбудит исключение 'file', если он обнаружит в шаблоне прямую или непрямую рекурсию. Установка этой опции в истинное значение позволяет шаблонам включать друг друга рекурсивно.

  • LOAD_TEMPLATES

    Через опцию LOAD_TEMPLATE можно передать ссылку на массив объектов Template::Provider или его производных классов, которые будут отвечать за загрузку и компиляцию шаблонов.

        my $context = Template::Context->new({
    	LOAD_TEMPLATES => [
        	    MyOrg::Template::Provider->new({ ... }),
        	    Template::Provider->new({ ... }),
    	],
        });

    Шаблон в директивах PROCESS, INCLUDE или WRAPPER может быть именем локально определенного блока BLOCK или путем к файлу относительно INCLUDE_PATH (или абсолютным или относительным путем, если установлены опции ABSOLUTE или RELATIVE соответственно). Если определение блока не найдено (смотри обсуждение особенностей BLOCK в описании метода Template::Context template()), требующийся шаблон запрашивается у каждого из объектов-поставщиков LOAD_TEMPLATES через метод fetch(). Каждый поставщик может вернуть скомпилированный шаблон, ошибку, или отказать в обслуживании запроса (в этом случае ответственность переходить к следующему поставщику). Если ни один из поставщиков не может обслужить запрос, возвращается ошибка 'not found'. Аналогичный в основе механизм поставщиков используется для директивы INSERT, но игнорируются определения BLOCK и разбор или обработка содержимого файла шаблона не выполняется.

    Это реализация модели 'Цепочка ответственности' ('Chain of Responsibility'), описанной в "Design Patterns", Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides), Addision-Wesley, ISBN 0-201-63361-2, page 223.

    Если LOAD_TEMPLATES неопределена, будет создан единичный объект поставщика по умолчанию с текущими параметрами конфигурации. Например, опция Template::Provider INCLUDE_PATH может быть указан в конфигурации Template::Context и будет корректно передана конструктору поставщика.

        my $context = Template::Context->new({
    	INCLUDE_PATH => '/here:/there',
        });
  • LOAD_PLUGINS

    Опция LOAD_PLUGINS используется для указания списка объектов-поставщиков (то есть они предоставляют метод fetch()), которые отвечают за загрузку и инициализацию объектов-плагинов шаблона. Метод Template::Context plugin() делает запрос к каждому поставщику по принципу "Цепочка ответственности" аналогично методам template() и filter().

        my $context = Template::Context->new({
    	LOAD_PLUGINS => [
        	    MyOrg::Template::Plugins->new({ ... }),
        	    Template::Plugins->new({ ... }),
    	],
        });

    По умолчанию создается единичный объект Template::Plugins с использованием текушего хеша конфигурации. Опции конфигурации для конструктора Template::Plugins можно передать через конструктор Template::Context.

        my $context = Template::Context->new({
    	PLUGIN_BASE => 'MyOrg::Template::Plugins',
    	LOAD_PERL   => 1,
        });
  • LOAD_FILTERS

    Опция LOAD_FILTERS используется для указания списка объектов-поставщиков (то есть они предоставляют метод fetch()), которые отвечают за возврат и/или создание функций-фильтров. Метод Template::Context filter() делает запрос к каждому поставщику по принципу "Цепочка ответственности" аналогично методам template() и plugin().

        my $context = Template::Context->new({
    	LOAD_FILTERS => [
        	    MyTemplate::Filters->new(),
        	    Template::Filters->new(),
    	],
        });

    По умолчанию для массива LOAD_FILTERS создается единичный объект Template::Filters.

  • STASH

    Ссылка на объект Template::Stash или производный класс, который будет отвечать за управление переменными шаблона.

        my $stash = MyOrg::Template::Stash->new({ ... });
        my $context = Template::Context->new({
    	STASH => $stash,
        });

    Если опция не указана, создается объект по умолчанию с использованием опции конфигурации VARIABLES для инициализации хранилища переменных. Для обратной совместимости с версией 1 также используется опция PRE_DEFINE.

        my $context = Template::Context->new({
    	VARIABLES => {
    	    id    => 'abw',
    	    name  => 'Andy Wardley',
    	},
        };
  • DEBUG

    Опцию DEBUG можно использовать для разрешения различных отладочных возможностей в модуле Template::Context.

        use Template::Constants qw( :debug );
        my $template = Template->new({
    	DEBUG => DEBUG_CONTEXT | DEBUG_DIRS,
        });

    DEBUG может включать любые из перечисленных значений. Различные значения можно комбинировать, используя логический оператор '|' (ИЛИ).

    • DEBUG_CONTEXT

      Разрешает общие отладочные сообщения для модуля Template::Context.

    • DEBUG_DIRS

      Включение этой опции приводит к генерации комментариев, содержащих имя исходного файла, номер строки и текст каждой директивы шаблона. Эти комментарии включаются в вывод шаблона в формате, определенном опцией конфигурации DEBUG_FORMAT, либо в простом формате по умолчанию, если опция не указана.

      Например, следующий фрагмент шаблона:

          Hello World

      сгенерирует следующий вывод:

          ## input text line 1 :  ##
          Hello
          ## input text line 2 : World ##
          World

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>)

http://www.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.

СМОТРИ ТАКЖЕ

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