Contents
TopSYNOPSIS
Topuse 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
Top
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 redirects 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 Template module. Any
Template::Service options may be passed to the Template new() constructor method and
will be forwarded 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) 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::Service';
my $template = Template->new({
PRE_PROCESS => 'header',
POST_PROCESS => 'footer',
COOL_OPTION => 'enabled in spades',
});
METHODS
Topnew(\%config)
Top
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 => '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::Service::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)
Top
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_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()
TopReturns a reference to the internal context object which is, by default, an instance of the Template::Context class.
CONFIGURATION OPTIONS
Top
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 configuration option in use.
PRE_PROCESS, POST_PROCESS
Top
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 processed 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
Top
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
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 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
Top
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/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
Top
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 finished processing.
AUTHOR
TopAndy Wardley <abw@wardley.org> http://wardley.org/
COPYRIGHT
TopCopyright (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.