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

Модуль Template::Service реализует объектный класс для предоставления согласованной службы по обработке шаблонов.

Можно задать стандартные шаблоны шапок (PRE_PROCESS) и подвалов (POST_PROCESS), которые будут добавлены в начало и конец всех обрабатываемых службой шаблонов (но никаких других шаблонов и блоков, включаемых через INCLUDE или PROCESS из шаблонов). Можно указать хеш ERROR, который переадресует службу к альтернативному файлу шаблона в случае возникновения неперхваченного исключения. Это позволяет автоматически обрабатывать ошибки службой и гарантировать правильный ответ вне зависимости от любых возникших проблем.

Объект Template::Service по умолчанию создаётся модулем Template. Любые опции Template::Service можно пердать через конструктор Template new() и они будут переданы конструктору Template::Service.

    use Template;

    my $template = Template->new({
	PRE_PROCESS  => 'header',
	POST_PROCESS => 'footer',
    });

Аналогично, конструктор Template::Service передаст все параметры конфигурации в другие объекты по умолчанию (например, Template::Context), которые возможно потребуется инициализировать.

Объект Template::Service (или подкласс/производный класс) может быть явно создан и передан конструктору Template new() в качестве значения элемента SERVICE.

    use Template;
    use Template::Service;

    my $service = Template::Service->new({
	PRE_PROCESS  => 'header',
	POST_PROCESS => 'footer',
    });

    my $template = Template->new({
	SERVICE => $service,
    });

Template::Service можно унаследовать, чтобы создать собственный обработчик службы.

    use Template;
    use MyOrg::Template::Service;

    my $service = MyOrg::Template::Service->new({
	PRE_PROCESS  => 'header',
	POST_PROCESS => 'footer',
	COOL_OPTION  => 'enabled in spades',
    });

    my $template = Template->new({
	SERVICE => $service,
    });

Модуль Template использует производящий метод Template::Config service(), чтобы создать когда необходимо объект службы по умолчанию. Чтобы указать альтернативный модуль службы можно установить переменную пакета $Template::Config::SERVICE. Этот модуль будет загружен автоматически и его конструктор new() будет вызван производящим методом service(), когда потребуется объект службы по умолчанию. Таким образом, предыдущий пример можно переписать так:

    use Template;

    $Template::Config::SERVICE = 'MyOrg::Template::Service';

    my $template = Template->new({
	PRE_PROCESS  => 'header',
	POST_PROCESS => 'footer',
	COOL_OPTION  => 'enabled in spades',
    });

new(\%config)

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

    my $service1 = Template::Service->new({
	PRE_PROCESS  => 'header',
	POST_PROCESS => 'footer',
    });

    my $service2 = Template::Service->new( ERROR => 'error.html' );

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

    my $service = Template::Service->new(\%config)
	|| die Template::Service->error();

    my $service = Template::Service->new(\%config)
	|| die $Template::Service::ERROR;

Конструктору можно передать следующие опции конфигурации:

PRE_PROCESS, POST_PROCESS

Эти опции могут содержать имя (имена) файлов шаблонов (относительно INCLUDE_PATH), которые будут немедленно обработаны до и/или после каждого шаблона. Это не относится к шаблонам, которые обрабатываются в документе через директивы INCLUDE, PROCESS, WRAPPER и т.д.
```
    my $service = Template::Service->new({
	PRE_PROCESS  => 'header',
	POST_PROCESS => 'footer',
    };
```
Несколько шаблонов можно передать с помощью ссылки на массив. Каждый шаблон будет обработан в определенном порядке.
```
    my $service = Template::Service->new({
	PRE_PROCESS  => [ 'config', 'header' ],
	POST_PROCESS => 'footer',
    };
```
Другой способ определения нескольких шаблонов - использование строки с именами шаблонов, разделенных символом ':'. Строка-разделитель может быть изменена через опцию DELIMITER.
```
    my $service = Template::Service->new({
	PRE_PROCESS  => 'config:header',
	POST_PROCESS => 'footer',
    };
```
Шаблоны PRE_PROCESS и POST_PROCESS вычисляются в том же окружении переменных, что и главный документ, и могут определять или изменять переменные шаблона для последующего использования.

