NAME
Template Toolkit - a Perl toolkit for template processing.
OBTAINING AND INSTALLING THE TEMPLATE TOOLKIT
The Template Toolkit module bundle is available from CPAN as:
/authors/id/ABW/Template-Toolkit-1.02.tar.gz
Unpack the archive to create an installation directory.
Something like this:
zcat Template-Toolkit-1.02.tar.gz | tar xvf -
'cd' into that directory, make, test and install the modules:
cd Template-Toolkit-1.02
perl Makefile.PL
make
make test
make install
NOTE: on Win32 systems, Microsoft's 'nmake' appears to be a
suitable replacement for 'make'.
The 'make install' will install the module on your system. You
may need administrator privileges to perform this task. If you
install the module in a local directory (for example, by
executing "perl Makefile.PL LIB=~/lib" in the above - see
`perldoc MakeMaker' for full details), you will need to ensure
that the PERL5LIB environment variable is set to include the
location, or add a line to your scripts explicitly naming the
library location:
use lib '/local/path/to/lib';
PREREQUISITES
The Template Toolkit requires Perl 5.005.
The ttree script uses the AppConfig module (version 1.52+) for
managing configuration information. This is available from CPAN
as
/modules/by-module/AppConfig/AppConfig-<version>.tar.gz
/authors/id/ABW/AppConfig-<version>.tar.gz
TOOLKIT CONTENTS
The Template Toolkit comprises of a number of Perl modules and
two additional scripts.
The Template module acts as a general interface to the toolkit
and contains comprehensive documentation describing the toolkit,
its usage and further sources of reference.
perldoc Template
The tpage and ttree scripts are useful utilities for processing
template documents, or entire content trees, respectively.
perldoc tpage
perldoc ttree
OVERVIEW
The Template Toolkit is a collection of Perl modules which
collectively implement a 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 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 *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 (i.e. Perl, C, C++, etc) and
then loaded, used and re-used as required.
This gives you the facility to add any programmable
functionality you require but without having to write the code
directly into the document. In other words, it promotes the
separation of application code (the *implementation*) from the
user interface (the *presentation*). It tries to keep templates
clutter-free, concentrating on what the document looks like, and
hides the implementation specific details of how the various
items of content are stored, retrieved or calculated.
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 *separately*
from the template documents. This is a key feature of the
Template Toolkit with the emphasis being on moving code *out* of
documents, rather than moving it *in*. 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.
This isn't the only way to do it. There are 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. The Template Toolkit has an option (EVAL_PERL -
disabled by default) to allow Perl code to be embedded into
special 'PERL' sections which are then evaluated when the
template is processed. These Perl code fragments have full
access to the Template Toolkit interface and may read or update
variables, process other template files, load plugins, and so
on.
If you prefer the embedded Perl approach and have a need to get
some functionality into a document with the minimum fuss, setup
time and effort, then you might want to consider using a
dedicated embedded Perl processor. In those cases, Mark-Jason
Dominus' Text::Template module, available from CPAN, comes
highly recommended.
In many ways, this is like CGI scripting in reverse. Instead of
embedding HTML within the Perl script, you are embeddding Perl
within the HTML document. The Template Toolkit tries to better
separate the two in attempt to create a more structured approach
to constructing dynamic content. There's a slight "startup" cost
to using this approach because, like life in general, it often
takes a little longer to get yourself properly organised. The
payoff comes in terms of scalability and subsequent ease of re-
use - the more you add, the more you benefit from having
structure. 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.
So rather than emphasing the raw programming power embeddable
within any *single document*, it focuses on tools and techniques
to help better partition and subsequently re-integrate the
different components that constitute the *many* documents in a
system. It offers speed and simplicity in constructing document
systems and delegates "real programming" to a more powerful,
general purpose language - Perl.
There are many benefits to be gained from keeping Perl code
separate from template documents. You could, for example, write
a single web application with a dozen different sets of
templates to represent alternate user interfaces. These would
represent multiple "views" on the same underlying "model" and
might 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 localised interface, and so on. On the
other side of the same coin, you could change your underlying
code to implement a faster algorithm or more efficient storage
method, but you wouldn't have to change the template files. They
still get their "content" from the same "place" and don't need
to concern themselves with what happens inside each black box.
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.
It is worth noting that there is nothing to stop you from
adopting a well structured approach to content construction
using Text::Template or one of the other fine template
processing modules available. Many people do indeed develop
content using these tools in such a way as to promote
reusability and maintainability every bit as much as the
Template Toolkit does. The benefit of using the toolkit is that
much of this is done for you. You get to reap the benefits of
template caching (resulting in fast runtime processing),
automatic error detection and handling, variable localisation
and namespacing, dynamic loading of external modules, and so on,
without having to code it yourself or even worry about the
specifics of implementation. The details are hidden away, the
directive syntax is simplified and you can get a lot done very
quickly with the minimum of fuss. The benefit of the
Text::Template approach is that you have complete control over
exactly what happens and you can be as structured or as
unstructured as the task in hand demands.
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.
FEATURES
- Fast, flexible, generic and open template processing system.
- Simple template "mini-language" provides functionality to
manipulate variables (GET/SET/DEFAULT), process other
template component files (INCLUDE/PROCESS), iterate through
various values (FOREACH), conditional branching
(IF/UNLESS/ELSIF/ELSE), error handling (CATCH, THROW), flow
control (BREAK, RETURN, STOP), loading "plugin" code (USE)
and post-processing (FILTER). Optional PERL sections
(disabled by default - see EVAL_PERL option) allow Perl code
to be directly embedded with full interface to the Template
Toolkit interface and variables.
- More complex application code can be developed in Perl (or C,
C++, etc) and maintained separately as "plugin" code.
Template processor binds user code to variables to provide
access to application functionality from templates.
- This natural extensibility promotes the separation of the
application (implementation) from the interface
(presentation). Template documents remain simple and
focussed on rendering the interface. Application code can be
made more generic by concentrating on what the application
does, not what it looks like. If and when you really need to
embed Perl code, you can.
- Ideally suited, but not limited to, web content generation. The
'tpage' and 'ttree' scripts help manage and build entire
directory trees from source templates, library files and
plugin components. The Template module can be used directly
from CGI scripts, Apache/mod_perl handlers, or any other
Perl code as a simple front-end to the Toolkit. Plugin
modules are available for interfacing to CGI, DBI, etc.
- Template documents parsed by a fast LALR(1) parser which is
generated from a YACC-like grammar. Parse::Yapp is used to
compile the grammar. Parser grammar can be modified and re-
compiled to create custom template languages.
- Parsed template documents are compiled to an intermediate form
and cache. They can subsequently be rendered repeatedly in
minimal time.
- Stash object manages references to complex external code and
data and provides a simple template interface via bound
variables.
- Variables may be partitioned into nested namespaces.
- Custom error handling and recovery mechanisms implemented as
basic exception handling. Users can define template blocks
to be processed automatically when errors occur and define
the subsequent course of action.
- Iterator objects can be created to handle complex set iteration.
This is handled transparently by the FOREACH directive.
- Provides an extensible framework for other template languages,
processors and applications, servers, etc.
- Template language is largely independent (theoretically at
least) of the implementation language, platform, operating
system, etc.
- Extensive documentation, test suite, examples, etc.
- `use strict' and `-w' safe. Y2K compliant (no dates used or
stored).
- Ongoing development and maintenance is part of a general
research program into web-relevant software tools and
techniques at Canon Research Centre Europe Ltd.
- Fully open source code. Contributions, collaborations,
suggestions and other feedback welcome.
- Mailing list: send email to majordomo@cre.canon.co.uk containing
the text "subscribe templates".
EXAMPLE
#!/path/to/perl -w
use strict;
use Template;
# create a template processor
my $tproc = Template->new({
INCLUDE_PATH => '/user/abw/templates', # template search path
});
# define variables for use in templates
my $vars = {
'animal' => 'cat',
'place' => 'mat',
'list' => [ 'foo', 'bar', 'baz' ],
'user' => {
'name' => 'Me, Myself, I',
'email' => 'me@here.com'
},
};
# process a template file, output defaults to STDOUT
$tproc->process('myfile', $vars)
|| die $tproc->error(), "\n";
myfile:
[% INCLUDE header
title = 'Hello World!'
%]
The [% animal %] sat on the [% place %]
<a href="mailto:[% user.email %]">[% user.name %]</a>
<ul>
[% FOREACH item = list %]
<li>[% item %]
[% END %]
</ul>
Output:
<!-- ...output from processing 'header' template... -->
The cat sat on the mat
<a href="mailto:me@here.com">Me, Myself, I</a>
<ul>
<li>foo
<li>bar
<li>baz
</ul>
Apache/mod_perl handler:
sub handler {
my $r = shift;
my $file = $r->path_info(); # or some other mapping
my $template = Template->new({
INCLUDE_PATH => '/where/to/look/for/templates',
OUTPUT => $r,
});
$template->process($file) || do {
$r->log_reason($template->error());
return SERVER_ERROR;
};
return OK;
}
MAILING LIST
A mailing list exists for up-to-date information on the Template
Toolkit and for following and contributing to the development
process. Send email to majordomo@cre.canon.co.uk with the
following message in the body:
subscribe templates
AUTHOR
Andy Wardley <abw@cre.canon.co.uk>
http://www.kfs.org/~abw/
http://www.cre.canon.co.uk/perl
VERSION
This is version 1.02 of the Template Toolkit.
Please consult the Changes file for information about visible
changes in the Template Toolkit between releases. The TODO file
contains details of known bugs, planned enhancements, features,
fixes, etc.
The latest version of the Template Toolkit can be downloaded
from any CPAN site:
/authors/id/ABW/Template-Toolkit-<version>.tar.gz
Information regarding interim and development versions is posted
to the templates mailing list.
COPYRIGHT
Copyright (C) 1996-1999 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-1999 Canon Research Centre Europe Ltd.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.