1HTML::Template::SYNTAX(U3s)er Contributed Perl DocumentatHiToMnL::Template::SYNTAX(3)
2
3
4

NAME

6       HTML::Template::SYNTAX - syntax of html template language for
7       HTML::Template
8

SYNOPSIS

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
14       First you make a template - this is just a normal HTML file with a few
15       extra tags, the simplest being <TMPL_VAR>
16
17       For example, test.tmpl:
18
19         <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
28       Now define the value for HOME and PATH, for example, in perl it will
29       look like
30
31         $template->param(HOME => $ENV{HOME});
32         $template->param(PATH => $ENV{PATH});
33
34       and process the template. If all is well in the universe this should
35       show something like this in your browser:
36
37         My Home Directory is /home/some/directory
38         My Path is set to /bin;/usr/bin
39

DESCRIPTION

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
51       This module is licensed under the (L)GPL or perl license.  See the
52       LICENSE section below for more details.
53

TUTORIAL

55       If you're new to HTML::Template, I suggest you start with the
56       introductory article available on the HTML::Template website:
57
58          http://html-template.sourceforge.net
59

MOTIVATION

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
67       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
75       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
84       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

THE TAGS

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
98       template tags could be decorated as html comments <!-- TMPL_SOMETHING
99       A="B" -->
100
101       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
104       See NOTES.
105
106   TMPL_VAR
107         <TMPL_VAR NAME="PARAMETER_NAME">
108
109       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
115       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 &quot;, &lt;, &gt;
119       and &amp; respectively.  This is useful when you want to use a TMPL_VAR
120       in a context where those characters would cause trouble.  Example:
121
122          <input name=param type=text value="<TMPL_VAR NAME="PARAM">">
123
124       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
128          <input name=param type=text value="<TMPL_VAR ESCAPE=HTML NAME="PARAM">">
129
130       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
134       "ESCAPE=0" and "ESCAPE=NONE" turn off escaping, which is the default
135       behavior.
136
137       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
141       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
145       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
149         The <TMPL_VAR NAME=WHO DEFAULT=devil> gave me a taco.
150
151   TMPL_LOOP
152         <TMPL_LOOP NAME="LOOP_NAME"> ... </TMPL_LOOP>
153
154       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)
158       for this loop.  The loop iterates over the list and produces output
159       from the text block for each pass.  Unset parameters are skipped.
160       Here's an example:
161
162        In the template:
163
164          <TMPL_LOOP NAME=EMPLOYEE_INFO>
165             Name: <TMPL_VAR NAME=NAME> <br>
166             Job:  <TMPL_VAR NAME=JOB>  <p>
167          </TMPL_LOOP>
168
169
170        In the script:
171
172          $template->param(EMPLOYEE_INFO => [
173                                              { name => 'Sam', job => 'programmer' },
174                                              { name => 'Steve', job => 'soda jerk' },
175                                            ]
176                          );
177          print $template->output();
178
179
180        The output in a browser:
181
182          Name: Sam
183          Job: programmer
184
185          Name: Steve
186          Job: soda jerk
187
188       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
191       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
195          # 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
199          my @loop_data = ();  # initialize an array to hold your loop
200
201          while (@words and @numbers) {
202            my %row_data;  # get a fresh hash for the row data
203
204            # fill in this row
205            $row_data{WORD} = shift @words;
206            $row_data{NUMBER} = shift @numbers;
207
208            # the crucial step - push a reference to this row into the loop!
209            push(@loop_data, \%row_data);
210          }
211
212          # finally, assign the loop data to the loop param, again with a
213          # reference:
214          $template->param(THIS_LOOP => \@loop_data);
215
216       The above example would work with a template like:
217
218          <TMPL_LOOP NAME="THIS_LOOP">
219             Word: <TMPL_VAR NAME="WORD">     <br>
220             Number: <TMPL_VAR NAME="NUMBER"> <p>
221          </TMPL_LOOP>
222
223       It would produce output like:
224
225          Word: I
226          Number: 1
227
228          Word: Am
229          Number: 2
230
231          Word: Cool
232          Number: 3
233
234       <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
238         $template->param(LOOP => [
239                                   { name => 'Bobby',
240                                     nicknames => [
241                                                   { name => 'the big bad wolf' },
242                                                   { name => 'He-Man' },
243                                                  ],
244                                   },
245                                  ],
246                         );
247
248       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
252       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
259   TMPL_INCLUDE
260         <TMPL_INCLUDE NAME="filename.tmpl">
261         <TMPL_INCLUDE EXPR="function_call, variable, expression" DEFAULT='some_file'>
262
263       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
268       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
277       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
282       For the <TMPL_INCLUDE EXPR=".."> see "INCLUDE extension to Expr" for
283       more details.
284
285   TMPL_IF
286         <TMPL_IF NAME="PARAMETER_NAME"> ... </TMPL_IF>
287
288       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
295       Example Template:
296
297          <TMPL_IF NAME="BOOL">
298            Some text that only gets displayed if BOOL is true!
299          </TMPL_IF>
300
301       Now if you call $template->param(BOOL => 1) then the above block will
302       be included by output.
303
304       <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
308          Not going to work:
309          <TMPL_IF BOOL>
310             <TMPL_LOOP SOME_LOOP>
311          </TMPL_IF>
312             </TMPL_LOOP>
313
314       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
317         <TMPL_IF LOOP_ONE>
318           This will output if the loop is not empty.
319         </TMPL_IF>
320
321         <TMPL_LOOP LOOP_ONE>
322           ....
323         </TMPL_LOOP>
324
325       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
332   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
338       WARNING: TMPL_ELSIF is a HTML::Template::Pro extension! It is not
339       supported in HTML::Template (as of 2.9).
340
341   TMPL_ELSE
342         <TMPL_IF NAME="PARAMETER_NAME"> ... <TMPL_ELSE> ... </TMPL_IF>
343
344       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
348          Example:
349
350          <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
356   TMPL_UNLESS
357         <TMPL_UNLESS NAME="PARAMETER_NAME"> ... </TMPL_UNLESS>
358
359       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
363         Example:
364
365         <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
371       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
374         <TMPL_UNLESS LOOP_ONE>
375           This will output if the loop is empty.
376         </TMPL_UNLESS>
377
378         <TMPL_LOOP LOOP_ONE>
379           ....
380         </TMPL_LOOP>
381
382   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
386          <img src="<TMPL_VAR IMAGE_SRC>">
387
388       is not really valid HTML, but it is a perfectly valid use and will work
389       as planned.
390
391       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
394       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
400         <!-- TMPL_VAR NAME=PARAM1 -->
401
402       In order to realize a dramatic savings in bandwidth, the standard (non-
403       comment) tags will be used throughout this documentation.
404

