In addition to the fact that ttree works well with large collections of page templates, it also has the benefit of providing a large number of configuration options that allow you to change the way it works and how it uses the underlying Template Toolkit processor. Two of the most convenient and frequently used options are pre_process and post_process . These allow you to specify one or more templates that should be automatically added to the top or bottom of each page template, respectively. This can be used to add standard headers and footers to a generated page, but pre-and postprocessed templates may not generate any visible output at all. For example, we can use a preprocessed template to configure some variables that we might want defined for use in the page template or other template components.
The following can be added to the bottom of the etc/ttree.cfg file to have the config and header templates preprocessed (in that order so that we can use variables defined in config in the header) and the footer template postprocessed:
pre_process = config
Now the page templates can be made even simpler, as Example 2-12 shows.
* This occurs not because ttree is being lazy. Itís actually very difficult, if not impossible, to do it accurately without processing the templates in their entirety. By this time, the Template Toolkit has already done the hard work, so thereís nothing to be gained by discovering that the template didnít need processing after all.
Example 2-12. src/magrethea.html
[% title = 'Magrethea' -%]
Remember that youíll need to use the -a option to force ttree to rebuild all pages in the site to have the changes take effect:
$ bin/build -a
Defining META Tags
There is one problem with this approach. The header template is processed in its entirety before the main page template gets a look in. This means that the title variable isnít set to any value when the header is processed. It doesnít get set until the page template is processed, by which time itís too late for the header to use it.
The Template Toolkit wonít complain if it encounters a variable for which it doesnít have a value defined. Instead, it will quietly use an empty string (i.e., nothing at all) for the value of the variable and continue to process the remainder of the template. The DEBUG option (described in the Appendix) can be set to have it raise an error in these cases, and can be useful to help track down mistyped variable names and those that have somehow eluded definition.
We can use the META directive to solve our immediate problem. It works by allowing us to define values within the page template that are accessible for use in the header and any other preprocessed templates, before the main page template is itself processed.
Example 2-13 shows how this is done. Instead of defining the title in a SET directive (which technically we were, even if we had omitted the SET keyword for convenience), we use the META directive, but otherwise leave the definition of the variable unmodified.
Example 2-13. src/milliways.html
[% META title = 'Milliways' %]
Variables defined like this are made available as soon as the template is loaded. This happens before any of the preprocessed templates are processed so that these META variables are defined and ready for use.
There are some subtle differences between META variables and normal SET variables. The first is that you canít use double-quoted strings to interpolate other variables into the values for META variables. You can use double-quoted strings, but you canít embed variables in them and expect them to get resolved. The simple reason for this is that META variables are defined before the template is processed with any live data. At this time, there arenít any variables defined, so thereís no point trying to use them.
The second difference is that the variables must be accessed using the template. prefix:
[% template.title %] not [% title %]
The template variable is a special variable provided by the Template Toolkit containing information about the current page template being processed. It defines a number of items, including the name of the template file ( template.name ) and the modification time ( template.modtime ), as well as any META variables defined in the template ( template.title ).
The dot operator, ., is the Template Toolkitís standard notation for accessing a variable such as title that is one small part of a larger, more complex data structure such as template . It doesnít matter for now (or generally at all) how this is implemented behind the scenes because the dot operator hides or abstracts that detail from you so that you donít need to worry about it.
Weíll be coming back to the dot operator later on in this chapter when we look at defining and using complex data structures. For now, it is sufficient to know that template.title is how we access the title META variable defined in the main page template.
We can easily modify our header template to accommodate these requirements and restore the page title to the generated header (see Example 2-14).
Example 2-14. lib/header
blog comments powered by Disqus