D.5 Processing Templates

In addition to the ttree script mentioned earlier, tpage is distributed with the Template Toolkit for no-frills simple template processing.

You might use it like this:

panic% tpage myfile.tt2 > myfile.html

or:

panic% tpage src/myfile.html > dest/myfile.html

It is extremely useful as a command-line tool to process a template without having to write any Perl code. However, for most uses, be it an offline script, CGI application, or mod_perl handler, you'll want to hook the Template module into your Perl code.

To see how we would go about this, let us first take one of our earlier examples and save it in a file called example.html (see Example D-1).

Example D-1. example1/example.html

[% PROCESS header title="Some Interesting Links" %]

<p>
Here are some interesting links:
<ul>
[% FOREACH link = weblinks %]
   <li><a href="[% link.url %]">[% link.title %]</a></li>
[% END %]
</ul>
</p>

[% PROCESS footer %]

We're referencing two external templates, header and footer, so we'll have to create them, too. See Examples D-2 and D-3.

Example D-2. example1/header

<html>
<head>
<title>[% title %]</title>
</head>

<body bgcolor="#ffffff">

<h1>[% title %]</h1>

Example D-3. example1/footer

<div align="center">
[% copyright %]
</div>

</body>
</html>

Now we can write a simple Perl script to process example.html, as shown in Example D-4.:

Example D-4. example1/process_template.pl

#!/usr/bin/perl

use strict;
use warnings;
use Template;

# create template processor
my $tt = Template->new( );

# define data
my $data = {
  copyright => '&copy; 2002 Andy Wardley',
  weblinks  => [
      { 
        url   => 'http://perl.apache.org/',
        title => 'Apache/mod_perl',
      },
      { 
        url   => 'http://tt2.org/',
        title => 'Template Toolkit',
      },
      # ...and so on...
  ]
};

# process template - output to STDOUT by default
$tt->process('example.html', $data)
    || die $tt->error( );

After loading the Template module (use Template;) we create a Template object via the new( ) constructor method. You can specify all sorts of options, either as a list of named arguments or by reference to a hash array. If, for example, you want to put your templates in a different directory (the default is the current working directory), then you might do something like this:

my $tt = Template->new( INCLUDE_PATH => 'templates' );

A more complete example might look like this:

my $tt = Template->new({
    INCLUDE_PATH => [ '/home/stas/web/tt2/templates',
                      '/usr/local/tt2/templates',
                    ],
    PRE_PROCESS  => 'header',
    POST_PROCESS => 'footer',
    INTERPOLATE  => 1,
    POST_CHOMP   => 1,
});

The Template::Manual::Config manpage has full details on the various different configuration options and what they do.

Once you've created a Template object, you can call the process( ) method to process a template. The first argument specifies the template by name (relative to one of the INCLUDE_PATH directories) or as a reference to a file handle or scalar containing the template text. The second optional argument is a reference to a hash array of data that defines the template variables. A third optional argument can also be provided to indicate where the output should be directed, specified as a filename, file handle, reference to a scalar, or object that implements a print( ) method (e.g., an Apache request object $r). By default, the generated output is sent directly to STDOUT.

This is what it looks like:

<html>
<head>
<title>Some Interesting Links</title>
</head>

<body bgcolor="#ffffff">

<h1>Some Interesting Links</h1>

<p>
Here are some interesting links:
<ul>
   <li><a href="http://perl.apache.org/">Apache/mod_perl</a></li>
   <li><a href="http://tt2.org/">Template Toolkit</a></li>
</ul>
</p>

<div align="center">
&copy; 2002 Andy Wardley
</div>

</body>
</html>

The external templates (header and footer) have been pulled into place and the title reference in the header and copyright in the footer have been correctly resolved. The body of the document is built from the data passed in as weblinks.

[ Team LiB ]