config:
```
    [% # set some site-wide variables
       bgcolor = '#ffffff'
       version = 2.718
    %]
```
header:
```
    [% DEFAULT title = 'My Funky Web Site' %]
    <html>
    <head>
    <title>[% title %]</title>
    </head>
    <body bgcolor="[% bgcolor %]">
```
footer:
```
    <hr>
    Version [% version %]
    </body>
    </html>
```
Объект Template::Document, представляющий главный шаблон, который будет обработан, доступен внутри шаблонов PRE_PROCESS и POST_PROCESS как переменная 'template'. Таким же образом можно получить доступ к метаданным, определенным с помощью директивы META.
```
    $service->process('mydoc.html', $vars);
```
mydoc.html:
```
    [% META title = 'My Document Title' %]
    blah blah blah
    ...
```
header:
```
    <html>
    <head>
    <title>[% template.title %]</title></head>
    <body bgcolor="[% bgcolor %]">
```
PROCESS

С помощью опции PROCESS можно задать файл(ы) шаблонов (относительно INCLUDE_PATH), которые будут обрабатываться вместо главного шаблона, который передается методу Template process(). Это можно использовать для применения нескольких последовательных оберток для всех шаблонов, как и при использовании шаблонов PRE_PROCESS и POST_PROCESS.
```
    my $service = Template::Service->new({
	PROCESS  => 'content',
    };
```
```
    # обрабатывается 'content' вместо 'foo.html'
    $service->process('foo.html');
```
Ссылка на оригинальный шаблон доступна через переменную 'template'. Можно использовать элементы метаданных определенные в нем, а сам шаблон можно обработать, указав его как ссылку на переменную (с префиксом '$') директивам INCLUDE, PROCESS или WRAPPER.

content:
```
    <html>
    <head>
    <title>[% template.title %]</title>
    </head>

    <body>
    [% PROCESS $template %]
    <hr>
    &copy; Copyright [% template.copyright %]
    </body>
    </html>
```
foo.html:
```
    [% META
       title     = 'The Foo Page'
       author    = 'Fred Foo'
       copyright = '2000 Fred Foo'
    %]
    <h1>[% template.title %]</h1>
    Welcome to the Foo Page, blah blah blah
```
Вывод:
```
    <html>
    <head>
    <title>The Foo Page</title>
    </head>
```
```
    <body>
    <h1>The Foo Page</h1>
    Welcome to the Foo Page, blah blah blah
    <hr>
    &copy; Copyright 2000 Fred Foo
    </body>
    </html>
```
ERROR

Опция ERROR (или ERRORS, если вам так больше нравится) используется для указания шаблона или определения хэша, связывающего типы исключений с шаблонами, используемыми для обработки ошибок. Если внутри шаблона возникает неперехваченное исключение, вместо него будет обработан соответствующий шаблон ошибки.

Если указать опции одиночное значение, то этот шаблон будет обрабатываться для всех неперехваченных исключений.
```
    my $service = Template::Service->new({
	ERROR => 'error.html'
    });
```
Если опция ERROR - ссылка на хеш, то предполагается, что ключи этого хеша - типы исключений и будет выбран подходящий шаблон для данного исключения. Для общего случая можно указать шаблон 'default'. Вы можете использовать 'ERRORS' вместо 'ERROR', если находите это название более подходящим для данного случая.
```
    my $service = Template::Service->new({
	ERRORS => {
	    user     => 'user/index.html',
	    dbi      => 'error/database',
	    default  => 'error/default',
	},
    });
```
В данном примере, любые возбужденные исключения 'user' приведут к обработке шаблона 'user/index.html', ошибки 'dbi' обрабатываются шаблоном 'error/database', а все остальные шаблоном 'error/default'. Любые шаблоны PRE_PROCESS и/или POST_PROCESS также будут применены к этим шаблонам ошибок.

