This tutorial document provides a introduction to the Template Toolkit and demonstrates some of the typical ways it may be used for generating web content. It covers the generation of static pages from templates using the tpage and ttree scripts and then goes on to show dynamic content generation using CGI scripts and Apache/mod_perl handlers.
Various features of the Template Toolkit are introduced and described briefly and explained by use of example. For further information, see Template, Template::Manual and the various sections within it. e.g
perldoc Template # Template.pm module usage perldoc Template::Manual # index to manual perldoc Template::Manual::Config # e.g. configuration options
The documentation is also available in HTML format to read online, or download from the Template Toolkit web site:
http://template-toolkit.org/docs/
The Template Toolkit is a set of Perl modules which collectively implement a template processing system.
A template is a text document with special markup tags embedded in it. By
default, the Template Toolkit uses '[%' and
'%]' to denote the start and end of a tag. Here's an
example:
[% INCLUDE header %] People of [% planet %], your attention please. This is [% captain %] of the Galactic Hyperspace Planning Council. As you will no doubt be aware, the plans for development of the outlying regions of the Galaxy require the building of a hyperspatial express route through your star system, and regrettably your planet is one of those scheduled for destruction. The process will take slightly less than [% time %]. Thank you. [% INCLUDE footer %]
Tags can contain simple variables (like planet and
captain) and more complex directives that start with
an upper case keyword (like INCLUDE). A directive is an
instruction that tells the template processor to perform some action,
like processing another template (header and
footer in this example) and inserting the output into the
current template. In fact, the simple variables we mentioned are actually
GET directives, but the GET keyword is
optional.
People of [% planet %], your attention please. # short form People of [% GET planet %], your attention please. # long form
Other directives include SET to set a variable value (the
SET keyword is also optional), FOREACH to
iterate through a list of values, and IF,
UNLESS, ELSIF and ELSE to declare
conditional blocks.
The Template Toolkit processes all text files equally, regardless of what kind of content they contain. So you can use TT to generate HTML, XML, CSS, Javascript, Perl, RTF, LaTeX, or any other text-based format. In this tutorial, however, we'll be concentrating on generating HTML for web pages.
Here's an example of a template used to generate an HTML document.
[% INCLUDE header title = 'This is an HTML example'; pages = [ { url = 'http://foo.org' title = 'The Foo Organisation' } { url = 'http://bar.org' title = 'The Bar Organisation' } ] %] <h1>Some Interesting Links</h1> <ul> [% FOREACH page IN pages %] <li><a href="[% page.url %]">[% page.title %]</a> [% END %] </ul> [% INCLUDE footer %]
This example shows how the INCLUDE directive is used to load
and process separate 'header' and 'footer'
template files, including the output in the current document. These files
might look something like this:
header:
<html>
<head>
<title>[% title %]</title>
</head>
<body>
footer:
<div class="copyright">
© Copyright 2007 Arthur Dent
</div>
</body>
</html>
The example also uses the FOREACH directive to iterate
through the 'pages' list to build a table of links. In this
example, we have defined this list within the template to contain a
number of hash references, each containing a 'url' and
'title' member. The FOREACH directive iterates
through the list, aliasing 'page' to each item (in this
case, hash array references). The [% page.url %] and
[% page.title %] directives then access the individual
values in the hash arrays and insert them into the document.
Having created a template file we can now process it to generate some real output. The quickest and easiest way to do this is to use the tpage script. This is provided as part of the Template Toolkit and should be installed in your usual Perl bin directory.
Assuming you saved your template file as example.html, you would run the command:
$ tpage example.html
This will process the template file, sending the output to
STDOUT (i.e. whizzing past you on the screen). You may want
to redirect the output to a file but be careful not to specify the same
name as the template file, or you'll overwrite it. You may want to use
one prefix for your templates (e.g. '.tt') and another (e.g.
'.html') for the output files.
$ tpage example.tt > example.html
Or you can redirect the output to another directory. e.g.
$ tpage templates/example.tt > html/example.html
The output generated would look like this:
<html>
<head>
<title>This is an HTML example</title>
</head>
<body>
<h1>Some Interesting Links</h1>
<ul>
<li><a href="http://foo.org">The Foo Organsiation</a>
<li><a href="http://bar.org">The Bar Organsiation</a>
</ul>
<div class="copyright">
© Copyright 2007 Arthur Dent
</div>
</body>
</html>
The header and footer
template files have been included (assuming you created them and they're
in the current directory) and the link data has been built into an HTML
list.
The tpage script gives you a simple and easy way to process a single template without having to write any Perl code. The ttree:Template::Tools::ttree script, also distributed as part of the Template Toolkit, provides a more flexible way to process a number of template documents in one go.
The first time you run the script, it will ask you if it should create a
configuration file (.ttreerc) in your home
directory. Answer y to have it create the file.
The ttree:Template::Tools::ttree documentation describes how you can change the location of this file and also explains the syntax and meaning of the various options in the file. Comments are written to the sample configuration file which should also help.
In brief, the configuration file describes the directories in which
template files are to be found (src), where the
corresponding output should be written to (dest), and any
other directories (lib) that may contain template files that
you plan to INCLUDE into your source documents. You can also
specify processing options (such as verbose and
recurse) and provide regular expression to match files that
you don't want to process (ignore, accept)>
or should be copied instead of being processed as templates
(copy).
An example .ttreerc file is shown here:
$HOME/.ttreerc:
verbose recurse # this is where I keep other ttree config files cfg = ~/.ttree src = ~/websrc/src lib = ~/websrc/lib dest = ~/public_html/test ignore = \b(CVS|RCS)\b ignore = ^#
You can create many different configuration files and store them in the
directory specified in the cfg option, shown above. You then
add the -f filename option to ttree to have it
read that file.
When you run the script, it compares all the files in the
src directory (including those in sub-directories if the
recurse option is set), with those in the dest
directory. If the destination file doesn't exist or has an earlier
modification time than the corresponding source file, then the source
will be processed with the output written to the destination file. The
-a option forces all files to be processed, regardless of
modification times.
The script doesn't process any of the files in the
lib directory, but it does add it to the
INCLUDE_PATH for the template processor so that it can
locate these files via an INCLUDE, PROCESS or
WRAPPER directive. Thus, the lib directory is
an excellent place to keep template elements such as header, footers,
etc., that aren't complete documents in their own right.
You can also specify various Template Toolkit options from the
configuration file. Consult the ttree documentation and help
summary (ttree -h) for full details. e.g.
$HOME/.ttreerc:
pre_process = config interpolate post_chomp
The pre_process option allows you to specify a template file
which should be processed before each file. Unsurprisingly, there's also
a post_process option to add a template after each file. In
the fragment above, we have specified that the config
template should be used as a prefix template. We can create this file in
the lib directory and use it to define some common
variables, including those web page links we defined earlier and might
want to re-use in other templates. We could also include an HTML header,
title, or menu bar in this file which would then be prepended to each and
every template file, but for now we'll keep all that in a separate
header file.
$lib/config:
[% root = '~/abw'
home = "$root/index.html"
images = "$root/images"
email = 'abw@wardley.org'
graphics = 1
webpages = [
{ url => 'http://foo.org', title => 'The Foo Organsiation' }
{ url => 'http://bar.org', title => 'The Bar Organsiation' }
]
%]
Assuming you've created or copied the header and
footer files from the earlier example into your
lib directory, you can now start to create web pages like
the following in your src directory and process them with
ttree.
$src/newpage.html:
[% INCLUDE header title = 'Another Template Toolkit Test Page' %] <a href="[% home %]">Home</a> <a href="mailto:[% email %]">Email</a> [% IF graphics %] <img src="[% images %]/logo.gif" align=right width=60 height=40> [% END %] [% INCLUDE footer %]
Here we've shown how pre-defined variables can be used as flags to enable
certain feature (e.g. graphics) and to specify common items
such as an email address and URL's for the home page, images directory
and so on. This approach allows you to define these values once so that
they're consistent across all pages and can easily be changed to new
values.
When you run ttree, you should see output
similar to the following (assuming you have the verbose flag set).
ttree 2.9 (Template Toolkit version 2.20)
Source: /home/abw/websrc/src
Destination: /home/abw/public_html/test
Include Path: [ /home/abw/websrc/lib ]
Ignore: [ \b(CVS|RCS)\b, ^# ]
Copy: [ ]
Accept: [ * ]
+ newpage.html
The + in front of the newpage.html filename
shows that the file was processed, with the output being written to the
destination directory. If you run the same command again, you'll see the
following line displayed instead showing a - and giving a
reason why the file wasn't processed.
- newpage.html (not modified)
It has detected a newpage.html in the destination directory
which is more recent than that in the source directory and so hasn't
bothered to waste time re-processing it. To force all files to be
processed, use the -a option. You can also specify one or
more filenames as command line arguments to ttree:
tpage newpage.html
This is what the destination page looks like.
$dest/newpage.html:
<html>
<head>
<title>Another Template Toolkit Test Page</title>
</head>
<body>
<a href="~/abw/index.html">Home</a>
<a href="mailto:abw@wardley.org">Email me</a>
<img src="~/abw/images/logo.gif" align=right width=60 height=40>
<div class="copyright">
© Copyright 2007 Arthur Dent
</div>
</body>
</html>
You can add as many documents as you like to the src
directory and ttree will apply the same process to them all.
In this way, it is possible to build an entire tree of static content for
a web site with a single command. The added benefit is that you can be
assured of consistency in links, header style, or whatever else you
choose to implement in terms of common templates elements or variables.
The Template module provides
a simple front-end to the Template Toolkit for use in CGI scripts and
Apache/mod_perl handlers. Simply use the Template module, create an object instance
with the new() method and then call the process() method on the object, passing the
name of the template file as a parameter. The second parameter passed is
a reference to a hash array of variables that we want made available to
the template:
#!/usr/bin/perl
use strict;
use warnings;
use Template;
my $file = 'src/greeting.html';
my $vars = {
message => "Hello World\n"
};
my $template = Template->new();
$template->process($file, $vars)
|| die "Template process failed: ", $template->error(), "\n";
So that our scripts will work with the same template files as our earlier examples, we'll can add some configuration options to the constructor to tell it about our environment:
my $template->new({
# where to find template files
INCLUDE_PATH => ['/home/abw/websrc/src', '/home/abw/websrc/lib'],
# pre-process lib/config to define any extra values
PRE_PROCESS => 'config',
});
Note that here we specify the config file as a
PRE_PROCESS option. This means that the templates we process
can use the same global variables defined earlier for our static pages.
We don't have to replicate their definitions in this script. However, we
can supply additional data and functionality specific to this script via
the hash of variables that we pass to the process() method.
These entries in this hash may contain simple text or other values, references to lists, others hashes, sub-routines or objects. The Template Toolkit will automatically apply the correct procedure to access these different types when you use the variables in a template.
Here's a more detailed example to look over. Amongst the different
template variables we define in $vars, we create a reference
to a CGI object and a
get_user_projects() sub-routine.
#!/usr/bin/perl
use strict;
use warnings;
use Template;
use CGI;
$| = 1;
print "Content-type: text/html\n\n";
my $file = 'userinfo.html';
my $vars = {
'version' => 3.14,
'days' => [ qw( mon tue wed thu fri sat sun ) ],
'worklist' => \&get_user_projects,
'cgi' => CGI->new(),
'me' => {
'id' => 'abw',
'name' => 'Andy Wardley',
},
};
sub get_user_projects {
my $user = shift;
my @projects = ... # do something to retrieve data
return \@projects;
}
my $template = Template->new({
INCLUDE_PATH => '/home/abw/websrc/src:/home/abw/websrc/lib',
PRE_PROCESS => 'config',
});
$template->process($file, $vars)
|| die $template->error();
Here's a sample template file that we might create to build the output for this script.
$src/userinfo.html:
[% INCLUDE header title = 'Template Toolkit CGI Test' %] <a href="mailto:[% email %]">Email [% me.name %]</a> <p>This is version [% version %]</p> <h3>Projects</h3> <ul> [% FOREACH project IN worklist(me.id) %] <li> <a href="[% project.url %]">[% project.name %]</a> [% END %] </ul> [% INCLUDE footer %]
This example shows how we've separated the Perl implementation (code) from the presentation (HTML). This not only makes them easier to maintain in isolation, but also allows the re-use of existing template elements such as headers and footers, etc. By using template to create the output of your CGI scripts, you can give them the same consistency as your static pages built via ttree or other means.
Furthermore, we can modify our script so that it processes any one of a number of different templates based on some condition. A CGI script to maintain a user database, for example, might process one template to provide an empty form for new users, the same form with some default values set for updating an existing user record, a third template for listing all users in the system, and so on. You can use any Perl functionality you care to write to implement the logic of your application and then choose one or other template to generate the desired output for the application state.
NOTE: the Apache::Template module is available from CPAN and provides a simple and easy to use Apache/mod_perl interface to the Template Toolkit. Although basic, it implements most, if not all of what is described below, and it avoids the need to write your own handler. However, in many cases, you'll want to write your own handler to customise processing for your own need, and this section will show you how to get started.
The Template module can be
used from an Apache/mod_perl handler. Here's an example of a typical
Apache httpd.conf file:
PerlModule CGI;
PerlModule Template
PerlModule MyOrg::Apache::User
PerlSetVar websrc_root /home/abw/websrc
<Location /user/bin>
SetHandler perl-script
PerlHandler MyOrg::Apache::User
</Location>
This defines a location called /user/bin to which all
requests will be forwarded to the handler() method of the
MyOrg::Apache::User module. That module might look something
like this:
package MyOrg::Apache::User;
use strict;
use Apache::Constants qw( :common );
use Template qw( :template );
use CGI;
our $VERSION = 1.59;
sub handler {
my $r = shift;
my $websrc = $r->dir_config('websrc_root')
or return fail($r, SERVER_ERROR,
"'websrc_root' not specified");
my $template = Template->new({
INCLUDE_PATH => "$websrc/src/user:$websrc/lib",
PRE_PROCESS => 'config',
OUTPUT => $r, # direct output to Apache request
});
my $params = {
uri => $r->uri,
cgi => CGI->new,
};
# use the path_info to determine which template file to process
my $file = $r->path_info;
$file =~ s[^/][];
$r->content_type('text/html');
$r->send_http_header;
$template->process($file, $params)
|| return fail($r, SERVER_ERROR, $template->error());
return OK;
}
sub fail {
my ($r, $status, $message) = @_;
$r->log_reason($message, $r->filename);
return $status;
}
The handler accepts the request and uses it to determine the
websrc_root value from the config file. This is then used to
define an INCLUDE_PATH for a new Template object. The URI is extracted from
the request and a CGI object is
created. These are both defined as template variables.
The name of the template file itself is taken from the
PATH_INFO element of the request. In this case, it would
comprise the part of the URL coming after /user/bin, e.g for
/user/bin/edit, the template file would be edit
located in $websrc/src/user. The headers are sent and the
template file is processed. All output is sent directly to the
print() method of the Apache request object.
As we've already shown, it is possible to bind Perl data and functions to
template variables when creating dynamic content via a CGI script or
Apache/mod_perl process. The Template Toolkit also supports a plugin
interface which allows you define such additional data and/or
functionality in a separate module and then load and use it as required
with the USE directive.
The main benefit to this approach is that you can load the extension into
any template document, even those that are processed "statically" by
tpage or ttree. You don't need to write
a Perl wrapper to explicitly load the module and make it available via
the stash.
Let's demonstrate this principle using the DBI plugin
written by Simon Matthews (available from CPAN). You can create this
template in your src directory and process it using
ttree to see the results. Of course, this example relies on
the existence of the appropriate SQL database but you should be able to
adapt it to your own resources, or at least use it as a demonstrative
example of what's possible.
[% INCLUDE header title = 'User Info' %] [% USE DBI('dbi:mSQL:mydbname') %] <table border=0 width="100%"> <tr> <th>User ID</th> <th>Name</th> <th>Email</th> </tr> [% FOREACH user IN DBI.query('SELECT * FROM user ORDER BY id') %] <tr> <td>[% user.id %]</td> <td>[% user.name %]</td> <td>[% user.email %]</td> </tr> [% END %] </table> [% INCLUDE footer %]
A plugin is simply a Perl module in a known location and conforming to a known standard such that the Template Toolkit can find and load it automatically. You can create your own plugin by inheriting from the Template::Plugin module.
Here's an example which defines some data items (foo and
people) and also an object method (bar). We'll
call the plugin FooBar for want of a better name and create
it in the MyOrg::Template::Plugin::FooBar package. We've
added a MyOrg to the regular
Template::Plugin::* package to avoid any conflict with
existing plugins.
package MyOrg::Template::Plugin::FooBar;
use base 'Template::Plugin'
our $VERSION = 1.23;
sub new {
my ($class, $context, @params) = @_;
bless {
_CONTEXT => $context,
foo => 25,
people => [ 'tom', 'dick', 'harry' ],
}, $class;
}
sub bar {
my ($self, @params) = @_;
# ...do something...
return $some_value;
}
The plugin constructor new() receives the class name as the
first parameter, as is usual in Perl, followed by a reference to
something called a Template::Context object. You don't need to worry too much about
this at the moment, other than to know that it's the main processing
object for the Template Toolkit. It provides access to the functionality
of the processor and some plugins may need to communicate with it. We
don't at this stage, but we'll save the reference anyway in the
_CONTEXT member. The leading underscore is a convention
which indicates that this item is private and the Template Toolkit won't
attempt to access this member. The other members defined,
foo and people are regular data items which
will be made available to templates using this plugin. Following the
context reference are passed any additional parameters specified with the
USE directive, such as the data source parameter,
dbi:mSQL:mydbname, that we used in the earlier DBI example.
If you don't or can't install it to the regular place for your Perl
modules (perhaps because you don't have the required privileges) then you
can set the PERL5LIB environment variable to specify another location. If
you're using ttree then you can add the following line to
your configuration file instead.
$HOME/.ttreerc:
perl5lib = /path/to/modules
One further configuration item must be added to inform the toolkit of the new package name we have adopted for our plugins:
$HOME/.ttreerc:
plugin_base = 'MyOrg::Template::Plugin'
If you're writing Perl code to control the Template modules directly, then this value can be passed as a configuration parameter when you create the module.
use Template;
my $template = Template->new({
PLUGIN_BASE => 'MyOrg::Template::Plugin'
});
Now we can create a template which uses this plugin:
[% INCLUDE header title = 'FooBar Plugin Test' %] [% USE FooBar %] Some values available from this plugin: [% FooBar.foo %] [% FooBar.bar %] The users defined in the 'people' list: [% FOREACH uid = FooBar.people %] * [% uid %] [% END %] [% INCLUDE footer %]
The foo, bar, and people items of
the FooBar plugin are automatically resolved to the appropriate data
items or method calls on the underlying object.
Using this approach, it is possible to create application functionality in a single module which can then be loaded and used on demand in any template. The simple interface between template directives and plugin objects allows complex, dynamic content to be built from a few simple template documents without knowing anything about the underlying implementation.
Andy Wardley <abw@wardley.org> http://wardley.org/
