<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">use strict;
use warnings;
package HTML::Template::FAQ;

# ABSTRACT: Frequently Asked Questions about HTML::Template
use Carp ();
Carp::confess "you're not meant to use the FAQ, just read it!";
1;

__END__

=pod 

=head1 NAME 

HTML::Template::FAQ - Frequently Asked Questions about HTML::Template

=head1 SYNOPSIS

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

=head1 FREQUENTLY ASKED QUESTIONS

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

There's a mailing-list for discussing L&lt;HTML::Template&gt; at
html-template-users@lists.sourceforge.net. Join at:

   http://lists.sourceforge.net/lists/listinfo/html-template-users

If you just want to get email when new releases are available you can
join the announcements mailing-list here:

    http://lists.sourceforge.net/lists/listinfo/html-template-announce
    
=head2 Is there a searchable archive for the mailing-list?

Yes, you can find an archive of the SourceForge list here:

    http://dir.gmane.org/gmane.comp.lang.perl.modules.html-template

=head2 I want support for &lt;TMPL_XXX&gt;! How about it?

Maybe. I definitely encourage people to discuss their ideas for
L&lt;HTML::Template&gt; 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 L&lt;HTML::Template&gt; will definitely
have a softening effect on potential opponents!

=head2 I found a bug, can you fix it?

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

If you're feeling really adventurous, L&lt;HTML::Template&gt; is publicly
available on GitHub (https://github.com/mpeters/html-template). Please
feel free to fork it and send me a pull request with any changes you have.

=head2 &lt;TMPL_VAR&gt;s from the main template aren't working inside a &lt;TMPL_LOOP&gt;! Why?

This is the intended behavior. C&lt;&lt; &lt;TMPL_LOOP&gt; &gt;&gt; introduces a separate
scope for C&lt;&lt; &lt;TMPL_VAR&gt;s &gt;&gt; much like a subroutine call in Perl
introduces a separate scope for C&lt;my&gt; variables.

If you want your C&lt;&lt; &lt;TMPL_VAR&gt; &gt;&gt;s to be global you can set the
C&lt;global_vars&gt; option when you call C&lt;new()&gt;. See above for documentation
of the C&lt;global_vars&gt; C&lt;new()&gt; option.

=head2 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-&gt;new(
                filename =&gt; "$File::Find::dir/$_",
                cache    =&gt; 1,
            );
        },
        '/path/to/templates',
        '/another/path/to/templates/'
    );

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

One potential problem: the F&lt;/path/to/templates/&gt; must be B&lt;EXACTLY&gt; the
same path you use when you call C&lt;&lt; HTML::Template-&gt;new() &gt;&gt;. 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 C&lt;cache_debug =&gt; 1&gt; in your
application code and look for "CACHE MISS" messages in the logs.

=head2 What characters are allowed in TMPL_* names?

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

=head2 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 L&lt;HTML::Template&gt; - that design and code
should be separate.

But, inevitably some people still want to do it. If that describes
you then you should take a look at L&lt;HTML::Template::Expr&gt;. Using
L&lt;HTML::Template::Expr&gt; it should be easy to write a C&lt;run_program()&gt;
function. Then you can do awful stuff like:

    &lt;tmpl_var expr="run_program('foo.pl')"&gt;

Just, please, don't tell me about it. I'm feeling guilty enough just
for writing L&lt;HTML::Template::Expr&gt; in the first place.

=head2 What's the best way to create a &lt;select&gt; form element using HTML::Template?

There is much disagreement on this issue. My personal preference is
to use L&lt;CGI.pm&gt;'s excellent C&lt;popup_menu()&gt; and C&lt;scrolling_list()&gt;
functions to fill in a single C&lt;&lt; &lt;tmpl_var select_foo&gt; &gt;&gt; variable.

To some people this smacks of mixing HTML and code in a way that
they hoped L&lt;HTML::Template&gt; would help them avoid. To them I'd say
that HTML is a violation of the principle of separating design from
programming. There's no clear separation between the programmatic
elements of the C&lt;&lt; &lt;form&gt; &gt;&gt; tags and the layout of the C&lt;&lt; &lt;form&gt;
&gt;&gt; tags.  You'll have to draw the line somewhere - clearly the designer
can't be entirely in charge of form creation.

It's a balancing act and you have to weigh the pros and cons on each
side. It is certainly possible to produce a C&lt;&lt; &lt;select&gt; &gt;&gt; element
entirely inside the template. What you end up with is a rat's nest of
loops and conditionals. Alternately you can give up a certain amount of
flexibility in return for vastly simplifying your templates. I generally
choose the latter.

Another option is to investigate L&lt;HTML::FillInForm&gt; which some have
reported success using to solve this problem.
</pre></body></html>