.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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::Manual::Intro 3"
.TH Template::Manual::Intro 3 "2014-04-24" "perl v5.16.3" "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::Manual::Intro \- Introduction to the Template Toolkit
.SH "Introduction"
.IX Header "Introduction"
The Template Toolkit is a collection of Perl modules which implement a
fast, flexible, powerful and extensible template processing system.
It is most often used for generating dynamic web content, although it can 
be used equally well for processing any kind of text documents.
.PP
At the simplest level it provides an easy way to process template
files, filling in embedded variable references with their equivalent
values.  Here's an example of a template.
.PP
.Vb 1
\&    Dear [% name %],
\&    
\&    It has come to our attention that your account is in 
\&    arrears to the sum of [% debt %].
\&    
\&    Please settle your account before [% deadline %] or we 
\&    will be forced to revoke your Licence to Thrill.
\&    
\&    The Management.
.Ve
.PP
By default, template directives are embedded within the character
sequences \f(CW\*(C`[%\*(C'\fR ... \f(CW\*(C`%]\*(C'\fR but you can change these and various other
options to configure how the Template Toolkit looks, feels and works.
You can set the \f(CW\*(C`INTERPOLATE\*(C'\fR option, for example, if you prefer to
embed your variables in Perl style:
.PP
.Vb 1
\&    Dear $name,
\&    
\&    It has come to our attention that your account is in 
\&    arrears to the sum of $debt.
\&
\&    ...etc...
.Ve
.SH "The Template Perl Module"
.IX Header "The Template Perl Module"
The Template Perl module is the front end to the Template Toolkit for Perl
programmers, providing access to the full range of functionality through a
single module with a simple interface. It loads the other modules as required
and instantiates a default set of objects to handle subsequent template
processing requests. Configuration parameters may be passed to the Template
constructor method, \fInew()\fR, which are then used to
configure the generate object.
.PP
.Vb 1
\&    use Template;
\&    
\&    my $tt = Template\->new({
\&        INCLUDE_PATH => \*(Aq/usr/local/templates\*(Aq,
\&        INTERPOLATE  => 1,
\&    }) || die "$Template::ERROR\en";
.Ve
.PP
The Template object implements a \fIprocess()\fR method for
processing template files or text. The name of the input template (or various
other sources) is passed as the first argument, followed by a reference to a
hash array of variable definitions for substitution in the template.
.PP
.Vb 5
\&    my $vars = {
\&        name     => \*(AqCount Edward van Halen\*(Aq,
\&        debt     => \*(Aq3 riffs and a solo\*(Aq,
\&        deadline => \*(Aqthe next chorus\*(Aq,
\&    };
\&    
\&    $tt\->process(\*(Aqletters/overdrawn\*(Aq, $vars)
\&        || die $tt\->error(), "\en";
.Ve
.PP
The \fIprocess()\fR method returns a true value (\f(CW1\fR) on success
and prints the template output to \f(CW\*(C`STDOUT\*(C'\fR, by default. On error, the
\&\fIprocess()\fR method returns a false value (\f(CW\*(C`undef\*(C'\fR).
The \fIerror()\fR method can then be called to retrieve
details of the error.
.SH "Component Based Content Construction"
.IX Header "Component Based Content Construction"
A number of special directives are provided, such as \f(CW\*(C`INSERT\*(C'\fR, \f(CW\*(C`INCLUDE\*(C'\fR and
\&\f(CW\*(C`PROCESS\*(C'\fR, which allow content to be built up from smaller template
components. This permits a modular approach to building a web site or other
content repository, promoting reusability, cross-site consistency, ease of
construction and subsequent maintenance. Common elements such as headers,
footers, menu bars, tables, and so on, can be created as separate template
files which can then be processed into other documents as required. All
defined variables are inherited by these templates along with any additional
\&\*(L"local\*(R" values specified.
.PP
.Vb 3
\&    [% PROCESS header 
\&         title = "The Cat Sat on the Mat"
\&    %]
\&    
\&    [% PROCESS menu %]
\&    
\&    The location of the missing feline has now been established.
\&    Thank you for your assistance.
\&    
\&    [% INSERT legal/disclaimer %]
\&    
\&    [% PROCESS footer %]
.Ve
.PP
You can also define a template as a \s-1BLOCK\s0 within the same file and
\&\s-1PROCESS\s0 it just like any other template file.  This can be invaluable
for building up repetitive elements such as tables, menus, etc.
.PP
.Vb 3
\&    [% BLOCK tabrow %]
\&       <tr><td>[% name %]</td><td>[% email %]</td></tr>
\&    [% END %]
\&    
\&    <table>
\&    [% PROCESS tabrow name="tom"   email="tom@here.org"    %]
\&    [% PROCESS tabrow name="dick"  email="disk@there.org"  %]
\&    [% PROCESS tabrow name="larry" email="larry@where.org" %]
\&    </table>
.Ve
.SH "Data and Code Binding"
.IX Header "Data and Code Binding"
One of the key features that sets the Template Toolkit apart from
other template processors is the ability to bind template variables to
any kind of Perl data: scalars, lists, hash arrays, sub-routines and
objects.
.PP
.Vb 10
\&    my $vars = {
\&        root   => \*(Aqhttp://here.com/there\*(Aq,
\&        menu   => [ \*(Aqmodules\*(Aq, \*(Aqauthors\*(Aq, \*(Aqscripts\*(Aq ],
\&        client => {
\&            name => \*(AqDoctor Joseph von Satriani\*(Aq,
\&            id   => \*(AqJVSAT\*(Aq,
\&        },
\&        checkout => sub { my $total = shift; ...; return $something },
\&        shopcart => My::Cool::Shopping::Cart\->new(),
\&    };
.Ve
.PP
The Template Toolkit will automatically Do The Right Thing to access the data
in an appropriate manner to return some value which can then be output. The
dot operator '\f(CW\*(C`.\*(C'\fR' is used to access into lists and hashes or to call object
methods. The \f(CW\*(C`FOREACH\*(C'\fR directive is provided for iterating through lists, and
various logical tests are available using directives such as \f(CW\*(C`IF\*(C'\fR, \f(CW\*(C`UNLESS\*(C'\fR,
\&\f(CW\*(C`ELSIF\*(C'\fR, \f(CW\*(C`ELSE\*(C'\fR, \f(CW\*(C`SWITCH\*(C'\fR, \f(CW\*(C`CASE\*(C'\fR, etc.
.PP
.Vb 3
\&    [% FOREACH section = menu %]
\&       <a href="[% root %]/[% section %]/index.html">[% section %]</a>
\&    [% END %]
\&    
\&    <b>Client</b>: [% client.name %] (id: [% client.id %])
\&    
\&    [% IF shopcart.nitems %]
\&       Your shopping cart contains the following items:
\&       <ul>
\&       [% FOREACH item = shopcart.contents %]
\&         <li>[% item.name %] : [% item.qty %] @ [% item.price %]
\&       [% END %]
\&       </ul>
\&       
\&       [% checkout(shopcart.total) %]
\&       
\&    [% ELSE %]
\&       No items currently in shopping cart.
\&    [% END %]
.Ve
.SH "Advanced Features: Filters, Macros, Exceptions, Plugins"
.IX Header "Advanced Features: Filters, Macros, Exceptions, Plugins"
The Template Toolkit also provides a number of additional directives
for advanced processing and programmatical functionality.  It supports
output filters (\s-1FILTER\s0), allows custom macros to be defined (\s-1MACRO\s0),
has a fully-featured exception handling system (\s-1TRY, THROW, CATCH,
FINAL\s0) and supports a plugin architecture (\s-1USE\s0) which allows special
plugin modules and even regular Perl modules to be loaded and used
with the minimum of fuss.  The Template Toolkit is \*(L"just\*(R" a template
processor but you can trivially extend it to incorporate the
functionality of any Perl module you can get your hands on.  Thus, it
is also a scalable and extensible template framework, ideally suited
for managing the presentation layer for application servers, content
management systems and other web applications.
.SH "Separating Presentation and Application Logic"
.IX Header "Separating Presentation and Application Logic"
Rather than embedding Perl code or some other scripting language
directly into template documents, it encourages you to keep functional
components (i.e. Perl code) separate from presentation components
(e.g. \s-1HTML\s0 templates).  The template variables provide the interface
between the two layers, allowing data to be generated in code and then
passed to a template component for displaying (pipeline model) or for
sub-routine or object references to be bound to variables which can
then be called from the template as and when required (callback
model).
.PP
The directives that the Template Toolkit provide implement their own
mini programming language, but they're not really designed for
serious, general purpose programming.  Perl is a far more appropriate
language for that.  If you embed application logic (e.g. Perl or other
scripting language fragments) in \s-1HTML\s0 templates then you risk losing
the clear separation of concerns between functionality and
presentation.  It becomes harder to maintain the two elements in
isolation and more difficult, if not impossible, to reuse code or
presentation elements by themselves.  It is far better to write your
application code in separate Perl modules, libraries or scripts and
then use templates to control how the resulting data is presented as
output.  Thus you should think of the Template Toolkit language as a
set of layout directives for displaying data, not calculating it.
.PP
Having said that, the Template Toolkit doesn't force you into one
approach or the other.  It attempts to be pragmatic rather than
dogmatic in allowing you to do whatever best gets the job done.
Thus, if you enable the \s-1EVAL_PERL\s0 option then you can happily embed
real Perl code in your templates within \s-1PERL ... END\s0 directives.
.SH "Performance"
.IX Header "Performance"
The Template Toolkit uses a fast YACC-like parser which compiles
templates into Perl code for maximum runtime efficiency.  It also has
an advanced caching mechanism which manages in-memory and on-disk
(i.e. persistent) versions of compiled templates.  The modules that
comprise the toolkit are highly configurable and the architecture
around which they're built is designed to be extensible.  The Template
Toolkit provides a powerful framework around which content creation
and delivery systems can be built while also providing a simple
interface through the Template front-end module for general use.