Section 3.3. HTML::Template | Advanced Perl Programming

3.3. HTML::Template

HTML formatting is slightly different from plaintext formattingthere are essentially two main schools of thought. The first, used by HTML::Template, is similar to the method we saw in Text::Template; the template is stored somewhere, and a Perl program grabs it and fills it in. The other school of thought is represented by HTML::Mason, which we'll look at next; this is inside-outinstead of running a Perl program that prints out a load of HTML, you create an HTML file that contains embedded snippets of Perl and run that.

To compare these two approaches, we're going to build the same application in HTML::Template, HTML::Mason, and Template Toolkit, an aggregator of RSS (Remote Site Summary) feeds to grab headlines from various web sites and push them onto a single page. (Similar to Amphetadesk, http://www.disobey.com/amphetadesk/, and O'Reilly's Meerkat, http://www.oreillynet.com/meerkat/.) RSS is an XML-based format for providing details of individual items on a site; it's generally used for providing a feed of stories from news sites.

3.3.1. Variables and Conditions

First, though, we'll take a brief look at how HTML::Template does its stuff, how to get values into it, and how to get HTML out.

As with Text::Template, templates are specified in separate files. HTML::Template's templates are ordinary HTML files, but with a few special tags. The most important of these is <TMPL_VAR>, which is replaced by the contents of a Perl variable. For instance, here's a very simple page:

     <html>        <head><title>Product details for <TMPL_VAR NAME=PRODUCT></title></head>        <body>           <h1> <TMPL_VAR NAME=PRODUCT> </h1>           <div >                <TMPL_VAR NAME=DESCRIPTION>           </div>           <p >Price: $<TMPL_VAR NAME=PRICE></p>           <hr />           <p>Price correct as at <TMP_VAR NAME=DATE></p>        </body>     </html>

When filled in with the appropriate details, this should output something like:

     <html>        <head><title>Product details for World's Biggest Enchilada</title></head>        <body>           <h1> World's Biggest Enchilada </h1>           <div >                Recently discovered in the Mexican rain forests....           </div>           <p >Price: $1504.39</p>           <hr />           <p>Price correct as at 15:18 PST, 7 Mar 2005</p>        </body>     </html>

In order to fill in those values, we write a little CGI program similar to the following one:

     use strict;     use HTML::Template;     my $template = HTML::Template->new(filename => "catalogue.tmpl");     $template->param( PRODUCT     => "World's Biggest Enchilada" );     $template->param( DESCRIPTION => $description );     $template->param( PRICE       => 1504.39 );     $template->param( DATE        => format_date(localtime) );     print "Content-Type: text/html\n\n", $template->output;

Again, as with Text::Template, our driver program is very simpleload up the template, fill in the values, produce it. However, there are a few other things we can do with our templating language, and hence there are a few other tags that allow us a little more flexibility.

For instance, suppose we happen to have a picture of the world's biggest enchiladathat would be something worth putting on our web page. However, we don't have pictures for everything in the database; we want to output a pictures section only if we actually do have an image file kicking about. So, we could add something like this to our template:

     <TMPL_IF NAME=PICTURE_URL>     <div >        <img src="/books/2/171/1/html/2/<TMP_VALUE NAME=PICTURE_URL>" />     </div>     </TMPL_IF>

This means that if PICTURE_URL happens to have a true valuethat is, if we've given it something like a real URLthen we include the photo <DIV>. As these <TMPL_...> tags are not real HTML tags, only things processed by HTML::Template, it's not a problem to stick one in the middle of another HTML tag, as we have here with <IMG src="/books/2/171/1/html/2/...">.

Of course, if we don't have a picture, we might want to stick another one in its place, which we can do with the <TMPL_ELSE> pseudotag:

     <div >     <TMPL_IF NAME=PICTURE_URL>        <img src="/books/2/171/1/html/2/<TMP_VALUE NAME=PICTURE_URL>" />     <TMPL_ELSE>        <img src="/books/2/171/1/html/2/http://www.mysite.com/images/noimage.gif" />     </TMPL_IF>     </div>

Notice that although our <TMPL_IF> must be matched by a </TMPL_IF>, <TMPL_ELSE> is not matched.

But perhaps we're being unduly complex; all we need in this example is a default value for our PICTURE_URL, and we can do this directly with a DEFAULT attribute to <TMPL_VALUE>:

     <div >        <img src="/books/2/171/1/html/2/     <TMPL_VALUE NAME=PICTURE_URL                 DEFAULT="http://www.mysite.com/images/noimage.gif">        "/>     </div>

Validation

