perldoc > HTML::Template

Che Dong

📄 NAME

HTML::Template — Perl module to use HTML-like templating language

🚀 Quick Reference

Use Case	Command	Description
🆕 Create a template object	`my $t = HTML::Template->new(filename => 'file.tmpl')`	Load a template from a file
📝 Set a variable	`$t->param(NAME => 'value')`	Assign a value to a TMPL_VAR
🔄 Set a loop data	`$t->param(LOOP => [{...}, {...}])`	Pass an array of hashrefs for a TMPL_LOOP
🖨️ Output final HTML	`print $t->output()`	Generate the template output
🔍 Check if a parameter exists	`$t->query(name => 'VAR')`	Returns type (VAR, LOOP, etc.) or undef
🧹 Clear all parameters	`$t->clear_params()`	Reset all param values to undef
⚡ Lazy variable (code ref)	`$t->param(VAR => sub { expensive() })`	Only evaluated when used in template

📋 Synopsis

First you make a template — this is just a normal HTML file with a few extra tags, the simplest being <TMPL_VAR>

For example, test.tmpl:

<html>
<head><title>Test Template</title></head>
<body>
My Home Directory is <TMPL_VAR NAME=HOME>
<p>
My Path is set to <TMPL_VAR NAME=PATH>
</body>
</html>

Now you can use it in a small CGI program:

#!/usr/bin/perl -w
use HTML::Template;

# open the html template
my $template = HTML::Template->new(filename => 'test.tmpl');

# fill in some parameters
$template->param(HOME => $ENV{HOME});
$template->param(PATH => $ENV{PATH});

# send the obligatory Content-Type and print the template output
print "Content-Type: text/html\n\n", $template->output;

If all is well in the universe this should show something like this in your browser when visiting the CGI:

My Home Directory is /home/some/directory
My Path is set to /bin;/usr/bin

📖 Description

This module attempts to make using HTML templates simple and natural. It extends standard HTML with a few new HTML-esque tags — <TMPL_VAR>, <TMPL_LOOP>, <TMPL_INCLUDE>, <TMPL_IF>, <TMPL_ELSE> and <TMPL_UNLESS>. The file written with HTML and these new tags is called a template. It is usually saved separate from your script — possibly even created by someone else! Using this module you fill in the values for the variables, loops and branches declared in the template. This allows you to separate design — the HTML — from the data, which you generate in the Perl script.

This module is licensed under the same terms as Perl. See the LICENSE section below for more details.

📘 Tutorial

If you're new to HTML::Template, I suggest you start with the introductory article available on Perl Monks:

http://www.perlmonks.org/?node_id=65642

❓ FAQ

Please see HTML::Template::FAQ

💡 Motivation

It is true that there are a number of packages out there to do HTML templates. On the one hand you have things like HTML::Embperl which allows you freely mix Perl with HTML. On the other hand lie home-grown variable substitution solutions. Hopefully the module can find a place between the two.

One advantage of this module over a full HTML::Embperl-esque solution is that it enforces an important divide — design and programming. By limiting the programmer to just using simple variables and loops in the HTML, the template remains accessible to designers and other non-perl people. The use of HTML-esque syntax goes further to make the format understandable to others. In the future this similarity could be used to extend existing HTML editors/analyzers to support HTML::Template.

An advantage of this module over home-grown tag-replacement schemes is the support for loops. In my work I am often called on to produce tables of data in html. Producing them using simplistic HTML templates results in programs containing lots of HTML since the HTML itself cannot represent loops. The introduction of loop statements in the HTML simplifies this situation considerably. The designer can layout a single row and the programmer can fill it in as many times as necessary — all they must agree on is the parameter names.

For all that, I think the best thing about this module is that it does just one thing and it does it quickly and carefully. It doesn't try to replace Perl and HTML, it just augments them to interact a little better. And it's pretty fast.

🏷️ The Tags

🔤 TMPL_VAR

<TMPL_VAR NAME="PARAMETER_NAME">

The <TMPL_VAR> tag is very simple. For each <TMPL_VAR> tag in the template you call:

$template->param(PARAMETER_NAME => "VALUE")

When the template is output the <TMPL_VAR> is replaced with the VALUE text you specified. If you don't set a parameter it just gets skipped in the output.

You can also specify the value of the parameter as a code reference in order to have "lazy" variables. These sub routines will only be referenced if the variables are used. See LAZY VALUES for more information.

Attributes

The following attributes can also be specified in template var tags:

escape — This allows you to escape the value before it's put into the output. Useful when you want to use a TMPL_VAR in a context where those characters would cause trouble. For example:

<input name=param type=text value="<TMPL_VAR PARAM>">

If you called param() with a value like sam"my you'll get in trouble with HTML's idea of a double-quote. On the other hand, if you use escape=html, like this:

