At the simplest level it provides an easy way to process template files, filling in embedded variable references with their equivalent values. Here's an example of a template.
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. ...etc...
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', }; $tt->process('letters/overdrawn', $vars) || die $tt->error(), "\n";
The process() method returns a true value (1) on success and prints the template output to "STDOUT", by default. On error, the process() method returns a false value ("undef"). The error() method can then be called to retrieve details of the error.
[% 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>
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 access into lists and hashes or to call object methods. The "FOREACH" directive is provided for iterating through lists, and various logical 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</b>: [% 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 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.