[% TAGS [** **] -%]
=head1 OVERVIEW 

The Template Toolkit is a collection of Perl modules which
collectively implement fast, powerful and generic template
processing system.  In this context, a template is a text document
which contains embedded processing "directives".  These instruct the
template processor to perform certain actions such as; inserting the
value of a variable, processing and including another template file or
user-defined block, testing some condition and generating output of
one kind or another accordingly, iterating through a set of values,
and so on.  Anything not marked as a template directive is treated as
plain text and gets passed through unaltered.  By default, directives
look something like this:

   [% INCLUDE header %]

The "mini-language" that the toolkit uses (ATML - A Template Markup
Language?) is designed to be clear, concise, regular in structure and
simple in syntax.  It is a specialised language which boasts many
powerful features for constructing dynamic content but it is I<not> a
general purpose programming language.  Instead, it supports a plugin
interface which allows separate modules of application specific code
to be written in the language of choice and then loaded, used and
re-used as required.  "Language of choice" can be read as "Perl" in
this case, through which you have access to C, C++, and (speaking
tentatively) Java.

In other words, it helps to promote the separation of application code
(the I<implementation>) from the user interface (the I<presentation>).
It tries to keep templates clutter-free, concentrating on what the
document looks like, not how the various items of content are
stored, retrieved or calculated.  From the perspective of a web
designer, for example, they're just bits of text that get inserted
into different parts of the page.

Development and subsequent maintenance become easier and less error
prone when the "back-end" is separated from the "front-end".  You (or
your web designer) can first decide how the page(s) should look by
creating the output templates, perhaps by re-using other common
elements that you've already defined for your web site such as
headers, footers, menus, etc.  Then, you (or your progammer) can
create any Perl code required to required to generate the dynamic
parts of the content, perhaps by using CPAN modules, one of the
existing Template Toolkit "plugins" or by re-using some code you've
previously written for another web "application" running on your site.
The important thing is that the code is developed I<separately> from
the template documents.  It doesn't matter if you put every function
in a separate file or every bit of application code into one big module.
Just tell the Template Toolkit where to find the code and leave it to
handle the rest.

The new functionality is then available without distraction or
discourse in any and all of your template documents.  In other words,
the code is portable between templates.  This is true if you're using
the Template Toolkit to generate static pages off-line, or dynamic
pages on-line via CGI script or Apache/mod_perl handler - it's all the
same as far as the Template Toolkit is concerned.  And because the way
it I<looks> isn't encoded with what it I<does>, you can change the way
it looks, or the specific implementation of how it does whatever it
does, without affecting the other.

There are many benefits.  You can write a single web application with
a dozen different sets of templates to represent alternate user
interfaces.  These represent many "views" on the same underlying
"model" and may differ in layout or design style, contain text only or
go hard on the graphics, contain HTML frames or not, show "novice" or
"expert" functionality, allow per-user customisation, present an
internationalised or interface localised to other written languages or
cultures, and so on.  On the other side of the same coin, you can
change your underlying code to implement a faster algorithm or more
efficient storage method, but you don't have to change the template
files because the output doesn't change.  They still get their
"content" from the same "place" and don't need to concern themselves
with what happens inside each black box.  Implementation details
matter greatly when you're writing programs, but they're rarely
important when you're gluing bits of text together to build pages.
Page design and layout is a lot easier when you don't have Perl code
strewn throughout the document.  Writing code is a lot easier when 
you don't have HTML strewn throught the program.

The end result is that complex, dynamic content systems can be built
easily and quickly from a number of small, reusable components.  Some
of these components are template files representing user interface
"chunks" and others may be data structures, library code, user-defined
sub-routines or objects that implement various functionalities of the
system.  The Template Toolkit's role is to help pull all the different
pieces together as quickly and simply as possible, hiding as many of
the unnecessary details as it can.

