Using the Template Toolkit - Perl

The rest of this chapter provides a brief introduction to using the Template Toolkit. We look at the structure and syntax of templates, showing how variables and directives are embedded in plain text and expanded by the template processing engine. We talk about some of the different kinds of directives that the Template Toolkit provides, what they’re used for, and how you go about using them.

We start by looking at the four main ways of using the Template Toolkit to process templates: from the command line using the tpage and ttree programs; from a Perl script using the Template module; and in a mod_perl-enabled Apache web server using the Apache::Template module.

The tpage program provides a quick and easy way to process a template file from the command line. The name of the template file is specified as a command-line argument. This is processed through the Template Toolkit processing engine, and the resultant output is printed to STDOUT:

$ tpage infile

You can use the > file redirect operator (if your operating system supports it, or something similar) to save the output into another file:

$ tpage infile > outfile

In this example, the input template, infile, is processed by tpage with the output saved in outfile. If something goes wrong and the template can’t be processed (for example, if the input file specified doesn’t exist or contains an invalid template directive or markup error), an error is printed to STDERR, and tpage exits without generating any standard output.

The following shows what happens if we try and coerce tpage into processing a file, nosuchfile, which doesn’t exist on our system:

$ tpage nosuchfile
file error - nosuchfile: not found at /usr/bin/tpage line 60.

tpage offers just one command-line option, --define, which allows you to provide values for template variables embedded in the document. We saw this earlier in Example 1-1 where it processed the Vogon form letter:

$ tpage --define planet=Earth \
>         --define captain="Prostetnic Vogon Jeltz" \
>         --define time="two of your earth minutes" \
>         destruction.tt

The tpage program is ideal for simple template processing such as this, where nothing more is required than the ability to insert a few variable values. More complex tasks need the ttree program or custom programs using the Template module.

However, there is one last tpage trick we can show you. If you don’t provide tpage with the name of a template file, it reads it from STDIN. This allows you to use it as Unix-style pipeline filter. For example, if the output of the mktemplate program is a Template Toolkit template, the following command can be used to pipe it into tpage to have it processed:

$ mktemplate | tpage

Invoking tpage by itself, with no arguments and no piped input, starts it in interactive mode. In this case, tpage sits and waits for you to type in a source template. This can be very useful for trying out small snippets of template syntax to see what they do.

Here’s an example:

$ tpage
[% subject = 'cat'
     object = 'mat'
%]
The [% subject %] sat on the [% object %].
^D
The cat sat on the mat.

The first line invokes tpage from the command line. The next three lines are the body of the template in which we type, followed by the end-of-file (EOF) character telling tpage that we’re done. On Unix systems, this is Ctrl-D, shown in the example as ^D. On Microsoft Windows platforms, Ctrl-Z is the EOF character.

The rest of the example shows the output generated by tpage from processing the template. The cat is sitting on the mat, and everything is working as expected.

The ttree program offers many more features and options than tpage does. The first major difference is that ttree works with entire directories of templates rather than with single files. If you’re using the Template Toolkit to build a web site, for example, you can point ttree at a directory of source templates to process them all, saving the generated HTML pages to corresponding files in an output directory.

The following example shows how you could invoke ttree to process all the templates in the templates directory (containing the files cat and dog for the purpose of this example), and save the generated output in files of the same name, which are located in the output directory:

$ ttree -s templates -d output -v

The -s option defines the source directory for templates, and -d defines the destination directory for output files. The -v (verbose) option causes ttree to print a sum mary of what it’s doing to STDERR.

Here’s an example of the kind of information generated by the -v option:

ttree 2.63 (Template Toolkit version 2.10)

      Source:   templates
 Destination:   output
Include Path:   [  ] 
      Ignore:   [  ] 
        Copy:   [  ] 
      Accept:   [*]

+ dog
+ cat

This is a summary of the processing options, including the Source and Destination that we provided as the -s and -d command-line options. The dog and cat files are listed as the two files that ttree found in the templates directory. The + characters indicate that both files were successfully processed, creating dog and cat files in the output directory.

Now that these templates have been processed, ttree will not process them again until they are modified or the corresponding output file is deleted. By looking at the file modification times of the source template and destination file, ttree can decide which templates have changed and which have not. It saves time by processing only those that have changed.

If you run the same ttree command again, you see that the + characters to the left of the filenames have changed to -characters:

ttree 2.63 (Template Toolkit version 2.10)

      Source:   templates
 Destination:   output
Include Path:   [  ] 
      Ignore:   [  ] 
        Copy:   [  ] 
      Accept:   [*]

+ dog                   (not modified)
+ cat                   (not modified)

These -characters indicate that the template files were not processed this time, with the reason given in parentheses to the right. This can save a great deal of time when

building large document systems using templates (e.g., a typical web site) in which only a few pages change at any one time.

The -a option forces ttree to process all templates, regardless of their modification times:

$ ttree -a

A second benefit of ttree is that it offers numerous options for changing its behavior. Adding a standard header and footer to each page template, for example, is as easy as setting the relevant option:

$ ttree -s templates -d output -v \
> --pre_process=header \
> --post_process=footer

The number of options can be overwhelming at first, but in practice, only a few are used on a regular basis. To avoid having to always use the command line to specify options—something that can quickly become cumbersome and error prone, especially if you are using more than a few— ttree allows you to use configuration files to

define all the options for a particular web site or other document system. You can then invoke ttree, passing the name of the configuration file using the -f option:

$ ttree -f /home/dent/web/ttree.cfg

src = /home/dent/web/templates
dest = /home/dent/web/html
lib = /home/dent/web/lib

pre_process = header
post_process = footer

verbose

Example 1-5. A sample ttree configuration file, ttree.cfg

In the configuration file, the -s and -d options are represented by the src and dest options. We also added a lib option (-l on the command line), which tells ttree about an additional library directory where our header and footer templates are found.

Setting up ttree is a little more involved than using tpage, but the effort quickly pays off in the time it saves you. We look at ttree in detail in Chapter 2, showing everything from first-time use through writing and managing configuration files.  

If you've enjoyed what you've seen here, or to get more information, click on the "Buy the book!" graphic. Pick up a copy today! Visit the O'Reilly Network http://www.oreillynet.com for more online content.