template::service(3)

NAME

Template::Service - General purpose template processing
service

SYNOPSIS

use Template::Service;
my $service = Template::Service->new({
    PRE_PROCESS  => [ 'config', 'header' ],
    POST_PROCESS => 'footer',
    ERROR        => {
        user     => 'user/index.html',
        dbi      => 'error/database',
        default  => 'error/default',
    },
});
my  $output  =  $service->process($template_name,  replace)
    || die $service->error(), "0;

DESCRIPTION

The Template::Service module implements an object class
for providing a consistent template processing service.

Standard header (PRE_PROCESS) and footer (POST_PROCESS)
templates may be specified which are prepended and
appended to all templates processed by the service (but
not any other templates or blocks INCLUDEd or PROCESSed
from within). An ERROR hash may be specified which redi
rects the service to an alternate template file in the
case of uncaught exceptions being thrown. This allows
errors to be automatically handled by the service and a
guaranteed valid response to be generated regardless of
any processing problems encountered.

A default Template::Service object is created by the Tem plate module. Any Template::Service options may be passed to the Template new() constructor method and will be for warded to the Template::Service constructor.: use Template;; my $template = Template->new({
PRE_PROCESS => 'header',
POST_PROCESS => 'footer',; });
Similarly, the Template::Service constructor will forward all configuration parameters onto other default objects (e.g. Template::Context) that it may need to instantiate.
A Template::Service object (or subclass/derivative) can be explicitly instantiated and passed to the Template new() constructor method as the SERVICE item.: use Template;
use Template::Service;; my $service = Template::Service->new({
PRE_PROCESS => 'header',
POST_PROCESS => 'footer',; });; my $template = Template->new({
SERVICE => $service,; });
The Template::Service module can be sub-classed to create custom service handlers.: 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,; });
The Template module uses the Template::Config service() factory method to create a default service object when required. The $Template::Config::SERVICE package variable may be set to specify an alternate service module. This will be loaded automatically and its new() constructor method called by the service() factory method when a default service object is required. Thus the previous example could be written as:: use Template;; $Template::Config::SERVICE = 'MyOrg::Template::Ser; vice';; my $template = Template->new({
PRE_PROCESS => 'header',
POST_PROCESS => 'footer',
COOL_OPTION => 'enabled in spades',; });

METHODS

new%(config)

The new() constructor method is called to instantiate a Template::Service object. Configuration parameters may be specified as a HASH reference or as a list of (name => value) pairs.: my $service1 = Template::Service->new({
PRE_PROCESS => 'header',
POST_PROCESS => 'footer',; });; my $service2 = Template::Service->new( ERROR => 'er; ror.html' );
The new() method returns a Template::Service object (or sub-class) or undef on error. In the latter case, a rele vant error message can be retrieved by the error() class method or directly from the $Template::Service::ERROR package variable.: my $service = Template::Service->new(config)
|| die Template::Service->error();; my $service = Template::Service->new(config)
|| die $Template::Service::ERROR;
The following configuration items may be specified:
PRE_PROCESS, POST_PROCESS: These values may be set to contain the name(s) of tem
plate files (relative to INCLUDE_PATH) which should be
processed immediately before and/or after each tem
plate. These do not get added to templates processed
into a document via directives such as INCLUDE, PRO
CESS, WRAPPER etc.

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

};; Multiple templates may be specified as a reference to
a list. Each is processed in the order defined.

my $service = Template::Service->new({
PRE_PROCESS => [ 'config', 'header' ],
POST_PROCESS => 'footer',

};; Alternately, multiple template may be specified as a
single string, delimited by ':'. This delimiter
string can be changed via the DELIMITER option.

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

};; The PRE_PROCESS and POST_PROCESS templates are evalu
ated in the same variable context as the main document
and may define or update variables for subsequent use.; 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>; The Template::Document object representing the main
template being processed is available within PRE_PRO
CESS and POST_PROCESS templates as the 'template'
variable. Metadata items defined via the META direc
tive may be accessed accordingly.

$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: The PROCESS option may be set to contain the name(s)
of template files (relative to INCLUDE_PATH) which
should be processed instead of the main template
passed to the Template::Service process() method. This can be used to apply consistent wrappers around
all templates, similar to the use of PRE_PROCESS and
POST_PROCESS templates.

