The WRAPPER Directive

The entry template from Example 2-15 works well when the content to be displayed is relatively simple. However, it quickly becomes cumbersome for longer entries such as the one shown here:

[% INCLUDE entry
     title   = 'Vogon Poetry'
     content = 'Vogon poetry is of course the
                third worst in the Universe.
                The second worst is that of...
                ...etc...
                ...in the destruction of the planet Earth'
%]

Special care must be taken when quoting content that contains quote characters. Consider the following extract that illustrates this problem:

Grunthos is reported to have been "disappointed"
by the poem's reception.

If this is enclosed in single-quote characters, the apostrophe in “ poem's ” must be escaped by preceding it with a backslash \ character (the apostrophe and single-quote characters are one and the same for these purposes):

[% INCLUDE entry
     title   = 'Grunthos the Flatulent'  
     content = 'Grunthos is reported to have
                been "disappointed" by the
                poem\'s reception.'
%]

Another alternative is to use double quotes to define the variable, allowing single quotes to remain as they are. But in this case, any occurrences of double quotes will then need to be escaped:

[% INCLUDE entry
     title   = 'Grunthos the Flatulent'
     content = "Grunthos is reported to have
                been \"disappointed\" by the
                poem's reception."
%]

A better solution is to use the WRAPPER directive. It works in a similar way to INCLUDE , but uses an additional END directive to enclose a block of template content. The WRAPPER directive uses this block as the value for the content variable:

[% WRAPPER entry 
     title = 'Grunthos the Flatulent'
%] 
   Grunthos is reported to have
   been "disappointed" by the
   poem's reception.
[% END %]

The immediate benefit in this example is that the extract is now a block of plain text rather than a quoted string. There is no longer any need to escape the quote characters within it.

The WRAPPER block can contain any combination of text and template directives, even including other nested WRAPPER blocks. The following fragment shows a simple example in which the reaction variable is used to report Grunthos’ reaction:

[% reaction = 'disappointed' %]

[% WRAPPER entry
     title = 'Grunthos the Flatulent'
%]
   Grunthos is reported to have
   been "[% reaction %]" by the
   poem's reception.
[% END %]

The WRAPPER block is processed first to resolve any directives within it. Then the com plete block, including any output generated dynamically by embedded directives, is passed to the entry template as the value for the content variable.

It’s no coincidence that we chose content as a variable name in the entry template in Example 2-15, knowing full well that we would later use it in this example for WRAPPER . The WRAPPER directive always assigns the block content to the content variable, and in that sense it’s one of the Template Toolkit’s “special” variables, like the template variable that we used earlier. However, there’s nothing to stop you from using it as a regular variable, and indeed it makes a good choice in any template for a variable that you might one day want to define as a block in a WRAPPER directive.

The end result is that the entry template works as expected, whether we call it using INCLUDE and pass the content explicitly as a variable, or call it using WRAPPER and define the content implicitly in the enclosed block.

Using an Automatic Wrapper Template

In Examples 2-4 and 2-14, we created separate header and footer files to add to the start and end of each HTML page generated. One problem with this approach is that neither file contains valid HTML markup. The header provides the opening tag of the

html element, for example, but the corresponding closing tag is located at the end of the footer file.

Having HTML elements split across separate files makes them harder to maintain, and increases the likelihood of them being accidentally mismatched or incorrectly nested. It is also likely to confuse or infuriate any HTML-aware text editors or validation tools that you may be using.

A better approach is to use a wrapper template to combine the header and footer into one template. The

content variable is used to denote the position for the page content. This is shown in Example 2-16.

Example 2-16. lib/wrapper

<html>
  <head>
    <title>[% author %]: [% template.title %]</title>
  </head>

  <body bgcolor="[% bgcol %]">
    <h1>[% template.title %]</h1>

    [% content %]

    <hr />

    <div align="middle">
      &copy; [% copyr %]
    </div>
  </body>
</html>

We need to modify the etc/ttree.cfg file to specify the new wrapper template using the

wrapper option. The fact that our wrapper template happens to be called wrapper is entirely coincidental (but intentional). We could have named the file tom, dick, larry, or something else if we wanted to, but it wouldn’t be as succinct or descriptive as wrapper.

We’re still using the pre_process option to load the config template, but we can now remove the references to the header and footer (or comment them out as shown here), replacing them with a single wrapper option:

pre_process = config
wrapper     = wrapper
# pre_process  = header
# post_process = footer

With the wrapper option in place, the Template Toolkit processes the main page tem

plate (after preprocessing the config template) and then calls the wrapper template, passing the generated page content as the content variable. It has the same effect as if there were an explicit WRAPPER directive around the entire page content:

[% WRAPPER wrapper %]
   The entire page content goes here...
[% END %]

Of course, the benefit of having the Template Toolkit apply a wrapper automatically is that you don’t need to edit any of your page templates to add it explicitly. You can switch from using pre_process and post_process to wrapper , or you can change the name of any of the header, footer,or wrapper templates, without having to make any changes to your core content.

To put the change into effect, run the bin/build script with the -a option to have it rebuild all pages in the site:

$ bin/build -a

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.