EXPR EXTENSION

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
410       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
414          <TMPL_IF EXPR="banana_count > 10">
415            I've got a lot of bananas.
416          </TMPL_IF>
417
418       This will output "I've got a lot of bananas" if you call:
419
420          $template->param(banana_count => 100);
421
422       In your script.  <TMPL_VAR>s also work with expressions:
423
424          I'd like to have <TMPL_VAR EXPR="banana_count * 2"> bananas.
425
426       This will output "I'd like to have 200 bananas." with the same param()
427       call as above.
428

BASIC SYNTAX

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
436          <TMPL_VAR EXPR="foo">
437
438          <TMPL_VAR NAME="foo">
439
440   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
445       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
451       COMPATIBILITY WARNING.  Currently, this extension is not present in
452       HTML::Template::Expr (as of 0.04).
453
454   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
460       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
465       COMPATIBILITY WARNING.  Currently, this extension is not present in
466       HTML::Template::Expr (as of 0.04).
467
468   Constants
469       Numbers are unquoted strings of numbers and may have a single "." to
470       indicate a floating point number.  For example:
471
472          <TMPL_VAR EXPR="10 + 20.5">
473
474       String constants must be enclosed in quotes, single or double.  For
475       example:
476
477          <TMPL_VAR EXPR="sprintf('%d', foo)">
478
479       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
483       Backward compatible examples:
484
485          <TMPL_VAR EXPR="(10 + foo) / bar">
486
487          <TMPL_IF EXPR="(foo % 10) > (bar + 1)">
488
489       Nevertheless, in HTML::Template::Pro, you can safely write things like
490
491          <TMPL_VAR EXPR="1+2*foo/bar^2 ">
492
493       with proper priority of operations.
494
495       Pattern in a regular expression must be enclosed with "/":
496
497          <TMPL_VAR EXPR="foo =~ /bar/">
498

COMPARISON

500       Here's a list of supported comparison operators:
501
502       ·   Numeric Comparisons
503
504           ·   <
505
506           ·   >
507
508           ·   ==
509
510           ·   !=
511
512           ·   >=
513
514           ·   <=
515
516           ·   <=>
517
518       ·   String Comparisons
519
520           ·   gt
521
522           ·   lt
523
524           ·   eq
525
526           ·   ne
527
528           ·   ge
529
530           ·   le
531
532           ·   cmp
533

MATHEMATICS

535       The basic operators are supported:
536
537       ·   +
538
539       ·   -
540
541       ·   *
542
543       ·   /
544
545       ·   %
546
547       ·   ^ (not supported in HTML::Template::Expr)
548
549       There are also some mathy functions.  See the FUNCTIONS section below.
550

LOGIC

552       Boolean logic is available:
553
554       ·   && (synonym: and)
555
556       ·   || (synonym: or)
557

REGULAR EXPRESSION SUPPORT

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
563       Standard regexp syntax:
564
565       ·   =~
566
567       ·   !~
568

FUNCTIONS

570       The following functions are available to be used in expressions.  See
571       perldoc perlfunc for details.
572
573       ·   sprintf
574
575       ·   substr (2 and 3 arg versions only)
576
577       ·   lc
578
579       ·   lcfirst
580
581       ·   uc
582
583       ·   ucfirst
584
585       ·   length
586
587       ·   defined
588
589       ·   abs
590
591       ·   atan2
592
593       ·   cos
594
595       ·   exp
596
597       ·   hex
598
599       ·   int
600
601       ·   log
602
603       ·   oct
604
605       ·   rand
606
607       ·   sin
608
609       ·   sqrt
610
611       ·   srand
612
613       All functions must be called using full parenthesis.  For example, this
614       is a syntax error:
615
616          <TMPL_IF expr="defined foo">
617
618       But this is good:
619
620          <TMPL_IF expr="defined(foo)">
621

EXPR: DEFINING NEW FUNCTIONS

623       You may also define functions of your own.  See
624       HTML::Template::PerlInterface for details.
625

AUTHOR

627       Sam Tregar, sam@tregar.com (Main text)
628
629       I. Vlasenko, <viy@altlinux.org> (Pecularities of HTML::Template::Pro)
630

LICENSE

632         HTML::Template : A module for using HTML Templates with Perl
633         Copyright (C) 2000-2008 Sam Tregar (sam@tregar.com)
634
635         This module is free software; you can redistribute it and/or modify it
636         under the terms of either:
637
638         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
641         or
642
643         b) the "Artistic License" which comes with this module.
644
645         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
650         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
653         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
657
658
659
660perl v5.28.1                      2010-09-06         HTML::Template::SYNTAX(3)
Impressum