Building a Complete Website using the Template Toolkit - Layered Configuration Templates (Page 14 of 15 )
As your site data structure becomes more complicated, you might find it easier to build it in layers using several templates. Example 2-30 shows a preprocessed configuration template that loads the site, col, and url templates using PROCESS .
Example 2-30. lib/configs
[% PROCESS site
+ col
+ url
-%]
We have already seen the site template in Example 2-29. Example 2-31 shows the col and url configuration templates.
Example 2-31. lib/col
[% site.rgb = {
white = '#FFFFFF'
black = '#000000'
orange = '#FF6600'
}
site.col = {
back = site.rgb.orange
text = site.rgb.white
}
-%]
Example 2-31 shows the definition of a site.rgb hash and then another, site.col , which references values in the first. Template authors can use explicit colors, by referencing site.rgb.orange , for example, to fetch the correct RGB value, #FF6600 .Or they can code their templates to use colors defined in the site.col structure—for example, referencing site.col.back in the html template to set the bgcolor attribute of the HTML element. Either way, the colors are defined in one place, and the symbolic names allow us to see at a glance that the background color for the pages in the site is currently orange.
The url template is a little simpler, but also illustrates how variables can be built in stages (see Example 2-32).
Example 2-32. lib/url
[% url = 'http://tt2.org/ttbook'
site.url = {
root = url
home = "$url/index.html"
help = "$url/help.html"
images = "$url/images"
}
-%]
The benefits of this approach are twofold. The first is that you can save yourself a great deal of typing by replacing a long-winded URL with a shorter variable name. The second benefit is that you can easily change all the URL values in a single stroke by changing the root url from which they are constructed.
One advantage of building a complex data structure from several templates is that you can easily replace one of the templates without affecting the others. For exam ple, you might want to use a different set of URL values at some point. Rather than edit the url template, you can copy the contents to a new file (e.g., url2), make the changes there, and then update the configs template accordingly:
[% PROCESS site
+ col
+ url2
-% ]
If you must revert to the old URLs at a later date, you need to change only the configs template to load url instead of url2. You can also use this approach to load different configuration templates based on a conditional expression. For example:
[% PROCESS site
+ col;
IF developing;
PROCESS url2;
ELSE;
PROCESS url;
END
-%]
Choosing Global Variables Wisely
Fewer global variables are better, but don’t try to cram everything into the one site
variable if more would do the job better. Try and separate your variables into struc tures according to their general purpose and relevance to different aspects of the site. For example, you can define one structure containing everything related to the site as a whole (e.g., site ), and another related to the individual page being processed (e.g., page ):
[% site = {
title = "Arthur Dent's Web Site"
author = 'Arthur Dent'
# ...etc...
}
page = {
title = template.title
author = template.author or site.author
}
%]
You may also want to define others to represent a user, server, application, or request depending on how you’re using the Template Toolkit and what you’re using it for.
The Template Toolkit allows you to use upper-or lowercase, or some combination of the two, to specify variable names. It’s not recommended that you use all upper case variable names, as they might clash with current (or future) Template Toolkit directives. However, you might like to capitalize your global variables to help you remember that they’re special in some way (e.g., Site versus site ):
[% Site = {
# ...etc...
}
Page = {
# ...etc...
}
User = {
# ...etc.. .
}
%]
Passing Around Data Structures
You can pass a complex data structure around the Template Toolkit as easily as you would a scalar variable. Example 2-33 shows a configuration template that defines the site.menu data structure to contain the menu items that we used earlier in Example 2-26.
Example 2-33. lib/menudef
[% site.menu = [
{ text = 'Earth'
link = 'earth.html' }
{ text = 'Magrethea'
link = 'magrethea.html' }
]
%]
We’ve moved the definition of the sitewide menu into a central configuration file and will need to add it to the list of templates loaded by the PROCESS directive in the pre processed configs template shown in Example 2-30:
[% PROCESS site
+ col
+ url
+ menudef
-%]
Now we can remove the definition of the menu structure from the component (o r components) that generate the menu in a particular style, as shown in Example 2-34.
Example 2-34. lib/menu5
[% PROCESS mylib %]
<table border="0">
[%- FOREACH item IN menu;
PROCESS menuitem
text = item.text
link = item.link;
END
-%]
</table>
[% BLOCK menuitem %]
<tr>
<td>
[% PROCESS icon %]
</td>
<td>
[% PROCESS link %]
</td>
</tr>
[% END %]
The value for menu ( site.menu in this case) is passed to the menu5 template as an argument in an INCLUDE directive:
[% INCLUDE menu5
menu = site.menu
%]
The benefit of this approach is that the component that generates the menu is now generic, and will work with any menu data you care to define. Wherever you need a menu in the same style, simply call the component and pass in a different definition of menu data:
[% INCLUDE menu5
menu = [
{ text = 'Milliways'
link = 'milliways.html' }
{ text = 'Hotblack Desiato'
link = 'desiato.html' }
]
%]
Separating the definition of a menu from its presentation also makes it easier to change the menu style at a later date. There’s only one generic menu component to update or replace, regardless of how many times it is used in various places around the site. If you want two or more different menu styles, simply create additional menu components with different names or in different locations. For example, you
may have site_menu and page_menu,or site/menu and page/menu, or perhaps some thing such as slick/graphical/menu and plain/text/menu.
/ 29 
