Template::Service(3)

💖 NAME 💖

okay so welcome to the Template::Service(3) page from User Contributed Perl Documentation, bestie! Template::Service is the general purpose template processing service module. it's the thing that gives you a consistent template processing service, no cap. 💅

---

✨ SYNOPSIS ✨

here's the whole vibe in code, bestie:

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 🦋

so the Template::Service module implements an object class for providing a consistent template processing service. it's literally the main character of template processing. 👑

you can specify standard header (PRE_PROCESS) and footer (POST_PROCESS) templates. those get prepended and appended to all templates processed by the service — but not to any other templates or blocks that get INCLUDEd or PROCESSed from within, okay? lowkey important. 🫶

an ERROR hash may be specified. it redirects the service to an alternate template file in the case of uncaught exceptions being thrown. this lets errors be automatically handled by the service, and a guaranteed valid response gets generated regardless of any processing problems encountered. slay. ✨

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. it's giving delegation, honestly. 🎀

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. custom service handler era, fr fr. 🦋

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. choose your fighter. 💅

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. sad girl hours, but at least you get the error. 😭

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. very flexible, we love to see it. 🌸

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. periodt. 🔥

$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. context bestie. 🫶

---

🎀 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. iykyk. 💜

💅 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. important distinction, bestie. 🎀

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. order matters, obviously. ✨

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. wrappers on wrappers, iconic. 👑

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. main character template energy. 🌟

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. error handling, but make it cute. 😭💖

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. very organized, very demure. 🎀

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 BLOCKs defined within a template will only persist until that template is finished processing. no lingering blocks, bestie. 🧹✨

💅 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. debug era. 🔍

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-2022 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. periodt. 💅

---

🔥 SEE ALSO 🔥

Template, Template::Context

---

and that's the whole page, bestie! this cutie was rendered by perl v5.42.0 on 2024-06-23 as Template::Service(3) 💖✨🎀