<input name=param type=text value="<TMPL_VAR PARAM ESCAPE=HTML>">

You'll get what you wanted no matter what value happens to be passed in for param.

The following escape values are supported:

html — Replaces &, ", ', <, > with HTML entities
js — Escapes \, ', ", \n, \r with backslash
url — URL escapes any ASCII characters except letters, numbers, _, ., -
none — No escaping (default) — useful to explicitly turn off escaping if using default_escape

default — Assign a default value to a variable. Example:

<TMPL_VAR WHO DEFAULT="the devil"> gave me a taco.

Outputs "the devil gave me a taco" if who is not set.

🔄 TMPL_LOOP

<TMPL_LOOP NAME="LOOP_NAME"> ... </TMPL_LOOP>

The <TMPL_LOOP> tag allows you to delimit a section of text and give it a name. Inside this named loop you place <TMPL_VAR>s. You pass to param() a list (an array ref) of parameter assignments (hash refs) for this loop. The loop iterates over the list and produces output from the text block for each pass. Unset parameters are skipped.

Example template:

<TMPL_LOOP NAME=EMPLOYEE_INFO>
   Name: <TMPL_VAR NAME=NAME> <br>
   Job:  <TMPL_VAR NAME=JOB>  <p>
</TMPL_LOOP>

Perl code:

$template->param(
    EMPLOYEE_INFO => [{name => 'Sam', job => 'programmer'}, {name => 'Steve', job => 'soda jerk'}]
);
print $template->output();

Output:

Name: Sam
Job: programmer

Name: Steve
Job: soda jerk

Nested loops work as expected. Each loop gets an array reference of hash references. Inside a loop, only the loop's variables are visible unless global_vars is used.

📂 TMPL_INCLUDE

<TMPL_INCLUDE NAME="filename.tmpl">

Includes a template directly at the point of the tag. The file can be absolute or relative. Search order: path of enclosing file, HTML_TEMPLATE_ROOT environment variable, path option, then direct open(). Maximum include depth is 10 (configurable via max_includes).

🤔 TMPL_IF

<TMPL_IF NAME="PARAMETER_NAME"> ... </TMPL_IF>

Conditionally includes a block if the parameter is true (in Perl sense). If the parameter is a loop name, the block is output if the loop has at least one row.

🔀 TMPL_ELSE

<TMPL_IF NAME="PARAMETER_NAME"> ... <TMPL_ELSE> ... </TMPL_IF>

Alternate block for <TMPL_IF>. End with </TMPL_IF>.

🚫 TMPL_UNLESS

<TMPL_UNLESS NAME="PARAMETER_NAME"> ... </TMPL_UNLESS>

Opposite of <TMPL_IF> — block is output if parameter is false or undefined. Works with <TMPL_ELSE>.

📝 Notes

HTML::Template's tags are meant to mimic normal HTML tags, but they can "break the rules" (e.g., <img src="<TMPL_VAR IMAGE_SRC>">). The NAME= is optional. Tags can also be written as HTML comments: .

🔧 Methods

🆕 new

Create a new Template object:

my $template = HTML::Template->new(
    filename => 'file.tmpl',
    option   => 'value',
);

Alternate source types: scalarref, arrayref, filehandle. Convenience methods: new_file, new_scalar_ref, new_array_ref, new_filehandle. Also new(type => 'filename', source => 'file.tmpl').

The environment variable HTML_TEMPLATE_ROOT affects relative paths.

Options

🔍 Error Detection Options

die_on_bad_params (default 1) — Die if setting a parameter not in template.
force_untaint (default 0) — Require untainted values. 1 = unescaped only, 2 = all parameters.
strict (default 1) — Die on unknown TMPL_* tags.
vanguard_compatibility_mode (default 0) — Accept %NAME% style vars.

💾 Caching Options

cache (default 0) — In-memory cache for persistent environments (mod_perl).
shared_cache (default 0) — Shared memory cache via IPC::SharedCache. Requires IPC::SharedCache.
double_cache (default 0) — Both shared_cache and normal cache.
blind_cache (default 0) — Cache without checking file modification time.
file_cache (default 0) — File-based cache using Storable. Requires file_cache_dir.
file_cache_dir — Directory for file cache.
file_cache_dir_mode (default 0700) — Permissions for cache directories.
double_file_cache (default 0) — Both file_cache and normal cache.
cache_lazy_vars (default 0) — Cache code ref results for TMPL_VARs.
cache_lazy_loops (default 0) — Cache code ref results for TMPL_LOOPs.

📁 Filesystem Options

path — Array of directories to search for template files (relative paths).
search_path_on_include (default 0) — Search path array on every TMPL_INCLUDE.
utf8 (default 0) — Treat templates as UTF-8 encoded.
open_mode — PerlIO mode string for opening template files (e.g., '