Contents
TopSYNOPSIS
Topuse 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
Top
                      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
                      INCLUDEd or PROCESSed 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
Topnew(\%config)
Top
                          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)
Top
                          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()
TopReturns a reference to the internal context object which is, by default, an instance of the Template::Context class.
CONFIGURATION OPTIONS
Top
                      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
Top
                          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
Top
                          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
Top
                          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
Top
                          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
                          BLOCKs defined within a template will only persist until
                          that template is finished processing.
                        
AUTHOR
TopAndy Wardley <abw@wardley.org> http://wardley.org/
COPYRIGHT
TopCopyright (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.