Building a Complete Website using the Template Toolkit - More Template Components (Page 8 of 15 )
You can create any number of different reusable template components to help you generate the content for your web site. Whenever you find yourself repeating the same, or a similar, block of markup in more than one place, you might want to con sider moving it into a separate template file that you can then use and reuse when-ever you need it. This not only saves you a lot of typing, but also ensures that the HTML generated in each place you use it is identical, or as near to identical as you would like it to be, accounting for any variables that might change from one use to the next.
Example 2-15 shows a template component for displaying an entry from Arthur’s favorite reference book.
Example 2-15. lib/entry
<p>
The Hitch Hiker's Guide to the Galaxy
has this to say on the subject of
"[% title %]".
</p>
<table border="0">
<tr valign="top">
<td>
<b>[% title %]:</b>
</td>
<td>
[% content %]
</td>
</tr>
</table>
The template uses two variables, title and content . The value for title can in this case be copied from template.title , thereby providing the title set in the META direc tive for the page. A value for content will be set explicitly for the sake of simplicity. These variables can be set either before the PROCESS directive:
[% title = template.title
content = 'Mostly harmless'
%]
[% PROCESS entry %]
or as part of the PROCESS directive, following the template name as additional arguments:
[% PROCESS entry
title = template.title
content = 'Mostly harmless'
%]
The end result is the same. The Template Toolkit treats all variables as global by default so that you can define a variable in one template and use it later in another without having to explicitly pass it as an argument every time. In both of the preced ing examples, the title and content variables are defined globally and can subsequently be used in both the called template (entry) and the calling template (earth.tt) after the point of definition.
In the following fragment, for example, the reference to the content variable at the end of the template will generate the value “Mostly harmless” as set in the earlier PROCESS directive:
[% PROCESS entry
title = template.title
content = 'Mostly harmless'
%]
[% content %] # Mostly harmless
The INCLUDE Directive
There may be times when you would rather keep the definition of certain variables local to a particular template. The INCLUDE directive provides a way of doing this. In terms of syntax, it is used in exactly the same way as the PROCESS directive in all except the keyword.
The key difference between INCLUDE and PROCESS is that INCLUDE localizes any variables that are passed to the template as arguments in the directive. The variables passed have local values for the template component being processed by INCLUDE, but then revert to their previous values or undefined states.
In the following fragment, we define two variables at the start of the template whose values we would like to preserve to be used in the sentence at the end:
[% name = 'Zaphod Beeblebrox'
title = 'President of the Galaxy '
%]
[% INCLUDE entry
title = 'Earth'
content = 'Mostly harmless'
%]
Hi! I'm [% name %], [% title %].
The INCLUDE directive provides local definitions for the title and content variables for the entry template to display. However, the original value for the title variable will be left untouched, and there will be no trace of the content variable outside of the entry template.
The final line of the template generates the output that we’re expecting:
Hi! I'm Zaphod Beeblebrox, President of the Galaxy.
Had we used PROCESS instead of INCLUDE , the value for title would have been over written and the output generated by the final line would incorrectly read:
Hi! I'm Zaphod Beeblebrox, Earth.
There is one important caveat to be aware of. The INCLUDE directive only localizes simple variables. Any complex variables containing dot operators are effectively global regardless of whether you use INCLUDE, PROCESS, or any other directive.
Dotted variables are a little like Perl’s package variables. In Perl, you can refer to a variable as, for example, $My::Dog::Spot. This tells Perl the precise location for the variable $Spot in the My::Dog package. In the Template Toolkit, the equivalent variable would be something like my.dog.spot.
On the other hand, a Perl variable written as just $Spot could be either a “global” (for these purposes) variable defined in the current package, or a lexically scoped variable in the current subroutine, for example. Similarly, in the Template Toolkit, the equivalent variable spot could also be a global variable or a local copy created by invoking a template using INCLUDE .
The explanation isn’t important as long as you remember the simple rule: the INCLUDE localizes only simple variables that don’t contain any “ . ” dots.
 | 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. |
/ 29 
