Template Toolkit - a fast, flexible and extensible template processing system
use Template;
# some useful options (see below for full list)
my $config = {
INCLUDE_PATH => '/search/path', # or list ref
INTERPOLATE => 1, # expand "$var" in plain text
POST_CHOMP => 1, # cleanup whitespace
PRE_PROCESS => 'header', # prefix each template
EVAL_PERL => 1, # evaluate Perl code blocks
};
# create Template object my $template = Template->new($config);
# define template variables for replacement
my $vars = {
var1 => $value,
var2 => \%hash,
var3 => \@list,
var4 => \&code,
var5 => $object,
};
# specify input filename, or file handle, text reference, etc. my $input = 'myfile.html';
# process input template, substituting variables
$template->process($input, $vars)
|| die $template->error();
GET - evaluate and print a variable or value
[% GET variable %] # 'GET' keyword is optional
[% variable %]
[% hash.key %]
[% list.n %]
[% code(args) %]
[% obj.meth(args) %]
[% "value: $var" %]
CALL - as above without printing result (e.g. call code)
[% CALL variable %]
SET - assign a value to a variable
[% SET variable = value %] # 'SET' also optional
[% variable = other_variable
variable = 'literal text @ $100'
variable = "interpolated text: $var"
list = [ val, val, val, val, ... ]
list = [ val..val ]
hash = { var => val, var => val, ... }
%]
DEFAULT - as SET above, if variable(s) not set
[% DEFAULT variable = value %]
INSERT - insert a file without any processing
[% INSERT legalese.txt %]
INCLUDE - process another template file/block, localising vars
[% INCLUDE template %]
[% INCLUDE template var = val, ... %]
PROCESS - as above, without localising variables
[% PROCESS template %]
[% PROCESS template var = val, ... %]
WRAPPER - process a template to enclose specified block
[% WRAPPER template %]
content
[% END %]
BLOCK - define a named template block for INCLUDE, etc.
[% BLOCK template %]
content
[% END %]
FOREACH - repeat block for each value in a list
[% FOREACH variable = [ val, val, val ] %]
[% FOREACH variable = list %]
[% FOREACH list %]
content...
[% variable %]
[% END %]
WHILE - iterate while condition is true
[% WHILE condition %]
content
[% END %]
IF / UNLESS / ELSIF / ELSE
- process block if condition is true/false.
[% IF condition %]
content
[% ELSIF condition %]
content
[% ELSE %]
content
[% END %]
[% UNLESS condition %]
content
[% # ELSIF/ELSE as per IF, above %]
content
[% END %]
SWITCH / CASE
- multi-way switch/case statement
[% SWITCH variable %]
[% CASE val1 %]
content
[% CASE [ val2, val3 ] %]
content
[% CASE %] # or [% CASE DEFAULT %]
content
[% END %]
MACRO - create a named macro for some other directive or block
[% MACRO name <directive> %]
[% MACRO name(arg1, arg2) <directive> %]
...
[% name %]
[% name(val1, val2) %]
FILTER - post-process block through a filter
[% FILTER name %]
[% FILTER name( params ) %]
[% FILTER alias = name( params ) %]
content
[% END %]
USE - load a "plugin" module (or any regular Perl module
with LOAD_PERL option)
[% USE name %]
[% USE name( params ) %]
[% USE var = name( params ) %]
...
[% name.method %]
[% var.method %]
PERL / RAWPERL
- evaluate blocks of Perl code (requires EVAL_PERL option)
[% PERL %]
# perl code goes here
$stash->set('foo', 10);
print "set 'foo' to ", $stash->get('foo'), "\n";
print $context->include('footer', { var => $val });
[% END %]
[% RAWPERL %]
# raw perl code goes here, no magic but fast.
$output .= 'some output';
[% END %]
TRY / THROW / CATCH / FINAL
- exception handling
[% TRY %]
content
[% THROW type info %]
[% CATCH type %]
catch content
[% error.type %] [% error.info %]
[% CATCH %] # or [% CATCH DEFAULT %]
content
[% FINAL %]
this block is always processed
[% END %]
NEXT - next item in a FOREACH/WHILE loop
[% NEXT %]
LAST - break out of FOREACH/WHILE loop
[% LAST %]
RETURN - stop processing current template
[% RETURN %]
STOP - stop processing all templates and return to caller
[% STOP %]
COMMENT - ignored and deleted
[% # this is a comment to the end of line
foo = 'bar'
%]
[%# placing the '#' immediately inside the directive
tag comments out the entire directive
%]
TAGS - define new tag style or characters (default: [% %])
[% TAGS html %]
[% TAGS <!-- --> %]
This is version 2.00-rc2 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 in the directory:
/modules/by-module/Template/
For a list of CPAN sites, see:
http://www.cpan.org/
Information regarding interim and development versions is posted to the templates mailing list and available from the Template Toolkit web site:
http://www.template-toolkit.org/
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 kind of text documents. This POD documentation is all generated using the Template Toolkit batch mode utility ttree, for example.
At the simplest level it provides an easy way to process template files, filling in embedded variable references with their equivalent values.
Dear [% name %],
It has come to our attention that your account is in
arrears to the sum of [% debt %].
Please settle your account before [% deadline %] or we
will be forced to revoke your Licence to Thrill.
The Management.
By default, template directives are embedded within the character sequences '[%' ... '%]' but you can change these and various other options to configure how the Template Toolkit looks, feels and works. You can set the INTERPOLATE option, for example, if you prefer to embed your variables in Perl style:
Dear $name,
It has come to our attention that your account is in
arrears to the sum of $debt.
...
The Template.pm module is the front end to the Template Toolkit, providing access to the full range of functionality through a single module with a simple interface. It loads the other modules as required and instantiates a default set of objects to handle subsequent template processing requests. Configuration parameters may be passed to the Template.pm constructor, new(), which are then used to configure the underlying objects.
use Template;
my $tt = Template->new({
INCLUDE_PATH => '/usr/local/templates',
INTERPOLATE => 1,
}) || die "$Template::ERROR\n";
The Template object implements a process() method for processing template
files or text. The name of the input template (or various other sources)
is passed as the first argument, followed by a reference to a hash array
of variable definitions for substitution in the template.
my $vars = {
name => 'Count Edward van Halen',
debt => '3 riffs and a solo',
deadline => 'the next chorus',
};
$template->process('letters/overdrawn', $vars)
|| die $template->error(), "\n";
The process() method returns true (1) on success and prints the
template output to STDOUT, by default. On error, the process() method
returns false (undef). The error() method can then be called to
retrieve details of the error.
A number of special directives are provided, such as INSERT, INCLUDE and PROCESS, which allow content to be built up from smaller template components. This permits a modular approach to building a web site or other content repository, promoting reusability, cross-site consistency, ease of construction and subsequent maintenance. Common elements such as headers, footers, menu bars, tables, and so on, can be created as separate template files which can then be processed into other documents as required. All defined variables are inherited by these templates along with any additional ``local'' values specified.
[% PROCESS header
title = "The Cat Sat on the Mat"
%]
[% PROCESS menu %]
The location of the missing feline has now been established.
Thank you for your assistance.
[% INSERT legal/disclaimer %]
[% PROCESS footer %]
You can also define a template as a BLOCK within the same file and PROCESS it just like any other template file. This can be invaluable for building up repetitive elements such as tables, menus, etc.
[% BLOCK tabrow %]
<tr><td>[% name %]</td><td>[% email %]</td></tr>
[% END %]
<table>
[% PROCESS tabrow name="tom" email="tom@here.org" %]
[% PROCESS tabrow name="dick" email="disk@there.org" %]
[% PROCESS tabrow name="larry" email="larry@where.org" %]
</table>
One of the key features that sets the Template Toolkit apart from other template processors is the ability to bind template variables to any kind of Perl data: scalars, lists, hash arrays, sub-routines and objects.
my $vars = {
root => 'http://here.com/there',
menu => [ 'modules', 'authors', 'scripts' ],
client => {
name => 'Doctor Joseph von Satriani',
id => 'JVSAT',
},
checkout => sub { my $total = shift; ...; return $something },
shopcart => My::Cool::Shopping::Cart->new(),
};
The Template Toolkit will automatically Do The Right Thing to access the data in an appropriate manner to return some value which can then be output. The dot operator '.' is used to accesses into lists and hashes or to call object methods. The FOREACH directive is provided for iterating through lists, and various logicial tests are available using directives such as IF, UNLESS, ELSIF, ELSE, SWITCH, CASE, etc.
[% FOREACH section = menu %]
<a href="[% root %]/[% section %]/index.html">[% section %]</a>
[% END %]
<b>Client</a>: [% client.name %] (id: [% client.id %])
[% IF shopcart.nitems %]
Your shopping cart contains the following items:
<ul>
[% FOREACH item = shopcart.contents %]
<li>[% item.name %] : [% item.qty %] @ [% item.price %]
[% END %]
</ul>
[% checkout(shopcart.total) %]
[% ELSE %]
No items currently in shopping cart.
[% END %]
The Template Toolkit also provides a number of additional directives for advanced processing and programmatical functionality. It supports output filters (FILTER), allows custom macros to be defined (MACRO), has a fully-featured exception handling system (TRY, THROW, CATCH, FINAL) and supports a plugin architecture (USE) which allows special plugin modules and even regular Perl modules to be loaded and used with the minimum of fuss. The Template Toolkit is ``just'' a template processor but you can trivially extend it to incorporate the functionality of any Perl module you can get your hands on. Thus, it is also a scalable and extensible template framework, ideally suited for managing the presentation layer for application servers, content management systems and other web applications.
Rather than embedding Perl code or some other scripting language directly into template documents, it encourages you to keep functional components (i.e. Perl code) separate from presentation components (e.g. HTML templates). The template variables provide the interface between the two layers, allowing data to be generated in code and then passed to a template component for displaying (pipeline model) or for sub-routine or object references to be bound to variables which can then be called from the template as and when required (callback model).
The directives that the Template Toolkit provide implement their own mini programming language, but they're not really designed for serious, general purpose programming. Perl is a far more appropriate language for that. If you embed application logic (e.g. Perl or other scripting language fragments) in HTML templates then you risk losing the clear separation of concerns between functionality and presentation. It becomes harder to maintain the two elements in isolation and more difficult, if not impossible, to reuse code or presentation elements by themselves. It is far better to write your application code in separate Perl modules, libraries or scripts and then use templates to control how the resulting data is presented as output. Thus you should think of the Template Toolkit language as a set of layout directives for displaying data, not calculating it.
Having said that, the Template Toolkit doesn't force you into one approach or the other. It attempts to be pragmatic rather than dogmatic in allowing you to do whatever best gets the job done. Thus, if you enable the EVAL_PERL option then you can happily embed real Perl code in your templates within PERL ... END directives.
The Template Toolkit uses a fast YACC-like parser which compiles templates into Perl code for maximum runtime efficiency. It also has an advanced caching mechanism which manages in-memory and on-disk (i.e. persistant) versions of compiled templates. The modules that comprise the toolkit are highly configurable and the architecture around which they're built is designed to be extensible. The Template Toolkit provides a powerful framework around which content creation and delivery systems can be built while also providing a simple interface through the Template front-end module for general use.
new(\%config)The new() constructor method (implemented by the Template::Base base
class) instantiates a new Template object. A reference to a hash
array of configuration items may be passed as a parameter.
my $tt = Template->new({
INCLUDE_PATH => '/usr/local/templates',
EVAL_PERL => 1,
}) || die $Template::ERROR, "\n";
A reference to a new Template object is returned, or undef on error.
In the latter case, the error message can be retrieved by calling
error() as a class method (e.g. Template->error()) or by
examining the $ERROR package variable directly
(e.g. $Template::ERROR).
my $tt = Template->new(\%config)
|| die Template->error(), "\n";
my $tt = Template->new(\%config)
|| die $Template::ERROR, "\n";
For convenience, configuration items may also be specified as a list of items instead of a hash array reference. These are automatically folded into a hash array by the constructor.
my $tt = Template->new(INCLUDE_PATH => '/tmp', POST_CHOMP => 1)
|| die $Template::ERROR, "\n";
The process() method is called to process a template. The first
parameter indicates the input template as one of: a filename relative
to INCLUDE_PATH, if defined; a reference to a text string containing
the template text; or a file handle reference (e.g. IO::Handle or
sub-class) or GLOB (e.g. \*STDIN), from which the template can be
read. A reference to a hash array may be passed as the second
parameter, containing definitions of template variables.
$text = "[% INCLUDE header %]\nHello world!\n[% INCLUDE footer %]";
# filename
$tt->process('welcome.tt2')
|| die $tt->error(), "\n";
# text reference
$tt->process(\$text)
|| die $tt->error(), "\n";
# GLOB
$tt->process(\*DATA)
|| die $tt->error(), "\n";
__END__
[% INCLUDE header %]
This is a template defined in the __END__ section which is
accessible via the DATA "file handle".
[% INCLUDE footer %]
By default, the processed template output is printed to STDOUT. The
process() method then returns 1 to indicate success. A third
parameter may be passed to the process() method to specify a different
output location. This value may be one of: a plain string indicating
a filename which will be opened (relative to OUTPUT_PATH, if defined)
and the output written to; a file GLOB opened ready for output; a
reference to a scalar (e.g. a text string) to which output/error is
appended; a reference to a subroutine which is called, passing the
output as a parameter; or any object reference which implements a
'print' method (e.g. IO::Handle, Apache::Request, etc.) which will
be called, passing the generated output as a parameter.
Examples:
# output filename
$tt->process('welcome.tt2', $vars, 'welcome.html')
|| die $tt->error(), "\n";
# reference to output subroutine
sub myout {
my $output = shift;
...
}
$tt->process('welcome.tt2', $vars, \&myout)
|| die $tt->error(), "\n";
# reference to output text string
my $output = '';
$tt->process('welcome.tt2', $vars, \$output)
|| die $tt->error(), "\n";
print "output: $output\n";
In an Apache/mod_perl handler:
sub handler {
my $req = shift;
...
# direct output to Apache::Request via $req->print($output)
$tt->process($file, $vars, $req) || do {
$req->log_reason($tt->error());
return SERVER_ERROR;
};
return OK;
}
The OUTPUT configuration item can be used to specify a default output location other than \*STDOUT. The OUTPUT_PATH specifies a directory which should be prefixed to all output locations specified as filenames.
my $tt = Template->new({
OUTPUT => sub { ... }, # default
OUTPUT_PATH => '/tmp',
...
}) || die Template->error(), "\n";
# use default OUTPUT (sub is called)
$tt->process('welcome.tt2', $vars)
|| die $tt->error(), "\n";
# write file to '/tmp/welcome.html'
$tt->process('welcome.tt2', $vars, 'welcome.html')
|| die $tt->error(), "\n";
The process() method returns 1 on success or undef on error. The error
message generated in the latter case can be retrieved by calling the
error() method. See also CONFIGURATION OPTIONS which describes how
error handling may be further customised.
error()When called as a class method, it returns the value of the $ERROR package variable. Thus, the following are equivalent.
my $tt = Template->new()
|| die Template->error(), "\n";
my $tt = Template->new()
|| die $Template::ERROR, "\n";
When called as an object method, it returns the value of the internal _ERROR variable, as set by an error condition in a previous call to process().
$tt->process('welcome.tt2')
|| die $tt->error(), "\n";
Errors are represented in the Template Toolkit by objects of the
Template::Exception class. If the process() method returns a false
value then the error() method can be called to return an object of
this class. The type() and info() methods can called on the object to
retrieve the error type and information string, respectively. The
as_string() method can be called to return a string of the form ``$type
- $info''. This method is also overloaded onto the stringification
operator allowing the object reference itself to be printed to return
the formatted error string.
$tt->process('somefile') || do {
my $error = $tt->error();
print "error type: ", $error->type(), "\n";
print "error info: ", $error->info(), "\n";
print $error, "\n";
};
service()The Template module delegates most of the effort of processing templates to an underlying Template::Service object. This method returns a reference to that object.
context()The Template::Service module uses a core Template::Context object for runtime processing of templates. This method returns a reference to that object and is equivalent to $template->service->context();
By default, template directives are embedded within the character sequences '[%' and '%]'. e.g.
[% PROCESS header %]
<h1>Hello World!</h1>
<a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
[% PROCESS footer %]
You can change the tag characters using the START_TAG, END_TAG and TAG_STYLE configuration options. You can also use the TAGS directive to define a new tag style for the current template file.
Directives may be embedded anywhere in a line of text and can be split across several lines. Insignificant whitespace is generally ignored within the directive.
[% INCLUDE header
title = 'Hello World'
bgcol = '#ffffff'
%]
[%INCLUDE menu align='right'%]
Name: [% name %] ([%id%])
You can also set the INTERPOLATE option to allow simple variable references to be embedded directly in templates, prefixed by a '$'.
# INTERPOLATE => 0
<td>[% name %]</td> <td>[% email %]</td>
# INTERPOLATE => 1
<td>$name</td> <td>$email</td>
The '#' character is used to indicate comments within a directive. When placed immediately inside the opening directive tag, it causes the entire directive to be ignored.
[%# this entire directive is ignored no
matter how many lines it wraps onto
%]
In any other position, it causes the remainder of the current line to be treated as a comment.
[% # this is a comment
theta = 20 # so is this
rho = 30 # <aol>me too!</aol>
%]
You can add '-' or '+' to the immediate start or end of a directive tag to control the whitespace chomping options. See the PRE_CHOMP and POST_CHOMP options for further details.
[% BLOCK foo -%] # remove trailing newline
This is block foo
[%- END %] # remove leading newline
The simplest directives are GET and SET which retrieve and update variable values respectively. The GET and SET keywords are actually optional as the parser is smart enough to see them for what they really are (but note the caveat below on using side-effect notation). Thus, you'll generally see:
[% SET foo = 10 %]
[% GET foo %]
written as:
[% foo = 10 %]
[% foo %]
You can also express simple logical statements as implicit GET directives:
[% title or template.title or 'Default Title' %]
[% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]
All other directives should start with a keyword specified in UPPER CASE (but see the ANYCASE option). All directives keywords are in UPPER CASE to make them visually distinctive and to distinguish them from variables of the same name but different case. It is perfectly valid, for example, to define a variable called 'stop' which is entirely separate from the STOP directive.
[% stop = 'Clackett Lane Bus Depot' %]
The bus will next stop at [% stop %] # variable
[% STOP %] # directive
Directives such as FOREACH, WHILE, BLOCK, FILTER, etc., mark the start of a block which may contain text or other directives up to the matching END directive. Blocks may be nested indefinately. The IF, UNLESS, ELSIF and ELSE directives also define blocks and may be grouped together in the usual manner.
[% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
* Item: [% item %]
[% END %]
[% BLOCK footer %]
Copyright 2000 [% me %]
[% INCLUDE company/logo %]
[% END %]
[% IF foo %]
[% FOREACH thing = foo.things %]
[% thing %]
[% END %]
[% ELSIF bar %]
[% INCLUDE barinfo %]
[% ELSE %]
do nothing...
[% END %]
Block directives can also be used in a convenient side-effect notation.
[% INCLUDE userinfo FOREACH user = userlist %]
[% INCLUDE debugtxt msg="file: $error.info"
IF debugging %]
[% "Danger Will Robinson" IF atrisk %]
versus:
[% FOREACH user = userlist %]
[% INCLUDE userinfo %]
[% END %]
[% IF debugging %]
[% INCLUDE debugtxt msg="file: $error.info" %]
[% END %]
[% IF atrisk %]
Danger Will Robinson
[% END %]
The output of a directive can be captured by simply assigning the directive to a variable.
[% headtext = PROCESS header title="Hello World" %]
[% people = PROCESS userinfo FOREACH user = userlist %]
This can be used in conjunction with the BLOCK directive for defining large blocks of text or other content.
[% poem = BLOCK %]
The boy stood on the burning deck,
His fleece was white as snow.
A rolling stone gathers no moss,
And Keith is sure to follow.
[% END %]
Note one important caveat of using this syntax in conjunction with side-effect notation. The following directive does not behave as might be expected:
[% var = 'value' IF some_condition %]
In this case, the directive is interpreted as (spacing added for clarity)
[% var = IF some_condition %]
value
[% END %]
rather than
[% IF some_condition %]
[% var = 'value' %]
[% END %]
The variable is assigned the output of the IF block which returns 'value' if true, but nothing if false. In other words, the following directive will always cause 'var' to be cleared.
[% var = 'value' IF 0 %]
To achieve the expected behaviour, the directive should be written as:
[% SET var = 'value' IF some_condition %]
Multiple FILTER directives can be chained together in sequence. They are called in the order defined, piping the output of one into the input of the next.
[% PROCESS somefile FILTER truncate(100) FILTER html %]
The pipe character, '|', can also be used as an alias for FILTER.
[% PROCESS somefile | truncate(100) | html %]
Multiple directives can be included within a single tag when delimited by semi-colons, ';'. Note however that the TAGS directive must always be specified in a tag by itself.
[% IF title;
INCLUDE header;
ELSE;
INCLUDE other/header title="Some Other Title";
END
%]
versus
[% IF title %]
[% INCLUDE header %]
[% ELSE %]
[% INCLUDE other/header title="Some Other Title" %]
[% END %]
A reference to a hash array may be passed as the second argument to
the process() method, containing definitions of template variables.
The VARIABLES (a.k.a. PRE_DEFINE) option can also be used to pre-define
variables for all templates processed by the object.
my $tt = Template->new({
VARIABLES => {
version => 3.14,
release => 'Sahara',
},
});
my $vars = {
serial_no => 271828,
};
$tt->process('myfile', $vars);
'myfile':
This is version [% version %] ([% release %]).
Serial number: [% serial_no %]
output:
This is version 3.14 (Sahara)
Serial number: 271828
Variable names may contain any alphanumeric characters or underscores. They may be lower, upper or mixed case although the usual convention is to use lower case. The case is significant however, and 'foo', 'Foo' and 'FOO' are all different variables. Upper case variable names are permitted, but not recommended due to a possible conflict with an existing or future reserved word. As of version 2.00, these are:
GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
CLEAR TO STEP AND OR NOT MOD DIV END
The variable values may be of virtually any Perl type, including simple scalars, references to lists, hash arrays, subroutines or objects. The Template Toolkit will automatically apply the correct procedure to accessing these values as they are used in the template.
Example:
my $vars = {
article => 'The Third Shoe',
person => {
id => 314,
name => 'Mr. Blue',
email => 'blue@nowhere.org',
},
primes => [ 2, 3, 5, 7, 11, 13 ],
wizard => sub { return join(' ', 'Abracadabra!', @_) },
cgi => CGI->new('mode=submit&debug=1'),
};
template:
[% article %]
[% person.id %]: [% person.name %] <[% person.email %]>
[% primes.first %] - [% primes.last %], including [% primes.3 %]
[% primes.size %] prime numbers: [% primes.join(', ') %]
[% wizard %]
[% wizard('Hocus Pocus!') %]
[% cgi.param('mode') %]
output:
The Third Shoe
314: Mr. Blue <blue@nowhere.org>
2 - 13, including 7
6 prime numbers: 2, 3, 5, 7, 11, 13
Abracadabra!
Abracadabra! Hocus Pocus!
submit
Regular scalar variables are accessed by simply specifying their name. As these are just entries in the top-level variable hash they can be considered special cases of hash array referencing as described below, with the main namespace hash automatically implied.
[% article %]
Members of hash arrays are accessed by specifying the hash reference and key separated by the dot '.' operator.
my $vars = {
'home' => 'http://www.myserver.com/homepage.html',
'page' => {
'this' => 'mypage.html',
'next' => 'nextpage.html',
'prev' => 'prevpage.html',
},
};
template:
<a href="[% home %]">Home</a>
<a href="[% page.prev %]">Previous Page</a>
<a href="[% page.next %]">Next Page</a>
output:
<a href="http://www.myserver.com/homepage.html";>Home</a>
<a href="prevpage.html">Previous Page</a>
<a href="nextpage.html">Next Page</a>
Any key in a hash which starts with a '_' or '.' character will be considered private and cannot be evaluated or updated from within a template. The undefined value will be returned for any such variable accessed which the Template Toolkit will silently ignore (unless the DEBUG option is enabled).
my $vars = {
message => 'Hello World!',
_secret => "On the Internet, no-one knows you're a dog",
thing => {
public => 123,
_private => 456,
'.hidden' => 789,
},
};
template:
[% message %] # outputs "Hello World!"
[% _secret %] # no output
[% thing.public %] # outputs "123"
[% thing._private %] # no output
[% thing..hidden %] # ERROR: unexpected token (..)
To access a hash entry using a key stored in another variable, prefix the key variable with '$' to have it interpolated before use (see Variable Interpolation).
[% pagename = 'next' %]
[% page.$pagename %] # same as [% page.next %]
When you assign to a variable that contains multiple namespace elements (i.e. it has one or more '.' characters in the name), any hashes required to represent intermediate namespaces will be created automatically. In this following example, the 'product' variable automatically springs into life as a hash array unless otherwise defined.
[% product.id = 'XYZ-2000'
product.desc = 'Bogon Generator'
product.price = 666
%]
The [% product.id %] [% product.desc %]
costs $[% product.price %].00
output:
The XYZ-2000 Bogon Generator
costs $666.00
You can use Perl's familiar '{' ... '}' construct to explicitly create a hash and assign it to a variable. Note that commas are optional between key/value pairs and '=' can be used in place of '=>'.
[% product = {
id => 'XYZ-2000',
desc => 'Bogon Generator',
price => 666,
}
%]
Items in lists are also accessed by use of the dot operator.
my $vars = {
'people' => [ 'Tom', 'Dick', 'Larry' ],
};
template:
[% people.0 %] # Tom
[% people.1 %] # Dick
[% people.2 %] # Larry
The FOREACH directive can be used to iterate through items in a list.
[% FOREACH person = people %]
Hello [% person %]
[% END %]
output:
Hello Tom
Hello Dick
Hello Larry
Lists can be constructed in-situ using the regular anonymous list '[' ... ']' construct. Commas between items are optional.
[% cols = [ 'red', 'green', 'blue' ] %]
[% FOREACH c = cols %]
...
or:
[% FOREACH c = [ 'red', 'green', 'blue' ] %]
...
You can also create simple numerical sequences using the familiar '..' operator:
[% n = [ 1 .. 4 ] %] # n is [ 1, 2, 3, 4 ]
[% x = 4
y = 8
z = [x..y] # z is [ 4, 5, 6, 7, 8 ]
%]
Template variables can contain references to Perl subroutines. When the variable is used, the Template Toolkit will automatically call the subroutine, passing any additional arguments specified. The return value from the subroutine is used as the variable value and inserted into the document output.
my $vars = {
wizard => sub { return join(' ', 'Abracadabra!', @_) },
};
template:
[% wizard %] # Abracadabra!
[% wizard('Hocus Pocus!') %] # Abracadabra! Hocus Pocus!
Template variables can also contain references to Perl objects. Methods are called using the dot operator to specify the method against the object variable. Additional arguments can be specified as with subroutines.
use CGI;
...
my $vars = {
# hard coded CGI params for purpose of example
cgi => CGI->new('mode=submit&debug=1'),
};
template:
[% FOREACH p = cgi.param %] # returns list of param keys
[% p %] => [% cgi.param(p) %] # fetch each param value
[% END %]
output:
mode => submit
debug => 1
Object methods can also be called as lvalues. That is, they can appear on the left side of an assignment. The method will be called passing the assigning value as an argument.
[% myobj.method = 10 %]
equivalent to:
[% myobj.method(10) %]
Subroutines and methods will be passed any arguments specified in the template. Any template variables in the argument list will first be evaluated and their resultant values passed to the code.
my $vars = {
mycode => sub { return 'received ' . join(', ', @_) },
};
template:
[% foo = 10 %]
[% mycode(foo, 20) %] # received 10, 20
Named parameters may also be specified. These are automatically collected into a single hash array which is passed by reference as the last parameter to the sub-routine. Named parameters can be specified using either '=>' or '=' and can appear anywhere in the argument list.
my $vars = {
myjoin => \&myjoin,
};
sub myjoin {
# look for hash ref as last argument
my $params = ref $_[-1] eq 'HASH' ? pop : { };
return join($params->{ joint } || ' + ', @_);
}
template:
[% myjoin(10, 20, 30) %]
[% myjoin(10, 20, 30, joint = ' - ' %]
[% myjoin(joint => ' * ', 10, 20, 30 %]
output:
10 + 20 + 30
10 - 20 - 30
10 * 20 * 30
Parenthesised parameters may be added to any element of a variable, not just those that are bound to code or object methods. At present, parameters will be ignored if the variable isn't ``callable'' but are supported for future extensions. Think of them as ``hints'' to that variable, rather than just arguments passed to a function.
[% r = 'Romeo' %]
[% r(100, 99, s, t, v) %] # outputs "Romeo"
User code should return a value for the variable it represents. This can be any of the Perl data types described above: a scalar, or reference to a list, hash, subroutine or object. Where code returns a list of multiple values the items will automatically be folded into a list reference which can be accessed as per normal.
my $vars = {
# either is OK, first is recommended
items1 => sub { return [ 'foo', 'bar', 'baz' ] },
items2 => sub { return ( 'foo', 'bar', 'baz' ) },
};
template:
[% FOREACH i = items1 %]
...
[% END %]
[% FOREACH i = items2 %]
...
[% END %]
Errors can be reported from user code by calling die(). Errors raised in this way are caught by the Template Toolkit and converted to structured exceptions which can be handled from within the template. A reference to the exception object is then available as the 'error' variable.
my $vars = {
barf => sub {
die "a sick error has occured\n";
},
};
template:
[% TRY %]
[% barf %] # calls sub which throws error via die()
[% CATCH %]
[% error.info %] # outputs "a sick error has occured\n"
[% END %]
Error messages thrown via die() are converted to exceptions of type
'undef'. Exceptions of user-defined types can be thrown by calling
die() with a reference to a Template::Exception object.
use Template::Exception;
...
my $vars = {
login => sub {
...
die Template::Exception->new('badpwd',
'password too silly');
},
};
template:
[% TRY %]
[% login %]
[% CATCH badpwd %]
Bad password: [% error.info %]
[% CATCH %]
Some other '[% error.type %]' error: [% error.info %]
[% END %]
The exception types 'stop' and 'return' are used to implement the STOP and RETURN directives. Throwing an exception as:
die Template::Exception->new('stop');
has the same effect as the directive:
[% STOP %]
Subroutines and methods can also raise errors by returning a list or reference to a list containing the undefined value (undef) followed by an exception object or error message. This is supported for backwards compatability with version 1 but may be deprecated in some future version.
my $vars = {
# currently equivalent
barf => sub {
die "I'm sorry Dave, I can't do that";
},
yack => sub {
return (undef, "I'm sorry Dave, I can't do that");
},
};
The Template Toolkit provides virtual methods for manipulating variable values. Most of them are analagous to regular Perl functions of the same names.
The following methods can be called against any scalar value:
[% user = get_user(uid) IF uid.defined %]
[% IF password.length < 8 %]
Password too short, dumbass!
[% END %]
split() function to split a string into a list of
strings.
[% FOREACH dir = mypath.split(':') %]
[% dir %]
[% END %]
The following can be called against hash references.
[% FOREACH key = product.keys %]
[% key %] => [% product.$key %]
[% END %]
[% FOREACH n = phones.sort %]
[% phones.$n %] is [% n %],
[% END %]
[% hash1 = {
foo => 'Foo',
bar => 'Bar',
}
hash2 = {
wiz => 'Wiz',
woz => 'Woz',
}
%]
[% hash1.import(hash2) %]
[% hash1.wiz %] # Wiz
You can also call the import() method by itself to import a hash array
into the current namespace hash.
[% user = { id => 'lwall', name => 'Larry Wall' } %]
[% import(user) %]
[% id %]: [% name %] # lwall: Larry Wall
The following virtual methods are provided for lists:
[% results.first %] to [% results.last %]
[% results.size %] search results matched your query
[% FOREACH s = scores.reverse %]
...
[% END %]
[% items.join(', ') %]
[% library = books.sort %]
Where the list contains hash array references, a hash key can be passed as an argument to specify the sort field.
[% library = books.sort('author') %]
push()
[% mylist.unshift('prev item') %]
[% mylist.push('next item') %]
pop()
[% first = mylist.shift %]
[% last = mylist.pop %]
The following example demonstrates how an empty list ('folk') can be
populated with formatted strings by using the push() method in conjunction
with a FOREACH loop. The resultant list can then be printed using join.
[% # define some initial data
people => [
{ id => 'tom', name => 'Tom' },
{ id => 'dick', name => 'Richard' },
{ id => 'larry', name => 'Larry' },
]
# define an empty list that list methods can be called against
folk = []
-%]
[% folk.push("<a href=\"${person.id}.html\">$person.name</a>")
FOREACH person = people.sort('name') -%]
[% folk.join(",\n") %]
Output:
<a href="larry.html">Larry</a>,
<a href="dick.html">Richard</a>,
<a href="tom.html">Tom</a>
You can define your own virtual methods for scalars, lists and hash arrays. The Template::Stash package variables $SCALAR_OPS, $LIST_OPS and $HASH_OPS are references to hash arrays that define these virtual methods. HASH_OPS and LIST_OPS methods are subroutines that accept a hash/list reference as the first item. SCALAR_OPS are subroutines that accept a scalar value as the first item. Any other arguments specified when the method is called will be passed to the subroutine.
# load Template::Stash to make method tables visible
use Template::Stash;
# define list method to return new list of odd numbers only
$Template::Stash::LIST_OPS->{ odd } = sub {
my $list = shift;
return [ grep { $_ % 2 } @$list ];
};
template:
[% primes = [ 2, 3, 5, 7, 9 %] %]
[% primes.odd.join(', ') %] # 3, 5, 7, 9
See also the examples in the t/vmeth.t test script.
Compound 'dotted' variables may contain any number of separate elements. Each element may evaluate to any of the permitted variable types and the processor will then correctly use this value to evaluate the rest of the variable. Arguments may be passed to any of the intermediate elements.
[% myorg.people.sort('surname').first.fullname %]
Intermediate variables may be used and will behave entirely as expected.
[% sorted = myorg.people.sort('surname') %]
[% sorted.first.fullname %]
This simplified dotted notation has the benefit of hiding the implementation details of your data. For example, you could implement a data structure as a hash array one day and then change it to an object the next without requiring any change to the templates.
The Template Toolkit uses '$' consistently to indicate that a variable should be interpolated in position. Most frequently, you see this in double-quoted strings:
[% fullname = "$honorific $firstname $surname" %]
Or embedded in plain text when the INTERPOLATE option is set:
Dear $honorific $firstname $surname,
The same rules apply within directives. If a variable is prefixed with a '$' then it is replaced with its value before being used. The most common use is to retrieve an element from a hash where the key is stored in a variable.
[% uid = 'abw' %]
[% userlist.$uid %] # same as 'userlist.abw'
Curly braces can be used to delimit interpolated variable names where necessary.
[% userlist.${me.id}.name %]
Directives such as INCLUDE, PROCESS, etc., that accept a template name as the first argument, will automatically quote it for convenience.
[% INCLUDE foo/bar.txt %]
equivalent to:
[% INCLUDE "foo/bar.txt" %]
To INCLUDE a template whose name is stored in a variable, simply prefix the variable name with '$' to have it interpolated.
[% myfile = 'header' %]
[% INCLUDE $myfile %]
equivalent to:
[% INCLUDE header %]
Note also that a variable containing a reference to a Template::Document object can also be processed in this way.
my $vars = {
header => Template::Document->new({ ... }),
};
template:
[% INCLUDE $header %]
Any simple variables that you create, or any changes you make to existing variables, will only persist while the template is being processed. The top-level variable hash is copied before processing begins and any changes to variables are made in this copy, leaving the original intact. The same thing happens when you INCLUDE another template. The current namespace hash is cloned to prevent any variable changes made in the included template from interfering with existing variables. The PROCESS option bypasses the localisation step altogether making it slightly faster, but requiring greater attention to the possibility of side effects caused by creating or changing any variables within the processed template.
[% BLOCK change_name %]
[% name = 'bar' %]
[% END %]
[% name = 'foo' %]
[% INCLUDE change_name %]
[% name %] # foo
[% PROCESS change_name %]
[% name %] # bar
Dotted compound variables behave slightly differently because the localisation process is only skin deep. The current variable namespace hash is copied, but no attempt is made to perform a deep-copy of other structures within it (hashes, arrays, objects, etc). A variable referencing a hash, for example, will be copied to create a new reference but which points to the same hash. Thus, the general rule is that simple variables (undotted variables) are localised, but existing complex structures (dotted variables) are not.
[% BLOCK all_change %]
[% x = 20 %] # changes copy
[% y.z = 'zulu' %] # changes original
[% END %]
[% x = 10
y = { z => 'zebra' }
%]
[% INCLUDE all_change %]
[% x %] # still '10'
[% y.z %] # now 'zulu'
If you create a complex structure such as a hash or list reference within a local template context then it will cease to exist when the template is finished processing.
[% BLOCK new_stuff %]
[% # define a new 'y' hash array in local context
y = { z => 'zulu' }
%]
[% END %]
[% x = 10 %]
[% INCLUDE new_stuff %]
[% x %] # outputs '10'
[% y %] # nothing, y is undefined
Similarly, if you update an element of a compound variable which doesn't already exists then a hash will be created automatically and deleted again at the end of the block.
[% BLOCK new_stuff %]
[% y.z = 'zulu' %]
[% END %]
However, if the hash does already exist then you will modify the original with permanent effect. To avoid potential confusion, it is recommended that you don't update elements of complex variables from within blocks or templates included by another.
If you want to create or update truly global variables then you can use the 'global' namespace. This is a hash array automatically created in the top-level namespace which all templates, localised or otherwise see the same reference to. Changes made to variables within this hash are visible across all templates.
[% global.version = 123 %]
A number of special variables are automatically defined by the Template Toolkit.
Note that the 'template' variable always references the top-level template, even when processing other template components via INCLUDE, PROCESS, etc.
This example should demonstrate the difference:
$template->process('foo')
|| die $template->error(), "\n";
'foo':
[% template.name %] # foo
[% component.name %] # foo
[% PROCESS footer %]
'footer':
[% template.name %] # foo
[% component.name %] # footer
[% FOREACH item = [ 'foo', 'bar', 'baz' ] -%]
[% "Items:\n" IF loop.first -%]
[% loop.count %]/[% loop.size %]: [% item %]
[% END %]
[% TRY %]
...
[% CATCH %]
[% error %]
[% END %]
[% WRAPPER box %]
Be not afeard; the isle is full of noises,
Sounds and sweet airs, that give delight and hurt not.
[% END %]
[% BLOCK box %]
<table border=1>
<tr>
<td>
[% content %]
</td>
</tr>
</table>
[% END %]
[% GET foo %]
The GET keyword is optional. A variable can be specified in a directive tag by itself.
[% foo %]
The variable may take any of the forms described above:
[% foo %]
[% bar.baz %]
[% biz.baz(10) %]
...etc...
You can also specify expressions using the logical (and, or, not, ?:) and mathematic operators (+ - * / % mod div).
[% template.title or default.title %]
[% score * 100 %]
[% order.nitems ? checkout(order.total) : 'no items' %]
The 'div' operator returns the integer result of division. Both '%' and 'mod' return the modulus (i.e. remainder) of division. 'mod' is provided as an alias for '%' for backwards compatability with version 1.
[% 15 / 6 %] # 2.5
[% 15 div 6 %] # 2
[% 15 mod 6 %] # 3
[% CALL dbi.disconnect %]
[% CALL inc_page_counter(page_count) %]
[% SET title = 'Hello World' %]
The SET keyword is also optional.
[% title = 'Hello World' %]
Variables may be assigned the values of other variables, unquoted numbers (digits), literal text ('single quotes') or quoted text (``double quotes''). In the latter case, any variable references within the text will be interpolated when the string is evaluated. Variables should be prefixed by '$', using curly braces to explicitly scope the variable name where necessary.
[% foo = 'Foo' %] # literal value 'Foo'
[% bar = foo %] # value of variable 'foo'
[% cost = '$100' %] # literal value '$100'
[% item = "$bar: ${cost}.00" %] # value "Foo: $100.00"
Multiple variables may be assigned in the same directive and are evaluated in the order specified. Thus, the above could have been written:
[% foo = 'Foo'
bar = foo
cost = '$100'
item = "$bar: ${cost}.00"
%]
Simple expressions can also be used, as per GET.
[% ten = 10
twenty = 20
thirty = twenty + ten
forty = 2 * twenty
fifty = 100 div 2
six = twenty mod 7
%]
[% DEFAULT
name = 'John Doe'
id = 'jdoe'
%]
This can be particularly useful in common template components to ensure that some sensible default are provided for otherwise undefined variables.
[% DEFAULT
title = 'Hello World'
bgcol = '#ffffff'
%]
<html>
<head>
<title>[% title %]</title>
</head>
<body bgcolor="[% bgcol %]">
[% INSERT myfile %]
No attempt to parse or process the file is made. The contents, possibly including any embedded template directives, are inserted intact.
The filename specified should be relative to one of the INCLUDE_PATH
directories. Absolute (i.e. starting with /) and relative
(i.e. starting with .) filenames may be used if the ABSOLUTE and
RELATIVE options are set, respectively. Both these options are
disabled by default.
my $template = Template->new({
INCLUDE_PATH => '/here:/there',
});
$template->process('myfile');
'myfile':
[% INSERT foo %] # looks for /here/foo then /there/foo
[% INSERT /etc/passwd %] # file error: ABSOLUTE not set
[% INSERT ../secret %] # file error: RELATIVE not set
For convenience, the filename does not need to be quoted as long as it contains only alphanumeric characters, underscores, dots or forward slashes. Names containing any other characters should be quoted.
[% INSERT misc/legalese.txt %]
[% INSERT 'dos98/Program Files/stupid' %]
To evaluate a variable to specify a filename, you should explicitly prefix it with a '$' or use double-quoted string interpolation.
[% language = 'en'
legalese = 'misc/legalese.txt'
%]
[% INSERT $legalese %] # 'misc/legalese.txt'
[% INSERT "$language/$legalese" %] # 'en/misc/legalese.txt'
[% INCLUDE header %]
If a BLOCK of the specified name is defined in the same file, or in a file from which the current template has been called (i.e. a parent template) then it will be used in preference to any file of the same name.
[% INCLUDE table %] # uses BLOCK defined below
[% BLOCK table %]
<table>
...
</table>
[% END %]
If a BLOCK definition is not currently visible then the template name should be a file relative to one of the INCLUDE_PATH directories, or an absolute or relative file name if the ABSOLUTE/RELATIVE options are appropriately enabled. The INCLUDE directive automatically quotes the filename specified, as per INSERT described above. When a variable contains the name of the template for the INCLUDE directive, it should be explicitly prefixed by '$'.
[% myheader = 'my/misc/header' %]
[% INCLUDE myheader %] # 'myheader'
[% INCLUDE $myheader %] # 'my/misc/header'
Any template directives embedded within the file will be processed accordingly. All variables currently defined will be visible and accessible from within the included template.
[% title = 'Hello World' %]
[% INCLUDE header %]
<body>
...
'header': <html> <title>[% title %]</title>
output: <html> <title>Hello World</title> <body> ...
Local variable definitions may be specified after the template name, temporarily masking any existing variables. Insignificant whitespace is ignore within directives so you can add variable definitions on the same line, the next line or split across several line with comments interspersed, if you prefer.
[% INCLUDE table %]
[% INCLUDE table title="Active Projects" %]
[% INCLUDE table
title = "Active Projects"
bgcolor = "#80ff00" # chartreuse
border = 2
%]
The INCLUDE directive localises (i.e. copies) all variables before processing the template. Any changes made within the included template will not affect variables in the including template.
[% foo = 10 %]
foo is originally [% foo %]
[% INCLUDE bar %]
foo is still [% foo %]
[% BLOCK bar %]
foo was [% foo %]
[% foo = 20 %]
foo is now [% foo %]
[% END %]
output: foo is originally 10 foo was 10 foo is now 20 foo is still 10
Technical Note: the localisation of the stash (that is, the process by which variables are copied before an INCLUDE to prevent being overwritten) is only skin deep. The top-level variable namespace (hash) is copied, but no attempt is made to perform a deep-copy of other structures (hashes, arrays, objects, etc.) Therefore, a 'foo' variable referencing a hash will be copied to create a new 'foo' variable but which points to the same hash array. Thus, if you update compound variables (e.g. foo.bar) then you will change the original copy, regardless of any stash localisation. If you're not worried about preserving variable values, or you trust the templates you're including then you might prefer to use the PROCESS directive which is faster by virtue of not performing any localisation.
[% foo = 10 %]
foo is [% foo %]
[% PROCESS bar %]
foo is [% foo %]
[% BLOCK bar %]
[% foo = 20 %]
changed foo to [% foo %]
[% END %]
output:
foo is 10
changed foo to 20
foo is 20
Parameters may be specified in the PROCESS directive, but these too will become visible changes to current variable values.
[% foo = 10 %]
foo is [% foo %]
[% PROCESS bar
foo = 20
%]
foo is [% foo %]
[% BLOCK bar %]
this is bar, foo is [% foo %]
[% END %]
output:
foo is 10
this is bar, foo is 20
foo is 20
The PROCESS directive is slightly faster than INCLUDE because it avoids the need to localise (i.e. copy) the variable stash before processing the template. As with INSERT and INCLUDE, the first parameter does not need to be quoted as long as it contains only alphanumeric characters, underscores, periods or forward slashes. A '$' prefix can be used to explicitly indicate a variable which should be interpolated to provide the template name:
[% myheader = 'my/misc/header' %]
[% PROCESS myheader %] # 'myheader'
[% PROCESS $myheader %] # 'my/misc/header'
[% INCLUDE section/header
title = 'Quantum Mechanics'
%]
Quantum mechanics is a very interesting subject wish
should prove easy for the layman to fully comprehend.
[% INCLUDE section/footer %]
[% INCLUDE section/header
title = 'Desktop Nuclear Fusion for under $50'
%]
This describes a simple device which generates significant
sustainable electrical power from common tap water by process
of nuclear fusion.
[% INCLUDE section/footer %]
The individual template components being included might look like these:
section/header: <p> <h2>[% title %]</h2>
section/footer: </p>
The WRAPPER directive provides a way of simplifying this a little. It encloses a block up to a matching END directive, which is first processed to generate some output. This is then passed to the named template file or BLOCK as the 'content' variable.
[% WRAPPER section
title = 'Quantum Mechanics'
%]
Quantum mechanics is a very interesting subject wish
should prove easy for the layman to fully comprehend.
[% END %]
[% WRAPPER section
title = 'Desktop Nuclear Fusion for under $50'
%]
This describes a simple device which generates significant
sustainable electrical power from common tap water by process
of nuclear fusion.
[% END %]
The single 'section' template can then be defined as:
<p>
<h2>[% title %]</h2>
[% content %]
</p>
Like other block directives, it can be used in side-effect notation:
[% INSERT legalese.txt WRAPPER big_bold_table %]
[% BLOCK tabrow %]
<tr><td>[% name %]<td><td>[% email %]</td></tr>
[% END %]
<table>
[% PROCESS tabrow name='Fred' email='fred@nowhere.com' %]
[% PROCESS tabrow name='Alan' email='alan@nowhere.com' %]
</table>
A BLOCK definition can be used before it is defined, as long as the definition resides in the same file. The block definition itself does not generate any output.
[% PROCESS tmpblk %]
[% BLOCK tmpblk %] This is OK [% END %]
You can use an anonymous BLOCK to capture the output of a template fragment.
[% julius = BLOCK %]
And Caesar's spirit, ranging for revenge,
With Ate by his side come hot from hell,
Shall in these confines with a monarch's voice
Cry 'Havoc', and let slip the dogs of war;
That this foul deed shall smell above the earth
With carrion men, groaning for burial.
[% END %]
Like a named block, it can contain any other template directives which are processed when the block is defined. The output generated by the block is then assigned to the variable 'julius'.
Anonymous BLOCKs can also be used to define block macros. The enclosing block is processed each time the macro is called.
[% MACRO whereabouts BLOCK %]
The [% animal %] sat on the [% place %].
[% END %]
[% foo(animal='cat', place='mat') %] # The cat sat on the mat
[% foo(animal='dog', place='log') %] # The dog sat on the log
[% IF frames %]
[% INCLUDE frameset %]
[% END %]
[% UNLESS text_mode %]
[% INCLUDE biglogo %]
[% END %]
Multiple conditions may be joined with ELSIF and/or ELSE blocks.
[% IF age < 10 %]
Hello [% name %], does your mother know you're
using her AOL account?
[% ELSIF age < 18 %]
Sorry, you're not old enough to enter
(and too dumb to lie about your age)
[% ELSE %]
Welcome [% name %].
[% END %]
The following conditional and boolean operators may be used:
== != < <= > >= ! && || and or not
Conditions may be arbitrarily complex and are evaluated with the same precedence as in Perl. Parenthesis may be used to explicitly determine evaluation order.
# ridiculously contrived complex example
[% IF (name == 'admin' || uid <= 0) && mode == 'debug' %]
I'm confused.
[% ELSIF more > less %]
That's more or less correct.
[% END %]
[% SWITCH myvar %]
[% CASE value1 %]
...
[% CASE [ value2 value3 ] %] # multiple values
...
[% CASE myhash.keys %] # ditto
...
[% CASE %] # default
...
[% END %]
my $vars = {
foo => 'Foo',
items => [ 'one', 'two', 'three' ],
};
template:
Things:
[% FOREACH thing = [ foo 'Bar' "$foo Baz" ] %]
* [% thing %]
[% END %]
Items:
[% FOREACH i = items %]
* [% i %]
[% END %]
Stuff:
[% stuff = [ foo "$foo Bar" ] %]
[% FOREACH s = stuff %]
* [% s %]
[% END %]
output:
Things:
* Foo
* Bar
* Foo Baz
Items:
* one
* two
* three
Stuff:
* Foo
* Foo Bar
When the FOREACH directive is used without specifying a target variable, any iterated values which are hash references will be automatically imported.
[% userlist = [
{ id => 'tom', name => 'Thomas' },
{ id => 'dick', name => 'Richard' },
{ id => 'larry', name => 'Lawrence' },
]
%]
[% FOREACH user = userlist %]
[% user.id %] [% user.name %]
[% END %]
short form:
[% FOREACH userlist %]
[% id %] [% name %]
[% END %]
Note that this particular usage creates a localised variable context to prevent the imported hash keys from overwriting any existing variables. The imported definitions and any other variables defined in such a FOREACH loop will be lost at the end of the loop, when the previous context and variable values are restored.
The FOREACH directive can also be used to iterate through the entries in a hash array. Each entry in the hash is returned in sorted order (based on the key) as a hash array containing 'key' and 'value' items.
[% users = {
tom => 'Thomas',
dick => 'Richard',
larry => 'Lawrence',
}
%]
[% FOREACH u = users %]
* [% u.key %] : [% u.value %]
[% END %]
Output:
* dick : Richard
* larry : Lawrence
* tom : Thomas
The NEXT directive starts the next iteration in the FOREACH loop.
[% FOREACH user = userlist %]
[% NEXT IF user.isguest %]
Name: [% user.name %] Email: [% user.email %]
[% END %]
The LAST directive can be used to prematurely exit the loop. BREAK is also provided as an alias for LAST.
[% FOREACH match = results.nsort('score').reverse %]
[% LAST IF match.score < 50 %]
[% match.score %] : [% match.url %]
[% END %]
The FOREACH directive is implemented using the Template::Iterator module. A reference to the iterator object for a FOREACH directive is implicitly available in the 'loop' variable. The following methods can be called on the 'loop' iterator.
size() number of elements in the list
max() index number of last element (size - 1)
index() index of current iteration from 0 to max()
count() iteration counter from 1 to size() (i.e. index() + 1)
first() true if the current iteration is the first
last() true if the current iteration is the last
prev() return the previous item in the list
next() return the next item in the list
See the Template::Iterator manpage for further details.
Example:
[% FOREACH item = [ 'foo', 'bar', 'baz' ] -%]
[%- "<ul>\n" IF loop.first %]
<li>[% loop.count %]/[% loop.size %]: [% item %]
[%- "</ul>\n" IF loop.last %]
[% END %]
Output:
<ul>
<li>1/3: foo
<li>2/3: bar
<li>3/3: baz
</ul>
Note that the number() method is supported as an alias for count() for
backwards compatability but may be deprecated in some future version.
Nested loops will work as expected, with the 'loop' variable correctly referencing the innermost loop and being restored to any previous value (i.e. an outer loop) at the end of the loop.
[% FOREACH group = grouplist %]
[% "Groups:\n" IF loop.first %] # loop => group iterator
[% FOREACH user = group.userlist %]
[% loop.count %]: [% user.name %] # loop => user iterator
[% END %]
[% "End of Groups\n" IF loop.last %] # loop => group iterator
[% END %]
The 'iterator' plugin can also be used to explicitly create an iterator object. This can be useful within nested loops where you need to keep a reference to the outer iterator within the inner loop. The iterator plugin effectively allows you to create an iterator by a name other than 'loop'. See Template::Plugin::Iterator for further details.
[% USE giter = iterator(grouplist) %]
[% FOREACH group = giter %]
[% FOREACH user = group.userlist %]
user [% loop.count %] in group [% giter.count %]: [% user.name %]
[% END %]
[% END %]
[% WHILE total < 100 %]
...
[% total = calculate_new_total %]
[% END %]
An assignment can be enclosed in parenthesis to evaluate the assigned value.
[% WHILE (user = get_next_user_record) %]
[% user.name %]
[% END %]
The NEXT directive can be used to start the next iteration of a WHILE loop and BREAK can be used to exit the loop, both as per FOREACH.
The Template Toolkit uses a failsafe counter to prevent runaway WHILE loops which would otherwise never terminate. If the loop exceeds 1000 iterations then an 'undef' exception will be thrown, reporting the error:
WHILE loop terminated (> 1000 iterations)
The $Template::Directive::WHILE_MAX variable controls this behaviour and can be set to a higher value if necessary.
[% FILTER html %]
HTML text may have < and > characters embedded
which you want converted to the correct HTML entities.
[% END %]
output:
HTML text may have < and > characters embedded
which you want converted to the correct HTML entities.
The FILTER directive can also follow various other non-block directives. For example:
[% INCLUDE mytext FILTER html %]
The '|' character can also be used as an alias for 'FILTER'.
[% INCLUDE mytext | html %]
Multiple filters can be chained together and will be called in sequence.
[% INCLUDE mytext FILTER html FILTER html_para %]
or
[% INCLUDE mytext | html | html_para %]
Filters come in two flavours, known as 'static' or 'dynamic'. A static filter is a simple subroutine which accepts a text string as the only argument and returns the modified text. The 'html' filter is an example of a static filter, implemented as:
sub html_filter {
my $text = shift;
for ($text) {
s/&/&/g;
s/</</g;
s/>/>/g;
}
return $text;
}
Dynamic filters can accept arguments which are specified when the filter is called from a template. The 'repeat' filter is such an example, accepting a numerical argument which specifies the number of times that the input text should be repeated.
[% FILTER repeat(3) %]blah [% END %]
output:
blah blah blah
These are implemented as filter 'factories'. The factory subroutine is passed a reference to the current Template::Context object along with any additional arguments specified. It should then return a subroutine reference (e.g. a closure) which implements the filter. The 'repeat' filter factory is implemented like this:
sub repeat_filter_factory {
my ($context, $iter) = @_;
$iter = 1 unless defined $iter;
return sub {
my $text = shift;
$text = '' unless defined $text;
return join('\n', $text) x $iter;
}
}
The FILTERS option, described in CONFIGURATION OPTIONS, allows
custom filters to be defined when a Template object is instantiated.
The Template::Context define_filter() method allows further filters
to be defined at any time.
When using a filter, it is possible to assign an alias to it for further use. This is most useful for dynamic filters that you want to re-use with the same configuration.
[% FILTER echo = repeat(2) %]
Is there anybody out there?
[% END %]
[% FILTER echo %]
Mother, should I build a wall?
[% END %]
Output:
Is there anybody out there?
Is there anybody out there?
Mother, should I build a wall?
Mother, should I build a wall?
The FILTER directive automatically quotes the name of the filter. As with INCLUDE et al, you can use a variable to provide the name of the filter, prefixed by '$'.
[% myfilter = 'html' %]
[% FILTER $myfilter %] # same as [% FILTER html %]
...
[% END %]
A template variable can also be used to define a static filter subroutine. However, the Template Toolkit will automatically call any subroutine bound to a variable and use the value returned. Thus, the above example could be implemented as:
my $vars = {
myfilter => sub { return 'html' },
};
template:
[% FILTER $myfilter %] # same as [% FILTER html %]
...
[% END %]
To define a template variable that evaluates to a subroutine reference that can be used by the FILTER directive, you should create a subroutine that, when called automatically by the Template Toolkit, returns another subroutine reference which can then be used to perform the filter operation. Note that only static filters can be implemented in this way.
my $vars = {
myfilter => sub { \&my_filter_sub },
};
sub my_filter_sub {
my $text = shift;
# do something
return $text;
}
template:
[% FILTER $myfilter %]
...
[% END %]
Alternately, you can bless a subroutine reference into a class (any class will do) to fool the Template Toolkit into thinking it's an object rather than a subroutine. This will then bypass the automatic ``call-a-subroutine-to-return-a-value'' magic.
my $vars = {
myfilter => bless(\&my_filter_sub, 'anything_you_like'),
};
template:
[% FILTER $myfilter %]
...
[% END %]
Filters bound to template variables remain local to the variable
context in which they are defined. That is, if you define a filter in
a PERL block within a template that is loaded via INCLUDE, then the
filter definition will only exist until the end of that template when
the stash is delocalised, restoring the previous variable state. If
you want to define a filter which persists for the lifetime of the
processor, or define additional dynamic filter factories, then you can
call the define_filter() method on the current Template::Context
object.
See TEMPLATE TOOLKIT FILTERS for a complete list of available filters, their descriptions and examples of use.
[% USE myplugin %]
A plugin is a regular Perl module that conforms to a particular object-oriented interface, allowing it to be loaded into and used automatically by the Template Toolkit. For details of this interface and information on writing plugins, consult the Template::Plugin manpage.
The plugin name is case-sensitive and will be appended to the PLUGIN_BASE value (default: 'Template::Plugin') to construct a full module name. Any periods, '.', in the name will be converted to '::'.
[% USE MyPlugin %] # => Template::Plugin::MyPlugin
[% USE Foo.Bar %] # => Template::Plugin::Foo::Bar
Various standard plugins are included with the Template Toolkit (see below and TEMPLATE TOOLKIT PLUGINS). These can be specified in lower case and are mapped to the appropriate name.
[% USE cgi %] # => Template::Plugin::CGI
[% USE table %] # => Template::Plugin::Table
Any additional parameters supplied in parenthesis after the plugin
name will be also be passed to the new() constructor. A reference to
the current Template::Context object is always passed as the first
parameter.
[% USE MyPlugin('foo', 123) %]
equivalent to:
Template::Plugin::MyPlugin->new($context, 'foo', 123);
Named parameters may also be specified. These are collated into a hash which is passed by reference as the last parameter to the constructor, as per the general code calling interface.
[% USE url('/cgi-bin/foo', mode='submit', debug=1) %]
equivalent to:
Template::Plugin::URL->new($context, '/cgi-bin/foo'
{ mode => 'submit', debug => 1 });
The plugin may represent any data type; a simple variable, hash, list or code reference, but in the general case it will be an object reference. Methods can be called on the object (or the relevant members of the specific data type) in the usual way:
[% USE table(mydata, rows=3) %]
[% FOREACH row = table.rows %]
<tr>
[% FOREACH item = row %]
<td>[% item %]</td>
[% END %]
</tr>
[% END %]
An alternative name may be provided for the plugin by which it can be referenced:
[% USE scores = table(myscores, cols=5) %]
[% FOREACH row = scores.rows %]
...
[% END %]
You can use this approach to create multiple plugin objects with different configurations. This example shows how the 'format' plugin is used to create sub-routines bound to variables for formatting text as per printf().
[% USE bold = format('<b>%s</b>') %]
[% USE ital = format('<i>%s</i>') %]
[% bold('This is bold') %]
[% ital('This is italic') %]
Output:
<b>This is bold</b>
<i>This is italic</i>
This next example shows how the URL plugin can be used to build dynamic URLs from a base part and optional query parameters.
[% USE mycgi = URL('/cgi-bin/foo.pl', debug=1) %]
<a href="[% mycgi %]">...
<a href="[% mycgi(mode='submit') %]"...
Output:
<a href="/cgi-bin/foo.pl?debug=1">...
<a href="/cgi-bin/foo.pl?mode=submit&debug=1">...
The CGI plugin is an example of one which delegates to another Perl module. In this this case, it is to Lincoln Stein's CGI.pm module. All of the methods provided by CGI.pm are available via the plugin.
[% USE CGI %]
[% CGI.start_form %]
[% CGI.checkbox_group(name => 'colours',
values => [ 'red' 'green' 'blue' ])
%]
[% CGI.popup_menu(name => 'items',
values => [ 'foo' 'bar' 'baz' ])
%]
[% CGI.end_form %]
Simon Matthews has written the DBI plugin which provides an interface to Tim Bunce's DBI module (available from CPAN). Here's a short example:
[% USE DBI('DBI:mSQL:mydbname') %]
[% FOREACH user = DBI.query('SELECT * FROM users') %]
[% user.id %] [% user.name %] [% user.etc.etc %]
[% END %]
See TEMPLATE TOOLKIT PLUGINS for more information on the plugins distributed with the toolkit or available from CPAN.
The LOAD_PERL option (disabled by default) provides a further way by
which external Perl modules may be loaded. If a regular Perl module
(i.e. not a Template::Plugin::* or other module relative to some
PLUGIN_BASE) supports an object-oriented interface and a new()
constructor then it can be loaded and instantiated automatically. The
following trivial example shows how the IO::File module might be used.
[% USE file = IO.File('/tmp/mydata') %]
[% WHILE (line = file.getline) %]
<!-- [% line %] -->
[% END %]
[% MACRO header INCLUDE header %]
Calling the macro as:
[% header %]
is then equivalent to:
[% INCLUDE header %]
Macros can be passed named parameters when called. These values remain local to the macro.
[% header(title='Hello World') %]
equivlant to:
[% INCLUDE header title='Hello World' %]
A MACRO definition may include parameter names. Values passed to the macros are then mapped to these local variables. Other named parameters may follow these.
[% MACRO header(title) INCLUDE header %]
[% header('Hello World') %]
[% header('Hello World', bgcol='#123456') %]
equivalent to:
[% INCLUDE header title='Hello World' %]
[% INCLUDE header title='Hello World' bgcol='#123456# %]
A MACRO may preceed any directive and must conform to the structure of the directive.
[% MACRO header IF frames %]
[% INCLUDE frames/header %]
[% ELSE %]
[% INCLUDE header %]
[% END %]
[% header %]
A MACRO may also be defined as an anonymous BLOCK. The block will be evaluated each time the macro is called.
[% MACRO header BLOCK %]
...content...
[% END %]
[% header %]
Perl code is evaluated in the Template::Perl package. The $context package variable contains a reference to the current Template::Context object. This can be used to access the functionality of the Template Toolkit to process other templates, load plugins, filters, etc. See the Template::Context manpage for further details.
[% PERL %]
print $context->include('myfile');
[% END %]
The $stash variable contains a reference to the top-level stash object which manages template variables. Through this, variable values can be retrieved and updated. See the Template::Stash manpage for further details.
[% PERL %]
$stash->set(foo => 'bar');
print "foo value: ", $stash->get('foo');
[% END %]
Output foo value: bar
Output is generated from the PERL block by calling print(). Note that the Template::Perl::PERLOUT handle is selected (tied to an output buffer) instead of STDOUT.
[% PERL %]
print "foo\n"; # OK
print PERLOUT "bar\n"; # OK, same as above
print Template::Perl::PERLOUT "baz\n"; # OK, same as above
print STDOUT "qux\n"; # WRONG!
[% END %]
The PERL block may contain other template directives. These are processed before the Perl code is evaluated.
[% name = 'Fred Smith' %]
[% PERL %]
print "[% name %]\n";
[% END %]
Thus, the Perl code in the above example is evaluated as:
print "Fred Smith\n";
Exceptions may be thrown from within PERL blocks via die() and will be
correctly caught by enclosing TRY blocks.
[% TRY %]
[% PERL %]
die "nothing to live for\n";
[% END %]
[% CATCH %]
error: [% error.info %]
[% END %]
output: error: nothing to live for
eval() to evaluate
it into a subroutine reference. This subroutine is then called to
process the template, passing a reference to the current
Template::Context object through which the functionality of the
Template Toolkit can be accessed. The subroutine reference can be
cached, allowing the template to be processed repeatedly without
requiring any further parsing.
For example, a template such as:
[% PROCESS header %]
The [% animal %] sat on the [% location %]
[% PROCESS footer %]
is converted into the following Perl subroutine definition:
sub {
my $context = shift;
my $stash = $context->stash;
my $output = '';
my $error;
eval { BLOCK: {
$output .= $context->process('header');
$output .= "The ";
$output .= $stash->get('animal');
$output .= " sat on the ";
$output .= $stash->get('location');
$output .= $context->process('footer');
$output .= "\n";
} };
if ($@) {
$error = $context->catch($@, \$output);
die $error unless $error->type eq 'return';
}
return $output;
}
To examine the Perl code generated, such as in the above example, set the $Template::Parser::DEBUG package variable to any true value. You can also set the $Template::Directive::PRETTY variable true to have the code formatted in a readable manner for human consumption. The source code for each generated template subroutine will be printed to STDERR on compilation (i.e. the first time a template is used).
$Template::Parser::DEBUG = 1;
$Template::Directive::PRETTY = 1;
...
$template->process($file, $vars)
|| die $template->error(), "\n";
The PERL ... END construct allows Perl code to be embedded into a
template (when the EVAL_PERL option is set), but it is evaluated at
``runtime'' using eval() each time the template subroutine is called.
This is inherently flexible, but not as efficient as it could be,
especially in a persistant server environment where a template may be
processed many times.
The RAWPERL directive allows you to write Perl code that is integrated directly into the generated Perl subroutine text. It is evaluated once at compile time and is stored in cached form as part of the compiled template subroutine. This makes RAWPERL blocks more efficient than PERL blocks.
The downside is that you must code much closer to the metal. Within
PERL blocks, you can call print() to generate some output. RAWPERL
blocks don't afford such luxury. The code is inserted directly into
the generated subroutine text and should conform to the convention of
appending to the '$output' variable.
[% PROCESS header %]
[% RAWPERL %]
$output .= "Some output\n";
...
$output .= "Some more output\n";
[% END %]
The critical section of the generated subroutine for this example would then look something like:
...
eval { BLOCK: {
$output .= $context->process('header');
$output .= "\n";
$output .= "Some output\n";
...
$output .= "Some more output\n";
$output .= "\n";
} };
...
As with PERL blocks, the $context and $stash references are pre-defined and available for use within RAWPERL code.
[% TRY %]
...blah...blah...
[% CALL somecode %]
...etc...
[% INCLUDE someblock %]
...and so on...
[% CATCH %]
An error occurred!
[% END %]
Errors are raised as exceptions (objects of the Template::Exception class) and contain two fields, 'type' and 'info'. The exception 'type' can be any string containing letters, numbers, '_' or '.', and is used to indicate the kind of error that occurred. The 'info' field contains an error message indicating what actually went wrong. Within a catch block, the exception object is aliased to the 'error' variable. You can access the 'type' and 'info' fields directly.
[% mydsn = 'dbi:MySQL:foobar' %]
...
[% TRY %]
[% USE DBI(mydsn) %]
[% CATCH %]
ERROR! Type: [% error.type %]
Info: [% error.info %]
[% END %]
output (assuming a non-existant database called 'foobar'):
ERROR! Type: DBI
Info: Unknown database "foobar"
The 'error' variable can also be specified by itself and will return a string of the form ``$type error - $info''.
...
[% CATCH %]
ERROR: [% error %]
[% END %]
output:
ERROR: DBI error - Unknown database "foobar"
Each CATCH block may be specified with a particular exception type denoting the kind of error that it should catch. Multiple CATCH blocks can be provided to handle different types of exception that may be thrown in the TRY block. A CATCH block specified without any type, as in the previous example, is a default handler which will catch any otherwise uncaught exceptions. This can also be specified as [% CATCH DEFAULT %].
[% TRY %]
[% INCLUDE myfile %]
[% USE DBI(mydsn) %]
[% CALL somecode %]
...
[% CATCH file %]
File Error! [% error.info %]
[% CATCH DBI %]
[% INCLUDE database/error.html %]
[% CATCH %]
[% error %]
[% END %]
Remember that you can specify multiple directives within a single tag, each delimited by ';'. Thus, you might prefer to write your simple CATCH blocks more succinctly as:
[% TRY %]
...
[% CATCH file; "File Error! $error.info" %]
[% CATCH DBI; INCLUDE database/error.html %]
[% CATCH; error %]
[% END %]
or even:
[% TRY %]
...
[% CATCH file ;
"File Error! $error.info" ;
CATCH DBI ;
INCLUDE database/error.html ;
CATCH ;
error ;
END
%]
The DBI plugin throws exceptions of the 'DBI' type (in case that wasn't already obvious). The other specific exception caught here is of the 'file' type.
A 'file' error is automatically thrown by the Template Toolkit when it can't find a file, or fails to load, parse or process a file that has been requested by an INCLUDE, PROCESS, INSERT or WRAPPER directive. If 'myfile' can't be found in the example above, the [% INCLUDE myfile %] directive will raise a 'file' exception which is then caught by the [% CATCH file %] block, generating the output:
File Error! myfile: not found
Note that the DEFAULT option (disabled by default) allows you to specify a default file to be used any time a template file can't be found. This will prevent file exceptions from ever being raised when a non-existant file is requested (unless, of course, the DEFAULT file doesn't exist). Errors encountered once the file has been found (i.e. read error, parse error) will be raised as file exceptions as per usual.
Uncaught exceptions (i.e. the TRY block doesn't have a type specific
or default CATCH handler) may be caught by enclosing TRY blocks which
can be nested indefinately across multiple templates. If the error
isn't caught at any level then processing will stop and the Template
process() method will return a false value to the caller. The
relevant Template::Exception object can be retrieved by calling the
error() method.
[% TRY %]
...
[% TRY %]
[% INCLUDE $user.header %]
[% CATCH file %]
[% INCLUDE header %]
[% END %]
...
[% CATCH DBI %]
[% INCLUDE database/error.html %]
[% END %]
In this example, the inner TRY block is used to ensure that the first INCLUDE directive works as expected. We're using a variable to provide the name of the template we want to include, user.header, and it's possible this contains the name of a non-existant template, or perhaps one containing invalid template directives. If the INCLUDE fails with a 'file' error then we CATCH it in the inner block and INCLUDE the default 'header' file instead. Any DBI errors that occur within the scope of the outer TRY block will be caught in the relevant CATCH block, causing the 'database/error.html' template to be processed. Note that included templates inherit all currently defined template variable so these error files can quite happily access the 'error' variable to retrieve information about the currently caught exception. e.g.
'database/error.html':
<h2>Database Error</h2>
A database error has occurred: [% error.info %]
You can also specify a FINAL block. This is always processed regardless of the outcome of the TRY and/or CATCH block. If an exception is uncaught then the FINAL block is processed before jumping to the enclosing block or returning to the caller.
[% TRY %]
...
[% CATCH this %]
...
[% CATCH that %]
...
[% FINAL %]
All done!
[% END %]
The output from the TRY block is left intact up to the point where an exception occurs. For example, this template:
[% TRY %]
This gets printed
[% THROW food 'carrots' %]
This doesn't
[% CATCH food %]
culinary delights: [% error.info %]
[% END %]
generates the following output:
This gets printed
culinary delights: carrots
The CLEAR directive can be used in a CATCH or FINAL block to clear any output created in the TRY block.
[% TRY %]
This gets printed
[% THROW food 'carrots' %]
This doesn't
[% CATCH food %]
[% CLEAR %]
culinary delights: [% error.info %]
[% END %]
output:
culinary delights: carrots
Exception types are hierarchical, with each level being separated by the familiar dot operator. A 'DBI.connect' exception is a more specific kind of 'DBI' error. Similarly, a 'myown.error.barf' is a more specific kind of 'myown.error' type which itself is also a 'myown' error. A CATCH handler that specifies a general exception type (such as 'DBI' or 'myown.error') will also catch more specific types that have the same prefix as long as a more specific handler isn't defined. Note that the order in which CATCH handlers are defined is irrelevant; a more specific handler will always catch an exception in preference to a more generic or default one.
[% TRY %]
...
[% CATCH DBI ;
INCLUDE database/error.html ;
CATCH DBI.connect ;
INCLUDE database/connect.html ;
CATCH ;
INCLUDE error.html ;
END
%]
In this example, a 'DBI.connect' error has it's own handler, a more general 'DBI' block is used for all other DBI or DBI.* errors and a default handler catches everything else.
Exceptions can be raised in a template using the THROW directive. The first parameter is the exception type which doesn't need to be quoted (but can be, it's the same as INCLUDE) followed by the relevant error message which can be any regular value such as a quoted string, variable, etc.
[% THROW food "Missing ingredients: $recipe.error" %]
[% THROW user.login 'no user id: please login' %]
[% THROW $myerror.type "My Error: $myerror.info" %]
Exceptions can also be thrown from Perl code which you've bound to
template variables, or defined as a plugin or other extension. To
raise an exception, call die() passing a reference to a
Template::Exception object as the argument. This will then be caught
by any enclosing TRY blocks from where the code was called.
use Template::Exception;
...
my $vars = {
foo => sub {
# ... do something ...
die Template::Exception->new('myerr.naughty',
'Bad, bad error');
},
};
template:
[% TRY %]
...
[% foo %]
...
[% CATCH myerr ;
"Error: $error" ;
END
%]
output:
Error: myerr.naughty error - Bad, bad error
You can also call die() with a single string, as is common in much
existing Perl code. This will automatically be converted to an
exception of the 'undef' type (that's the literal string 'undef',
not the undefined value). If the string isn't terminated with a
newline then Perl will append the familiar `` at $file line $line''
message.
sub foo {
# ... do something ...
die "I'm sorry, Dave, I can't do that\n";
}
If you're writing a plugin, or some extension code that has the
current Template::Context in scope (you can safely skip this section
if this means nothing to you) then you can also raise an exception by
calling the context throw() method. You can pass it an
Template::Exception object reference, a pair of ($type, $info) parameters
or just an $info string to create an exception of 'undef' type.
$context->throw($e); # exception object
$context->throw('Denied'); # 'undef' type
$context->throw('user.passwd', 'Bad Password');
[% FOREACH user = userlist %]
[% NEXT IF user.isguest %]
Name: [% user.name %] Email: [% user.email %]
[% END %]
[% FOREACH user = userlist %]
Name: [% user.name %] Email: [% user.email %]
[% LAST IF some.condition %]
[% END %]
BREAK can also be used as an alias for LAST.
process() method will return to the calling code with a
true value.
Before
[% INCLUDE half_wit %]
After
[% BLOCK half_wit %]
This is just half...
[% RETURN %]
...a complete block
[% END %]
output:
Before
This is just half...
After
process() method will return a
true value to the caller. This indicates that the template was
processed successfully according to the directives within it.
[% IF something.terrible.happened %]
[% INCLUDE fatal/error.html %]
[% STOP %]
[% END %]
[% TRY %]
[% USE DBI(mydsn) %]
...
[% CATCH DBI.connect %]
<p>Cannot connect to the database: [% error.info %]</p>
<br>
We apologise for the inconvenience. The cleaning lady
has removed the server power to plug in her vacuum cleaner.
Please try again later.
</p>
[% INCLUDE footer %]
[% STOP %]
[% END %]
[% TRY %]
blah blah blah # this is normally left intact
[% THROW some 'error' %] # up to the point of error
...
[% CATCH %]
[% CLEAR %] # clear the TRY output
[% error %] # print error string
[% END %]
[% META
title = 'The Cat in the Hat'
author = 'Dr. Seuss'
version = 1.23
%]
The 'template' variable contains a reference to the main template being processed. These metadata items may be retrieved as attributes of the template.
<h1>[% template.title %]</h1>
<h2>[% template.author %]</h2>
The 'name' and 'modtime' metadata items are automatically defined for each template to contain its name and modification time in seconds since the epoch.
[% USE date %] # use Date plugin to format time
...
[% template.name %] last modified
at [% date.format(template.modtime) %]
The PRE_PROCESS and POST_PROCESS options allow common headers and footers to be added to all templates. The 'template' reference is correctly defined when these templates are processed, allowing headers and footers to reference metadata items from the main template.
$template = Template->new({
PRE_PROCESS => 'header',
POST_PROCESS => 'footer',
});
$template->process('cat_in_hat');
header: <html> <head> <title>[% template.title %]</title> </head> <body>
cat_in_hat: [% META title = 'The Cat in the Hat' author = 'Dr. Seuss' version = 1.23 year = 2000 %]
The cat in the hat sat on the mat.
footer: <hr> © [% template.year %] [% template.author %] </body> </html>
The output generated from the above example is:
<html>
<head>
<title>The Cat in the Hat</title>
</head>
<body>
The cat in the hat sat on the mat.
<hr>
© 2000 Dr. Seuss
</body>
</html>
[% TAGS <+ +> %]
<+ INCLUDE header +>
The TAGS directive may also be used to set a named TAG_STYLE
[% TAGS html %]
<!-- INCLUDE header -->
See the TAGS and TAG_STYLE configuration options for further details.
The Template module accepts configuration items destined for any other Template::* module that it may create and will forward them appropriately. The following list summarises the various options under several broad categories.
[% example %]
Any Perl regex characters can be used and therefore should be escaped
(or use the Perl quotemeta function) if they are intended to
represent literal characters.
my $template = Template->new({
START_TAG => quotemeta('<+'),
END_TAG => quotemeta('+>'),
});
example:
<+ INCLUDE foobar +>
The TAGS directive can also be used to set the START_TAG and END_TAG values on a per-template file basis.
[% TAGS <+ +> %]
my $template = Template->new({
TAG_STYLE => 'php',
});
Available styles are:
template [% ... %] (default)
template1 [% ... %] or %% ... %% (Template version 1)
metatext %% ... %% (Text::MetaText)
php <? ... ?> (PHP)
asp <% ... %> (ASP)
mason <% ... > (HTML::Mason)
html <!-- ... --> (HTML comments)
Any values specified for START_TAG and/or END_TAG will over-ride those defined by a TAG_STYLE.
The TAGS directive may also be used to set a TAG_STYLE
[% TAGS html %]
<!-- INCLUDE header -->
Example:
Foo
[% a = 10 %]
Bar
Output:
Foo
Bar
The PRE_CHOMP and POST_CHOMP options can help to clean up some of this extraneous whitespace. Both are disabled by default.
my $template = Template->new({
PRE_CHOMP => 1,
POST_CHOMP => 1,
});
With PRE_CHOMP set true, the newline and whitespace preceeding a directive at the start of a line will be deleted. This has the effect of concatenating a line that starts with a directive onto the end of the previous line.
Foo <----------.
|
,---(PRE_CHOMP)----'
|
`-- [% a = 10 %] --.
|
,---(POST_CHOMP)---'
|
`-> Bar
With POST_CHOMP set true, any whitespace after a directive up to and including the newline will be deleted. This has the effect of joining a line that ends with a directive onto the start of the next line.
PRE_CHOMP and POST_CHOMP can be activated for individual directives by placing a '-' immediately at the start and/or end of the directive.
[% FOREACH user = userlist %]
[%- user -%]
[% END %]
The '-' characters activate both PRE_CHOMP and POST_CHOMP for the one directive '[%- name -%]'. Thus, the template will be processed as if written:
[% FOREACH user = userlist %][% user %][% END %]
Similarly, '+' characters can be used to disable PRE_CHOMP or POST_CHOMP (i.e. leave the whitespace/newline intact) options on a per-directive basis.
[% FOREACH user = userlist %]
User: [% user +%]
[% END %]
With POST_CHOMP enabled, the above example would be parsed as if written:
[% FOREACH user = userlist %]User: [% user %]
[% END %]
By example, the following BLOCK definition
[% BLOCK foo %]
Line 1 of foo
[% END %]
will be processed is as ``\nLine 1 of foo\n''. When INCLUDEd, the surrounding newlines will also be introduced.
before
[% INCLUDE foo %]
after
output: before
Line 1 of foo
after
With the TRIM option set to any true value, the leading and trailing newlines (which count as whitespace) will be removed from the output of the BLOCK.
before
Line 1 of foo
after
The TRIM option is disabled (0) by default.
my $template = Template->new({
INTERPOLATE => 1,
});
Variables should be prefixed by a '$' to identify them. Curly braces can be used in the familiar Perl/shell style to explicitly scope the variable name where required.
# INTERPOLATE => 0
<a href="http://[% server %]/[% help %]">
<img src="[% images %]/help.gif"></a>
[% myorg.name %]
# INTERPOLATE => 1
<a href="http://$server/$help">
<img src="$images/help.gif"></a>
$myorg.name
# explicit scoping with { }
<img src="$images/${icon.next}.gif">
Note that a limitation in Perl's regex engine restricts the maximum length of an interpolated template to around 32 kilobytes or possibly less. Files that exceed this limit in size will typically cause Perl to dump core with a segmentation fault. If you routinely process templates of this size then you should disable INTERPOLATE or split the templates in several smaller files or blocks which can then be joined backed together via PROCESS or INCLUDE.
# ANYCASE => 0 (default)
[% INCLUDE foobar %] # OK
[% include foobar %] # ERROR
[% include = 10 %] # OK, 'include' is a variable
# ANYCASE => 1
[% INCLUDE foobar %] # OK
[% include foobar %] # OK
[% include = 10 %] # ERROR, 'include' is reserved word
One side-effect of enabling ANYCASE is that you cannot use a variable of the same name as a reserved word, regardless of case. The reserved words are currently:
GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
CLEAR TO STEP AND OR NOT MOD DIV END
The only lower case reserved words that cannot be used for variables, regardless of the ANYCASE option, are the operators:
and or not mod div
my $template = Template->new({
INCLUDE_PATH => '/usr/local/templates',
});
my $template = Template->new({
INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
});
my $template = Template->new({
INCLUDE_PATH => [ '/usr/local/templates',
'/tmp/my/templates' ],
});
# tolerate Silly Billy's file system conventions
my $template = Template->new({
DELIMITER => ' ',
INCLUDE_PATH => 'C:/HERE/NOW D:/THERE/THEN',
});
# better solution: install Linux! :-)
my $template = Template->new({
ABSOLUTE => 1,
});
# this is why it's disabled by default
[% INSERT /etc/passwd %]
my $template = Template->new({
RELATIVE => 1,
});
[% INCLUDE ../logs/error.log %]
my $template = Template->new({
DEFAULT => 'notfound.html',
});
If a non-existant template is requested through the Template process()
method, or by an INCLUDE, PROCESS or WRAPPER directive, then the
DEFAULT template will instead be processed, if defined. Note that the
DEFAULT template is not used when templates are specified with
absolute or relative filenames, or as a reference to a input file
handle or text string.
my $template = Template->new({
BLOCKS => {
header => 'The Header. [% title %]',
footer => sub { return $some_output_text },
another => Template::Document->new({ ... }),
},
});
process() method. This ensures that any BLOCKs defined
within a template will only persist until that template is finished
processing. This prevents BLOCKs defined in one processing request
from interfering with other independant requests subsequently
processed by the same context object.
The BLOCKS item may be used to specify a default set of block definitions
for the Template::Context object. Subsequent BLOCK definitions in templates
will over-ride these but they will be reinstated on each reset if AUTO_RESET
is enabled (default), or if the Template::Context reset() method is called.
my $template = Template->new({
VARIABLES => {
title => 'A Demo Page',
author => 'Joe Random Hacker',
version => 3.14,
},
};
or
my $template = Template->new({
PRE_DEFINE => {
title => 'A Demo Page',
author => 'Joe Random Hacker',
version => 3.14,
},
};
name(s) of template files
(relative to INCLUDE_PATH) which should be processed immediately
before and/or after each template. These do not get added to
templates processed into a document via directives such as INCLUDE,
PROCESS, WRAPPER etc.
my $template = Template->new({
PRE_PROCESS => 'header',
POST_PROCESS => 'footer',
};
Multiple templates may be specified as a reference to a list. Each is processed in the order defined.
my $template = Template->new({
PRE_PROCESS => [ 'config', 'header' ],
POST_PROCESS => 'footer',
};
Alternately, multiple template may be specified as a single string, delimited by ':'. This delimiter string can be changed via the DELIMITER option.
my $template = Template->new({
PRE_PROCESS => 'config:header',
POST_PROCESS => 'footer',
};
The PRE_PROCESS and POST_PROCESS templates are evaluated in the same variable context as the main document and may define or update variables for subseqent use.
config: [% # set some site-wide variables bgcolor = '#ffffff' version = 2.718 %]
header: [% DEFAULT title = 'My Funky Web Site' %] <html> <head> <title>[% title %]</title> </head> <body bgcolor=``[% bgcolor %]''>
footer: <hr> Version [% version %] </body> </html>
The Template::Document object representing the main template being processed is available within PRE_PROCESS and POST_PROCESS templates as the 'template' variable. Metadata items defined via the META directive may be accessed accordingly.
$template->process('mydoc.html', $vars);
mydoc.html: [% META title = 'My Document Title' %] blah blah blah ...
header: <html> <head> <title>[% template.title %]</title></head> <body bgcolor=``[% bgcolor %]''>
name(s) of template files
(relative to INCLUDE_PATH) which should be processed instead of the
main template passed to the Template process() method. This can
be used to apply consistent wrappers around all templates, similar to
the use of PRE_PROCESS and POST_PROCESS templates.
my $template = Template->new({
PROCESS => 'content',
};
# processes 'content' instead of 'foo.html'
$template->process('foo.html');
A reference to the original template is available in the 'template' variable. Metadata items can be inspected and the template can be processed by specifying it as a variable reference (i.e. prefixed by '$') to an INCLUDE, PROCESS or WRAPPER directive.
content:
<html>
<head>
<title>[% template.title %]</title>
</head>
<body>
[% PROCESS $template %]
<hr>
© Copyright [% template.copyright %]
</body>
</html>
foo.html:
[% META
title = 'The Foo Page'
author = 'Fred Foo'
copyright = '2000 Fred Foo'
%]
<h1>[% template.title %]</h1>
Welcome to the Foo Page, blah blah blah
output:
<html>
<head>
<title>The Foo Page</title>
</head>
<body>
<h1>The Foo Page</h1>
Welcome to the Foo Page, blah blah blah
<hr>
© Copyright 2000 Fred Foo
</body>
</html>
If specified as a single value then that template will be processed for all uncaught exceptions.
my $template = Template->new({
ERROR => 'error.html'
});
If the ERROR item is a hash reference the keys are assumed to be exception types and the relevant template for a given exception will be selected. A 'default' template may be provided for the general case. Note that 'ERROR' can be pluralised to 'ERRORS' if you find it more appropriate in this case.
my $template = Template->new({
ERRORS => {
user => 'user/index.html',
dbi => 'error/database',
default => 'error/default',
},
});
In this example, any 'user' exceptions thrown will cause the 'user/index.html' template to be processed, 'dbi' errors are handled by 'error/database' and all others by the 'error/default' template. Any PRE_PROCESS and/or POST_PROCESS templates will also be applied to these error templates.
Note that exception types are hierarchical and a 'foo' handler will
catch all 'foo.*' errors (e.g. foo.bar, foo.bar.baz) if a more
specific handler isn't defined. Be sure to quote any exception types
that contain periods to prevent Perl concatenating them into a single
string (i.e. user.passwd is parsed as 'user'.'passwd').
my $template = Template->new({
ERROR => {
'user.login' => 'user/login.html',
'user.passwd' => 'user/badpasswd.html',
'user' => 'user/index.html',
'default' => 'error/default',
},
});
In this example, any template processed by the $template object, or other templates or code called from within, can raise a 'user.login' exception and have the service redirect to the 'user/login.html' template. Similarly, a 'user.passwd' exception has a specific handling template, 'user/badpasswd.html', while all other 'user' or 'user.*' exceptions cause a redirection to the 'user/index.html' page. All other exception types are handled by 'error/default'.
Exceptions can be raised in a template using the THROW directive,
[% THROW user.login 'no user id: please login' %]
or by calling the throw() method on the current Template::Context object,
$context->throw('user.passwd', 'Incorrect Password');
$context->throw('Incorrect Password'); # type 'undef'
or from Perl code by calling die() with a Template::Exception object,
die Template::Exception->new('user.denied', 'Invalid User ID');
or by simply calling die() with an error string. This is
automagically caught and converted to an exception of 'undef'
type which can then be handled in the usual way.
die "I'm sorry Dave, I can't do that";
print()
method. This latter option includes the Apache::Request object which
is passed as the argument to Apache/mod_perl handlers.
example 1 (file name):
my $template = Template->new({
OUTPUT => "/tmp/foo",
});
example 2 (text string):
my $output = '';
my $template = Template->new({
OUTPUT => \$output,
});
example 3 (file handle):
open (TOUT, "> $file") || die "$file: $!\n";
my $template = Template->new({
OUTPUT => \*TOUT,
});
example 4 (subroutine):
sub output { my $out = shift; print "OUTPUT: $out" }
my $template = Template->new({
OUTPUT => \&output,
});
example 5 (Apache/mod_perl handler):
sub handler {
my $r = shift;
my $t = Template->new({
OUTPUT => $r,
});
...
}
The default OUTPUT location be overridden by passing a third parameter
to the Template process() method. This can be specified as any of the
above argument types.
$t->process($file, $vars, "/tmp/foo");
$t->process($file, $vars, "bar");
$t->process($file, $vars, \*MYGLOB);
$t->process($file, $vars, $r); # Apache::Request
...
process() method.
my $template = Template->new({
INPUT_PATH => "/tmp/src",
OUTPUT_PATH => "/tmp/dest",
});
my $vars = {
...
};
foreach my $file ('foo.html', 'bar.html') {
$template->process($file, $vars, $file)
|| die $template->error();
}
This example will read the input files '/tmp/src/foo.html' and '/tmp/src/bar.html' and write the processed output to '/tmp/dest/foo.html' and '/tmp/dest/bar.html', respectively.
By default, the CACHE_SIZE is undefined and all compiled templates are cached. When set to any positive value, the cache will be limited to storing no more than that number of compiled templates. When a new template is loaded and compiled and the cache is full (i.e. the number of entries == CACHE_SIZE), the least recently used compiled template is discarded to make room for the new one.
The CACHE_SIZE can be set to 0 to disable caching altogether.
my $template = Template->new({
CACHE_SIZE => 64, # only cache 64 compiled templates
});
my $template = Template->new({
CACHE_SIZE => 0, # don't cache any compiled templates
});
my $template = Template->new({
COMPILE_EXT => '.ttc',
});
If COMPILE_EXT is defined (and COMPILE_DIR isn't, see below) then compiled template files with the COMPILE_EXT extension will be written to the same directory from which the source template files were loaded.
Compiling and subsequent reuse of templates happens automatically whenever the COMPILE_EXT or COMPILE_DIR options are set. The Template Toolkit will automatically reload and reuse compiled files when it finds them on disk. If the corresponding source file has been modified since the compiled version as written, then it will load and re-compile the source and write a new compiled version to disk.
This form of cache persistance offers significant benefits in terms of time and resources required to reload templates. Compiled templates can be reloaded by a simple call to Perl's require(), leaving Perl to handle all the parsing and compilation. This is a Good Thing.
my $template = Template->new({
COMPILE_DIR => '/tmp/ttc',
});
The COMPILE_EXT option may also be specified to have a consistent file extension added to these files.
my $template1 = Template->new({
COMPILE_DIR => '/tmp/ttc',
COMPILE_EXT => '.ttc1',
});
my $template2 = Template->new({
COMPILE_DIR => '/tmp/ttc',
COMPILE_EXT => '.ttc2',
});
When COMPILE_EXT is undefined, the compiled template files have the same name as the original template files, but reside in a different directory tree.
Each directory in the INCLUDE_PATH is replicated in full beneath the COMPILE_DIR directory. This example:
my $template = Template->new({
COMPILE_DIR => '/tmp/ttc',
INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
});
would create the following directory structure:
/tmp/ttc/home/abw/templates/
/tmp/ttc/usr/share/templates/
Files loaded from different INCLUDE_PATH directories will have their compiled forms save in the relevant COMPILE_DIR directory.
my $template = Template->new({
PLUGINS => [
cgi => 'MyOrg::Template::Plugin::CGI',
foo => 'MyOrg::Template::Plugin::Foo',
bar => 'MyOrg::Template::Plugin::Bar',
],
});
The USE directive is used to create plugin objects and does so by
calling the plugin() method on the current Template::Context object.
If the plugin name is defined in the PLUGINS hash then the
corresponding Perl module is loaded via require(). The context then
calls the load() class method which should return the class name
(default and general case) or a prototype object against which the
new() method can be called to instantiate individual plugin objects.
If the plugin name is not defined in the PLUGINS hash then the PLUGIN_BASE and/or LOAD_PERL options come into effect.
The PLUGIN_BASE can be specified as a single value or as a reference to an array of multiple values. The default PLUGIN_BASE value, 'Template::Plugin', is always added the the end of the PLUGIN_BASE list (a single value is first converted to a list). Each value should contain a Perl package name to which the requested plugin name is appended.
example 1:
my $template = Template->new({
PLUGIN_BASE => 'MyOrg::Template::Plugin',
});
[% USE Foo %] # => MyOrg::Template::Plugin::Foo
or Template::Plugin::Foo
example 2:
my $template = Template->new({
PLUGIN_BASE => [ 'MyOrg::Template::Plugin',
'YourOrg::Template::Plugin' ],
});
[% USE Foo %] # => MyOrg::Template::Plugin::Foo
or YourOrg::Template::Plugin::Foo
or Template::Plugin::Foo
By default, the LOAD_PERL option is set to 0 and no attempt will be made to load any Perl modules that aren't named explicitly in the PLUGINS hash or reside in a package as named by one of the PLUGIN_BASE components.
Plugins loaded using the PLUGINS or PLUGIN_BASE receive a reference to
the current context object as the first argument to the new()
constructor. Modules loaded using LOAD_PERL are assumed to not
conform to the plugin interface. They must provide a new() class
method for instantiating objects but it will not receive a reference
to the context as the first argument. Plugin modules should provide a
load() class method (or inherit the default one from the
Template::Plugin base class) which is called the first time the plugin
is loaded. Regular Perl modules need not. In all other respects,
regular Perl objects and Template Toolkit plugins are identical.
If a particular Perl module does not conform to the common, but not
unilateral, new() constructor convention then a simple plugin wrapper
can be written to interface to it.
The FILTERS option should be specified as a reference to a hash array in which each key represents the name of a filter. The corresponding value should contain a reference to an array containing a subroutine reference and a flag which indicates if the filter is static (0) or dynamic (1). A filter may also be specified as a solitary subroutine reference and is assumed to be static.
$template = Template->new({
FILTERS => {
'sfilt1' => \&static_filter, # static
'sfilt2' => [ \&static_filter, 0 ], # same as above
'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
},
});
Additional filters can be specified at any time by calling the
define_filter() method on the current Template::Context object.
The method accepts a filter name, a reference to a filter
subroutine and an optional flag to indicate if the filter is
dynamic.
my $context = $template->context();
$context->define_filter('new_html', \&new_html);
$context->define_filter('new_repeat', \&new_repeat, 1);
Static filters are those where a single subroutine reference is used for all invocations of a particular filter. Filters that don't accept any configuration parameters (e.g. 'html') can be implemented statically. The subroutine reference is simply returned when that particular filter is requested. The subroutine is called to filter the output of a template block which is passed as the only argument. The subroutine should return the modified text.
sub static_filter {
my $text = shift;
# do something to modify $text...
return $text;
}
The following template fragment:
[% FILTER sfilt1 %]
Blah blah blah.
[% END %]
is approximately equivalent to:
&static_filter("\nBlah blah blah.\n");
Filters that can accept parameters (e.g. 'truncate') should be implemented dynamically. In this case, the subroutine is taken to be a filter 'factory' that is called to create a unique filter subroutine each time one is requested. A reference to the current Template::Context object is passed as the first parameter, followed by any additional parameters specified. The subroutine should return another subroutine reference (usually a closure) which implements the filter.
sub dynamic_filter_factory {
my ($context, @args) = @_;
return sub {
my $text = shift;
# do something to modify $text...
return $text;
}
}
The following template fragment:
[% FILTER dfilt1(123, 456) %]
Blah blah blah
[% END %]
is approximately equivalent to:
my $filter = &dynamic_filter_factory($context, 123, 456);
&$filter("\nBlah blah blah.\n");
See the FILTER directive for further examples.
# VERSION 1
[% $foo %] === [% foo %]
[% $hash.$key %] === [% hash.key %]
To interpolate a variable value the '${' ... '}' construct was used. Typically, one would do this to index into a hash array when the key value was stored in a variable.
example:
my $vars = {
users => {
aba => { name => 'Alan Aardvark', ... },
abw => { name => 'Andy Wardley', ... },
...
},
uid => 'aba',
...
};
$template->process('user/home.html', $vars)
|| die $template->error(), "\n";
'user/home.html':
[% user = users.${uid} %] # users.aba
Name: [% user.name %] # Alan Aardvark
This was inconsistent with double quoted strings and also the INTERPOLATE mode, where a leading '$' in text was enough to indicate a variable for interpolation, and the additional curly braces were used to delimit variable names where necessary. Note that this use is consistent with UNIX and Perl conventions, among others.
# double quoted string interpolation
[% name = "$title ${user.name}" %]
# INTERPOLATE = 1
<img src="$images/help.gif"></a>
<img src="$images/${icon.next}.gif">
For version 2, these inconsistencies have been removed and the syntax clarified. A leading '$' on a variable is now used exclusively to indicate that the variable name should be interpolated (e.g. subsituted for its value) before being used. The earlier example from version 1:
# VERSION 1
[% user = users.${uid} %]
Name: [% user.name %]
can now be simplified in version 2 as:
# VERSION 2
[% user = users.$uid %]
Name: [% user.name %]
The leading dollar is no longer ignored and has the same effect of interpolation as '${' ... '}' in version 1. The curly braces may still be used to explicitly scope the interpolated variable name where necessary.
e.g.
[% user = users.${me.id} %]
Name: [% user.name %]
The rule applies for all variables, both within directives and in plain text if processed with the INTERPOLATE option. This means that you should no longer (if you ever did) add a leading '$' to a variable inside a directive, unless you explicitly want it to be interpolated.
One obvious side-effect is that any version 1 templates with variables using a leading '$' will no longer be processed as expected. Given the following variable definitions,
[% foo = 'bar'
bar = 'baz'
%]
version 1 would interpret the following as:
# VERSION 1
[% $foo %] => [% GET foo %] => bar
whereas version 2 interprets it as:
# VERSION 2
[% $foo %] => [% GET $foo %] => [% GET bar %] => baz
In version 1, the '$' is ignored and the value for the variable 'foo' is retrieved and printed. In version 2, the variable '$foo' is first interpolated to give the variable name 'bar' whose value is then retrieved and printed.
The use of the optional '$' has never been strongly recommended, but to assist in backwards compatibility with any version 1 templates that may rely on this ``feature'', the V1DOLLAR option can be set to 1 (default: 0) to revert the behaviour and have leading '$' characters ignored.
my $template = Template->new({
V1DOLLAR => 1,
});
my $template = Template->new({
LOAD_TEMPLATES => [
MyOrg::Template::Provider->new({ ... }),
Template::Provider->new({ ... }),
],
});
When a PROCESS, INCLUDE or WRAPPER directive is encountered, the named
template may refer to a locally defined BLOCK or a file relative to
the INCLUDE_PATH (or an absolute or relative path if the appropriate
ABSOLUTE or RELATIVE options are set). If a BLOCK definition can't be
found (see the Template::Context template() method for a discussion of
BLOCK locality) then each of the LOAD_TEMPLATES provider objects is
queried in turn via the fetch() method to see if it can supply the
required template. Each provider can return a compiled template, an
error, or decline to service the request in which case the
responsiblity is passed to the next provider. If none of the
providers can service the request then a 'not found' error is
returned. The same basic provider mechanism is also used for the
INSERT directive but it bypasses any BLOCK definitions and doesn't
attempt is to parse or process the contents of the template file.
This is an implementation of the 'Chain of Responsiblity' design pattern as described in ``Design Patterns'', Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides), Addision-Wesley, ISBN 0-201-63361-2, page 223.
If LOAD_TEMPLATES is undefined, a single default provider will be instantiated using the current configuration parameters. For example, the Template::Provider INCLUDE_PATH option can be specified in the Template configuration and will be correctly passed to the provider's constructor method.
my $template = Template->new({
INCLUDE_PATH => '/here:/there',
});
fetch() method) which are responsible
for loading and instantiating template plugin objects. The
Template::Content plugin() method queries each provider in turn in a
``Chain of Responsibility'' as per the template() and filter() methods.
my $template = Template->new({
LOAD_PLUGINS => [
MyOrg::Template::Plugins->new({ ... }),
Template::Plugins->new({ ... }),
],
});
By default, a single Template::Plugins object is created using the current configuration hash. Configuration items destined for the Template::Plugins constructor may be added to the Template constructor.
my $template = Template->new({
PLUGIN_BASE => 'MyOrg::Template::Plugins',
LOAD_PERL => 1,
});
fetch() method) which are responsible
for returning and/or creating filter subroutines. The
Template::Context filter() method queries each provider in turn in a
``Chain of Responsibility'' as per the template() and plugin() methods.
my $template = Template->new({
LOAD_FILTERS => [
MyTemplate::Filters->new(),
Template::Filters->new(),
],
});
By default, a single Template::Filters object is created for the LOAD_FILTERS list.
my $template = Template->new({
SERVICE => MyOrg::Template::Service->new({ ... }),
});
process() methods, respectively), to USE a plugin (plugin()) or
instantiate a filter (filter()) or to access the stash (stash()) which
manages variable definitions via the get() and set() methods.
my $template = Template->new({
CONTEXT => MyOrg::Template::Context->new({ ... }),
});
my $stash = MyOrg::Template::Stash->new({ ... });
my $template = Template->new({
STASH => $stash,
});
If unspecified, a default stash object is created using the VARIABLES configuration item to initialise the stash variables. These may also be specified as the PRE_DEFINE option for backwards compatibility with version 1.
my $template = Template->new({
VARIABLES => {
id => 'abw',
name => 'Andy Wardley',
},
};
my $template = Template->new({
PARSER => MyOrg::Template::Parser->new({ ... }),
});
Source templates are compiled to Perl code by the Template::Parser using the Template::Grammar (by default) to define the language structure and semantics. Compiled templates are thus inherently ``compatible'' with each other and there is nothing to prevent any number of different template languages being compiled and used within the same Template Toolkit processing environment (other than the usual time and memory constraints).
The Template::Grammar file is constructed from a YACC like grammar (using Parse::YAPP) and a skeleton module template. These files are provided, along with a small script to rebuild the grammar, in the 'parser' sub-directory of the distribution. You don't have to know or worry about these unless you want to hack on the template language or define your own variant. There is a README file in the same directory which provides some small guidance but it is assumed that you know what you're doing if you venture herein. If you grok LALR parsers, then you should find it comfortably familiar.
By default, an instance of the default Template::Grammar will be created and used automatically if a GRAMMAR item isn't specified.
use MyOrg::Template::Grammar;
my $template = Template->new({
GRAMMAR = MyOrg::Template::Grammar->new();
});
The following standard filters are distributed with the Template Toolkit.
[% FILTER html %]
Binary "<=>" returns -1, 0, or 1 depending on...
[% END %]
output:
Binary "<=>" returns -1, 0, or 1 depending on...
[% FILTER html_para %]
The cat sat on the mat.
Mary had a little lamb.
[% END %]
output:
<p>
The cat sat on the mat.
</p>
<p>
Mary had a little lamb.
</p>
[% FILTER html_break %]
The cat sat on the mat.
Mary had a little lamb.
[% END %]
output:
The cat sat on the mat.
<br>
<br>
Mary had a little lamb.
format(format)printf()) and formats each line of text accordingly.
[% FILTER format('<!-- %-40s -->') %]
This is a block of text filtered
through the above format.
[% END %]
output:
<!-- This is a block of text filtered -->
<!-- through the above format. -->
truncate(length)
[% FILTER truncate(21) %]
I have much to say on this matter that has previously
been said on more than one occassion.
[% END %]
output:
I have much to say...
repeat(iterations)
[% FILTER repeat(3) %]
We want more beer and we want more beer,
[% END %]
We are the more beer wanters!
output:
We want more beer and we want more beer,
We want more beer and we want more beer,
We want more beer and we want more beer,
We are the more beer wanters!
remove(string)
[% "The cat sat on the mat" FILTER remove('\s+') %]
output:
Thecatsatonthemat
[% "The cat sat on the mat" | replace('\s+', '_') %]
output:
The_cat_sat_on_the_mat
redirect(file)
[% FOREACH user = myorg.userlist %]
[% FILTER redirect("users/${user.id}.html") %]
[% INCLUDE userinfo %]
[% END %]
[% END %]
or more succinctly, using side-effect notation:
[% INCLUDE userinfo
FILTER redirect("users/${user.id}.html")
FOREACH user = myorg.userlist
%]
A 'file' exception will be thrown if the OUTPUT_PATH option is undefined.
eval(template_text)
my $vars = {
fragment => "The cat sat on the [% place %]",
};
$template->process($file, $vars);
The following example:
[% fragment | eval %]
is therefore equivalent to
The cat sat on the [% place %]
The 'evaltt' filter is provided as an alias for 'eval'.
perl(perlcode)
[% my_perl_code | perl %]
In most cases, the [% PERL %] ... [% END %] block should suffice for evaluating Perl code, given that template directives are processed before being evaluate as Perl. Thus, the previous example could have been written in the more verbose form:
[% PERL %]
[% my_perl_code %]
[% END %]
as well as
[% FILTER perl %]
[% my_perl_code %]
[% END %]
The 'evalperl' filter is provided as an alias for 'perl' for backwards compatability.
The following plugin modules are distributed with the Template Toolkit. Some of the plugins interface to external modules (detailed below) which should be downloaded from any CPAN site and installed before using the plugin.
[% USE autoformat(left=10, right=20) %]
[% autoformat(mytext) %] # call autoformat sub
[% mytext FILTER autoformat %] # or use autoformat filter
The Text::Autoformat module is available from CPAN:
http://www.cpan.org/modules/by-module/Text/
[% USE CGI %]
[% CGI.param('param_name') %]
[% CGI.start_form %]
[% CGI.popup_menu( Name => 'color',
Values => [ 'Green', 'Brown' ] ) %]
[% CGI.end_form %]
/tmp/mydata:
# define names for each field
id : email : name : tel
# here's the data
fred : fred@here.com : Fred Smith : 555-1234
bill : bill@here.com : Bill White : 555-5678
example:
[% USE userlist = datafile('/tmp/mydata') %]
[% FOREACH user = userlist %]
[% user.name %] ([% user.id %])
[% END %]
strftime() routine. See
the Template::Plugin::Date manpage and POSIX for further details.
[% USE date %]
[% date.format %] # current time/date
File last modified: [% date.format(template.modtime) %]
[% USE DBI('dbi:driver:database', 'user', 'pass') %]
[% FOREACH user = DBI.query( 'SELECT * FROM users' ) %]
[% user.id %] [% user.name %]
[% END %]
The DBI and relevant DBD modules are available from CPAN:
http://www.cpan.org/modules/by-module/DBI/
[% USE dumper(indent=0, pad="<br>") %]
[% dumper.dump(myvar, yourvar) %]
[% USE bold = format('<b>%s</b>') %]
[% bold('Hello') %]
[% USE iterator(list, args) %]
[% FOREACH item = iterator %]
[% '<ul>' IF iterator.first %]
<li>[% item %]
[% '</ul>' IF iterator.last %]
[% END %]
[% USE table(list, rows=10, overlap=1) %]
[% FOREACH item = table.col(3) %]
[% item %]
[% END %]
[% USE mycgi = url('/cgi-bin/bar.pl', debug=1) %]
[% mycgi %]
# ==> /cgi/bin/bar.pl?debug=1
[% mycgi(mode='submit') %]
# ==> /cgi/bin/bar.pl?mode=submit&debug=1
[% USE wrap %]
[% wrap(mytext, 40, '* ', ' ') %] # use wrap sub
[% mytext FILTER wrap(40) -%] # or wrap FILTER
The Text::Wrap module is available from CPAN:
http://www.cpan.org/modules/by-module/Text/
[% USE dom = XML.DOM %]
[% doc = dom.parse(filename) %]
[% FOREACH node = doc.getElementsByTagName('CODEBASE') %]
* [% node.getAttribute('href') %]
[% END %]
The plugin requires the XML::DOM module, available from CPAN:
http://www.cpan.org/modules/by-module/XML/
[% USE xpath = XML.XPath(xmlfile) %]
[% FOREACH page = xpath.findnodes('/html/body/page') %]
[% page.getAttribute('title') %]
[% END %]
The plugin requires the XML::XPath module, available from CPAN:
http://www.cpan.org/modules/by-module/XML/
[% USE news = XML.RSS(filename) %]
[% FOREACH item = news.items %]
<a href="[% item.link %]">[% item.title %]</a>
[% END %]
The XML::RSS module is available from CPAN:
http://www.cpan.org/modules/by-module/XML/
The Template Toolkit web site contains the latest information, news and other resources.
http://www.template-toolkit.org/
A mailing list exists for up-to-date information on the Template Toolkit and for following and contributing to the development process. To subscribe, send an email to
templates-request@template-toolkit.org
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
The tpage and ttree scripts are distributed and installed along with the Template Toolkit. The tpage script simply processes named files or STDIN if unspecified, using a default Template object. The ttree script can be used to process entire directory trees of templates, allowing large content systems such as web sites to be rebuilt from a single command or configuration file.
perldoc tpage
perldoc ttree
The Template::Tutorial document provides an introduction to the Template Toolkit and shows some typical examples of usage.
perldoc Template::Tutorial
You may also like to consult the paper 'Building and Managing Web Systems with the Template Toolkit' and accompanying slides from the presentation at the 4th Perl Conference. These are available from the Template Toolkit web site:
http://www.template-toolkit.org/docs.html
The following modules comprise the Template Toolkit. Consult the individual documentation for further details.
fetch($template) method which will accept a
wide range of inputs (filename, text ref, GLOB, IO::Handle, etc) and
attempt to read the template and call on a Template::Parser to parse and compile it to a Template::Document
which is then cached.
Andy Wardley <abw@kfs.org>
http://www.template-toolkit.org/
http://www.kfs.org/~abw/
Copyright (C) 1996-2000 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2000 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.
The Template Toolkit was derived in part from ideas and techniques developed in the Text::MetaText module. This itself was the public manifestation of an earlier template processing system I developed while working at Peritas Ltd. (http://www.knowledgepool.com/).
In later years, the Template Toolkit was developed at Canon Research Centre Europe Ltd. (http://www.cre.canon.co.uk) as part of a general research theme into Web-related publishing and dynamic content generation.
Many people have contributed ideas, inspiration, fixes and features to the Template Toolkit. Their efforts continue to be very much appreciated. Please let me know if you think anyone is missing from this list.
Chuck Adams <scrytch@uswest.net> Thierry-Michel Barral <kktos@electron-libre.com> Stas Beckman <stas@stason.org> Neil Bowers <neilb@cre.canon.co.uk> Leon Brocard <acme@astray.com> Chris Dean <ctdean@babycenter.com> Francois Desarmenien <desar@club-internet.fr> Horst Dumcke <hdumcke@cisco.com> Michael Fowler <michael@shoebox.net> Perrin Harkins <pharkins@etoys.com> Rafael Kitover <caelum@debian.org> Hans von Lengerke <hans@lengerke.org> Jonas Liljegren <jonas@paranormal.se> Simon Matthews <sam@knowledgepool.com> Craig McLane <mclanec@oxy.edu> Leslie Michael Orchard <deus_x@ninjacode.com> Eugene Miretskiy <eugene@invision.net> Chris Nandor <pudge@pobox.com> Martin Portman <mrp@cre.canon.co.uk> Randal L. Schwartz <merlyn@stonehenge.com> Paul Sharpe <paul@miraclefish.com> Doug Steinwand <dsteinwand@etoys.com> Drew Taylor <dtaylor@vialogix.com> Swen Thuemmler <Swen.Thuemmler@paderlinx.de> Jim Vaughan <jim@mrjim.com> Chris Winters <cwinters@intes.net>