Provided by: libtemplate-perl_2.27-1_amd64 bug

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