Template::Service
Template::Service(3) User Contributed Perl Documentation 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(), "\n";
DESCRIPTION
The "Template::Service" module implements an object class for provid-
ing 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 pro-
cessed by the service (but not any other templates or blocks
"INCLUDE"d or "PROCESS"ed from within). An ERROR hash may be specified
which redirects the service to an alternate template file in the case
of uncaught exceptions being thrown. This allows errors to be automat-
ically 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 Template mod-
ule. Any "Template::Service" options may be passed to the Template
new() constructor method and will be forwarded to the Template::Ser-
vice constructor.
use Template;
my $template = Template->new({
PRE_PROCESS => ’header’,
POST_PROCESS => ’footer’,
});
Similarly, the "Template::Service" constructor will forward all con-
figuration parameters onto other default objects (e.g. Template::Con-
text) that it may need to instantiate.
A "Template::Service" object (or subclass) can be explicitly instanti-
ated and passed to the Template new() constructor method as the SER-
VICE 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::Con-
fig::SERVICE package variable may be set to specify an alternate ser-
vice module. This will be loaded automatically and its new() construc-
tor method called by the service() factory method when a default ser-
vice object is required. Thus the previous example could be written
as:
use Template;
$Template::Config::SERVICE = ’MyOrg::Template::Service’;
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 "Tem-
plate::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 => ’error.html’ );
The "new()" method returns a "Template::Service" object or "undef" on
error. In the latter case, a relevant error message can be retrieved
by the error() class method or directly from the $Template::Ser-
vice::ERROR package variable.
my $service = Template::Service->new(\%config)
││ die Template::Service->error();
my $service = Template::Service->new(\%config)
││ die $Template::Service::ERROR;
process($input, \%replace)
The "process()" method is called to process a template specified 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 additional hash reference may be
passed containing template variable definitions.
The method processes the template, adding any PRE_PROCESS or POST_PRO-
CESS 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_PRO-
CESS templates, or those that occur in the main input template and
aren’t handled, cause the method to return "undef" to indicate fail-
ure. 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.
CONFIGURATION OPTIONS
The following list summarises the configuration options that can be
provided to the "Template::Service" new() constructor. Please consult
Template::Manual::Config for further details and examples of each con-
figuration option in use.
PRE_PROCESS, POST_PROCESS
The PRE_PROCESS and POST_PROCESS options may be set to contain the
name(s) of template files which should be processed immediately before
and/or after each template. These do not get added to templates pro-
cessed into a document via directives such as "INCLUDE" "PROCESS",
"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’,
};
PROCESS
The PROCESS option may be set to contain the name(s) of template files
which should be processed instead of the main template passed to the
"Template::Service" process() method. This can be used to apply con-
sistent wrappers around all templates, similar to the use of PRE_PRO-
CESS 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 specifying it as a variable reference (i.e. prefixed by
’"$"’) to an "INCLUDE", "PROCESS" or "WRAPPER" directive.
Example "PROCESS" template:
<html>
<head>
<title>[% template.title %]</title>
</head>
<body>
[% PROCESS $template %]
</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 appropri-
ate 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/ERRORS item is a hash reference the keys are assumed to
be exception types and the relevant template for a given exception
will be selected. A "default" template may be provided for the general
case.
my $service = Template::Service->new({
ERRORS => {
user => ’user/index.html’,
dbi => ’error/database’,
default => ’error/default’,
},
});
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 "BLOCK"s defined
within a template will only persist until that template is finished
processing.
DEBUG
The DEBUG option can be used to enable debugging messages from the
"Template::Service" module by setting it to include the "DEBUG_SER-
VICE" value.
use Template::Constants qw( :debug );
my $template = Template->new({
DEBUG => DEBUG_SERVICE,
});
AUTHOR
Andy Wardley <abw@wardley.org> <http://wardley.org/>
COPYRIGHT
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
Template, Template::Context
perl v5.8.8 2007-09-20 Template::Service(3)
