Components and Macros - Perl

When we looked at HTML::Mason, one of the things we praised was the ability to split template functionality up into multiple components, then include those components with particular parameters. It shouldn't be a surprise that we can do precisely the same in Template Toolkit.

The mechanism through which we pull in components is the INCLUDE directive. For instance, we can specify our box drawing library in a way very similar to the HTML::Mason method, as in Example 3-16.

Example 3-16. BoxTop

<table bgcolor="#777777" cellspacing=0 border=0 cellpadding=0>
<tr>
  <td rowspan=2></td>
  <td valign=middle align=left bgcolor="[% color %]">
    &nbsp;
   <font size=-1 color="#ffffff">
   <b>
   [% IF title_href %]
      <a href="[% title_href %]"> [% title %] </a>
   [% ELSE %]
      [% title %]
   [% END %]
   </b>
   </font>
  </td>
  <td rowspan=2>&nbsp;</td>
</tr>
<tr>
  <td colspan=2 bgcolor="#eeeeee" valign=top align=left width=100%>
  <table cellpadding=2 width=100%>
    <tr><td>

And in the same way as HTML::Mason, we can use local parameters when we include these components:

  [% INCLUDE boxtop
             title = "Login"
             ...
  %]

However, Template Toolkit provides another method of abstracting out common components, the MACRO directive. We can define a MACRO to expand to any Template Toolkit code; let's start by defining it to simply INCLUDE the drawing component:

  [% MACRO boxtop INCLUDE boxtop %]
  [% MACRO boxend INCLUDE boxend %]

With this, we can draw boxes with a little less syntax:

  [% boxtop(title="My Box") %] 
     <P> Hello, people! </P>
  [% boxend %]

Instead of using a component file and INCLUDE, we can also associate a block of Template Toolkit directives with a macro name.

  [% MACRO boxtop BLOCK %]
  <table bgcolor="#777777" cellspacing=0 border=0 cellpadding=0>
  <tr> 
    ...
  [% END %]

  [% MACRO boxend BLOCK %]
  </td></tr></table>

  </td></tr>
  <tr><td colspan=4>&nbsp;</td></tr>
  </table>
  [% END %]

Eventually, we can build up a library of useful macros and then INCLUDE that, instead of having a bunch of component files hanging around.

Let's assume we've created such a library and it contains these two box-drawing macros, and now we'll move on to putting together our RSS aggregator.

The RSS Aggregator

When it comes to writing the aggregator, we first look at the list of Template Toolkit plugins and notice with some delight that there's already a Template::Plugin::XML::RSS, which talks to XML::RSS. Unfortunately, our delight is short-lived, as we soon discover that this expects to get a filename rather than a URL or a string of XML data. We don't really want to be writing out files and then parsing them in again.

Template Toolkit

So let's create our own subclass of Template::Plugin::XML::RSS that fetches URLs and parses those instead:

  package Template::Plugin::XML::RSS::URL;
  use base 'Template::Plugin::XML::RSS';
  use LWP::Simple;

  sub new {
      my ($class, $context, $url) = @_;

      return $class->fail('No URL specified') unless $url;

      my $url_data = get($url)
        or return $class->fail("Couldn't fetch $url");

      my $rss = XML::RSS->new
        or return $class->fail('failed to create XML::RSS');

      eval { $rss->parse($url_data) } and not $@
        or return $class->fail("failed to parse $url: $@");

        return $rss;
  }

  1;

Now we can build up the equivalent of the RSSBox component we made in Mason:

  [% MACRO RSSBox(url) USE rss = XML.RSS.URL(url) %]
  [% box_top(title = rss.channel.title, title_href = rss.channel.link) %]

  <dl class="rss">
  [% FOREACH item = news.items %]
      <dt class="rss">
         <a href="[% item.link %]"> [% item.title %] </a>
      [% IF full %]
         <dd> [% item.description %] </dd>
      [% END ]
      </dt>
  [% END %]
  </dl>
  [% box_end %]
  [% END %]

The important difference between this and the Mason example is that this piece of code handles everything itself--the whole process of obtaining and parsing the RSS feed is available to the template designer. There's no Perl code here to be seen at all. It's also considerably more concise and easier to read and understand. Now that we have this macro, we can produce an HTML box full of RSS stories with a simple call to it:

  [% RSSBox("http://slashdot.org/slashdot.rss") %]

From here on, constructing an RSS aggregator is a simple matter of templating; all of the Perl work has been abstracted away.