Mini Shell

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Template::Service 3"
.TH Template::Service 3 "2024-06-21" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Template::Service \- General purpose template processing service
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Template::Service;
\&
\&    my $service = Template::Service\->new({
\&        PRE_PROCESS  => [ \*(Aqconfig\*(Aq, \*(Aqheader\*(Aq ],
\&        POST_PROCESS => \*(Aqfooter\*(Aq,
\&        ERROR        => {
\&            user     => \*(Aquser/index.html\*(Aq,
\&            dbi      => \*(Aqerror/database\*(Aq,
\&            default  => \*(Aqerror/default\*(Aq,
\&        },
\&    });
\&
\&    my $output = $service\->process($template_name, \e%replace)
\&        || die $service\->error(), "\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Template::Service\*(C'\fR module implements an object class for providing
a consistent template processing service.
.PP
Standard header (\s-1PRE_PROCESS\s0) and footer
(\s-1POST_PROCESS\s0) templates may be specified which
are prepended and appended to all templates processed by the service (but not
any other templates or blocks \f(CW\*(C`INCLUDE\*(C'\fRd or \f(CW\*(C`PROCESS\*(C'\fRed from within). An
\&\s-1ERROR\s0 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.
.PP
A default \f(CW\*(C`Template::Service\*(C'\fR object is created by the Template module.
Any \f(CW\*(C`Template::Service\*(C'\fR options may be passed to the Template
\&\fBnew()\fR constructor method and will be forwarded to the
Template::Service constructor.
.PP
.Vb 1
\&    use Template;
\&
\&    my $template = Template\->new({
\&        PRE_PROCESS  => \*(Aqheader\*(Aq,
\&        POST_PROCESS => \*(Aqfooter\*(Aq,
\&    });
.Ve
.PP
Similarly, the \f(CW\*(C`Template::Service\*(C'\fR constructor will forward all configuration
parameters onto other default objects (e.g. Template::Context) that it may
need to instantiate.
.PP
A \f(CW\*(C`Template::Service\*(C'\fR object (or subclass) can be explicitly instantiated and
passed to the Template \fBnew()\fR constructor method as the
\&\s-1SERVICE\s0 item.
.PP
.Vb 2
\&    use Template;
\&    use Template::Service;
\&
\&    my $service = Template::Service\->new({
\&        PRE_PROCESS  => \*(Aqheader\*(Aq,
\&        POST_PROCESS => \*(Aqfooter\*(Aq,
\&    });
\&
\&    my $template = Template\->new({
\&        SERVICE => $service,
\&    });
.Ve
.PP
The \f(CW\*(C`Template::Service\*(C'\fR module can be sub-classed to create custom service
handlers.
.PP
.Vb 2
\&    use Template;
\&    use MyOrg::Template::Service;
\&
\&    my $service = MyOrg::Template::Service\->new({
\&        PRE_PROCESS  => \*(Aqheader\*(Aq,
\&        POST_PROCESS => \*(Aqfooter\*(Aq,
\&        COOL_OPTION  => \*(Aqenabled in spades\*(Aq,
\&    });
\&
\&    my $template = Template\->new({
\&        SERVICE => $service,
\&    });
.Ve
.PP
The Template module uses the Template::Config
\&\fBservice()\fR factory method to create a default
service object when required. The \f(CW$Template::Config::SERVICE\fR package
variable may be set to specify an alternate service module. This will be
loaded automatically and its \fBnew()\fR constructor method called by the
\&\fBservice()\fR factory method when a default service
object is required. Thus the previous example could be written as:
.PP
.Vb 1
\&    use Template;
\&
\&    $Template::Config::SERVICE = \*(AqMyOrg::Template::Service\*(Aq;
\&
\&    my $template = Template\->new({
\&        PRE_PROCESS  => \*(Aqheader\*(Aq,
\&        POST_PROCESS => \*(Aqfooter\*(Aq,
\&        COOL_OPTION  => \*(Aqenabled in spades\*(Aq,
\&    });
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new(\e%config)"
.IX Subsection "new(%config)"
The \f(CW\*(C`new()\*(C'\fR constructor method is called to instantiate a \f(CW\*(C`Template::Service\*(C'\fR
object.  Configuration parameters may be specified as a \s-1HASH\s0 reference or
as a list of \f(CW\*(C`name => value\*(C'\fR pairs.
.PP
.Vb 4
\&    my $service1 = Template::Service\->new({
\&        PRE_PROCESS  => \*(Aqheader\*(Aq,
\&        POST_PROCESS => \*(Aqfooter\*(Aq,
\&    });
\&
\&    my $service2 = Template::Service\->new( ERROR => \*(Aqerror.html\*(Aq );
.Ve
.PP
The \f(CW\*(C`new()\*(C'\fR method returns a \f(CW\*(C`Template::Service\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR on
error. In the latter case, a relevant error message can be retrieved by the
\&\fBerror()\fR class method or directly from the
\&\f(CW$Template::Service::ERROR\fR package variable.
.PP
.Vb 2
\&    my $service = Template::Service\->new(\e%config)
\&        || die Template::Service\->error();
\&
\&    my $service = Template::Service\->new(\e%config)
\&        || die $Template::Service::ERROR;
.Ve
.SS "process($input, \e%replace)"
.IX Subsection "process($input, %replace)"
The \f(CW\*(C`process()\*(C'\fR method is called to process a template specified as the first
parameter, \f(CW$input\fR. This may be a file name, file handle (e.g. \f(CW\*(C`GLOB\*(C'\fR or
\&\f(CW\*(C`IO::Handle\*(C'\fR) or a reference to a text string containing the template text. An
additional hash reference may be passed containing template variable
definitions.
.PP
The method processes the template, adding any
\&\s-1PRE_PROCESS\s0 or
\&\s-1POST_PROCESS\s0 templates defined, and returns the
output text. An uncaught exception thrown by the template will be handled by a
relevant \s-1ERROR\s0 handler if defined. Errors that occur in the
\&\s-1PRE_PROCESS\s0 or
\&\s-1POST_PROCESS\s0 templates, or those that occur in the
main input template and aren't handled, cause the method to return \f(CW\*(C`undef\*(C'\fR to
indicate failure. The appropriate error message can be retrieved via the
\&\fBerror()\fR method.
.PP
.Vb 2
\&    $service\->process(\*(Aqmyfile.html\*(Aq, { title => \*(AqMy Test File\*(Aq })
\&        || die $service\->error();
.Ve
.SS "\fBcontext()\fP"
.IX Subsection "context()"
Returns a reference to the internal context object which is, by default, an
instance of the Template::Context class.
.SH "CONFIGURATION OPTIONS"
.IX Header "CONFIGURATION OPTIONS"
The following list summarises the configuration options that can be provided
to the \f(CW\*(C`Template::Service\*(C'\fR \fBnew()\fR constructor. Please consult
Template::Manual::Config for further details and examples of each
configuration option in use.
.SS "\s-1PRE_PROCESS, POST_PROCESS\s0"
.IX Subsection "PRE_PROCESS, POST_PROCESS"
The \s-1PRE_PROCESS\s0 and
\&\s-1POST_PROCESS\s0 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 \f(CW\*(C`INCLUDE\*(C'\fR
\&\f(CW\*(C`PROCESS\*(C'\fR, \f(CW\*(C`WRAPPER\*(C'\fR, etc.
.PP
.Vb 4
\&    my $service = Template::Service\->new({
\&        PRE_PROCESS  => \*(Aqheader\*(Aq,
\&        POST_PROCESS => \*(Aqfooter\*(Aq,
\&    };
.Ve
.PP
Multiple templates may be specified as a reference to a list.  Each is
processed in the order defined.
.PP
.Vb 4
\&    my $service = Template::Service\->new({
\&        PRE_PROCESS  => [ \*(Aqconfig\*(Aq, \*(Aqheader\*(Aq ],
\&        POST_PROCESS => \*(Aqfooter\*(Aq,
\&    };
.Ve
.SS "\s-1PROCESS\s0"
.IX Subsection "PROCESS"
The \s-1PROCESS\s0 option may be set to contain
the name(s) of template files which should be processed instead of the main
template passed to the \f(CW\*(C`Template::Service\*(C'\fR \fBprocess()\fR method. This can be used to
apply consistent wrappers around all templates, similar to the use of
\&\s-1PRE_PROCESS\s0 and
\&\s-1POST_PROCESS\s0 templates.
.PP
.Vb 3
\&    my $service = Template::Service\->new({
\&        PROCESS  => \*(Aqcontent\*(Aq,
\&    };
\&
\&    # processes \*(Aqcontent\*(Aq instead of \*(Aqfoo.html\*(Aq
\&    $service\->process(\*(Aqfoo.html\*(Aq);
.Ve
.PP
A reference to the original template is available in the \f(CW\*(C`template\*(C'\fR
variable.  Metadata items can be inspected and the template can be
processed by specifying it as a variable reference (i.e. prefixed by
\&'\f(CW\*(C`$\*(C'\fR') to an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR directive.
.PP
Example \f(CW\*(C`PROCESS\*(C'\fR template:
.PP
.Vb 8
\&    <html>
\&      <head>
\&        <title>[% template.title %]</title>
\&      </head>
\&      <body>
\&      [% PROCESS $template %]
\&      </body>
\&    </html>
.Ve
.SS "\s-1ERROR\s0"
.IX Subsection "ERROR"
The \s-1ERROR\s0 (or \f(CW\*(C`ERRORS\*(C'\fR 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.
.PP
If specified as a single value then that template will be processed
for all uncaught exceptions.
.PP
.Vb 3
\&    my $service = Template::Service\->new({
\&        ERROR => \*(Aqerror.html\*(Aq
\&    });
.Ve
.PP
If the \s-1ERROR\s0 or \s-1ERRORS\s0 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 \f(CW\*(C`default\*(C'\fR template may be provided for
the general case.
.PP
.Vb 7
\&    my $service = Template::Service\->new({
\&        ERRORS => {
\&            user     => \*(Aquser/index.html\*(Aq,
\&            dbi      => \*(Aqerror/database\*(Aq,
\&            default  => \*(Aqerror/default\*(Aq,
\&        },
\&    });
.Ve
.SS "\s-1AUTO_RESET\s0"
.IX Subsection "AUTO_RESET"
The \s-1AUTO_RESET\s0 option is set by default
and causes the local \f(CW\*(C`BLOCKS\*(C'\fR cache for the Template::Context object to be
reset on each call to the Template \fBprocess()\fR method.
This ensures that any \f(CW\*(C`BLOCK\*(C'\fRs defined within a template will only persist until
that template is finished processing.
.SS "\s-1DEBUG\s0"
.IX Subsection "DEBUG"
The \s-1DEBUG\s0 option can be used to enable
debugging messages from the \f(CW\*(C`Template::Service\*(C'\fR module by setting it to include
the \f(CW\*(C`DEBUG_SERVICE\*(C'\fR value.
.PP
.Vb 1
\&    use Template::Constants qw( :debug );
\&
\&    my $template = Template\->new({
\&        DEBUG => DEBUG_SERVICE,
\&    });
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley <abw@wardley.org> <http://wardley.org/>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1996\-2022 Andy Wardley.  All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Template, Template::Context