Обратите внимание на то, что типы исключений имеют иерархию, и обработчик 'foo' будет также перехватывать все ошибки 'foo.*' (например, foo.bar, foo.bar.baz), если не определен более подходящий обработчик. Заключайте типы исключений, содержащие точки, в кавычки, чтобы быть уверенным, что Perl не склеит их в одну строку (например 'user.passwd' интерпретируется как 'user'.'passwd').
```
    my $service = Template::Service->new({
	ERROR => {
	    'user.login'  => 'user/login.html',
	    'user.passwd' => 'user/badpasswd.html',
	    'user'        => 'user/index.html',
	    'default'     => 'error/default',
	},
    });
```
В этом примере, любой шаблон обрабатываемый объектом $template, или другие шаблоны или код, вызываемые изнутри, могут возбудить исключение 'user.login', которое будет обработано шаблоном 'user/login.html'. Аналогично, исключение 'user.passwd' имеет свой шаблон-обработчик 'user/badpasswd.html', в то время как все остальные исключения 'user' или 'user.*' приведут к использованию шаблона 'user/index.html'. Оставшиеся исключения обрабатываются 'error/default'.

Исключение можно возбудить с помощью директивы THROW внутри шаблона,
```
    [% THROW user.login 'no user id: please login' %]
```
или вызвав метод throw() текущего объекта Template::Context,
```
    $context->throw('user.passwd', 'Incorrect Password');
    $context->throw('Incorrect Password');    # тип 'undef'
```
или из кода Perl, вызвав die() с объектом Template::Exception,
```
    die (Template::Exception->new('user.denied', 'Invalid User ID'));
```
или простым вызовом die() со строкой-сообщением об ошибке. Этот die() будет автомагически перехвачен и преобразован в исключение типа 'undef', которое затем может быть обработано обычным способом.
```
    die "I'm sorry Dave, I can't do that";
```
AUTO_RESET

Опция AUTO_RESET установлена по умолчанию и вызывает очистку кэша локальных блоков (BLOCK) объекта Template::Context при каждом вызове метода Template process(). Это гарантирует, что любой блок определенный внутри шаблона будет существовать только во время обработки этого шаблона. Это предотвращает возможность влияния блоков, определенных при одном запросе на обработку шаблона, на последующие независимые запросы к тому же объекту Template::Context.

Опция BLOCKS может использоваться для определения набора блоков по умолчанию для объекта Template::Context. Последующие определения BLOCK в шаблонах переопределят их, но они будут восстанавливаться при каждом сбросе, если AUTO_RESET разрешена (по умолчанию), или после вызова метода reset() объекта Template::Context.
DEBUG

Опцию DEBUG можно использовать, чтобы включить отладочные сообщения модуля Template::Service, установкой (дополнением) этого флага значением DEBUG_SERVICE.
```
    use Template::Constants qw( :debug );
```
```
    my $template = Template->new({
	DEBUG => DEBUG_SERVICE,
    });
```

process($input, \%replace)

Метод process() вызывается для обработки шаблона, указаного в качестве первого аргумента $input. Это может быть имя файла, файловый дескриптор (например, GLOB или IO::Handle) или ссылка на текстовую строку, содержащую шаблон. Дополнительно можно передать ссылку на хеш, содержащий определения переменных шаблона.

Метод обрабатывает шаблон, добавляя любые определенные шаблоны PRE_PROCESS или POST_PROCESS, и возвращает выходной текст. Неперехваченные исключения, сгенерированные шаблоном будут обработаны подходящим обработчиком ERROR, если он определен. Ошибки, которые возникают в шаблонах PRE_PROCESS или POST_PROCESS, или те, которые возникают в основном шаблоне, но не обрабатываются, приведут к тому, что метод вернет undef, что означает неудачное выполнение. Соответствующее сообщение об ошибке можно получить через метод error().

    $service->process('myfile.html', { title => 'My Test File' })
	|| die $service->error();

context()

Возвращает ссылку на внутренний объект контекста, который по умолчанию является экземпляром класса Template::Context.

error()

Возвращает самое последнее сообщение об ошибке.

Template Toolkit

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

Template::Service

Оглавление

ОБЗОР

ОПИСАНИЕ

МЕТОДЫ

new(\%config)

process($input, \%replace)

context()

error()

АВТОР

ВЕРСИЯ

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

СМОТРИ ТАКЖЕ