NAME

       Template::Manual::Intro - Introduction to the Template Toolkit

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.

       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.

           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.

       By default, template directives are embedded within the character sequences "[%" ... "%]"
       but you can change these and various other options to configure how the Template Toolkit
       looks, feels and works.  You can set the "INTERPOLATE" option, for example, if you prefer
       to embed your variables in Perl style:

           Dear $name,

           It has come to our attention that your account is in
           arrears to the sum of $debt.

           ...etc...

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, new(), which are then used to configure the
       generate object.

           use Template;

           my $tt = Template->new({
               INCLUDE_PATH => '/usr/local/templates',
               INTERPOLATE  => 1,
           }) || die "$Template::ERROR\n";

       The Template object implements a process() 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.

           my $vars = {
               name     => 'Count Edward van Halen',
               debt     => '3 riffs and a solo',
               deadline => 'the next chorus',
           };

           $tt->process('letters/overdrawn', $vars)
               || die $tt->error(), "\n";

       The process() method returns a true value (1) on success and prints the template output to
       "STDOUT", by default. On error, the process() method returns a false value ("undef").  The
       error() method can then be called to retrieve details of the error.

Component Based Content Construction

       A number of special directives are provided, such as "INSERT", "INCLUDE" and "PROCESS",
       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 "local"
       values specified.

           [% 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 %]

       You can also define a template as a BLOCK within the same file and PROCESS it just like
       any other template file.  This can be invaluable for building up repetitive elements such
       as tables, menus, etc.

           [% 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>

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.

           my $vars = {
               root   => 'http://here.com/there',
               menu   => [ 'modules', 'authors', 'scripts' ],
               client => {
                   name => 'Doctor Joseph von Satriani',
                   id   => 'JVSAT',
               },
               checkout => sub { my $total = shift; ...; return $something },
               shopcart => My::Cool::Shopping::Cart->new(),
           };

       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 '"."'
       is used to access into lists and hashes or to call object methods. The "FOREACH" directive
       is provided for iterating through lists, and various logical tests are available using
       directives such as "IF", "UNLESS", "ELSIF", "ELSE", "SWITCH", "CASE", etc.

           [% 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 %]

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 (FILTER), allows
       custom macros to be defined (MACRO), has a fully-featured exception handling system (TRY,
       THROW, CATCH, FINAL) and supports a plugin architecture (USE) which allows special plugin
       modules and even regular Perl modules to be loaded and used with the minimum of fuss.  The
       Template Toolkit is "just" 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.

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. HTML 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).

       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 HTML 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.

       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 EVAL_PERL option then you can happily embed real
       Perl code in your templates within PERL ... END directives.

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.