local-lib5/lib/perl5/i486-linux-gnu-thread-multi/Template/Manual/Intro.pod

   1 #============================================================= -*-perl-*-
   2 #
   3 # Template::Manual::Intro
   4 #
   5 # AUTHOR
   6 #   Andy Wardley  <abw@wardley.org>
   7 #
   8 # COPYRIGHT
   9 #   Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
  10 #
  11 #   This module is free software; you can redistribute it and/or
  12 #   modify it under the same terms as Perl itself.
  13 #
  14 #========================================================================
  15
  16 =head1 NAME
  17
  18 Template::Manual::Intro - Introduction to the Template Toolkit
  19
  20 =head1 Introduction
  21
  22 The Template Toolkit is a collection of Perl modules which implement a
  23 fast, flexible, powerful and extensible template processing system.
  24 It is most often used for generating dynamic web content, although it can
  25 be used equally well for processing any kind of text documents.
  26
  27 At the simplest level it provides an easy way to process template
  28 files, filling in embedded variable references with their equivalent
  29 values.  Here's an example of a template.
  30
  31     Dear [% name %],
  32
  33     It has come to our attention that your account is in
  34     arrears to the sum of [% debt %].
  35
  36     Please settle your account before [% deadline %] or we
  37     will be forced to revoke your Licence to Thrill.
  38
  39     The Management.
  40
  41 By default, template directives are embedded within the character
  42 sequences C<[%> ... C<%]> but you can change these and various other
  43 options to configure how the Template Toolkit looks, feels and works.
  44 You can set the C<INTERPOLATE> option, for example, if you prefer to
  45 embed your variables in Perl style:
  46
  47     Dear $name,
  48
  49     It has come to our attention that your account is in
  50     arrears to the sum of $debt.
  51
  52     ...etc...
  53
  54 =head1 The Template Perl Module
  55
  56 The L<Template> Perl module is the front end to the Template Toolkit for Perl
  57 programmers, providing access to the full range of functionality through a
  58 single module with a simple interface. It loads the other modules as required
  59 and instantiates a default set of objects to handle subsequent template
  60 processing requests. Configuration parameters may be passed to the L<Template>
  61 constructor method, L<new()|Template#new()>, which are then used to
  62 configure the generate object.
  63
  64     use Template;
  65
  66     my $tt = Template->new({
  67         INCLUDE_PATH => '/usr/local/templates',
  68         INTERPOLATE  => 1,
  69     }) || die "$Template::ERROR\n";
  70
  71 The L<Template> object implements a L<process()|Template#process()> method for
  72 processing template files or text. The name of the input template (or various
  73 other sources) is passed as the first argument, followed by a reference to a
  74 hash array of variable definitions for substitution in the template.
  75
  76     my $vars = {
  77         name     => 'Count Edward van Halen',
  78         debt     => '3 riffs and a solo',
  79         deadline => 'the next chorus',
  80     };
  81
  82     $tt->process('letters/overdrawn', $vars)
  83         || die $tt->error(), "\n";
  84
  85 The L<process()|Template#process()> method returns a true value (C<1>) on success
  86 and prints the template output to C<STDOUT>, by default. On error, the
  87 L<process()|Template#process()> method returns a false value (C<undef>).
  88 The L<error()|Template#error()> method can then be called to retrieve
  89 details of the error.
  90
  91 =head1 Component Based Content Construction
  92
  93 A number of special directives are provided, such as C<INSERT>, C<INCLUDE> and
  94 C<PROCESS>, which allow content to be built up from smaller template
  95 components. This permits a modular approach to building a web site or other
  96 content repository, promoting reusability, cross-site consistency, ease of
  97 construction and subsequent maintenance. Common elements such as headers,
  98 footers, menu bars, tables, and so on, can be created as separate template
  99 files which can then be processed into other documents as required. All
 100 defined variables are inherited by these templates along with any additional
 101 "local" values specified.
 102
 103     [% PROCESS header
 104          title = "The Cat Sat on the Mat"
 105     %]
 106
 107     [% PROCESS menu %]
 108
 109     The location of the missing feline has now been established.
 110     Thank you for your assistance.
 111
 112     [% INSERT legal/disclaimer %]
 113
 114     [% PROCESS footer %]
 115
 116 You can also define a template as a BLOCK within the same file and
 117 PROCESS it just like any other template file.  This can be invaluable
 118 for building up repetitive elements such as tables, menus, etc.
 119
 120     [% BLOCK tabrow %]
 121        <tr><td>[% name %]</td><td>[% email %]</td></tr>
 122     [% END %]
 123
 124     <table>
 125     [% PROCESS tabrow name="tom"   email="tom@here.org"    %]
 126     [% PROCESS tabrow name="dick"  email="disk@there.org"  %]
 127     [% PROCESS tabrow name="larry" email="larry@where.org" %]
 128     </table>
 129
 130 =head1 Data and Code Binding
 131
 132 One of the key features that sets the Template Toolkit apart from
 133 other template processors is the ability to bind template variables to
 134 any kind of Perl data: scalars, lists, hash arrays, sub-routines and
 135 objects.
 136
 137     my $vars = {
 138         root   => 'http://here.com/there',
 139         menu   => [ 'modules', 'authors', 'scripts' ],
 140         client => {
 141             name => 'Doctor Joseph von Satriani',
 142             id   => 'JVSAT',
 143         },
 144         checkout => sub { my $total = shift; ...; return $something },
 145         shopcart => My::Cool::Shopping::Cart->new(),
 146     };
 147
 148 The Template Toolkit will automatically Do The Right Thing to access the data
 149 in an appropriate manner to return some value which can then be output. The
 150 dot operator 'C<.>' is used to access into lists and hashes or to call object
 151 methods. The C<FOREACH> directive is provided for iterating through lists, and
 152 various logical tests are available using directives such as C<IF>, C<UNLESS>,
 153 C<ELSIF>, C<ELSE>, C<SWITCH>, C<CASE>, etc.
 154
 155     [% FOREACH section = menu %]
 156        <a href="[% root %]/[% section %]/index.html">[% section %]</a>
 157     [% END %]
 158
 159     <b>Client</a>: [% client.name %] (id: [% client.id %])
 160
 161     [% IF shopcart.nitems %]
 162        Your shopping cart contains the following items:
 163        <ul>
 164        [% FOREACH item = shopcart.contents %]
 165          <li>[% item.name %] : [% item.qty %] @ [% item.price %]
 166        [% END %]
 167        </ul>
 168
 169        [% checkout(shopcart.total) %]
 170
 171     [% ELSE %]
 172        No items currently in shopping cart.
 173     [% END %]
 174
 175 =head1 Advanced Features: Filters, Macros, Exceptions, Plugins
 176
 177 The Template Toolkit also provides a number of additional directives
 178 for advanced processing and programmatical functionality.  It supports
 179 output filters (FILTER), allows custom macros to be defined (MACRO),
 180 has a fully-featured exception handling system (TRY, THROW, CATCH,
 181 FINAL) and supports a plugin architecture (USE) which allows special
 182 plugin modules and even regular Perl modules to be loaded and used
 183 with the minimum of fuss.  The Template Toolkit is "just" a template
 184 processor but you can trivially extend it to incorporate the
 185 functionality of any Perl module you can get your hands on.  Thus, it
 186 is also a scalable and extensible template framework, ideally suited
 187 for managing the presentation layer for application servers, content
 188 management systems and other web applications.
 189
 190 =head1 Separating Presentation and Application Logic
 191
 192 Rather than embedding Perl code or some other scripting language
 193 directly into template documents, it encourages you to keep functional
 194 components (i.e. Perl code) separate from presentation components
 195 (e.g. HTML templates).  The template variables provide the interface
 196 between the two layers, allowing data to be generated in code and then
 197 passed to a template component for displaying (pipeline model) or for
 198 sub-routine or object references to be bound to variables which can
 199 then be called from the template as and when required (callback
 200 model).
 201
 202 The directives that the Template Toolkit provide implement their own
 203 mini programming language, but they're not really designed for
 204 serious, general purpose programming.  Perl is a far more appropriate
 205 language for that.  If you embed application logic (e.g. Perl or other
 206 scripting language fragments) in HTML templates then you risk losing
 207 the clear separation of concerns between functionality and
 208 presentation.  It becomes harder to maintain the two elements in
 209 isolation and more difficult, if not impossible, to reuse code or
 210 presentation elements by themselves.  It is far better to write your
 211 application code in separate Perl modules, libraries or scripts and
 212 then use templates to control how the resulting data is presented as
 213 output.  Thus you should think of the Template Toolkit language as a
 214 set of layout directives for displaying data, not calculating it.
 215
 216 Having said that, the Template Toolkit doesn't force you into one
 217 approach or the other.  It attempts to be pragmatic rather than
 218 dogmatic in allowing you to do whatever best gets the job done.
 219 Thus, if you enable the EVAL_PERL option then you can happily embed
 220 real Perl code in your templates within PERL ... END directives.
 221
 222 =head1 Performance
 223
 224 The Template Toolkit uses a fast YACC-like parser which compiles
 225 templates into Perl code for maximum runtime efficiency.  It also has
 226 an advanced caching mechanism which manages in-memory and on-disk
 227 (i.e. persistent) versions of compiled templates.  The modules that
 228 comprise the toolkit are highly configurable and the architecture
 229 around which they're built is designed to be extensible.  The Template
 230 Toolkit provides a powerful framework around which content creation
 231 and delivery systems can be built while also providing a simple
 232 interface through the Template front-end module for general use.
 233
 234 =cut
 235
 236 # Local Variables:
 237 # mode: perl
 238 # perl-indent-level: 4
 239 # indent-tabs-mode: nil
 240 # End:
 241 #
 242 # vim: expandtab shiftwidth=4: