1HTML::Template(3) User Contributed Perl Documentation HTML::Template(3)
2
6 HTML::Template - Perl module to use HTML-like templating language
7
9 First you make a template - this is just a normal HTML file with a few
10 extra tags, the simplest being "<TMPL_VAR>"
11 For example, test.tmpl:
13 <html>
15 <head><title>Test Template</title></head>
16 <body>
17 My Home Directory is <TMPL_VAR NAME=HOME>
18 <p>
19 My Path is set to <TMPL_VAR NAME=PATH>
20 </body>
21 </html>
22 Now you can use it in a small CGI program:
24 #!/usr/bin/perl -w
26 use HTML::Template;
27 # open the html template
29 my $template = HTML::Template->new(filename => 'test.tmpl');
30 # fill in some parameters
32 $template->param(HOME => $ENV{HOME});
33 $template->param(PATH => $ENV{PATH});
34 # send the obligatory Content-Type and print the template output
36 print "Content-Type: text/html\n\n", $template->output;
37 If all is well in the universe this should show something like this in
39 your browser when visiting the CGI:
40 My Home Directory is /home/some/directory
42 My Path is set to /bin;/usr/bin
43
45 This module attempts to make using HTML templates simple and natural.
46 It extends standard HTML with a few new HTML-esque tags - "<TMPL_VAR>"
47 "<TMPL_LOOP>", "<TMPL_INCLUDE>", "<TMPL_IF>", "<TMPL_ELSE>" and
48 "<TMPL_UNLESS>". The file written with HTML and these new tags is
49 called a template. It is usually saved separate from your script -
50 possibly even created by someone else! Using this module you fill in
51 the values for the variables, loops and branches declared in the
52 template. This allows you to separate design - the HTML - from the
53 data, which you generate in the Perl script.
54 This module is licensed under the same terms as Perl. See the LICENSE
56 section below for more details.
57
59 If you're new to HTML::Template, I suggest you start with the
60 introductory article available on Perl Monks:
61 http://www.perlmonks.org/?node_id=65642
63
65 Please see HTML::Template::FAQ
66
68 It is true that there are a number of packages out there to do HTML
69 templates. On the one hand you have things like HTML::Embperl which
70 allows you freely mix Perl with HTML. On the other hand lie home-grown
71 variable substitution solutions. Hopefully the module can find a place
72 between the two.
73 One advantage of this module over a full HTML::Embperl-esque solution
75 is that it enforces an important divide - design and programming. By
76 limiting the programmer to just using simple variables and loops in the
77 HTML, the template remains accessible to designers and other non-perl
78 people. The use of HTML-esque syntax goes further to make the format
79 understandable to others. In the future this similarity could be used
80 to extend existing HTML editors/analyzers to support HTML::Template.
81 An advantage of this module over home-grown tag-replacement schemes is
83 the support for loops. In my work I am often called on to produce
84 tables of data in html. Producing them using simplistic HTML templates
85 results in programs containing lots of HTML since the HTML itself
86 cannot represent loops. The introduction of loop statements in the
87 HTML simplifies this situation considerably. The designer can layout a
88 single row and the programmer can fill it in as many times as necessary
89 - all they must agree on is the parameter names.
90 For all that, I think the best thing about this module is that it does
92 just one thing and it does it quickly and carefully. It doesn't try to
93 replace Perl and HTML, it just augments them to interact a little
94 better. And it's pretty fast.
95
97 TMPL_VAR
98 <TMPL_VAR NAME="PARAMETER_NAME">
99 The "<TMPL_VAR>" tag is very simple. For each "<TMPL_VAR>" tag in the
101 template you call:
102 $template->param(PARAMETER_NAME => "VALUE")
104 When the template is output the "<TMPL_VAR>" is replaced with the VALUE
106 text you specified. If you don't set a parameter it just gets skipped
107 in the output.
108 You can also specify the value of the parameter as a code reference in
110 order to have "lazy" variables. These sub routines will only be
111 referenced if the variables are used. See "LAZY VALUES" for more
112 information.
113 Attributes
115 The following "attributes" can also be specified in template var tags:
117 • escape
119 This allows you to escape the value before it's put into the
121 output.
122 This is useful when you want to use a TMPL_VAR in a context where
124 those characters would cause trouble. For example:
125 <input name=param type=text value="<TMPL_VAR PARAM>">
127 If you called param() with a value like "sam"my" you'll get in
129 trouble with HTML's idea of a double-quote. On the other hand, if
130 you use "escape=html", like this:
131 <input name=param type=text value="<TMPL_VAR PARAM ESCAPE=HTML>">
133 You'll get what you wanted no matter what value happens to be
135 passed in for param.
136 The following escape values are supported:
138 • html
140 Replaces the following characters with their HTML entity
142 equivalent: "&", """, "'", "<", ">"
143 • js
145 Escapes (with a backslash) the following characters: "\", "'",
147 """, "\n", "\r"
148 • url
150 URL escapes any ASCII characters except for letters, numbers,
152 "_", "." and "-".
153 • none
155 Performs no escaping. This is the default, but it's useful to
157 be able to explicitly turn off escaping if you are using the
158 "default_escape" option.
159 • default
161 With this attribute you can assign a default value to a variable.
163 For example, this will output "the devil gave me a taco" if the
164 "who" variable is not set.
165 <TMPL_VAR WHO DEFAULT="the devil"> gave me a taco.
167 TMPL_LOOP
169 <TMPL_LOOP NAME="LOOP_NAME"> ... </TMPL_LOOP>
170 The "<TMPL_LOOP>" tag is a bit more complicated than "<TMPL_VAR>". The
172 "<TMPL_LOOP>" tag allows you to delimit a section of text and give it a
173 name. Inside this named loop you place "<TMPL_VAR>"s. Now you pass to
174 param() a list (an array ref) of parameter assignments (hash refs) for
175 this loop. The loop iterates over the list and produces output from
176 the text block for each pass. Unset parameters are skipped. Here's an
177 example:
178 In the template:
180 <TMPL_LOOP NAME=EMPLOYEE_INFO>
182 Name: <TMPL_VAR NAME=NAME> <br>
183 Job: <TMPL_VAR NAME=JOB> <p>
184 </TMPL_LOOP>
185 In your Perl code:
187 $template->param(
189 EMPLOYEE_INFO => [{name => 'Sam', job => 'programmer'}, {name => 'Steve', job => 'soda jerk'}]
190 );
191 print $template->output();
192 The output is:
194 Name: Sam
196 Job: programmer
197 Name: Steve
199 Job: soda jerk
200 As you can see above the "<TMPL_LOOP>" takes a list of variable
202 assignments and then iterates over the loop body producing output.
203 Often you'll want to generate a "<TMPL_LOOP>"'s contents
205 programmatically. Here's an example of how this can be done (many
206 other ways are possible!):
207 # a couple of arrays of data to put in a loop:
209 my @words = qw(I Am Cool);
210 my @numbers = qw(1 2 3);
211 my @loop_data = (); # initialize an array to hold your loop
212 while (@words and @numbers) {
214 my %row_data; # get a fresh hash for the row data
215 # fill in this row
217 $row_data{WORD} = shift @words;
218 $row_data{NUMBER} = shift @numbers;
219 # the crucial step - push a reference to this row into the loop!
221 push(@loop_data, \%row_data);
222 }
223 # finally, assign the loop data to the loop param, again with a reference:
225 $template->param(THIS_LOOP => \@loop_data);
226 The above example would work with a template like:
228 <TMPL_LOOP NAME="THIS_LOOP">
230 Word: <TMPL_VAR NAME="WORD">
231 Number: <TMPL_VAR NAME="NUMBER">
232 </TMPL_LOOP>
234 It would produce output like:
236 Word: I
238 Number: 1
239 Word: Am
241 Number: 2
242 Word: Cool
244 Number: 3
245 "<TMPL_LOOP>"s within "<TMPL_LOOP>"s are fine and work as you would
247 expect. If the syntax for the param() call has you stumped, here's an
248 example of a param call with one nested loop:
249 $template->param(
251 LOOP => [
252 {
253 name => 'Bobby',
254 nicknames => [{name => 'the big bad wolf'}, {name => 'He-Man'}],
255 },
256 ],
257 );
258 Basically, each "<TMPL_LOOP>" gets an array reference. Inside the
260 array are any number of hash references. These hashes contain the
261 name=>value pairs for a single pass over the loop template.
262 Inside a "<TMPL_LOOP>", the only variables that are usable are the ones
264 from the "<TMPL_LOOP>". The variables in the outer blocks are not
265 visible within a template loop. For the computer-science geeks among
266 you, a "<TMPL_LOOP>" introduces a new scope much like a perl subroutine
267 call. If you want your variables to be global you can use
268 "global_vars" option to new() described below.
269 TMPL_INCLUDE
271 <TMPL_INCLUDE NAME="filename.tmpl">
272 This tag includes a template directly into the current template at the
274 point where the tag is found. The included template contents are used
275 exactly as if its contents were physically included in the master
276 template.
277 The file specified can be an absolute path (beginning with a '/' under
279 Unix, for example). If it isn't absolute, the path to the enclosing
280 file is tried first. After that the path in the environment variable
281 "HTML_TEMPLATE_ROOT" is tried, if it exists. Next, the "path" option
282 is consulted, first as-is and then with "HTML_TEMPLATE_ROOT" prepended
283 if available. As a final attempt, the filename is passed to open()
284 directly. See below for more information on "HTML_TEMPLATE_ROOT" and
285 the "path" option to new().
286 As a protection against infinitely recursive includes, an arbitrary
288 limit of 10 levels deep is imposed. You can alter this limit with the
289 "max_includes" option. See the entry for the "max_includes" option
290 below for more details.
291 TMPL_IF
293 <TMPL_IF NAME="PARAMETER_NAME"> ... </TMPL_IF>
294 The "<TMPL_IF>" tag allows you to include or not include a block of the
296 template based on the value of a given parameter name. If the
297 parameter is given a value that is true for Perl - like '1' - then the
298 block is included in the output. If it is not defined, or given a
299 false value - like '0' - then it is skipped. The parameters are
300 specified the same way as with "<TMPL_VAR>".
301 Example Template:
303 <TMPL_IF NAME="BOOL">
305 Some text that only gets displayed if BOOL is true!
306 </TMPL_IF>
307 Now if you call "$template->param(BOOL => 1)" then the above block will
309 be included by output.
310 "<TMPL_IF> </TMPL_IF>" blocks can include any valid HTML::Template
312 construct - "VAR"s and "LOOP"s and other "IF"/"ELSE" blocks. Note,
313 however, that intersecting a "<TMPL_IF>" and a "<TMPL_LOOP>" is
314 invalid.
315 Not going to work:
317 <TMPL_IF BOOL>
318 <TMPL_LOOP SOME_LOOP>
319 </TMPL_IF>
320 </TMPL_LOOP>
321 If the name of a "<TMPL_LOOP>" is used in a "<TMPL_IF>", the "IF" block
323 will output if the loop has at least one row. Example:
324 <TMPL_IF LOOP_ONE>
326 This will output if the loop is not empty.
327 </TMPL_IF>
328 <TMPL_LOOP LOOP_ONE>
330 ....
331 </TMPL_LOOP>
332 WARNING: Much of the benefit of HTML::Template is in decoupling your
334 Perl and HTML. If you introduce numerous cases where you have
335 "TMPL_IF"s and matching Perl "if"s, you will create a maintenance
336 problem in keeping the two synchronized. I suggest you adopt the
337 practice of only using "TMPL_IF" if you can do so without requiring a
338 matching "if" in your Perl code.
339 TMPL_ELSE
341 <TMPL_IF NAME="PARAMETER_NAME"> ... <TMPL_ELSE> ... </TMPL_IF>
342 You can include an alternate block in your "<TMPL_IF>" block by using
344 "<TMPL_ELSE>". NOTE: You still end the block with "</TMPL_IF>", not
345 "</TMPL_ELSE>"!
346 Example:
348 <TMPL_IF BOOL>
349 Some text that is included only if BOOL is true
350 <TMPL_ELSE>
351 Some text that is included only if BOOL is false
352 </TMPL_IF>
353 TMPL_UNLESS
355 <TMPL_UNLESS NAME="PARAMETER_NAME"> ... </TMPL_UNLESS>
356 This tag is the opposite of "<TMPL_IF>". The block is output if the
358 "PARAMETER_NAME" is set false or not defined. You can use
359 "<TMPL_ELSE>" with "<TMPL_UNLESS>" just as you can with "<TMPL_IF>".
360 Example:
362 <TMPL_UNLESS BOOL>
363 Some text that is output only if BOOL is FALSE.
364 <TMPL_ELSE>
365 Some text that is output only if BOOL is TRUE.
366 </TMPL_UNLESS>
367 If the name of a "<TMPL_LOOP>" is used in a "<TMPL_UNLESS>", the
369 "<UNLESS>" block output if the loop has zero rows.
370 <TMPL_UNLESS LOOP_ONE>
372 This will output if the loop is empty.
373 </TMPL_UNLESS>
374 <TMPL_LOOP LOOP_ONE>
376 ....
377 </TMPL_LOOP>
378 NOTES
380 HTML::Template's tags are meant to mimic normal HTML tags. However,
381 they are allowed to "break the rules". Something like:
382 <img src="<TMPL_VAR IMAGE_SRC>">
384 is not really valid HTML, but it is a perfectly valid use and will work
386 as planned.
387 The "NAME=" in the tag is optional, although for extensibility's sake I
389 recommend using it. Example - "<TMPL_LOOP LOOP_NAME>" is acceptable.
390 If you're a fanatic about valid HTML and would like your templates to
392 conform to valid HTML syntax, you may optionally type template tags in
393 the form of HTML comments. This may be of use to HTML authors who would
394 like to validate their templates' HTML syntax prior to HTML::Template
395 processing, or who use DTD-savvy editing tools.
396 <!-- TMPL_VAR NAME=PARAM1 -->
398 In order to realize a dramatic savings in bandwidth, the standard (non-
400 comment) tags will be used throughout this documentation.
401
403 new
404 Call new() to create a new Template object:
405 my $template = HTML::Template->new(
407 filename => 'file.tmpl',
408 option => 'value',
409 );
410 You must call new() with at least one "name =" value> pair specifying
412 how to access the template text. You can use "filename => 'file.tmpl'"
413 to specify a filename to be opened as the template. Alternately you
414 can use:
415 my $t = HTML::Template->new(
417 scalarref => $ref_to_template_text,
418 option => 'value',
419 );
420 and
422 my $t = HTML::Template->new(
424 arrayref => $ref_to_array_of_lines,
425 option => 'value',
426 );
427 These initialize the template from in-memory resources. In almost
429 every case you'll want to use the filename parameter. If you're
430 worried about all the disk access from reading a template file just use
431 mod_perl and the cache option detailed below.
432 You can also read the template from an already opened filehandle,
434 either traditionally as a glob or as a FileHandle:
435 my $t = HTML::Template->new(filehandle => *FH, option => 'value');
437 The four new() calling methods can also be accessed as below, if you
439 prefer.
440 my $t = HTML::Template->new_file('file.tmpl', option => 'value');
442 my $t = HTML::Template->new_scalar_ref($ref_to_template_text, option => 'value');
444 my $t = HTML::Template->new_array_ref($ref_to_array_of_lines, option => 'value');
446 my $t = HTML::Template->new_filehandle($fh, option => 'value');
448 And as a final option, for those that might prefer it, you can call new
450 as:
451 my $t = HTML::Template->new(
453 type => 'filename',
454 source => 'file.tmpl',
455 );
456 Which works for all three of the source types.
458 If the environment variable "HTML_TEMPLATE_ROOT" is set and your
460 filename doesn't begin with "/", then the path will be relative to the
461 value of c<HTML_TEMPLATE_ROOT>.
462 Example - if the environment variable "HTML_TEMPLATE_ROOT" is set to
464 /home/sam and I call "HTML::Template->new()" with filename set to
465 "sam.tmpl", HTML::Template will try to open /home/sam/sam.tmpl to
466 access the template file. You can also affect the search path for
467 files with the "path" option to new() - see below for more information.
468 You can modify the Template object's behavior with new(). The options
470 are available:
471 Error Detection Options
473 • die_on_bad_params
475 If set to 0 the module will let you call:
477 $template->param(param_name => 'value')
479 even if 'param_name' doesn't exist in the template body. Defaults
481 to 1.
482 • force_untaint
484 If set to 1 the module will not allow you to set unescaped
486 parameters with tainted values. If set to 2 you will have to
487 untaint all parameters, including ones with the escape attribute.
488 This option makes sure you untaint everything so you don't
489 accidentally introduce e.g. cross-site-scripting (XSS)
490 vulnerabilities. Requires taint mode. Defaults to 0.
491 • strict - if set to 0 the module will allow things that look like
493 they might be TMPL_* tags to get by without dieing. Example:
494 <TMPL_HUH NAME=ZUH>
496 Would normally cause an error, but if you call new with "strict =>
498 0" HTML::Template will ignore it. Defaults to 1.
499 • vanguard_compatibility_mode
501 If set to 1 the module will expect to see "<TMPL_VAR>"s that look
503 like "%NAME%" in addition to the standard syntax. Also sets
504 "die_on_bad_params =" 0>. If you're not at Vanguard Media trying
505 to use an old format template don't worry about this one. Defaults
506 to 0.
507 Caching Options
509 • cache
511 If set to 1 the module will cache in memory the parsed templates
513 based on the filename parameter, the modification date of the file
514 and the options passed to new(). This only applies to templates
515 opened with the filename parameter specified, not scalarref or
516 arrayref templates. Caching also looks at the modification times
517 of any files included using "<TMPL_INCLUDE>" tags, but again, only
518 if the template is opened with filename parameter.
519 This is mainly of use in a persistent environment like
521 Apache/mod_perl. It has absolutely no benefit in a normal CGI
522 environment since the script is unloaded from memory after every
523 request. For a cache that does work for a non-persistent
524 environment see the "shared_cache" option below.
525 My simplistic testing shows that using cache yields a 90%
527 performance increase under mod_perl. Cache defaults to 0.
528 • shared_cache
530 If set to 1 the module will store its cache in shared memory using
532 the IPC::SharedCache module (available from CPAN). The effect of
533 this will be to maintain a single shared copy of each parsed
534 template for all instances of HTML::Template on the same machine to
535 use. This can be a significant reduction in memory usage in an
536 environment with a single machine but multiple servers. As an
537 example, on one of our systems we use 4MB of template cache and
538 maintain 25 httpd processes - shared_cache results in saving almost
539 100MB! Of course, some reduction in speed versus normal caching is
540 to be expected. Another difference between normal caching and
541 shared_cache is that shared_cache will work in a non-persistent
542 environment (like normal CGI) - normal caching is only useful in a
543 persistent environment like Apache/mod_perl.
544 By default HTML::Template uses the IPC key 'TMPL' as a shared root
546 segment (0x4c504d54 in hex), but this can be changed by setting the
547 "ipc_key" new() parameter to another 4-character or integer key.
548 Other options can be used to affect the shared memory cache
549 correspond to IPC::SharedCache options - "ipc_mode",
550 "ipc_segment_size" and "ipc_max_size". See IPC::SharedCache for a
551 description of how these work - in most cases you shouldn't need to
552 change them from the defaults.
553 For more information about the shared memory cache system used by
555 HTML::Template see IPC::SharedCache.
556 • double_cache
558 If set to 1 the module will use a combination of "shared_cache" and
560 normal cache mode for the best possible caching. Of course, it
561 also uses the most memory of all the cache modes. All the same
562 ipc_* options that work with "shared_cache" apply to "double_cache"
563 as well. Defaults to 0.
564 • blind_cache
566 If set to 1 the module behaves exactly as with normal caching but
568 does not check to see if the file has changed on each request.
569 This option should be used with caution, but could be of use on
570 high-load servers. My tests show "blind_cache" performing only 1
571 to 2 percent faster than cache under mod_perl.
572 NOTE: Combining this option with shared_cache can result in stale
574 templates stuck permanently in shared memory!
575 • file_cache
577 If set to 1 the module will store its cache in a file using the
579 Storable module. It uses no additional memory, and my simplistic
580 testing shows that it yields a 50% performance advantage. Like
581 "shared_cache", it will work in a non-persistent environments (like
582 CGI). Default is 0.
583 If you set this option you must set the "file_cache_dir" option.
585 See below for details.
586 NOTE: Storable uses flock() to ensure safe access to cache files.
588 Using "file_cache" on a system or filesystem (like NFS) without
589 flock() support is dangerous.
590 • file_cache_dir
592 Sets the directory where the module will store the cache files if
594 "file_cache" is enabled. Your script will need write permissions
595 to this directory. You'll also need to make sure the sufficient
596 space is available to store the cache files.
597 • file_cache_dir_mode
599 Sets the file mode for newly created "file_cache" directories and
601 subdirectories. Defaults to "0700" for security but this may be
602 inconvenient if you do not have access to the account running the
603 webserver.
604 • double_file_cache
606 If set to 1 the module will use a combination of "file_cache" and
608 normal "cache" mode for the best possible caching. The
609 file_cache_* options that work with file_cache apply to
610 "double_file_cache" as well. Defaults to 0.
611 • cache_lazy_vars
613 The option tells HTML::Template to cache the values returned from
615 code references used for "TMPL_VAR"s. See "LAZY VALUES" for
616 details.
617 • cache_lazy_loops
619 The option tells HTML::Template to cache the values returned from
621 code references used for "TMPL_LOOP"s. See "LAZY VALUES" for
622 details.
623 Filesystem Options
625 • path
627 You can set this variable with a list of paths to search for files
629 specified with the "filename" option to new() and for files
630 included with the "<TMPL_INCLUDE>" tag. This list is only
631 consulted when the filename is relative. The "HTML_TEMPLATE_ROOT"
632 environment variable is always tried first if it exists. Also, if
633 "HTML_TEMPLATE_ROOT" is set then an attempt will be made to prepend
634 "HTML_TEMPLATE_ROOT" onto paths in the path array. In the case of
635 a "<TMPL_INCLUDE>" file, the path to the including file is also
636 tried before path is consulted.
637 Example:
639 my $template = HTML::Template->new(
641 filename => 'file.tmpl',
642 path => ['/path/to/templates', '/alternate/path'],
643 );
644 NOTE: the paths in the path list must be expressed as UNIX paths,
646 separated by the forward-slash character ('/').
647 • search_path_on_include
649 If set to a true value the module will search from the top of the
651 array of paths specified by the path option on every
652 "<TMPL_INCLUDE>" and use the first matching template found. The
653 normal behavior is to look only in the current directory for a
654 template to include. Defaults to 0.
655 • utf8
657 Setting this to true tells HTML::Template to treat your template
659 files as UTF-8 encoded. This will apply to any file's passed to
660 new() or any included files. It won't do anything special to
661 scalars templates passed to new() since you should be doing the
662 encoding on those yourself.
663 my $template = HTML::Template->new(
665 filename => 'umlauts_are_awesome.tmpl',
666 utf8 => 1,
667 );
668 Most templates are either ASCII (the default) or UTF-8 encoded
670 Unicode. But if you need some other encoding other than these 2,
671 look at the "open_mode" option.
672 NOTE: The "utf8" and "open_mode" options cannot be used at the same
674 time.
675 • open_mode
677 You can set this option to an opening mode with which all template
679 files will be opened.
680 For example, if you want to use a template that is UTF-16 encoded
682 unicode:
683 my $template = HTML::Template->new(
685 filename => 'file.tmpl',
686 open_mode => '<:encoding(UTF-16)',
687 );
688 That way you can force a different encoding (than the default ASCII
690 or UTF-8), CR/LF properties etc. on the template files. See PerlIO
691 for details.
692 NOTE: this only works in perl 5.7.1 and above.
694 NOTE: you have to supply an opening mode that actually permits
696 reading from the file handle.
697 NOTE: The "utf8" and "open_mode" options cannot be used at the same
699 time.
700 Debugging Options
702 • debug
704 If set to 1 the module will write random debugging information to
706 STDERR. Defaults to 0.
707 • stack_debug
709 If set to 1 the module will use Data::Dumper to print out the
711 contents of the parse_stack to STDERR. Defaults to 0.
712 • cache_debug
714 If set to 1 the module will send information on cache loads, hits
716 and misses to STDERR. Defaults to 0.
717 • shared_cache_debug
719 If set to 1 the module will turn on the debug option in
721 IPC::SharedCache. Defaults to 0.
722 • memory_debug
724 If set to 1 the module will send information on cache memory usage
726 to STDERR. Requires the GTop module. Defaults to 0.
727 Miscellaneous Options
729 • associate
731 This option allows you to inherit the parameter values from other
733 objects. The only requirement for the other object is that it have
734 a param() method that works like HTML::Template's param(). A good
735 candidate would be a CGI query object. Example:
736 my $query = CGI->new;
738 my $template = HTML::Template->new(
739 filename => 'template.tmpl',
740 associate => $query,
741 );
742 Now, "$template->output()" will act as though
744 $template->param(form_field => $cgi->param('form_field'));
746 had been specified for each key/value pair that would be provided
748 by the "$cgi->param()" method. Parameters you set directly take
749 precedence over associated parameters.
750 You can specify multiple objects to associate by passing an
752 anonymous array to the associate option. They are searched for
753 parameters in the order they appear:
754 my $template = HTML::Template->new(
756 filename => 'template.tmpl',
757 associate => [$query, $other_obj],
758 );
759 NOTE: The parameter names are matched in a case-insensitive manner.
761 If you have two parameters in a CGI object like 'NAME' and 'Name'
762 one will be chosen randomly by associate. This behavior can be
763 changed by the "case_sensitive" option.
764 • case_sensitive
766 Setting this option to true causes HTML::Template to treat template
768 variable names case-sensitively. The following example would only
769 set one parameter without the "case_sensitive" option:
770 my $template = HTML::Template->new(
772 filename => 'template.tmpl',
773 case_sensitive => 1
774 );
775 $template->param(
776 FieldA => 'foo',
777 fIELDa => 'bar',
778 );
779 This option defaults to off.
781 NOTE: with "case_sensitive" and "loop_context_vars" the special
783 loop variables are available in lower-case only.
784 • loop_context_vars
786 When this parameter is set to true (it is false by default) extra
788 variables that depend on the loop's context are made available
789 inside a loop. These are:
790 • __first__
792 Value that is true for the first iteration of the loop and
794 false every other time.
795 • __last__
797 Value that is true for the last iteration of the loop and false
799 every other time.
800 • __inner__
802 Value that is true for the every iteration of the loop except
804 for the first and last.
805 • __outer__
807 Value that is true for the first and last iterations of the
809 loop.
810 • __odd__
812 Value that is true for the every odd iteration of the loop.
814 • __even__
816 Value that is true for the every even iteration of the loop.
818 • __counter__
820 An integer (starting from 1) whose value increments for each
822 iteration of the loop.
823 • __index__
825 An integer (starting from 0) whose value increments for each
827 iteration of the loop.
828 Just like any other "TMPL_VAR"s these variables can be used in
830 "<TMPL_IF>", "<TMPL_UNLESS>" and "<TMPL_ELSE>" to control how a
831 loop is output.
832 Example:
834 <TMPL_LOOP NAME="FOO">
836 <TMPL_IF NAME="__first__">
837 This only outputs on the first pass.
838 </TMPL_IF>
839 <TMPL_IF NAME="__odd__">
841 This outputs every other pass, on the odd passes.
842 </TMPL_IF>
843 <TMPL_UNLESS NAME="__odd__">
845 This outputs every other pass, on the even passes.
846 </TMPL_UNLESS>
847 <TMPL_IF NAME="__inner__">
849 This outputs on passes that are neither first nor last.
850 </TMPL_IF>
851 This is pass number <TMPL_VAR NAME="__counter__">.
853 <TMPL_IF NAME="__last__">
855 This only outputs on the last pass.
856 </TMPL_IF>
857 </TMPL_LOOP>
858 One use of this feature is to provide a "separator" similar in
860 effect to the perl function join(). Example:
861 <TMPL_LOOP FRUIT>
863 <TMPL_IF __last__> and </TMPL_IF>
864 <TMPL_VAR KIND><TMPL_UNLESS __last__>, <TMPL_ELSE>.</TMPL_UNLESS>
865 </TMPL_LOOP>
866 Would output something like:
868 Apples, Oranges, Brains, Toes, and Kiwi.
870 Given an appropriate param() call, of course. NOTE: A loop with
872 only a single pass will get both "__first__" and "__last__" set to
873 true, but not "__inner__".
874 • no_includes
876 Set this option to 1 to disallow the "<TMPL_INCLUDE>" tag in the
878 template file. This can be used to make opening untrusted
879 templates slightly less dangerous. Defaults to 0.
880 • max_includes
882 Set this variable to determine the maximum depth that includes can
884 reach. Set to 10 by default. Including files to a depth greater
885 than this value causes an error message to be displayed. Set to 0
886 to disable this protection.
887 • die_on_missing_include
889 If true, then HTML::Template will die if it can't find a file for a
891 "<TMPL_INCLUDE>". This defaults to true.
892 • global_vars
894 Normally variables declared outside a loop are not available inside
896 a loop. This option makes "<TMPL_VAR>"s like global variables in
897 Perl - they have unlimited scope. This option also affects
898 "<TMPL_IF>" and "<TMPL_UNLESS>".
899 Example:
901 This is a normal variable: <TMPL_VAR NORMAL>.<P>
903 <TMPL_LOOP NAME=FROOT_LOOP>
905 Here it is inside the loop: <TMPL_VAR NORMAL><P>
906 </TMPL_LOOP>
907 Normally this wouldn't work as expected, since "<TMPL_VAR
909 NORMAL>"'s value outside the loop is not available inside the loop.
910 The global_vars option also allows you to access the values of an
912 enclosing loop within an inner loop. For example, in this loop the
913 inner loop will have access to the value of "OUTER_VAR" in the
914 correct iteration:
915 <TMPL_LOOP OUTER_LOOP>
917 OUTER: <TMPL_VAR OUTER_VAR>
918 <TMPL_LOOP INNER_LOOP>
919 INNER: <TMPL_VAR INNER_VAR>
920 INSIDE OUT: <TMPL_VAR OUTER_VAR>
921 </TMPL_LOOP>
922 </TMPL_LOOP>
923 One side-effect of "global_vars" is that variables you set with
925 param() that might otherwise be ignored when "die_on_bad_params" is
926 off will stick around. This is necessary to allow inner loops to
927 access values set for outer loops that don't directly use the
928 value.
929 NOTE: "global_vars" is not "global_loops" (which does not exist).
931 That means that loops you declare at one scope are not available
932 inside other loops even when "global_vars" is on.
933 • filter
935 This option allows you to specify a filter for your template files.
937 A filter is a subroutine that will be called after HTML::Template
938 reads your template file but before it starts parsing template
939 tags.
940 In the most simple usage, you simply assign a code reference to the
942 filter parameter. This subroutine will receive a single argument -
943 a reference to a string containing the template file text. Here is
944 an example that accepts templates with tags that look like
945 "!!!ZAP_VAR FOO!!!" and transforms them into HTML::Template tags:
946 my $filter = sub {
948 my $text_ref = shift;
949 $$text_ref =~ s/!!!ZAP_(.*?)!!!/<TMPL_$1>/g;
950 };
951 # open zap.tmpl using the above filter
953 my $template = HTML::Template->new(
954 filename => 'zap.tmpl',
955 filter => $filter,
956 );
957 More complicated usages are possible. You can request that your
959 filter receives the template text as an array of lines rather than
960 as a single scalar. To do that you need to specify your filter
961 using a hash-ref. In this form you specify the filter using the
962 "sub" key and the desired argument format using the "format" key.
963 The available formats are "scalar" and "array". Using the "array"
964 format will incur a performance penalty but may be more convenient
965 in some situations.
966 my $template = HTML::Template->new(
968 filename => 'zap.tmpl',
969 filter => {
970 sub => $filter,
971 format => 'array',
972 }
973 );
974 You may also have multiple filters. This allows simple filters to
976 be combined for more elaborate functionality. To do this you
977 specify an array of filters. The filters are applied in the order
978 they are specified.
979 my $template = HTML::Template->new(
981 filename => 'zap.tmpl',
982 filter => [
983 {
984 sub => \&decompress,
985 format => 'scalar',
986 },
987 {
988 sub => \&remove_spaces,
989 format => 'array',
990 },
991 ]
992 );
993 The specified filters will be called for any "TMPL_INCLUDE"ed files
995 just as they are for the main template file.
996 • default_escape
998 Set this parameter to a valid escape type (see the "escape" option)
1000 and HTML::Template will apply the specified escaping to all
1001 variables unless they declare a different escape in the template.
1002 config
1004 A package method that is used to set/get the global default
1005 configuration options. For instance, if you want to set the "utf8"
1006 flag to always be on for every template loaded by this process you
1007 would do:
1008 HTML::Template->config(utf8 => 1);
1010 Or if you wanted to check if the "utf8" flag was on or not, you could
1012 do:
1013 my %config = HTML::Template->config;
1015 if( $config{utf8} ) {
1016 ...
1017 }
1018 Any configuration options that are valid for new() are acceptable to be
1020 passed to this method.
1021 param
1023 param() can be called in a number of ways
1024 1 - To return a list of parameters in the template :
1026 my @parameter_names = $self->param();
1027 2 - To return the value set to a param :
1029 my $value = $self->param('PARAM');
1030 3 - To set the value of a parameter :
1032 # For simple TMPL_VARs:
1033 $self->param(PARAM => 'value');
1034 # with a subroutine reference that gets called to get the value
1036 # of the scalar. The sub will receive the template object as a
1037 # parameter.
1038 $self->param(PARAM => sub { return 'value' });
1039 # And TMPL_LOOPs:
1041 $self->param(LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}]);
1042 4 - To set the value of a number of parameters :
1044 # For simple TMPL_VARs:
1045 $self->param(
1046 PARAM => 'value',
1047 PARAM2 => 'value'
1048 );
1049 # And with some TMPL_LOOPs:
1051 $self->param(
1052 PARAM => 'value',
1053 PARAM2 => 'value',
1054 LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}],
1055 ANOTHER_LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}],
1056 );
1057 5 - To set the value of a number of parameters using a hash-ref :
1059 $self->param(
1060 {
1061 PARAM => 'value',
1062 PARAM2 => 'value',
1063 LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}],
1064 ANOTHER_LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}],
1065 }
1066 );
1067 An error occurs if you try to set a value that is tainted if the
1069 "force_untaint" option is set.
1070 clear_params
1072 Sets all the parameters to undef. Useful internally, if nowhere else!
1073 output
1075 output() returns the final result of the template. In most situations
1076 you'll want to print this, like:
1077 print $template->output();
1079 When output is called each occurrence of "<TMPL_VAR NAME=name>" is
1081 replaced with the value assigned to "name" via param(). If a named
1082 parameter is unset it is simply replaced with ''. "<TMPL_LOOP>"s are
1083 evaluated once per parameter set, accumulating output on each pass.
1084 Calling output() is guaranteed not to change the state of the
1086 HTML::Template object, in case you were wondering. This property is
1087 mostly important for the internal implementation of loops.
1088 You may optionally supply a filehandle to print to automatically as the
1090 template is generated. This may improve performance and lower memory
1091 consumption. Example:
1092 $template->output(print_to => *STDOUT);
1094 The return value is undefined when using the "print_to" option.
1096 query
1098 This method allow you to get information about the template structure.
1099 It can be called in a number of ways. The simplest usage of query is
1100 simply to check whether a parameter name exists in the template, using
1101 the "name" option:
1102 if ($template->query(name => 'foo')) {
1104 # do something if a variable of any type named FOO is in the template
1105 }
1106 This same usage returns the type of the parameter. The type is the
1108 same as the tag minus the leading 'TMPL_'. So, for example, a
1109 "TMPL_VAR" parameter returns 'VAR' from query().
1110 if ($template->query(name => 'foo') eq 'VAR') {
1112 # do something if FOO exists and is a TMPL_VAR
1113 }
1114 Note that the variables associated with "TMPL_IF"s and "TMPL_UNLESS"s
1116 will be identified as 'VAR' unless they are also used in a "TMPL_LOOP",
1117 in which case they will return 'LOOP'.
1118 query() also allows you to get a list of parameters inside a loop (and
1120 inside loops inside loops). Example loop:
1121 <TMPL_LOOP NAME="EXAMPLE_LOOP">
1123 <TMPL_VAR NAME="BEE">
1124 <TMPL_VAR NAME="BOP">
1125 <TMPL_LOOP NAME="EXAMPLE_INNER_LOOP">
1126 <TMPL_VAR NAME="INNER_BEE">
1127 <TMPL_VAR NAME="INNER_BOP">
1128 </TMPL_LOOP>
1129 </TMPL_LOOP>
1130 And some query calls:
1132 # returns 'LOOP'
1134 $type = $template->query(name => 'EXAMPLE_LOOP');
1135 # returns ('bop', 'bee', 'example_inner_loop')
1137 @param_names = $template->query(loop => 'EXAMPLE_LOOP');
1138 # both return 'VAR'
1140 $type = $template->query(name => ['EXAMPLE_LOOP', 'BEE']);
1141 $type = $template->query(name => ['EXAMPLE_LOOP', 'BOP']);
1142 # and this one returns 'LOOP'
1144 $type = $template->query(name => ['EXAMPLE_LOOP', 'EXAMPLE_INNER_LOOP']);
1145 # and finally, this returns ('inner_bee', 'inner_bop')
1147 @inner_param_names = $template->query(loop => ['EXAMPLE_LOOP', 'EXAMPLE_INNER_LOOP']);
1148 # for non existent parameter names you get undef this returns undef.
1150 $type = $template->query(name => 'DWEAZLE_ZAPPA');
1151 # calling loop on a non-loop parameter name will cause an error. This dies:
1153 $type = $template->query(loop => 'DWEAZLE_ZAPPA');
1154 As you can see above the "loop" option returns a list of parameter
1156 names and both "name" and "loop" take array refs in order to refer to
1157 parameters inside loops. It is an error to use "loop" with a parameter
1158 that is not a loop.
1159 Note that all the names are returned in lowercase and the types are
1161 uppercase.
1162 Just like param(), query() with no arguments returns all the parameter
1164 names in the template at the top level.
1165
1167 As mentioned above, both "TMPL_VAR" and "TMPL_LOOP" values can be code
1168 references. These code references are only executed if the variable or
1169 loop is used in the template. This is extremely useful if you want to
1170 make a variable available to template designers but it can be expensive
1171 to calculate, so you only want to do so if you have to.
1172 Maybe an example will help to illustrate. Let's say you have a template
1174 like this:
1175 <tmpl_if we_care>
1177 <tmpl_if life_universe_and_everything>
1178 </tmpl_if>
1179 If "life_universe_and_everything" is expensive to calculate we can wrap
1181 it's calculation in a code reference and HTML::Template will only
1182 execute that code if "we_care" is also true.
1183 $tmpl->param(life_universe_and_everything => sub { calculate_42() });
1185 Your code reference will be given a single argument, the HTML::Template
1187 object in use. In the above example, if we wanted calculate_42() to
1188 have this object we'd do something like this:
1189 $tmpl->param(life_universe_and_everything => sub { calculate_42(shift) });
1191 This same approach can be used for "TMPL_LOOP"s too:
1193 <tmpl_if we_care>
1195 <tmpl_loop needles_in_haystack>
1196 Found <tmpl_var __counter>!
1197 </tmpl_loop>
1198 </tmpl_if>
1199 And in your Perl code:
1201 $tmpl->param(needles_in_haystack => sub { find_needles() });
1203 The only difference in the "TMPL_LOOP" case is that the subroutine
1205 needs to return a reference to an ARRAY, not just a scalar value.
1206 Multiple Calls
1208 It's important to recognize that while this feature is designed to save
1209 processing time when things aren't needed, if you're not careful it can
1210 actually increase the number of times you perform your calculation.
1211 HTML::Template calls your code reference each time it seems your loop
1212 in the template, this includes the times that you might use the loop in
1213 a conditional ("TMPL_IF" or "TMPL_UNLESS"). For instance:
1214 <tmpl_if we care>
1216 <tmpl_if needles_in_haystack>
1217 <tmpl_loop needles_in_haystack>
1218 Found <tmpl_var __counter>!
1219 </tmpl_loop>
1220 <tmpl_else>
1221 No needles found!
1222 </tmpl_if>
1223 </tmpl_if>
1224 This will actually call find_needles() twice which will be even worse
1226 than you had before. One way to work around this is to cache the
1227 return value yourself:
1228 my $needles;
1230 $tmpl->param(needles_in_haystack => sub { defined $needles ? $needles : $needles = find_needles() });
1231
1233 I am aware of no bugs - if you find one, join the mailing list and tell
1234 us about it. You can join the HTML::Template mailing-list by visiting:
1235 http://lists.sourceforge.net/lists/listinfo/html-template-users
1237 Of course, you can still email me directly ("sam@tregar.com") with
1239 bugs, but I reserve the right to forward bug reports to the mailing
1240 list.
1241 When submitting bug reports, be sure to include full details, including
1243 the VERSION of the module, a test script and a test template
1244 demonstrating the problem!
1245 If you're feeling really adventurous, HTML::Template has a publically
1247 available Git repository. See below for more information in the PUBLIC
1248 GIT REPOSITORY section.
1249
1251 This module was the brain child of my boss, Jesse Erlbaum
1252 ("jesse@vm.com") at Vanguard Media (http://vm.com) . The most original
1253 idea in this module - the "<TMPL_LOOP>" - was entirely his.
1254 Fixes, Bug Reports, Optimizations and Ideas have been generously
1256 provided by:
1257 • Richard Chen
1259 • Mike Blazer
1261 • Adriano Nagelschmidt Rodrigues
1263 • Andrej Mikus
1265 • Ilya Obshadko
1267 • Kevin Puetz
1269 • Steve Reppucci
1271 • Richard Dice
1273 • Tom Hukins
1275 • Eric Zylberstejn
1277 • David Glasser
1279 • Peter Marelas
1281 • James William Carlson
1283 • Frank D. Cringle
1285 • Winfried Koenig
1287 • Matthew Wickline
1289 • Doug Steinwand
1291 • Drew Taylor
1293 • Tobias Brox
1295 • Michael Lloyd
1297 • Simran Gambhir
1299 • Chris Houser <chouser@bluweb.com>
1301 • Larry Moore
1303 • Todd Larason
1305 • Jody Biggs
1307 • T.J. Mather
1309 • Martin Schroth
1311 • Dave Wolfe
1313 • uchum
1315 • Kawai Takanori
1317 • Peter Guelich
1319 • Chris Nokleberg
1321 • Ralph Corderoy
1323 • William Ward
1325 • Ade Olonoh
1327 • Mark Stosberg
1329 • Lance Thomas
1331 • Roland Giersig
1333 • Jere Julian
1335 • Peter Leonard
1337 • Kenny Smith
1339 • Sean P. Scanlon
1341 • Martin Pfeffer
1343 • David Ferrance
1345 • Gyepi Sam
1347 • Darren Chamberlain
1349 • Paul Baker
1351 • Gabor Szabo
1353 • Craig Manley
1355 • Richard Fein
1357 • The Phalanx Project
1359 • Sven Neuhaus
1361 • Michael Peters
1363 • Jan Dubois
1365 • Moritz Lenz
1367 Thanks!
1369
1371 You can find information about HTML::Template and other related modules
1372 at:
1373 http://html-template.sourceforge.net
1375
1377 HTML::Template now has a publicly accessible Git repository provided by
1378 GitHub (github.com). You can access it by going to
1379 https://github.com/mpeters/html-template. Give it a try!
1380
1382 Sam Tregar, "sam@tregar.com"
1383
1385 Michael Peters, "mpeters@plusthree.com"
1386
1388 HTML::Template : A module for using HTML Templates with Perl
1389 Copyright (C) 2000-2011 Sam Tregar (sam@tregar.com)
1390 This module is free software; you can redistribute it and/or modify it
1392 under the same terms as Perl itself, which means using either:
1393 a) the GNU General Public License as published by the Free Software
1395 Foundation; either version 1, or (at your option) any later version,
1396 or
1398 b) the "Artistic License" which comes with this module.
1400 This program is distributed in the hope that it will be useful,
1402 but WITHOUT ANY WARRANTY; without even the implied warranty of
1403 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
1404 the GNU General Public License or the Artistic License for more details.
1405 You should have received a copy of the Artistic License with this
1407 module. If not, I'll be glad to provide one.
1408 You should have received a copy of the GNU General Public License
1410 along with this program. If not, write to the Free Software
1411 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
1412 USA
1413perl v5.36.0 2023-01-20 HTML::Template(3)