Some people worry, quite rightly, about the effect that this sort of indiscriminate SGML abuse has on checking templates for validity. (Although, sadly many more people don't worry about HTML validity.) Further, those who use DTD-aware validating editors might wonder how to get these pseudotags into their documents in a nice way.

HTML::Template has a way around this; instead of writing the tags as though they were ordinary HTML tags, you can also write them as though they were comments, like so:

     <!-- TMPL_IF NAME=PICTURE_URL -->     <div >        <img src="/books/2/171/1/html/2/<!-- TMP_VALUE NAME=PICTURE_URL -->" />     </div>     <!-- /TMPL_IF -->

3.3.2. Loops

If we're going to get anywhere with our RSS example, we'll need to loop over a series of itemsthe stories in our newsreel. Thankfully, HTML::Template provides the <TMPL_LOOP> pseudotag for treating a variable as an array. For instance, the following code:

     <ul>     <TMPL_LOOP NAME=STORIES>         <li> From <TMPL_VAR NAME=FEED_NAME>: <TMPL_VAR NAME=STORY_NAME> </li>     </TMPL_LOOP>     </ul>

when provided the appropriate data structure, loops over the items in the STORIES array reference and produces output like so:

     <ul>         <li> From Slashdot: NASA Finds Monkeys on Mars </li>         <li> From use.perl: Perl 6 Release Predicted for 2013 </li>     </ul>

The trick is that the array reference needs to contain an array of hashes, and each hash provides the appropriate variable names:

     $template->param(STORIES => [      { FEED_NAME => "Slashdot", STORY_NAME => "NASA Finds Monkeys on Mars" },      { FEED_NAME => "use.perl", STORY_NAME => "Perl 6 Release Predicted for 2013" }     ]);

3.3.3. RSS Aggregation

With this knowledge, putting together our RSS aggregator is pretty trivial; first, we grab all the feeds we're interested in, then sort out their stories and put them into a data structure suitable for feeding to a <TMPL_LOOP>.

We'll use LWP and XML::RSS to obtain and parse the RSS feeds. In our example, we're going to pretend that we're behind a pretty impressive web cache, so we have no problems fetching the RSS feeds repeatedly; in real life, you may want to save the XML to files with fixed names and check how old the files on disk are before fetching them from the web again.

We'll start our RSS aggregator by writing a little Perl program to grab and organize the feeds:

     #!/usr/bin/perl     use LWP::Simple;     use XML::RSS;     my @stories;     while (<DATA>) {         chomp;         my $xml = get($_) or next;         my $rss = XML::RSS->new;         eval { $rss->parse($xml) }; next if $@;         for my $item (@{$rss->{'items'}}) {             push @stories, {                  FEED_NAME  => $rss->channel->{'title'},                  FEED_URL   => $rss->channel->{'link'},                  STORY_NAME => $item->{'title'},                  STORY_URL  => $item->{'link'},                  STORY_DESC => $item->{'description'},                  STORY_DATE => $item->{'dc'}->{'date'}             }         }     }     @stories = sort { $b->{STORY_DATE} cmp $a->{STORY_DATE} } @stories;     _ _DATA_ _     http://slashdot.org/slashdot.rss     http://use.perl.org/perl-news-short.rdf     http://www.theregister.co.uk/tonys/slashdot.rdf     http://blog.simon-cozens.org/blosxom.cgi/xml     http://www.oreillynet.com/~rael/index.rss

Next we need to design a template to receive this list of feeds. Now, I'm an abysmal HTML designer, which is why I like templates so much. I can create something rough that does the job and hand it to someone with imagination to do the presentation bits. So here's a rough-and-ready template:

     <html>       <head> <title> Today's News </title> </head>       <body>          <h1> News Stories Collected at <TMPL_VAR TIME> </h1>          <TMPL_LOOP STORIES>             <table border="1">               <tr>                <td>                  <h2>                    <a href="<TMPL_VAR STORY_URL>"> <TMPL_VAR STORY_NAME> </a>                  </h2>                  <p> <TMPL_VAR STORY_DESC> </p>                  <hr>                  <p> <i> From                      <a href="<TMPL_VAR FEED_URL>"> <TMPL_VAR FEED_NAME> </a>                  </i> </p>                </td>               </tr>             </table>          </TMPL_LOOP>       </body>     </html>

(Notice that we're using short forms of the pseudotags: it's OK to say SOME_VARIABLE instead of NAME=SOME_VARIABLE where it's unambiguous.)

Finally, we put the finishing touches on our driver program, which merely takes the array we generated and feeds it to HTML::Template:

     #!/usr/bin/perl     use LWP::Simple;     use XML::RSS;     use HTML::Template;     my @stories;     while (<DATA>) {         chomp;         my $xml = get($_) or next;         my $rss = XML::RSS->new;         eval { $rss->parse($xml) }; next if $@;         for my $item (@{$rss->{'items'}}) {             push @stories, {                  FEED_NAME  => $rss->channel->{'title'},                  FEED_URL   => $rss->channel->{'link'},                  STORY_NAME => $item->{'title'},                  STORY_URL  => $item->{'link'},                  STORY_DESC => $item->{'description'},                  STORY_DATE => $item->{'dc'}->{'date'}             }         }     }     my $template = HTML::Template->new(filename => "aggregator.tmpl");     $template->param( STORIES => [         sort {$b->{STORY_DATE} cmp $a->{STORY_DATE} } @stories                         ] );     $template->param( TIME => scalar localtime );     delete $_->{STORY_DATE} for @stories;     print "Content-Type: text/html\n\n", $template->output;     _ _DATA_ _     http://blog.simon-cozens.org/blosxom.cgi/xml     http://slashdot.org/slashdot.rss     http://use.perl.org/perl-news-short.rdf     http://www.theregister.co.uk/tonys/slashdot.rdf     http://www.oreillynet.com/~rael/index.rss

We need to delete the STORY_DATE once we've used it for ordering, as HTML::Template gets irate if we have loop variables that we don't use in our template.

Plug this into a CGI-enabled web server, and, lo and behold, we have a cheap and cheerful Amphetadesk clone.