oracular (3) Template::Service.3pm.gz
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;
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_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 or 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