1HTML::Template::SYNTAX(U3s)er Contributed Perl DocumentatHiToMnL::Template::SYNTAX(3)
2
6 HTML::Template::SYNTAX - syntax of html template language for
7 HTML::Template
8
10 This help is only on syntax of html template files. For perl interface
11 of HTML::Template::Pro you should see "SYNOPSIS" in
12 HTML::Template::PerlInterface.
13 First you make a template - this is just a normal HTML file with a few
15 extra tags, the simplest being <TMPL_VAR>
16 For example, test.tmpl:
18 <html>
20 <head><title>Test Template</title>
21 <body>
22 My Home Directory is <TMPL_VAR NAME=HOME>
23 <p>
24 My Path is set to <TMPL_VAR NAME=PATH>
25 </body>
26 </html>
27 Now define the value for HOME and PATH, for example, in perl it will
29 look like
30 $template->param(HOME => $ENV{HOME});
32 $template->param(PATH => $ENV{PATH});
33 and process the template. If all is well in the universe this should
35 show something like this in your browser:
36 My Home Directory is /home/some/directory
38 My Path is set to /bin;/usr/bin
39
41 This module attempts to make using HTML templates simple and natural.
42 It extends standard HTML with a few new HTML-esque tags - <TMPL_VAR>,
43 <TMPL_LOOP>, <TMPL_INCLUDE>, <TMPL_IF>, <TMPL_ELSE> and <TMPL_UNLESS>.
44 (HTML::Template::Pro also supports <TMPL_ELSIF> tag.) The file written
45 with HTML and these new tags is called a template. It is usually saved
46 separate from your script - possibly even created by someone else!
47 Using this module you fill in the values for the variables, loops and
48 branches declared in the template. This allows you to separate design
49 - the HTML - from the data, which you generate in the Perl script.
50 This module is licensed under the (L)GPL or perl license. See the
52 LICENSE section below for more details.
53
55 If you're new to HTML::Template, I suggest you start with the
56 introductory article available on the HTML::Template website:
57 http://html-template.sourceforge.net
59
61 It is true that there are a number of packages out there to do HTML
62 templates. On the one hand you have things like HTML::Embperl which
63 allows you freely mix Perl with HTML. On the other hand lie home-grown
64 variable substitution solutions. Hopefully the module can find a place
65 between the two.
66 One advantage of this module over a full HTML::Embperl-esque solution
68 is that it enforces an important divide - design and programming. By
69 limiting the programmer to just using simple variables and loops in the
70 HTML, the template remains accessible to designers and other non-perl
71 people. The use of HTML-esque syntax goes further to make the format
72 understandable to others. In the future this similarity could be used
73 to extend existing HTML editors/analyzers to support HTML::Template.
74 An advantage of this module over home-grown tag-replacement schemes is
76 the support for loops. In my work I am often called on to produce
77 tables of data in html. Producing them using simplistic HTML templates
78 results in CGIs containing lots of HTML since the HTML itself cannot
79 represent loops. The introduction of loop statements in the HTML
80 simplifies this situation considerably. The designer can layout a
81 single row and the programmer can fill it in as many times as necessary
82 - all they must agree on is the parameter names.
83 For all that, I think the best thing about this module is that it does
85 just one thing and it does it quickly and carefully. It doesn't try to
86 replace Perl and HTML, it just augments them to interact a little
87 better. And it's pretty fast.
88
90 GENERAL TAG SYNTAX
91 A generic HTML::Template tag that is supported by HTML::Template::Pro
92 looks like <TMPL_SOMETHING A="B" [C="D" ...]>. Tags are case-
93 insensitve: <tmpl_something a="B" [c="D" ...]> is acceptable. Single
94 quotes can be used, <TMPL_SOMETHING A='B' [C='D' ...]> quotes can be
95 omitted, <TMPL_SOMETHING A=B ... > and option name could be often
96 guessed as in <TMPL_SOMETHING B>.
97 template tags could be decorated as html comments <!-- TMPL_SOMETHING
99 A="B" -->
100 Also, as HTML::Template::Pro extension (starting from version 0.90),
102 template tags could also be decorated as xml <TMPL_SOMETHING A="B" />
103 See NOTES.
105 TMPL_VAR
107 <TMPL_VAR NAME="PARAMETER_NAME">
108 The <TMPL_VAR> tag is very simple. For each <TMPL_VAR> tag in the
110 template you call $template->param(PARAMETER_NAME => "VALUE"). When
111 the template is output the <TMPL_VAR> is replaced with the VALUE text
112 you specified. If you don't set a parameter it just gets skipped in
113 the output.
114 Optionally you can use the "ESCAPE=HTML" option in the tag to indicate
116 that you want the value to be HTML-escaped before being returned from
117 output (the old ESCAPE=1 syntax is still supported). This means that
118 the ", <, >, and & characters get translated into ", <, >
119 and & respectively. This is useful when you want to use a TMPL_VAR
120 in a context where those characters would cause trouble. Example:
121 <input name=param type=text value="<TMPL_VAR NAME="PARAM">">
123 If you called param() with a value like sam"my you'll get in trouble
125 with HTML's idea of a double-quote. On the other hand, if you use
126 ESCAPE=HTML, like this:
127 <input name=param type=text value="<TMPL_VAR ESCAPE=HTML NAME="PARAM">">
129 You'll get what you wanted no matter what value happens to be passed in
131 for param. You can also write ESCAPE="HTML", ESCAPE='HTML' and
132 ESCAPE='1'.
133 "ESCAPE=0" and "ESCAPE=NONE" turn off escaping, which is the default
135 behavior.
136 There is also the "ESCAPE=URL" option which may be used for VARs that
138 populate a URL. It will do URL escaping, like replacing ' ' with '+'
139 and '/' with '%2F'.
140 There is also the "ESCAPE=JS" option which may be used for VARs that
142 need to be placed within a Javascript string. All \n, \r, ' and "
143 characters are escaped.
144 You can assign a default value to a variable with the DEFAULT
146 attribute. For example, this will output "the devil gave me a taco" if
147 the "who" variable is not set.
148 The <TMPL_VAR NAME=WHO DEFAULT=devil> gave me a taco.
150 TMPL_LOOP
152 <TMPL_LOOP NAME="LOOP_NAME"> ... </TMPL_LOOP>
153 The <TMPL_LOOP> tag is a bit more complicated than <TMPL_VAR>. The
155 <TMPL_LOOP> tag allows you to delimit a section of text and give it a
156 name. Inside this named loop you place <TMPL_VAR>s. Now you pass to
157 param() a list (an array ref) of parameter assignments (hash refs) for
158 this loop. The loop iterates over the list and produces output from
159 the text block for each pass. Unset parameters are skipped. Here's an
160 example:
161 In the template:
163 <TMPL_LOOP NAME=EMPLOYEE_INFO>
165 Name: <TMPL_VAR NAME=NAME> <br>
166 Job: <TMPL_VAR NAME=JOB> <p>
167 </TMPL_LOOP>
168 In the script:
171 $template->param(EMPLOYEE_INFO => [
173 { name => 'Sam', job => 'programmer' },
174 { name => 'Steve', job => 'soda jerk' },
175 ]
176 );
177 print $template->output();
178 The output in a browser:
181 Name: Sam
183 Job: programmer
184 Name: Steve
186 Job: soda jerk
187 As you can see above the <TMPL_LOOP> takes a list of variable
189 assignments and then iterates over the loop body producing output.
190 Often you'll want to generate a <TMPL_LOOP>'s contents
192 programmatically. Here's an example of how this can be done (many
193 other ways are possible!):
194 # a couple of arrays of data to put in a loop:
196 my @words = qw(I Am Cool);
197 my @numbers = qw(1 2 3);
198 my @loop_data = (); # initialize an array to hold your loop
200 while (@words and @numbers) {
202 my %row_data; # get a fresh hash for the row data
203 # fill in this row
205 $row_data{WORD} = shift @words;
206 $row_data{NUMBER} = shift @numbers;
207 # the crucial step - push a reference to this row into the loop!
209 push(@loop_data, \%row_data);
210 }
211 # finally, assign the loop data to the loop param, again with a
213 # reference:
214 $template->param(THIS_LOOP => \@loop_data);
215 The above example would work with a template like:
217 <TMPL_LOOP NAME="THIS_LOOP">
219 Word: <TMPL_VAR NAME="WORD"> <br>
220 Number: <TMPL_VAR NAME="NUMBER"> <p>
221 </TMPL_LOOP>
222 It would produce output like:
224 Word: I
226 Number: 1
227 Word: Am
229 Number: 2
230 Word: Cool
232 Number: 3
233 <TMPL_LOOP>s within <TMPL_LOOP>s are fine and work as you would expect.
235 If the syntax for the param() call has you stumped, here's an example
236 of a param call with one nested loop:
237 $template->param(LOOP => [
239 { name => 'Bobby',
240 nicknames => [
241 { name => 'the big bad wolf' },
242 { name => 'He-Man' },
243 ],
244 },
245 ],
246 );
247 Basically, each <TMPL_LOOP> gets an array reference. Inside the array
249 are any number of hash references. These hashes contain the
250 name=>value pairs for a single pass over the loop template.
251 Inside a <TMPL_LOOP>, the only variables that are usable are the ones
253 from the <TMPL_LOOP>. The variables in the outer blocks are not
254 visible within a template loop. For the computer-science geeks among
255 you, a <TMPL_LOOP> introduces a new scope much like a perl subroutine
256 call. If you want your variables to be global you can use
257 'global_vars' option to new() described below.
258 TMPL_INCLUDE
260 <TMPL_INCLUDE NAME="filename.tmpl">
261 <TMPL_INCLUDE EXPR="function_call, variable, expression" DEFAULT='some_file'>
262 This tag includes a template directly into the current template at the
264 point where the tag is found. The included template contents are used
265 exactly as if its contents were physically included in the master
266 template.
267 The file specified can be an absolute path (beginning with a '/' under
269 Unix, for example). If it isn't absolute, the path to the enclosing
270 file is tried first. After that the path in the environment variable
271 HTML_TEMPLATE_ROOT is tried, if it exists. Next, the "path" option is
272 consulted, first as-is and then with HTML_TEMPLATE_ROOT prepended if
273 available. As a final attempt, the filename is passed to open()
274 directly. See below for more information on HTML_TEMPLATE_ROOT and the
275 "path" option to new().
276 As a protection against infinitly recursive includes, an arbitrary
278 limit of 10 levels deep is imposed. You can alter this limit with the
279 "max_includes" option. See the entry for the "max_includes" option
280 below for more details.
281 For the <TMPL_INCLUDE EXPR=".."> see "INCLUDE extension to Expr" for
283 more details.
284 TMPL_IF
286 <TMPL_IF NAME="PARAMETER_NAME"> ... </TMPL_IF>
287 The <TMPL_IF> tag allows you to include or not include a block of the
289 template based on the value of a given parameter name. If the
290 parameter is given a value that is true for Perl - like '1' - then the
291 block is included in the output. If it is not defined, or given a
292 false value - like '0' - then it is skipped. The parameters are
293 specified the same way as with TMPL_VAR.
294 Example Template:
296 <TMPL_IF NAME="BOOL">
298 Some text that only gets displayed if BOOL is true!
299 </TMPL_IF>
300 Now if you call $template->param(BOOL => 1) then the above block will
302 be included by output.
303 <TMPL_IF> </TMPL_IF> blocks can include any valid HTML::Template
305 construct - VARs and LOOPs and other IF/ELSE blocks. Note, however,
306 that intersecting a <TMPL_IF> and a <TMPL_LOOP> is invalid.
307 Not going to work:
309 <TMPL_IF BOOL>
310 <TMPL_LOOP SOME_LOOP>
311 </TMPL_IF>
312 </TMPL_LOOP>
313 If the name of a TMPL_LOOP is used in a TMPL_IF, the IF block will
315 output if the loop has at least one row. Example:
316 <TMPL_IF LOOP_ONE>
318 This will output if the loop is not empty.
319 </TMPL_IF>
320 <TMPL_LOOP LOOP_ONE>
322 ....
323 </TMPL_LOOP>
324 WARNING: Much of the benefit of HTML::Template is in decoupling your
326 Perl and HTML. If you introduce numerous cases where you have TMPL_IFs
327 and matching Perl if()s, you will create a maintenance problem in
328 keeping the two synchronized. I suggest you adopt the practice of only
329 using TMPL_IF if you can do so without requiring a matching if() in
330 your Perl code.
331 TMPL_ELSIF
333 <TMPL_IF NAME="PARAMETER_NAME1"> ...
334 <TMPL_ELSIF NAME="PARAMETER_NAME2"> ...
335 <TMPL_ELSIF NAME="PARAMETER_NAME3"> ...
336 <TMPL_ELSE> ... </TMPL_IF>
337 WARNING: TMPL_ELSIF is a HTML::Template::Pro extension! It is not
339 supported in HTML::Template (as of 2.9).
340 TMPL_ELSE
342 <TMPL_IF NAME="PARAMETER_NAME"> ... <TMPL_ELSE> ... </TMPL_IF>
343 You can include an alternate block in your TMPL_IF block by using
345 TMPL_ELSE. NOTE: You still end the block with </TMPL_IF>, not
346 </TMPL_ELSE>!
347 Example:
349 <TMPL_IF BOOL>
351 Some text that is included only if BOOL is true
352 <TMPL_ELSE>
353 Some text that is included only if BOOL is false
354 </TMPL_IF>
355 TMPL_UNLESS
357 <TMPL_UNLESS NAME="PARAMETER_NAME"> ... </TMPL_UNLESS>
358 This tag is the opposite of <TMPL_IF>. The block is output if the
360 CONTROL_PARAMETER is set false or not defined. You can use <TMPL_ELSE>
361 with <TMPL_UNLESS> just as you can with <TMPL_IF>.
362 Example:
364 <TMPL_UNLESS BOOL>
366 Some text that is output only if BOOL is FALSE.
367 <TMPL_ELSE>
368 Some text that is output only if BOOL is TRUE.
369 </TMPL_UNLESS>
370 If the name of a TMPL_LOOP is used in a TMPL_UNLESS, the UNLESS block
372 output if the loop has zero rows.
373 <TMPL_UNLESS LOOP_ONE>
375 This will output if the loop is empty.
376 </TMPL_UNLESS>
377 <TMPL_LOOP LOOP_ONE>
379 ....
380 </TMPL_LOOP>
381 NOTES
383 HTML::Template's tags are meant to mimic normal HTML tags. However,
384 they are allowed to "break the rules". Something like:
385 <img src="<TMPL_VAR IMAGE_SRC>">
387 is not really valid HTML, but it is a perfectly valid use and will work
389 as planned.
390 The "NAME=" in the tag is optional, although for extensibility's sake I
392 recommend using it. Example - "<TMPL_LOOP LOOP_NAME>" is acceptable.
393 If you're a fanatic about valid HTML and would like your templates to
395 conform to valid HTML syntax, you may optionally type template tags in
396 the form of HTML comments. This may be of use to HTML authors who would
397 like to validate their templates' HTML syntax prior to HTML::Template
398 processing, or who use DTD-savvy editing tools.
399 <!-- TMPL_VAR NAME=PARAM1 -->
401 In order to realize a dramatic savings in bandwidth, the standard (non-
403 comment) tags will be used throughout this documentation.
404
406 This module supports an extension to HTML::Template which allows
407 expressions in the template syntax which was implemented in
408 HTML::Template::Expr. See HTML::Template::Expr for details.
409 Expression support includes comparisons, math operations, string
411 operations and a mechanism to allow you add your own functions at
412 runtime. The basic syntax is:
413 <TMPL_IF EXPR="banana_count > 10">
415 I've got a lot of bananas.
416 </TMPL_IF>
417 This will output "I've got a lot of bananas" if you call:
419 $template->param(banana_count => 100);
421 In your script. <TMPL_VAR>s also work with expressions:
423 I'd like to have <TMPL_VAR EXPR="banana_count * 2"> bananas.
425 This will output "I'd like to have 200 bananas." with the same param()
427 call as above.
428
430 Variables
431 Variables are unquoted alphanumeric strings with the same restrictions
432 as variable names in HTML::Template. Their values are set through
433 param(), just like normal HTML::Template variables. For example, these
434 two lines are equivalent:
435 <TMPL_VAR EXPR="foo">
437 <TMPL_VAR NAME="foo">
439 Emiliano Bruni extension to Expr
441 original HTML::Template allows almost arbitrary chars in parameter
442 names, but original HTML::Template::Expr (as to 0.04) allows variables
443 in the 'EXPR' tag to be only m![A-Za-z_][A-Za-z0-9_]*!.
444 With this extension, arbitrary chars can be used in variable name
446 inside the 'EXPR' tag if bracketed in ${}, as, for example,
447 EXPR="${foo.bar} eq 'a'". Note that old bracketing into {} is
448 considered obsolete, as it will clash with JSON assignments like A = {
449 "key" => "val" }.
450 COMPATIBILITY WARNING. Currently, this extension is not present in
452 HTML::Template::Expr (as of 0.04).
453 INCLUDE extension to Expr
455 With this extension, you can write something like <TMPL_INCLUDE
456 EXPR="variable">
457 or <TMPL_INCLUDE EXPR="function_call()">, or even <TMPL_INCLUDE
458 EXPR="function_call(VAR1,VAR2,func2()) DEFAULT='some_file'">
459 SECURITY WARNING. Using of this extension with untrasted values of
461 variables is a potential security leak (as in <TMPL_INCLUDE
462 EXPR="USER_INPUT"> with USER_INPUT='/etc/passwd'). Omit it unless you
463 know what you are doing.
464 COMPATIBILITY WARNING. Currently, this extension is not present in
466 HTML::Template::Expr (as of 0.04).
467 Constants
469 Numbers are unquoted strings of numbers and may have a single "." to
470 indicate a floating point number. For example:
471 <TMPL_VAR EXPR="10 + 20.5">
473 String constants must be enclosed in quotes, single or double. For
475 example:
476 <TMPL_VAR EXPR="sprintf('%d', foo)">
478 Note that the original parser of HTML::Template::Expr is currently
480 (0.04) rather simple, so if you need backward compatibility all
481 compound expressions must be parenthesized.
482 Backward compatible examples:
484 <TMPL_VAR EXPR="(10 + foo) / bar">
486 <TMPL_IF EXPR="(foo % 10) > (bar + 1)">
488 Nevertheless, in HTML::Template::Pro, you can safely write things like
490 <TMPL_VAR EXPR="1+2*foo/bar^2 ">
492 with proper priority of operations.
494 Pattern in a regular expression must be enclosed with "/":
496 <TMPL_VAR EXPR="foo =~ /bar/">
498
500 Here's a list of supported comparison operators:
501 • Numeric Comparisons
503 • <
505 • >
507 • ==
509 • !=
511 • >=
513 • <=
515 • <=>
517 • String Comparisons
519 • gt
521 • lt
523 • eq
525 • ne
527 • ge
529 • le
531 • cmp
533
535 The basic operators are supported:
536 • +
538 • -
540 • *
542 • /
544 • %
546 • ^ (not supported in HTML::Template::Expr)
548 There are also some mathy functions. See the FUNCTIONS section below.
550
552 Boolean logic is available:
553 • && (synonym: and)
555 • || (synonym: or)
557
559 regexp support is added to HTML::Template::Expr and HTML::Template::Pro
560 by Stanislav Yadykin <tosick at altlinux.ru>. Currently it is not
561 included in official distribution of HTML::Template::Expr.
562 Standard regexp syntax:
564 • =~
566 • !~
568
570 The following functions are available to be used in expressions. See
571 perldoc perlfunc for details.
572 • sprintf
574 • substr (2 and 3 arg versions only)
576 • lc
578 • lcfirst
580 • uc
582 • ucfirst
584 • length
586 • defined
588 • abs
590 • atan2
592 • cos
594 • exp
596 • hex
598 • int
600 • log
602 • oct
604 • rand
606 • sin
608 • sqrt
610 • srand
612 All functions must be called using full parenthesis. For example, this
614 is a syntax error:
615 <TMPL_IF expr="defined foo">
617 But this is good:
619 <TMPL_IF expr="defined(foo)">
621
623 You may also define functions of your own. See
624 HTML::Template::PerlInterface for details.
625
627 Sam Tregar, sam@tregar.com (Main text)
628 I. Vlasenko, <viy@altlinux.org> (Pecularities of HTML::Template::Pro)
630
632 HTML::Template : A module for using HTML Templates with Perl
633 Copyright (C) 2000-2008 Sam Tregar (sam@tregar.com)
634 This module is free software; you can redistribute it and/or modify it
636 under the terms of either:
637 a) the GNU General Public License as published by the Free Software
639 Foundation; either version 2, or (at your option) any later version,
640 or
642 b) the "Artistic License" which comes with this module.
644 This program is distributed in the hope that it will be useful,
646 but WITHOUT ANY WARRANTY; without even the implied warranty of
647 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
648 the GNU General Public License or the Artistic License for more details.
649 You should have received a copy of the Artistic License with this
651 module, in the file ARTISTIC. If not, I'll be glad to provide one.
652 You should have received a copy of the GNU General Public License
654 along with this program; if not, write to the Free Software
655 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
656 USA
657perl v5.38.0 2023-07-20 HTML::Template::SYNTAX(3)