my $service = Template::Service->new({
PROCESS => 'content',

};

# processes 'content' instead of 'foo.html'
$service->process('foo.html');; A reference to the original template is available in
the 'template' variable. Metadata items can be
inspected and the template can be processed by speci
fying it as a variable reference (i.e. prefixed by
'$') to an INCLUDE, PROCESS or WRAPPER directive.; content:

<html>
<head>
<title>[% template.title %]</title>
</head>

<body>
[% PROCESS $template %]
<hr>
© 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; output:

<html>
<head>
<title>The Foo Page</title>
</head>

<body>
<h1>The Foo Page</h1>
Welcome to the Foo Page, blah blah blah
<hr>
© Copyright 2000 Fred Foo
</body>
</html>
ERROR: The ERROR (or ERRORS if you prefer) configuration item
can be used to name a single template or specify a
hash array mapping exception types to templates which
should be used for error handling. If an uncaught
exception is raised from within a template then the
appropriate error template will instead be processed.; If specified as a single value then that template will
be processed for all uncaught exceptions.

my $service = Template::Service->new({
ERROR => 'error.html'

});; If the ERROR item is a hash reference the keys are
assumed to be exception types and the relevant tem
plate for a given exception will be selected. A
'default' template may be provided for the general
case. Note that 'ERROR' can be pluralised to 'ERRORS'
if you find it more appropriate in this case.

my $service = Template::Service->new({
ERRORS => {
user => 'user/index.html',
dbi => 'error/database',
default => 'error/default',

},

});; In this example, any 'user' exceptions thrown will
cause the 'user/index.html' template to be processed,
'dbi' errors are handled by 'error/database' and all
others by the 'error/default' template. Any PRE_PRO
CESS and/or POST_PROCESS templates will also be
applied to these error templates.; Note that exception types are hierarchical and a 'foo'
handler will catch all 'foo.*' errors (e.g. foo.bar,
foo.bar.baz) if a more specific handler isn't defined.
Be sure to quote any exception types that contain
periods to prevent Perl concatenating them into a sin
gle string (i.e. "user.passwd" is parsed as
'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',

},

});; In this example, any template processed by the $ser
vice object, or other templates or code called from
within, can raise a 'user.login' exception and have
the service redirect to the 'user/login.html' tem
plate. Similarly, a 'user.passwd' exception has a
specific handling template, 'user/badpasswd.html',
while all other 'user' or 'user.*' exceptions cause a
redirection to the 'user/index.html' page. All other
exception types are handled by 'error/default'.; Exceptions can be raised in a template using the THROW
directive,

[% THROW user.login 'no user id: please login' %]; or by calling the throw() method on the current Tem
plate::Context object,

$context->throw('user.passwd', 'Incorrect Pass

word');
$context->throw('Incorrect Password'); # type

'undef'; or from Perl code by calling die() with a Tem
plate::Exception object,

die Template::Exception->new('user.denied', 'In

valid User ID');; or by simply calling die() with an error string. This
is automagically caught and converted to an exception
of 'undef' type which can then be handled in the usual
way.

die "I'm sorry Dave, I can't do that";
AUTO_RESET: The AUTO_RESET option is set by default and causes the
local BLOCKS cache for the Template::Context object to
be reset on each call to the Template process()
method. This ensures that any BLOCKs defined within a
template will only persist until that template is fin
ished processing. This prevents BLOCKs defined in one
processing request from interfering with other inde
pendent requests subsequently processed by the same
context object.; The BLOCKS item may be used to specify a default set
of block definitions for the Template::Context object.
Subsequent BLOCK definitions in templates will override these but they will be reinstated on each reset
if AUTO_RESET is enabled (default), or if the Tem
plate::Context reset() method is called.
process($input,%replace)
The process() method is called to process a template spec ified as the first parameter, $input. This may be a file name, file handle (e.g. GLOB or IO::Handle) or a reference to a text string containing the template text. An addi tional hash reference may be passed containing template variable definitions.
The method processes the template, adding any PRE_PROCESS or POST_PROCESS templates defined, and returns the output text. An uncaught exception thrown by the template will be handled by a relevant ERROR handler if defined. Errors that occur in the PRE_PROCESS or POST_PROCESS templates, or those that occur in the main input template and aren't handled, cause the method to return undef to indicate failure. The appropriate error message can be retrieved via the error() method.: $service->process('myfile.html', { title => 'My Test; File' })
|| die $service->error();
context()
Returns a reference to the internal context object which is, by default, an instance of the Template::Context class.
error()
Returns the most recent error message.

AUTHOR

Andy Wardley <abw@andywardley.com>

<http://www.andywardley.com/|http://www.andywardley.com/>

VERSION

2.61, distributed as part of the Template Toolkit version
2.08, released on 30 July 2002.

COPYRIGHT

Ltd.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

docs.sk

comprehensive documentation repository

In section