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)
175 for this loop. The loop iterates over the list and produces output
176 from the text block for each pass. Unset parameters are skipped.
177 Here's an 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
248 an 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
468 information.
469 You can modify the Template object's behavior with "new()". The options
471 are available:
472 Error Detection Options
474 • die_on_bad_params
476 If set to 0 the module will let you call:
478 $template->param(param_name => 'value')
480 even if 'param_name' doesn't exist in the template body. Defaults
482 to 1.
483 • force_untaint
485 If set to 1 the module will not allow you to set unescaped
487 parameters with tainted values. If set to 2 you will have to
488 untaint all parameters, including ones with the escape attribute.
489 This option makes sure you untaint everything so you don't
490 accidentally introduce e.g. cross-site-scripting (XSS)
491 vulnerabilities. Requires taint mode. Defaults to 0.
492 • strict - if set to 0 the module will allow things that look like
494 they might be TMPL_* tags to get by without dieing. Example:
495 <TMPL_HUH NAME=ZUH>
497 Would normally cause an error, but if you call new with "strict =>
499 0" HTML::Template will ignore it. Defaults to 1.
500 • vanguard_compatibility_mode
502 If set to 1 the module will expect to see "<TMPL_VAR>"s that look
504 like "%NAME%" in addition to the standard syntax. Also sets
505 "die_on_bad_params =" 0>. If you're not at Vanguard Media trying
506 to use an old format template don't worry about this one. Defaults
507 to 0.
508 Caching Options
510 • cache
512 If set to 1 the module will cache in memory the parsed templates
514 based on the filename parameter, the modification date of the file
515 and the options passed to "new()". This only applies to templates
516 opened with the filename parameter specified, not scalarref or
517 arrayref templates. Caching also looks at the modification times
518 of any files included using "<TMPL_INCLUDE>" tags, but again, only
519 if the template is opened with filename parameter.
520 This is mainly of use in a persistent environment like
522 Apache/mod_perl. It has absolutely no benefit in a normal CGI
523 environment since the script is unloaded from memory after every
524 request. For a cache that does work for a non-persistent
525 environment see the "shared_cache" option below.
526 My simplistic testing shows that using cache yields a 90%
528 performance increase under mod_perl. Cache defaults to 0.
529 • shared_cache
531 If set to 1 the module will store its cache in shared memory using
533 the IPC::SharedCache module (available from CPAN). The effect of
534 this will be to maintain a single shared copy of each parsed
535 template for all instances of HTML::Template on the same machine to
536 use. This can be a significant reduction in memory usage in an
537 environment with a single machine but multiple servers. As an
538 example, on one of our systems we use 4MB of template cache and
539 maintain 25 httpd processes - shared_cache results in saving almost
540 100MB! Of course, some reduction in speed versus normal caching is
541 to be expected. Another difference between normal caching and
542 shared_cache is that shared_cache will work in a non-persistent
543 environment (like normal CGI) - normal caching is only useful in a
544 persistent environment like Apache/mod_perl.
545 By default HTML::Template uses the IPC key 'TMPL' as a shared root
547 segment (0x4c504d54 in hex), but this can be changed by setting the
548 "ipc_key" "new()" parameter to another 4-character or integer key.
549 Other options can be used to affect the shared memory cache
550 correspond to IPC::SharedCache options - "ipc_mode",
551 "ipc_segment_size" and "ipc_max_size". See IPC::SharedCache for a
552 description of how these work - in most cases you shouldn't need to
553 change them from the defaults.
554 For more information about the shared memory cache system used by
556 HTML::Template see IPC::SharedCache.
557 • double_cache
559 If set to 1 the module will use a combination of "shared_cache" and
561 normal cache mode for the best possible caching. Of course, it
562 also uses the most memory of all the cache modes. All the same
563 ipc_* options that work with "shared_cache" apply to "double_cache"
564 as well. Defaults to 0.
565 • blind_cache
567 If set to 1 the module behaves exactly as with normal caching but
569 does not check to see if the file has changed on each request.
570 This option should be used with caution, but could be of use on
571 high-load servers. My tests show "blind_cache" performing only 1
572 to 2 percent faster than cache under mod_perl.
573 NOTE: Combining this option with shared_cache can result in stale
575 templates stuck permanently in shared memory!
576 • file_cache
578 If set to 1 the module will store its cache in a file using the
580 Storable module. It uses no additional memory, and my simplistic
581 testing shows that it yields a 50% performance advantage. Like
582 "shared_cache", it will work in a non-persistent environments (like
583 CGI). Default is 0.
584 If you set this option you must set the "file_cache_dir" option.
586 See below for details.
587 NOTE: Storable uses "flock()" to ensure safe access to cache files.
589 Using "file_cache" on a system or filesystem (like NFS) without
590 "flock()" support is dangerous.
591 • file_cache_dir
593 Sets the directory where the module will store the cache files if
595 "file_cache" is enabled. Your script will need write permissions
596 to this directory. You'll also need to make sure the sufficient
597 space is available to store the cache files.
598 • file_cache_dir_mode
600 Sets the file mode for newly created "file_cache" directories and
602 subdirectories. Defaults to "0700" for security but this may be
603 inconvenient if you do not have access to the account running the
604 webserver.
605 • double_file_cache
607 If set to 1 the module will use a combination of "file_cache" and
609 normal "cache" mode for the best possible caching. The
610 file_cache_* options that work with file_cache apply to
611 "double_file_cache" as well. Defaults to 0.
612 • cache_lazy_vars
614 The option tells HTML::Template to cache the values returned from
616 code references used for "TMPL_VAR"s. See "LAZY VALUES" for
617 details.
618 • cache_lazy_loops
620 The option tells HTML::Template to cache the values returned from
622 code references used for "TMPL_LOOP"s. See "LAZY VALUES" for
623 details.
624 Filesystem Options
626 • path
628 You can set this variable with a list of paths to search for files
630 specified with the "filename" option to "new()" and for files
631 included with the "<TMPL_INCLUDE>" tag. This list is only
632 consulted when the filename is relative. The "HTML_TEMPLATE_ROOT"
633 environment variable is always tried first if it exists. Also, if
634 "HTML_TEMPLATE_ROOT" is set then an attempt will be made to prepend
635 "HTML_TEMPLATE_ROOT" onto paths in the path array. In the case of
636 a "<TMPL_INCLUDE>" file, the path to the including file is also
637 tried before path is consulted.
638 Example:
640 my $template = HTML::Template->new(
642 filename => 'file.tmpl',
643 path => ['/path/to/templates', '/alternate/path'],
644 );
645 NOTE: the paths in the path list must be expressed as UNIX paths,
647 separated by the forward-slash character ('/').
648 • search_path_on_include
650 If set to a true value the module will search from the top of the
652 array of paths specified by the path option on every
653 "<TMPL_INCLUDE>" and use the first matching template found. The
654 normal behavior is to look only in the current directory for a
655 template to include. Defaults to 0.
656 • utf8
658 Setting this to true tells HTML::Template to treat your template
660 files as UTF-8 encoded. This will apply to any file's passed to
661 "new()" or any included files. It won't do anything special to
662 scalars templates passed to "new()" since you should be doing the
663 encoding on those yourself.
664 my $template = HTML::Template->new(
666 filename => 'umlauts_are_awesome.tmpl',
667 utf8 => 1,
668 );
669 Most templates are either ASCII (the default) or UTF-8 encoded
671 Unicode. But if you need some other encoding other than these 2,
672 look at the "open_mode" option.
673 NOTE: The "utf8" and "open_mode" options cannot be used at the same
675 time.
676 • open_mode
678 You can set this option to an opening mode with which all template
680 files will be opened.
681 For example, if you want to use a template that is UTF-16 encoded
683 unicode:
684 my $template = HTML::Template->new(
686 filename => 'file.tmpl',
687 open_mode => '<:encoding(UTF-16)',
688 );
689 That way you can force a different encoding (than the default ASCII
691 or UTF-8), CR/LF properties etc. on the template files. See PerlIO
692 for details.
693 NOTE: this only works in perl 5.7.1 and above.
695 NOTE: you have to supply an opening mode that actually permits
697 reading from the file handle.
698 NOTE: The "utf8" and "open_mode" options cannot be used at the same
700 time.
701 Debugging Options
703 • debug
705 If set to 1 the module will write random debugging information to
707 STDERR. Defaults to 0.
708 • stack_debug
710 If set to 1 the module will use Data::Dumper to print out the
712 contents of the parse_stack to STDERR. Defaults to 0.
713 • cache_debug
715 If set to 1 the module will send information on cache loads, hits
717 and misses to STDERR. Defaults to 0.
718 • shared_cache_debug
720 If set to 1 the module will turn on the debug option in
722 IPC::SharedCache. Defaults to 0.
723 • memory_debug
725 If set to 1 the module will send information on cache memory usage
727 to STDERR. Requires the GTop module. Defaults to 0.
728 Miscellaneous Options
730 • associate
732 This option allows you to inherit the parameter values from other
734 objects. The only requirement for the other object is that it have
735 a "param()" method that works like HTML::Template's "param()". A
736 good candidate would be a CGI query object. Example:
737 my $query = CGI->new;
739 my $template = HTML::Template->new(
740 filename => 'template.tmpl',
741 associate => $query,
742 );
743 Now, "$template->output()" will act as though
745 $template->param(form_field => $cgi->param('form_field'));
747 had been specified for each key/value pair that would be provided
749 by the "$cgi->param()" method. Parameters you set directly take
750 precedence over associated parameters.
751 You can specify multiple objects to associate by passing an
753 anonymous array to the associate option. They are searched for
754 parameters in the order they appear:
755 my $template = HTML::Template->new(
757 filename => 'template.tmpl',
758 associate => [$query, $other_obj],
759 );
760 NOTE: The parameter names are matched in a case-insensitive manner.
762 If you have two parameters in a CGI object like 'NAME' and 'Name'
763 one will be chosen randomly by associate. This behavior can be
764 changed by the "case_sensitive" option.
765 • case_sensitive
767 Setting this option to true causes HTML::Template to treat template
769 variable names case-sensitively. The following example would only
770 set one parameter without the "case_sensitive" option:
771 my $template = HTML::Template->new(
773 filename => 'template.tmpl',
774 case_sensitive => 1
775 );
776 $template->param(
777 FieldA => 'foo',
778 fIELDa => 'bar',
779 );
780 This option defaults to off.
782 NOTE: with "case_sensitive" and "loop_context_vars" the special
784 loop variables are available in lower-case only.
785 • loop_context_vars
787 When this parameter is set to true (it is false by default) extra
789 variables that depend on the loop's context are made available
790 inside a loop. These are:
791 • __first__
793 Value that is true for the first iteration of the loop and
795 false every other time.
796 • __last__
798 Value that is true for the last iteration of the loop and false
800 every other time.
801 • __inner__
803 Value that is true for the every iteration of the loop except
805 for the first and last.
806 • __outer__
808 Value that is true for the first and last iterations of the
810 loop.
811 • __odd__
813 Value that is true for the every odd iteration of the loop.
815 • __even__
817 Value that is true for the every even iteration of the loop.
819 • __counter__
821 An integer (starting from 1) whose value increments for each
823 iteration of the loop.
824 • __index__
826 An integer (starting from 0) whose value increments for each
828 iteration of the loop.
829 Just like any other "TMPL_VAR"s these variables can be used in
831 "<TMPL_IF>", "<TMPL_UNLESS>" and "<TMPL_ELSE>" to control how a
832 loop is output.
833 Example:
835 <TMPL_LOOP NAME="FOO">
837 <TMPL_IF NAME="__first__">
838 This only outputs on the first pass.
839 </TMPL_IF>
840 <TMPL_IF NAME="__odd__">
842 This outputs every other pass, on the odd passes.
843 </TMPL_IF>
844 <TMPL_UNLESS NAME="__odd__">
846 This outputs every other pass, on the even passes.
847 </TMPL_UNLESS>
848 <TMPL_IF NAME="__inner__">
850 This outputs on passes that are neither first nor last.
851 </TMPL_IF>
852 This is pass number <TMPL_VAR NAME="__counter__">.
854 <TMPL_IF NAME="__last__">
856 This only outputs on the last pass.
857 </TMPL_IF>
858 </TMPL_LOOP>
859 One use of this feature is to provide a "separator" similar in
861 effect to the perl function "join()". Example:
862 <TMPL_LOOP FRUIT>
864 <TMPL_IF __last__> and </TMPL_IF>
865 <TMPL_VAR KIND><TMPL_UNLESS __last__>, <TMPL_ELSE>.</TMPL_UNLESS>
866 </TMPL_LOOP>
867 Would output something like:
869 Apples, Oranges, Brains, Toes, and Kiwi.
871 Given an appropriate "param()" call, of course. NOTE: A loop with
873 only a single pass will get both "__first__" and "__last__" set to
874 true, but not "__inner__".
875 • no_includes
877 Set this option to 1 to disallow the "<TMPL_INCLUDE>" tag in the
879 template file. This can be used to make opening untrusted
880 templates slightly less dangerous. Defaults to 0.
881 • max_includes
883 Set this variable to determine the maximum depth that includes can
885 reach. Set to 10 by default. Including files to a depth greater
886 than this value causes an error message to be displayed. Set to 0
887 to disable this protection.
888 • die_on_missing_include
890 If true, then HTML::Template will die if it can't find a file for a
892 "<TMPL_INCLUDE>". This defaults to true.
893 • global_vars
895 Normally variables declared outside a loop are not available inside
897 a loop. This option makes "<TMPL_VAR>"s like global variables in
898 Perl - they have unlimited scope. This option also affects
899 "<TMPL_IF>" and "<TMPL_UNLESS>".
900 Example:
902 This is a normal variable: <TMPL_VAR NORMAL>.<P>
904 <TMPL_LOOP NAME=FROOT_LOOP>
906 Here it is inside the loop: <TMPL_VAR NORMAL><P>
907 </TMPL_LOOP>
908 Normally this wouldn't work as expected, since "<TMPL_VAR
910 NORMAL>"'s value outside the loop is not available inside the loop.
911 The global_vars option also allows you to access the values of an
913 enclosing loop within an inner loop. For example, in this loop the
914 inner loop will have access to the value of "OUTER_VAR" in the
915 correct iteration:
916 <TMPL_LOOP OUTER_LOOP>
918 OUTER: <TMPL_VAR OUTER_VAR>
919 <TMPL_LOOP INNER_LOOP>
920 INNER: <TMPL_VAR INNER_VAR>
921 INSIDE OUT: <TMPL_VAR OUTER_VAR>
922 </TMPL_LOOP>
923 </TMPL_LOOP>
924 One side-effect of "global_vars" is that variables you set with
926 "param()" that might otherwise be ignored when "die_on_bad_params"
927 is off will stick around. This is necessary to allow inner loops
928 to access values set for outer loops that don't directly use the
929 value.
930 NOTE: "global_vars" is not "global_loops" (which does not exist).
932 That means that loops you declare at one scope are not available
933 inside other loops even when "global_vars" is on.
934 • filter
936 This option allows you to specify a filter for your template files.
938 A filter is a subroutine that will be called after HTML::Template
939 reads your template file but before it starts parsing template
940 tags.
941 In the most simple usage, you simply assign a code reference to the
943 filter parameter. This subroutine will receive a single argument -
944 a reference to a string containing the template file text. Here is
945 an example that accepts templates with tags that look like
946 "!!!ZAP_VAR FOO!!!" and transforms them into HTML::Template tags:
947 my $filter = sub {
949 my $text_ref = shift;
950 $$text_ref =~ s/!!!ZAP_(.*?)!!!/<TMPL_$1>/g;
951 };
952 # open zap.tmpl using the above filter
954 my $template = HTML::Template->new(
955 filename => 'zap.tmpl',
956 filter => $filter,
957 );
958 More complicated usages are possible. You can request that your
960 filter receives the template text as an array of lines rather than
961 as a single scalar. To do that you need to specify your filter
962 using a hash-ref. In this form you specify the filter using the
963 "sub" key and the desired argument format using the "format" key.
964 The available formats are "scalar" and "array". Using the "array"
965 format will incur a performance penalty but may be more convenient
966 in some situations.
967 my $template = HTML::Template->new(
969 filename => 'zap.tmpl',
970 filter => {
971 sub => $filter,
972 format => 'array',
973 }
974 );
975 You may also have multiple filters. This allows simple filters to
977 be combined for more elaborate functionality. To do this you
978 specify an array of filters. The filters are applied in the order
979 they are specified.
980 my $template = HTML::Template->new(
982 filename => 'zap.tmpl',
983 filter => [
984 {
985 sub => \&decompress,
986 format => 'scalar',
987 },
988 {
989 sub => \&remove_spaces,
990 format => 'array',
991 },
992 ]
993 );
994 The specified filters will be called for any "TMPL_INCLUDE"ed files
996 just as they are for the main template file.
997 • default_escape
999 Set this parameter to a valid escape type (see the "escape" option)
1001 and HTML::Template will apply the specified escaping to all
1002 variables unless they declare a different escape in the template.
1003 config
1005 A package method that is used to set/get the global default
1006 configuration options. For instance, if you want to set the "utf8"
1007 flag to always be on for every template loaded by this process you
1008 would do:
1009 HTML::Template->config(utf8 => 1);
1011 Or if you wanted to check if the "utf8" flag was on or not, you could
1013 do:
1014 my %config = HTML::Template->config;
1016 if( $config{utf8} ) {
1017 ...
1018 }
1019 Any configuration options that are valid for "new()" are acceptable to
1021 be passed to this method.
1022 param
1024 "param()" can be called in a number of ways
1025 1 - To return a list of parameters in the template :
1027 my @parameter_names = $self->param();
1028 2 - To return the value set to a param :
1030 my $value = $self->param('PARAM');
1031 3 - To set the value of a parameter :
1033 # For simple TMPL_VARs:
1034 $self->param(PARAM => 'value');
1035 # with a subroutine reference that gets called to get the value
1037 # of the scalar. The sub will receive the template object as a
1038 # parameter.
1039 $self->param(PARAM => sub { return 'value' });
1040 # And TMPL_LOOPs:
1042 $self->param(LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}]);
1043 4 - To set the value of a number of parameters :
1045 # For simple TMPL_VARs:
1046 $self->param(
1047 PARAM => 'value',
1048 PARAM2 => 'value'
1049 );
1050 # And with some TMPL_LOOPs:
1052 $self->param(
1053 PARAM => 'value',
1054 PARAM2 => 'value',
1055 LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}],
1056 ANOTHER_LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}],
1057 );
1058 5 - To set the value of a number of parameters using a hash-ref :
1060 $self->param(
1061 {
1062 PARAM => 'value',
1063 PARAM2 => 'value',
1064 LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}],
1065 ANOTHER_LOOP_PARAM => [{PARAM => VALUE_FOR_FIRST_PASS}, {PARAM => VALUE_FOR_SECOND_PASS}],
1066 }
1067 );
1068 An error occurs if you try to set a value that is tainted if the
1070 "force_untaint" option is set.
1071 clear_params
1073 Sets all the parameters to undef. Useful internally, if nowhere else!
1074 output
1076 "output()" returns the final result of the template. In most
1077 situations you'll want to print this, like:
1078 print $template->output();
1080 When output is called each occurrence of "<TMPL_VAR NAME=name>" is
1082 replaced with the value assigned to "name" via "param()". If a named
1083 parameter is unset it is simply replaced with ''. "<TMPL_LOOP>"s are
1084 evaluated once per parameter set, accumulating output on each pass.
1085 Calling "output()" is guaranteed not to change the state of the
1087 HTML::Template object, in case you were wondering. This property is
1088 mostly important for the internal implementation of loops.
1089 You may optionally supply a filehandle to print to automatically as the
1091 template is generated. This may improve performance and lower memory
1092 consumption. Example:
1093 $template->output(print_to => *STDOUT);
1095 The return value is undefined when using the "print_to" option.
1097 query
1099 This method allow you to get information about the template structure.
1100 It can be called in a number of ways. The simplest usage of query is
1101 simply to check whether a parameter name exists in the template, using
1102 the "name" option:
1103 if ($template->query(name => 'foo')) {
1105 # do something if a variable of any type named FOO is in the template
1106 }
1107 This same usage returns the type of the parameter. The type is the
1109 same as the tag minus the leading 'TMPL_'. So, for example, a
1110 "TMPL_VAR" parameter returns 'VAR' from "query()".
1111 if ($template->query(name => 'foo') eq 'VAR') {
1113 # do something if FOO exists and is a TMPL_VAR
1114 }
1115 Note that the variables associated with "TMPL_IF"s and "TMPL_UNLESS"s
1117 will be identified as 'VAR' unless they are also used in a "TMPL_LOOP",
1118 in which case they will return 'LOOP'.
1119 "query()" also allows you to get a list of parameters inside a loop
1121 (and inside loops inside loops). Example loop:
1122 <TMPL_LOOP NAME="EXAMPLE_LOOP">
1124 <TMPL_VAR NAME="BEE">
1125 <TMPL_VAR NAME="BOP">
1126 <TMPL_LOOP NAME="EXAMPLE_INNER_LOOP">
1127 <TMPL_VAR NAME="INNER_BEE">
1128 <TMPL_VAR NAME="INNER_BOP">
1129 </TMPL_LOOP>
1130 </TMPL_LOOP>
1131 And some query calls:
1133 # returns 'LOOP'
1135 $type = $template->query(name => 'EXAMPLE_LOOP');
1136 # returns ('bop', 'bee', 'example_inner_loop')
1138 @param_names = $template->query(loop => 'EXAMPLE_LOOP');
1139 # both return 'VAR'
1141 $type = $template->query(name => ['EXAMPLE_LOOP', 'BEE']);
1142 $type = $template->query(name => ['EXAMPLE_LOOP', 'BOP']);
1143 # and this one returns 'LOOP'
1145 $type = $template->query(name => ['EXAMPLE_LOOP', 'EXAMPLE_INNER_LOOP']);
1146 # and finally, this returns ('inner_bee', 'inner_bop')
1148 @inner_param_names = $template->query(loop => ['EXAMPLE_LOOP', 'EXAMPLE_INNER_LOOP']);
1149 # for non existent parameter names you get undef this returns undef.
1151 $type = $template->query(name => 'DWEAZLE_ZAPPA');
1152 # calling loop on a non-loop parameter name will cause an error. This dies:
1154 $type = $template->query(loop => 'DWEAZLE_ZAPPA');
1155 As you can see above the "loop" option returns a list of parameter
1157 names and both "name" and "loop" take array refs in order to refer to
1158 parameters inside loops. It is an error to use "loop" with a parameter
1159 that is not a loop.
1160 Note that all the names are returned in lowercase and the types are
1162 uppercase.
1163 Just like "param()", "query()" with no arguments returns all the
1165 parameter names in the template at the top level.
1166
1168 As mentioned above, both "TMPL_VAR" and "TMPL_LOOP" values can be code
1169 references. These code references are only executed if the variable or
1170 loop is used in the template. This is extremely useful if you want to
1171 make a variable available to template designers but it can be expensive
1172 to calculate, so you only want to do so if you have to.
1173 Maybe an example will help to illustrate. Let's say you have a template
1175 like this:
1176 <tmpl_if we_care>
1178 <tmpl_if life_universe_and_everything>
1179 </tmpl_if>
1180 If "life_universe_and_everything" is expensive to calculate we can wrap
1182 it's calculation in a code reference and HTML::Template will only
1183 execute that code if "we_care" is also true.
1184 $tmpl->param(life_universe_and_everything => sub { calculate_42() });
1186 Your code reference will be given a single argument, the HTML::Template
1188 object in use. In the above example, if we wanted "calculate_42()" to
1189 have this object we'd do something like this:
1190 $tmpl->param(life_universe_and_everything => sub { calculate_42(shift) });
1192 This same approach can be used for "TMPL_LOOP"s too:
1194 <tmpl_if we_care>
1196 <tmpl_loop needles_in_haystack>
1197 Found <tmpl_var __counter>!
1198 </tmpl_loop>
1199 </tmpl_if>
1200 And in your Perl code:
1202 $tmpl->param(needles_in_haystack => sub { find_needles() });
1204 The only difference in the "TMPL_LOOP" case is that the subroutine
1206 needs to return a reference to an ARRAY, not just a scalar value.
1207 Multiple Calls
1209 It's important to recognize that while this feature is designed to save
1210 processing time when things aren't needed, if you're not careful it can
1211 actually increase the number of times you perform your calculation.
1212 HTML::Template calls your code reference each time it seems your loop
1213 in the template, this includes the times that you might use the loop in
1214 a conditional ("TMPL_IF" or "TMPL_UNLESS"). For instance:
1215 <tmpl_if we care>
1217 <tmpl_if needles_in_haystack>
1218 <tmpl_loop needles_in_haystack>
1219 Found <tmpl_var __counter>!
1220 </tmpl_loop>
1221 <tmpl_else>
1222 No needles found!
1223 </tmpl_if>
1224 </tmpl_if>
1225 This will actually call "find_needles()" twice which will be even worse
1227 than you had before. One way to work around this is to cache the
1228 return value yourself:
1229 my $needles;
1231 $tmpl->param(needles_in_haystack => sub { defined $needles ? $needles : $needles = find_needles() });
1232
1234 I am aware of no bugs - if you find one, join the mailing list and tell
1235 us about it. You can join the HTML::Template mailing-list by visiting:
1236 http://lists.sourceforge.net/lists/listinfo/html-template-users
1238 Of course, you can still email me directly ("sam@tregar.com") with
1240 bugs, but I reserve the right to forward bug reports to the mailing
1241 list.
1242 When submitting bug reports, be sure to include full details, including
1244 the VERSION of the module, a test script and a test template
1245 demonstrating the problem!
1246 If you're feeling really adventurous, HTML::Template has a publically
1248 available Git repository. See below for more information in the PUBLIC
1249 GIT REPOSITORY section.
1250
1252 This module was the brain child of my boss, Jesse Erlbaum
1253 ("jesse@vm.com") at Vanguard Media (http://vm.com) . The most original
1254 idea in this module - the "<TMPL_LOOP>" - was entirely his.
1255 Fixes, Bug Reports, Optimizations and Ideas have been generously
1257 provided by:
1258 • Richard Chen
1260 • Mike Blazer
1262 • Adriano Nagelschmidt Rodrigues
1264 • Andrej Mikus
1266 • Ilya Obshadko
1268 • Kevin Puetz
1270 • Steve Reppucci
1272 • Richard Dice
1274 • Tom Hukins
1276 • Eric Zylberstejn
1278 • David Glasser
1280 • Peter Marelas
1282 • James William Carlson
1284 • Frank D. Cringle
1286 • Winfried Koenig
1288 • Matthew Wickline
1290 • Doug Steinwand
1292 • Drew Taylor
1294 • Tobias Brox
1296 • Michael Lloyd
1298 • Simran Gambhir
1300 • Chris Houser <chouser@bluweb.com>
1302 • Larry Moore
1304 • Todd Larason
1306 • Jody Biggs
1308 • T.J. Mather
1310 • Martin Schroth
1312 • Dave Wolfe
1314 • uchum
1316 • Kawai Takanori
1318 • Peter Guelich
1320 • Chris Nokleberg
1322 • Ralph Corderoy
1324 • William Ward
1326 • Ade Olonoh
1328 • Mark Stosberg
1330 • Lance Thomas
1332 • Roland Giersig
1334 • Jere Julian
1336 • Peter Leonard
1338 • Kenny Smith
1340 • Sean P. Scanlon
1342 • Martin Pfeffer
1344 • David Ferrance
1346 • Gyepi Sam
1348 • Darren Chamberlain
1350 • Paul Baker
1352 • Gabor Szabo
1354 • Craig Manley
1356 • Richard Fein
1358 • The Phalanx Project
1360 • Sven Neuhaus
1362 • Michael Peters
1364 • Jan Dubois
1366 • Moritz Lenz
1368 Thanks!
1370
1372 You can find information about HTML::Template and other related modules
1373 at:
1374 http://html-template.sourceforge.net
1376
1378 HTML::Template now has a publicly accessible Git repository provided by
1379 GitHub (github.com). You can access it by going to
1380 https://github.com/mpeters/html-template. Give it a try!
1381
1383 Sam Tregar, "sam@tregar.com"
1384
1386 Michael Peters, "mpeters@plusthree.com"
1387
1389 HTML::Template : A module for using HTML Templates with Perl
1390 Copyright (C) 2000-2011 Sam Tregar (sam@tregar.com)
1391 This module is free software; you can redistribute it and/or modify it
1393 under the same terms as Perl itself, which means using either:
1394 a) the GNU General Public License as published by the Free Software
1396 Foundation; either version 1, or (at your option) any later version,
1397 or
1399 b) the "Artistic License" which comes with this module.
1401 This program is distributed in the hope that it will be useful,
1403 but WITHOUT ANY WARRANTY; without even the implied warranty of
1404 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
1405 the GNU General Public License or the Artistic License for more details.
1406 You should have received a copy of the Artistic License with this
1408 module. If not, I'll be glad to provide one.
1409 You should have received a copy of the GNU General Public License
1411 along with this program. If not, write to the Free Software
1412 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
1413 USA
1414perl v5.34.0 2022-01-21 HTML::Template(3)