Larger sites will typically use dozens of different global site variables to represent colors, titles, URLs, copyright messages, and various other parameters. The Template Toolkit places no restriction on the number of different variables you use, but you and your template authors may soon lose track of them if you have too many.

Another problem with having lots of global variables lying around is that you might accidentally overwrite one of them. We saw in Example 2-7 how the author variable was used to store the name of the site author, Arthur Dent, for use in the header and footer templates. At some later date, we might decide to add a quote template component that also uses the author variable. This is shown in Example 2-28.

Example 2-28. lib/quote

<blockquote>
  [% quote %]
</blockquote>

-- [% author %]

There’s no problem if we use INCLUDE to load the template, providing a local variable value for author :

[% INCLUDE quote
     author = 'Douglas Adams'
     quote = 'I love deadlines. I like the
              whooshing sound they make as
              they fly by.'
%]

The value for author supplied as a parameter to the INCLUDE directive ( Douglas Adams ) remains set as a local variable within the quote template. It doesn’t affect the global author variable that is defined in the config ( Arthur Dent ).

However, it is all too easy to forget that the author variable is “reserved”—especially if it’s just one of a large number of such variables—and to use PROCESS instead of INCLUDE:

[% PROCESS quote
      author = 'Douglas Adams'
      quote = 'I love deadlines. I like the
               whooshing sound they make as
               they fly by.' %]

The PROCESS directive doesn’t localize any variables. As a result, our global author variable now is incorrectly set to Douglas Adams instead of Arthur Dent . One solution is to religiously use INCLUDE instead of

PROCESS at every opportunity. However, that’s just working around the problem rather than addressing the real issue. Furthermore, the INCLUDE directive is quite a bit slower than PROCESS , and if performance is a con cern for you, you should be looking to use PROCESS wherever possible.

Variables are localized for the INCLUDE directive in a part of the Template Toolkit called the Stash. It saves a copy of all the current variables in use before the template is processed, and then restores them to these original values when processing is complete. Understandably, this process takes a certain amount of time (not much in human terms, but still a finite amount), and the more variables you have, the longer it takes.

It is worth stressing that for most users of the Template Toolkit, these performance issues will be of no concern whatsoever. If you’re using the Template Toolkit to generate static web content offline, it makes little difference if a template takes a few hundredths or thousandths of a second longer to process. Even for generating dynamic content online, performance issues such as these probably aren’t going to concern you unless you have particularly complicated templates or your site is heavily loaded and continually generating lots of dynamic content.

The more important issue is one of human efficiency. We would like to make it easier for template authors to keep track of the variables in use, make it harder for them to accidentally trample on them in a template component, and ideally, allow them to use PROCESS or INCLUDE , whichever is most appropriate to the task at hand.

The answer is to use a nested data structure to define all the sitewide variables under one global variable. Example 2-29 shows how numerous configuration variables can be defined as part of the site data structure, in this case implemented using a hash array.

Example 2-29. lib/site

[% site = {
   author = 'Arthur Dent'
   bgcol  = '#FF6600' # orange
   year   = 2003
  }

  site.copyr = "Copyright $site.year $site.author"
%]

To interpolate the values for the year and author to generate the copyright string, we must now give them their full names, site.year and site.author. We need to set the site.copyr variable after the initial site data structure is defined so that we can use these variables. In effect, the site variable doesn’t exist until the closing brace, so any references to it before that point will return empty values (unless the site has previously been set to contain these items at some earlier point).

[% site = { 
    author = 'Arthur Dent' 
    bgcol  = '#FF6600' # orange 
    year   = 2003

    # this doesn't work because site.year 
    # and site.author are undefined at 
    # this point 
    copyr = "Copyright $site.year $site.author"
  }
%]

Sitewide values can now be accessed through the site hash in all templates, leaving author , bgcol , year , and all the other variables (except site , of course) free to be used, modified, and updated as “temporary” variables by page templates and template components. Now there’s just one variable to keep track of, so there’s much less chance of accidentally overwriting an important piece of data because you forgot it was there. It also means that the INCLUDE directive works faster because it has only one variable to localize instead of many. The Stash copies only the top-level variables in the process of localizing them and doesn’t drill down through any of the nested data structures it finds. 

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.