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.tpage
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:
You can use the > file redirect operator (if your operating system supports it, or something similar) to save the output into another file:
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 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:
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:
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:
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.ttree
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:
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:
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:
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:
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:
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:
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.
blog comments powered by Disqus