General information
Template Toolkit
Version 2.14
04 October 2004
Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
This is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
QUICK START (see INSTALL for further details)
-----------
The latest version of the Template Toolkit can be retrieved from:
http://www.cpan.org/modules/by-module/Template/
Fetch and install AppConfig 1.55 if you don't already have it installed.
Available from CPAN in:
http://www.cpan.org/authors/Andy_Wardley/
The following modules are optional. If you have them installed then
you will be able to access them via the appropriate Template Toolkit
plugins. If you don't have them and don't want them, then there's no
need to install them. They're all available from CPAN if you do.
Text::Autoformat 1.03+
DBI 1.14+ (and relevant DBD drivers)
GD 1.32+
GD::Text 0.80+
GD::Graph 1.33+
GD::Graph3d 0.55+
Pod::POM 0.1+
XML::Parser 2.23+
XML::DOM 1.27+ (in libxml-enno)
XML::RSS 0.9+
XML::XPath 1.00+
To install the Template Toolkit:
tar zxf Template-Toolkit-2.14.tar.gz
cd Template-Toolkit-2.14
perl Makefile.PL
make
make test
make install
The Makefile.PL will prompt for additional configuration options,
including the installation of optional template libraries, HTML
documentation and examples. You can safely answer 'n' to all of these
questions for a quick and basic installation.
If you're running ActivePerl on a Win32 platform then you can use the
Perl Package Manager (PPM) to install the Template Toolkit. Chris
Winters maintains a repository of pre-compiled PPM packages which contains
the Template Toolkit, AppConfig and others. For further information, see:
http://openinteract.sourceforge.net/
For further details on installation, see the separate INSTALL file.
DESCRIPTION
-----------
The Template Toolkit is a collection of modules which implement a
fast, flexible, powerful and extensible template processing system.
It was originally designed and remains primarily useful for generating
dynamic web content, but it can be used equally well for processing
any other kind of text based documents: HTML, XML, POD, PostScript,
LaTeX, and so on.
It can be used as a stand-alone Perl module or embedded within an
Apache/mod_perl server for generating highly configurable dynamic web
content. A number of Perl scripts are also provided which can greatly
simplify the process of creating and managing static web content and
other offline document systems.
Version 2 is a near-total rewrite which adds many new features while
remaining *almost* fully backwardly compatible with version 1 (see
'VERSION COMPATABILITY' below). The internal design and
architecture have been greatly improved and the template language
offers a number of powerful new directives, while retaining all but
the broken, buggy, undocumented or experimental features that had
crept into versions 0.* and 1.* over the years. Version 2 also offers
important performance benefits, running significantly faster and using
less memory than version 1. This can only be described as a Good
Thing.
The Template Toolkit (version 1) received the award for "Best New Perl
Module" at the 4th Perl Conference in Monterey last year (2000).
Version 2 is even better and if it doesn't make your content funkier,
your job easier, your life more fun and you more attractive to the
appropriate sex, then you can always return it for a full refund. :-)
WHAT'S NEW?
-----------
Version 2.14 adds Unicode support to TT, a full set of command line
options for tpage, the 'caller' and 'callers' items to each template
component, some enhancements to the XML::Simple plugin, and a number
of minor bug fixes.
Version 2.13 followed on quickly from 2.13 to fix a minor, but
annoying bug in the date.t test script that we thought we had
fixed in 2.12 but hadn't.
Version 2.12 followed on quickly from 2.11 to fix a minor, but
annoying bug in the date.t test script.
Version 2.11 includes a number of enhancements to ttree, and several
minor bug fixes. It also improves on how runtime errors and warnings
are reported, by adding the template file and line number to the
message generated.
Version 2.10 provided a few trivial new features and applies fixes to
some small bugs. For example, you can now use IN instead of = in a
loop, e.g. FOREACH item IN list. The WRAPPER configuration option is
new, and Template::Context and Template::Stash now both implement
define_vmethod() methods which make it easier to define new virtual
methods.
Version 2.09 contained mostly bug fixes and minor enhancements.
Version 2.08 added compile time constant folding which can result in a
significant performance boost when processing templates. It also
offered several other minor enhancements and bug fixes.
Version 2.07 was a major maintenance release, fixing numerous minor bugs
and smoothing out various rough edges. Version 2.06 was a very minor
bug release version.
The most exciting new feature in version 2.05 was Doug Steinwand's
high-speed drop-in replacement for Template::Stash written in
Perl XS. With this in place, the Template Toolkit typically runs
twice as fast as before!
Pretty much everything else in 2.05 and 2.04 before it consisted
of minor bug fixes and improvements.
Version 2.03 included Craig Barratt's 'latex' filter and GD plugins
and Dave Cross's tutorial on using the Template Toolkit for creating
and reusing XML data files.
Version 2.02 was another bugfix release.
Version 2.01 was a major release containing new filters, plugins,
template libraries, the experimental VIEW directive, and a total
overhaul of the documentation.
GENERAL FEATURES
----------------
Some of the key features of the Template Toolkit are listed below.
See the documentation for further detail.
* simple but powerful template language
* promotes a clear separation between application functionality and
presentation elements
* variable substitution allows binding to any Perl data types
(scalars, hashes, lists, subs, objects)
* conditional blocks (IF/UNLESS/ELSIF/ELSE, SWITCH/CASE)
* loops and iterators (FOREACH, WHILE)
* file/template inclusion (INSERT, INCLUDE, PROCESS, WRAPPER)
* definition of local template components (BLOCK)
* post-processing filters (FILTER)
* plugin module architecture for easy extensibility (USE)
* embedded Perl can be optionally enabled (PERL/RAWPERL)
* full exception handling (TRY/THROW/CATCH/FINAL)
* user-defined macros (MACRO)
* definition of template metadata (META)
* virtual methods for complex data types (e.g. list.size, hash.keys, etc.)
* numerous configuration options
* modular OO architecture allows extensive customisation
* fast LALR(1) parser modules compiles templates according to a
YACC-like grammar.
* templates compiled to Perl code for efficient runtime execution
* in-memory and on-disk caching of compiled templates
* simple front end module (Template.pm) for ease of use
* numerous plugin modules: CGI, DBI, XML, URL, Date, Table, etc
* standard filters for html, case folding, regex search and replace, etc.
DOCUMENTATION
-------------
The Template Toolkit is provided with enough documentation to keep all
but the most voracious reader happy for quite some time.
The 'Changes' file in the distribution directory documents all visible
changes between versions of the Template Toolkit. See the section
'VERSION COMPATABILITY' below for further details.
The 'TODO' file, also in the distribution directory, lists known bugs,
planned enhancements and possible new features for future versions.
The 'INSTALL' file covers the configuration and installation process.
The rest of the documentation is distributed in Pod and HTML formats.
The Pod pages are installed when you 'make install' and can be viewed
using 'perldoc', e.g.
perldoc Template
IMPORTANT NOTE: if you've had a previous verion of the Template
Toolkit installed (e.g. version 2.00) then perldoc might be displaying
an old version of the Pod documentation. This is because previous
versions distributed the Pod in separate .pod files but it's now
living back inside the relevant .pm files. Alas, perldoc selects the
older .pod files in preference over the newer .pm. The only solution
at present is to manually delete all the older .pod files in the
Template part of your Perl installation directory. Of course, if I had
thought of this back when I decided to move all the .pod back into the
.pm files...
If you're using a Unix based system then the pages should also be
converted to manpages suring the 'make install'. Thus, you can also:
man Template
(the man pages shouldn't have any problems relating to older versions)
The HTML documentation and the means to rebuild it can be found in the
'docs' sub-directory of the installation root. If you opted to
have it built at installation time, then there should be an 'html'
directory within it containing the generated HTML built from the
source templates.
The documentation is now split into several sections. The 'Template'
page is now much shorter, containing information relating to the
specifics of using the Template module, and a brief summary of
everything else. Information relating more generally to the Template
Toolkit, features, syntax of the template language, plugins and so
forth, has been split up into a number of Template::Manual::* pages.
Template::Manual provides the index for the manual.
perldoc Template::Manual
Individual sections can be viewed as, for example,
perldoc Template::Manual::Syntax
perldoc Template::Manual::Directives
perldoc Template::Manual::Plugins
The Template::Tutorial provides an index to the tutorial documents.
There are currently 2 tutorials, on generating web content, and on
creating and using data files.
perldoc Template::Tutorial
perldoc Template::Tutorial::Web
perldoc Template::Tutorial::Datafile
The new template libraries distributed with the Template Toolkit have
some documentation, but be warned that it is rather spartan at
present. If you're interested in using these libraries then the
examples (in the 'examples' sub-directory) are likely to be much more
useful until the documentation catches up.
perldoc Template::Library::HTML
perldoc Template::Library::Splash
Each of the various modules that comprise the Template Toolkit has its
own associated documention. The 'Template::Modules' manpage lists
these modules along with a brief description of their functions.
perldoc Template::Modules
See the individual pages for further detail:
perldoc Template::Context
perldoc Template::Parser
perldoc Template::Provider
If you're interested in the internals of the Template Toolkit and want
to know more about how it all works, then you might like to have a look
at the following:
perldoc Template::Manual::Internals
This document also contains important information for people wishing
to hack on the Template Toolkit.
The final bit of good news is that there is now a FAQ for the Template
Toolkit.
perldoc Template::FAQ
It's now got a few question in it, and better still, some answers!
Further contributions welcome.
Most of the documentation is stable and reliable. Where it's not then
it's usually marked as such. In particular, the documentation for the
template libraries (Template::Library::*), the FAQ (Template::FAQ) and
internals (Template::Internals) are all under construction.
SUPPORT
-------
The Template Toolkit mailing list provides a forum for discussing
issues relating to the use and abuse of the Template Toolkit. There
are a number of knowledgeable and helpful individuals who frequent the
list (including the author) who can often offer help or suggestions.
Please respect their time and patience by checking the documentation
and/or mailing list archives before asking questions that may already
have been answered.
To subscribe to the mailing list, send an email to:
[email protected]
with the message 'subscribe' in the body. You can also use the web
interface to subscribe or browse the archives:
http://www.template-toolkit.org/mailman/listinfo/templates
A low-volume, moderated mailing list exists for announcements about new
releases of the Template Toolkit and related products. To subscribe, send
an email to:
[email protected]
with the message 'subscribe' in the body. A web interface also exists
for subscription and browsing the archives:
http://www.template-toolkit.org/mailman/listinfo/templates-announce
For information about commercial support and consultancy for the Template
Toolkit, please contact the author.
VERSION COMPATABILITY
---------------------
In terms of the template language and features available, versions
2.01 through to 2.14 should be fully backwardly compatible with
version 2.00.
Version 2.00 is backwardly compatible with version 1 in all but a few
minor areas. The 'Changes' file details all the visible changes
between version 1 and version 2, including deltas between alphas and
betas. Within this file there is a 'Gotchas' section which lists the
changes that may affect backwards compatability with existing template
files. These are listed in brief below. Please consult the 'Changes'
file for full details.
* All directive keywords should now be written in UPPER CASE (by default)
to avoid conflict with reserved words. The CASE option is now called
ANYCASE and can be set true to permit lower case directive keywords.
* CATCH blocks must now be scoped with a TRY block.
* The ERROR directive is no longer supported. THROW an exception instead
or use the 'stderr' filter if you really must write to STDERR and nowhere
else.
* The ERROR configuration option (previously used to customise the ERROR
directive) is now used to specify handling for uncaught exceptions.
* Version 1 allowed (but didn't recommend) the use of a leading '$' on a
variable name (i.e. like Perl) which was silently ignored. Version 2
no longer ignores them and treats it as a variable
pre-interpolation. Most of the time you *don't* want to do this, so
don't add a leading '$' unless you know what you're doing. You can set
V1DOLLAR => 1 to revert to the old behaviour if you really have to.
* The default tag style for version 1 accepted [% ... %] or %% ... %%
(the latter for backwards compatability with Text::MetaText, the
predecessor to TT). Version 2 now only accepts [% ... %] by default.
You can set TAG_STYLE => 'template1' to get both.
* The 'into' filter is obsolete. You can now simply assign the output
of a directive into a variable, e.g. [% foo = INCLUDE header %]
* The IMPORT directive has been removed and replaced by an 'import'
hash method.
Most of the significant changes are in the internals of the Template
Toolkit. If you have any v1 code that delves into the individual
modules and tinkers with their guts then will need to check the
'Changes' file very carefully indeed and re-evaluate your code in the
light of the new architecture. The internals are cleaner and better
organised making extension code much easier to write. The downside is
that some of the old and crusty ways you previously had to do things
may no longer work.
AUTHOR
------
The Template Toolkit was written by Andy Wardley <[email protected]> with
the invaluable assistance and contributions from many other people.
See Template::Manual::Credits for details.
COPYRIGHT
---------
Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
This is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
