Text::Template

[mirod]

Item Description: A module that fills-in templates including Perl code

Review Synopsis: Stable and powerful, my template module of choice

Description

Text::Template let's you store templates in separate files.

• the templates can be anything, typically pure text (like email message templates) or HTML.
• the templates can include Perl code, between 2 matching { } (you can change the delimiter if you want to.
• you can pass variables to the template, usually in a separate package (my variables won't be passed to the template)
• you can trap errors when filling the standard with a custom handler.

Why use Text::Template

Warning: Text::Template is the only templating module I use, so I cannot compare it with other similar modules.

• it works just fine, I never did anything too fancy with it, but I never found a bug in it
• it is quite powerful: you can change the delimiters, evaluate the template in a safe environment, add custom code (like common subroutines) to existing templates...
• the documentation is very good

Why NOT use Text::Template

• you prefer an other module

Personal Notes

Text::Template is a no-brainer, it is powerful enough to handle most needs and won't cause you any trouble. Get it now!

[merlyn]

For the next step up in power (some would say "the ultimate step up"), check out Template Toolkit. I'll be doing a review on that in the near future, once I've finished tossing out HTML::Mason for www.stonehenge.com to replace it with Template Toolkit.

-- Randal L. Schwartz, Perl hacker

[mirod]

Why do you want to replace HTML::Mason? Any shortcomings or specific flaws, or you just find Template Toolkit more powerful?

The doc for Template Toolkit is quite... short and I really can't figure out what it does.

[merlyn]

In short, since I just had this discussion yesterday:
• TT is language-agnostic, and works well even in languages where whitespace matters.
• TT provides heavy customization callbacks at each level of processing
• TT has an embedded language that hides the difference between hashes and method calls so dumb hashes can be turned into smart objects later
• TT plays well outside mod_perl as a static transformation tool (or even in CGI)
• Mason has better "out of the box" caching, but TT has all the right hooks to write your own easily, probably better for real applications anyway
• TT permits Embedded Perl to be turned off or on for a given input source, useful in an enviroment where full Perl interface would be dangerous or misleading
• embedded TT triggers can be changed to suit the parsed language, and for HTML be selected so as to get into and out of WYSIWYG HTML wranglers without mangling
• One customer site I know doing $30M a year is using it and recommended it highly over the other embedded Perl/HTML solutions after doing their own study

-- Randal L. Schwartz, Perl hacker

[PotPieMan]

A couple of warnings on the use of Text::Template. If you use strict like a good Perl programmer, Text::Template will not see your variables as you might expect. Since templates are opened in new scopes by Text::Template, this behavior makes perfect sense, but is rather annoying.

You have two options available when you run into this problem:

1. As mirod mentions, declare and initialize your variables in a separate package. Personally, I don't think this is very elegant.
2. Pass your Text::Template object a hash reference with the variables to replace. On the plus side, this allows you to control what information is available to templates. On the minus side, you have to go to the trouble of building another hash. (Of course, if you've already built it, then this isn't an issue.)
Truthfully, neither option is that much of a problem in most situations. Just be aware.

Also, I found that Text::Template doesn't behave exactly as you might expect in dereferencing variables. For instance, take the following code as an example:

my %vars = ('measurements' => {'temperature' => {'current' => '22 degC
+',
                                                 'high' => '26 degC',
                                                 'low' => '18 degC'
                                                },
                               'humidity' => '82%'
                              },
            'time' => scalar(localtime)
           );

my $tt = Text::Template->new(SOURCE => $templateFile) or die "Couldn't
+ construct template: $Text::Template::ERROR";
my $weather = $tt->fill_in(HASH => \%vars);

Assuming your template delimiters are the default ({ and }), you might expect to use {$measurements->{'temperature'}->{'current'}} to print the current temperature in your template. I had to use {$measurements{'temperature'}{'current'}} instead, and I'm not entirely sure why. (If any monks have an idea, please let me know.) This was with version 1.41 (current as of 2001-10-22); I have emailed the author with the question and am awaiting a response.

With all that said, Text::Template is a great module for removing more of the display element from your code. For my scripts, I probably would have gone with either HTML::Template or Template Toolkit if they had been readily available.

Update: I overlooked one important section of the documentation. As Dominus politely pointed out in an email, the HASH section explains how the templates are filled. Indeed,

If the value is a reference to an array, then @key is set to that array. If the value is a reference to a hash, then %key is set to that hash. Similarly if value is any other kind of reference.

I always manage to miss the important parts of documentation. :-)

--PotPieMan

[markjugg]

Here's some more discussion on favorite templating systems.

-mark