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

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)

    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 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()

CONFIGURATION OPTIONS

PRE_PROCESS, POST_PROCESS

    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

    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>

AUTO_RESET

DEBUG

    use Template::Constants qw( :debug );
    
    my $template = Template->new({
        DEBUG => DEBUG_SERVICE,
    });

AUTHOR

COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

POD ERRORS

Around line 517:

alternative text 'ERROR/ERRORS' contains non-escaped | or /