# Template::Service - phpMan

## 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]