FREQUENTLY ASKED QUESTIONS

In the interest of greater understanding I've started a FAQ section of
the perldocs.  Please look in here before you send me email.

1) Is there a place to go to discuss HTML::Template and/or get help?

There's a mailing-list for HTML::Template at htmltmpl@lists.vm.com.
Send a blank message to htmltmpl-subscribe@lists.vm.com to join!

2) I want support for <TMPL_XXX>!  How about it?

Maybe.  I definitely encourage people to discuss their ideas for
HTML::Template on the mailing list.  Please be ready to explain to me
how the new tag fits in with HTML::Template's mission to provide a
fast, lightweight system for using HTML templates.

NOTE: Offering to program said addition and provide it in the form of
a patch to the most recent version of HTML::Template will definitely
have a softening effect on potential opponents!

3) I found a bug, can you fix it?

That depends.  Did you send me the VERSION of HTML::Template, a test
script and a test template?  If so, then almost certainly.

If you're feeling really adventurous, HTML::Template has a publically
available CVS server.  See below for more information in the PUBLIC
CVS SERVER section.

4) <TMPL_VAR>s from the main template aren't working inside a <TMPL_LOOP>!  Why?

This is the intended behavior.  <TMPL_LOOP> introduces a separate
scope for <TMPL_VAR>s much like a subroutine call in Perl introduces a
separate scope for "my" variables.  

If you want your <TMPL_VAR>s to be global you can set the
'global_vars' option when you call new().  See above for documentation
of the 'global_vars' new() option.

5) Why do you use /[Tt]/ instead of /t/i?  It's so ugly!

Simple - the case-insensitive match switch is very inefficient.
According to _Mastering_Regular_Expressions_ from O'Reilly Press,
/[Tt]/ is faster and more space efficient than /t/i - by as much as
double against long strings.  //i essentially does a lc() on the
string and keeps a temporary copy in memory.

When this changes, and it is in the 5.6 development series, I will
gladly use //i.  Believe me, I realize [Tt] is hideously ugly.

6) How can I pre-load my templates using cache-mode and mod_perl?

Add something like this to your startup.pl:

   use HTML::Template;
   use File::Find;

   print STDERR "Pre-loading HTML Templates...\n";
   find(
        sub {
          return unless /\.tmpl$/;
          HTML::Template->new(
                              filename => "$File::Find::dir/$_",
                              cache => 1,
                             );
        },
        '/path/to/templates',
        '/another/path/to/templates/'
      );

Note that you'll need to modify the "return unless" line to specify
the extension you use for your template files - I use .tmpl, as you
can see.  You'll also need to specify the path to your template files.

One potential problem: the "/path/to/templates/" must be EXACTLY the
same path you use when you call HTML::Template->new().  Otherwise the
cache won't know they're the same file and will load a new copy -
instead getting a speed increase, you'll double your memory usage.  To
find out if this is happening set cache_debug => 1 in your application
code and look for "CACHE MISS" messages in the logs.

7) What characters are allowed in TMPL_* NAMEs?

Numbers, letters, '.', '/', '+', '-' and '_'.

8) How can I execute a program from inside my template?  

Short answer: you can't.  Longer answer: you shouldn't since this
violates the fundamental concept behind HTML::Template - that design
and code should be seperate.

But, inevitably some people still want to do it.  At times it has even
seemed that HTML::Template development might split over this issue, so
I will attempt a compromise.  Here is a method you can use to allow
your template authors to evaluate arbitrary perl scripts from within
the template.

First, tell all your designers that when they want to run a perl
script named "program.pl" they should use a tag like:

  <TMPL_VAR NAME="__execute_program.pl__">

Then, have all your programmers call this subroutine instead of
calling HTML::Template::new directly.  They still use the same
parameters, but they also get the program execution.  

  sub new_template {
    # get the template object
    my $template = HTML::Template->new(@_);
    
    # find program parameters and fill them in
    my @params = $template->param();
    for my $param (@params) {      
       if ($param =~ /^__execute_(.*)__$/) {
         $template->param($param, do($1));
       }
    }

    # return the template object
    return $template;
  }

The programs called in this way should return a string containing
their output.  A more complicated subroutine could be written to
capture STDOUT from the scripts, but this one is simple enough to
include in the FAQ.  Another improvement would be to use query() to
enable program execution inside loops.

9) Can I get a copy of these docs in Japanese?

Yes you can.  See Kawai Takanori's translation at:

   http://member.nifty.ne.jp/hippo2000/perltips/html/template.htm