The Template Toolkit is ideally suited for generating web content, but
it is by no means limited or specific to this or any other application
area.  The plugin interface means that it doesn't have to be - it can
just concentrate on the task of constructing documents and doesn't
care if you subsequently use it to generate HTML, LaTeX, RTF or plain
text documents from a command-line, CGI script or an in-server web
process such as Apache/mod_perl using data extracted from a CGI form,
defined in a file, retrieved from a database or based on what Jim
Morrison told you in a dream.  You choose what do to with it and
how to do it.  Simply load additional functionality as you need it
from CPAN modules, Template Toolkit plugins, generic web applications
such as chat rooms, FAQ lists, bulletin boards, etc., or any other
code you can beg, borrow or write yourself.

The philosophy behind the toolkit should hopefully now be clearer.  It
is about speed and simplicity in constructing document systems.  It
doesn't concern itself with how you write the "clever stuff" that
performs whatever process and produces whatever output you desire.  It
defers that task to a far more powerful, general purpose language -
Perl.  

  "Dammit Jim!
     - I'm a template processor, not a programming language." 

There are many times when the "best solution" in terms of getting the
job done quickly and efficiently is to simply embed Perl code directly
into the document.  In those cases, Mark-Jason Dominus' Text::Template
module comes highly recommended (available from CPAN).  

The Template Toolkit is generally there for the times when you want to
build a more structured document I<system>. Rather than emphasing the
raw programming power embedded within any I<single document>, it
focusses on tools and techniques to help better partition and
subsequently re-integrate the different components that constitute the
I<many> documents in a system.  That's not to say that you can't use
it in many interesting ways with just a single document, but if you
only have a single document to worry about then the chances are that
you haven't got a lot to worry about.

You may be wondering how this differs from other Perl modules and how
it compares to similar dynamic content construction techniques such as
Server Side Include (SSI), Cascading Style Sheets (CSL), XML
(Extensible Markup Language), and so on.  The main points are these:

=over 4

=item *

The Template Toolkit promotes a structured approach to content
construction.  There's a slight "startup" cost to using this approach
because, like life, it always takes a little longer to get yourself
properly organised.  The payoff comes in terms of scalability.  The 
more you add, the more you benefit from having structure.

=item *

The Template Toolkit is not about how much raw programming power you
can cram into a document.  For that, you simply can't beat directly
embedding Perl and processing via a module such as Text::Template.
This approach is something like CGI in reverse - instead of putting
HTML in your program, you put your program in the HTML.  The Template
Toolkit instead keeps the two entities separate. 

=item *

The Template Toolkit doesn't try and do it all.  In fact, it tries to
do as little as possible, preferring instead to delegate to "Real
Perl" and "Real Perl Modules" for "Real Programming" tasks.  The
toolkit language concerns itself with nothing more than building
documents.  It doesn't need to be anything like as versatile,
powerful, complex or cryptic as Perl.  It remains blessedly focussed
and bloat-free, and implements as few new wheels as possibly.  This is
a Good Thing because it means I have less code to maintain and the
hubris gets properly shared out.

=item *

The Template Toolkit is not specific to any particular application or
environment.  Nothing in the core toolkit is specific in any way to
HTML, CGI or a web server environment.  It simply processes text and
doesn't concern itself which what that text might finally come to
represent: HTML, POD, XML, XSL, LaTeX, RTF, etc.  Additional
functionality is loaded only as required.  You can use it from a
command line script, via one of the distribution scripts, B<tpage> and
B<ttree>, in a CGI script or in a web or application server
environment.  Your call.  You don't have to change the way you write
templates or the way you write code because these things remain
independant of the final "delivery method" of the document.

=back

The Template Toolkit is a direct descendant of, and replacement for
the Text::MetaText module.  It has been designed and rebuilt from
scratch based on several years of experience gained from developing,
supporting and using Text::MetaText and other template processing
applications and tools.  It is an Open Source project in which
contribution and collaboration are encouraged.


