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
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 "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 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¶
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 => '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;
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()¶
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
configuration 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 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¶
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¶
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¶
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_SERVICE" 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