Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTML::Template::SYNTAXUser Contributed Perl DocumentaHTML::Template::SYNTAX(3)

NAME
       HTML::Template::SYNTAX -	syntax of html template	language for
       HTML::Template

SYNOPSIS
       This help is only on syntax of html template files.  For	perl interface
       of HTML::Template::Pro you should see "SYNOPSIS"	in
       HTML::Template::PerlInterface.

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

       For example, test.tmpl:

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

       Now define the value for	HOME and PATH, for example, in perl it will
       look like

	 $template->param(HOME => $ENV{HOME});
	 $template->param(PATH => $ENV{PATH});

       and process the template. If all	is well	in the universe	this should
       show something like this	in your	browser:

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

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

       This module is licensed under the (L)GPL	or perl	license.  See the
       LICENSE section below for more details.

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

	  http://html-template.sourceforge.net

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

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

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

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

THE TAGS
   GENERAL TAG SYNTAX
       A generic HTML::Template	tag that is supported by HTML::Template::Pro
       looks like <TMPL_SOMETHING A="B"	[C="D" ...]>. Tags are case-
       insensitve: <tmpl_something a="B" [c="D"	...]> is acceptable.  Single
       quotes can be used, <TMPL_SOMETHING A='B' [C='D'	...]> quotes can be
       omitted,	<TMPL_SOMETHING	A=B ...	> and option name could	be often
       guessed as in <TMPL_SOMETHING B>.

       template	tags could be decorated	as html	comments <!-- TMPL_SOMETHING
       A="B" -->

       Also, as	HTML::Template::Pro extension (starting	from version 0.90),
       template	tags could also	be decorated as	xml <TMPL_SOMETHING A="B" />

       See NOTES.

   TMPL_VAR
	 <TMPL_VAR NAME="PARAMETER_NAME">

       The <TMPL_VAR> tag is very simple.  For each <TMPL_VAR> tag in the
       template	you call $template->param(PARAMETER_NAME => "VALUE").  When
       the template is output the <TMPL_VAR> is	replaced with the VALUE	text
       you specified.  If you don't set	a parameter it just gets skipped in
       the output.

       Optionally you can use the "ESCAPE=HTML"	option in the tag to indicate
       that you	want the value to be HTML-escaped before being returned	from
       output (the old ESCAPE=1	syntax is still	supported).  This means	that
       the ", <, >, and	& characters get translated into &quot;, &lt;, &gt;
       and &amp; respectively.	This is	useful when you	want to	use a TMPL_VAR
       in a context where those	characters would cause trouble.	 Example:

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

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

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

       You'll get what you wanted no matter what value happens to be passed in
       for param.  You can also	write ESCAPE="HTML", ESCAPE='HTML' and
       ESCAPE='1'.

       "ESCAPE=0" and "ESCAPE=NONE" turn off escaping, which is	the default
       behavior.

       There is	also the "ESCAPE=URL" option which may be used for VARs	that
       populate	a URL.	It will	do URL escaping, like replacing	' ' with '+'
       and '/' with '%2F'.

       There is	also the "ESCAPE=JS" option which may be used for VARs that
       need to be placed within	a Javascript string. All \n, \r, ' and "
       characters are escaped.

       You can assign a	default	value to a variable with the DEFAULT
       attribute.  For example,	this will output "the devil gave me a taco" if
       the "who" variable is not set.

	 The <TMPL_VAR NAME=WHO	DEFAULT=devil> gave me a taco.

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

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

	In the template:

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

	In the script:

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

	The output in a	browser:

	  Name:	Sam
	  Job: programmer

	  Name:	Steve
	  Job: soda jerk

       As you can see above the	<TMPL_LOOP> takes a list of variable
       assignments and then iterates over the loop body	producing output.

       Often you'll want to generate a <TMPL_LOOP>'s contents
       programmatically.  Here's an example of how this	can be done (many
       other ways are possible!):

	  # a couple of	arrays of data to put in a loop:
	  my @words = qw(I Am Cool);
	  my @numbers =	qw(1 2 3);

	  my @loop_data	= ();  # initialize an array to	hold your loop

	  while	(@words	and @numbers) {
	    my %row_data;  # get a fresh hash for the row data

	    # fill in this row
	    $row_data{WORD} = shift @words;
	    $row_data{NUMBER} =	shift @numbers;

	    # the crucial step - push a	reference to this row into the loop!
	    push(@loop_data, \%row_data);
	  }

	  # finally, assign the	loop data to the loop param, again with	a
	  # reference:
	  $template->param(THIS_LOOP =>	\@loop_data);

       The above example would work with a template like:

	  <TMPL_LOOP NAME="THIS_LOOP">
	     Word: <TMPL_VAR NAME="WORD">     <br>
	     Number: <TMPL_VAR NAME="NUMBER"> <p>
	  </TMPL_LOOP>

       It would	produce	output like:

	  Word:	I
	  Number: 1

	  Word:	Am
	  Number: 2

	  Word:	Cool
	  Number: 3

       <TMPL_LOOP>s within <TMPL_LOOP>s	are fine and work as you would expect.
       If the syntax for the "param()" call has	you stumped, here's an example
       of a param call with one	nested loop:

	 $template->param(LOOP => [
				   { name => 'Bobby',
				     nicknames => [
						   { name => 'the big bad wolf'	},
						   { name => 'He-Man' },
						  ],
				   },
				  ],
			 );

       Basically, each <TMPL_LOOP> gets	an array reference.  Inside the	array
       are any number of hash references.  These hashes	contain	the
       name=>value pairs for a single pass over	the loop template.

       Inside a	<TMPL_LOOP>, the only variables	that are usable	are the	ones
       from the	<TMPL_LOOP>.  The variables in the outer blocks	are not
       visible within a	template loop.	For the	computer-science geeks among
       you, a <TMPL_LOOP> introduces a new scope much like a perl subroutine
       call.  If you want your variables to be global you can use
       'global_vars' option to new() described below.

   TMPL_INCLUDE
	 <TMPL_INCLUDE NAME="filename.tmpl">
	 <TMPL_INCLUDE EXPR="function_call, variable, expression" DEFAULT='some_file'>

       This tag	includes a template directly into the current template at the
       point where the tag is found.  The included template contents are used
       exactly as if its contents were physically included in the master
       template.

       The file	specified can be an absolute path (beginning with a '/'	under
       Unix, for example).  If it isn't	absolute, the path to the enclosing
       file is tried first.  After that	the path in the	environment variable
       HTML_TEMPLATE_ROOT is tried, if it exists.  Next, the "path" option is
       consulted, first	as-is and then with HTML_TEMPLATE_ROOT prepended if
       available.  As a	final attempt, the filename is passed to open()
       directly.  See below for	more information on HTML_TEMPLATE_ROOT and the
       "path" option to	new().

       As a protection against infinitly recursive includes, an	arbitrary
       limit of	10 levels deep is imposed.  You	can alter this limit with the
       "max_includes" option.  See the entry for the "max_includes" option
       below for more details.

       For the <TMPL_INCLUDE EXPR="..">	see "INCLUDE extension to Expr"	for
       more details.

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

       The <TMPL_IF> tag allows	you to include or not include a	block of the
       template	based on the value of a	given parameter	name.  If the
       parameter is given a value that is true for Perl	- like '1' - then the
       block is	included in the	output.	 If it is not defined, or given	a
       false value - like '0' -	then it	is skipped.  The parameters are
       specified the same way as with TMPL_VAR.

       Example Template:

	  <TMPL_IF NAME="BOOL">
	    Some text that only	gets displayed if BOOL is true!
	  </TMPL_IF>

       Now if you call $template->param(BOOL =>	1) then	the above block	will
       be included by output.

       <TMPL_IF> </TMPL_IF> blocks can include any valid HTML::Template
       construct - VARs	and LOOPs and other IF/ELSE blocks.  Note, however,
       that intersecting a <TMPL_IF> and a <TMPL_LOOP> is invalid.

	  Not going to work:
	  <TMPL_IF BOOL>
	     <TMPL_LOOP	SOME_LOOP>
	  </TMPL_IF>
	     </TMPL_LOOP>

       If the name of a	TMPL_LOOP is used in a TMPL_IF,	the IF block will
       output if the loop has at least one row.	 Example:

	 <TMPL_IF LOOP_ONE>
	   This	will output if the loop	is not empty.
	 </TMPL_IF>

	 <TMPL_LOOP LOOP_ONE>
	   ....
	 </TMPL_LOOP>

       WARNING:	Much of	the benefit of HTML::Template is in decoupling your
       Perl and	HTML.  If you introduce	numerous cases where you have TMPL_IFs
       and matching Perl if()s,	you will create	a maintenance problem in
       keeping the two synchronized.  I	suggest	you adopt the practice of only
       using TMPL_IF if	you can	do so without requiring	a matching if()	in
       your Perl code.

   TMPL_ELSIF
	 <TMPL_IF NAME="PARAMETER_NAME1"> ...
	 <TMPL_ELSIF NAME="PARAMETER_NAME2"> ...
	 <TMPL_ELSIF NAME="PARAMETER_NAME3"> ...
	 <TMPL_ELSE> ... </TMPL_IF>

       WARNING:	TMPL_ELSIF is a	HTML::Template::Pro extension! It is not
       supported in HTML::Template (as of 2.9).

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

       You can include an alternate block in your TMPL_IF block	by using
       TMPL_ELSE.  NOTE: You still end the block with </TMPL_IF>, not
       </TMPL_ELSE>!

	  Example:

	  <TMPL_IF BOOL>
	    Some text that is included only if BOOL is true
	  <TMPL_ELSE>
	    Some text that is included only if BOOL is false
	  </TMPL_IF>

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

       This tag	is the opposite	of <TMPL_IF>.  The block is output if the
       CONTROL_PARAMETER is set	false or not defined.  You can use <TMPL_ELSE>
       with <TMPL_UNLESS> just as you can with <TMPL_IF>.

	 Example:

	 <TMPL_UNLESS BOOL>
	   Some	text that is output only if BOOL is FALSE.
	 <TMPL_ELSE>
	   Some	text that is output only if BOOL is TRUE.
	 </TMPL_UNLESS>

       If the name of a	TMPL_LOOP is used in a TMPL_UNLESS, the	UNLESS block
       output if the loop has zero rows.

	 <TMPL_UNLESS LOOP_ONE>
	   This	will output if the loop	is empty.
	 </TMPL_UNLESS>

	 <TMPL_LOOP LOOP_ONE>
	   ....
	 </TMPL_LOOP>

   NOTES
       HTML::Template's	tags are meant to mimic	normal HTML tags.  However,
       they are	allowed	to "break the rules".  Something like:

	  <img src="<TMPL_VAR IMAGE_SRC>">

       is not really valid HTML, but it	is a perfectly valid use and will work
       as planned.

       The "NAME=" in the tag is optional, although for	extensibility's	sake I
       recommend using it.  Example - "<TMPL_LOOP LOOP_NAME>" is acceptable.

       If you're a fanatic about valid HTML and	would like your	templates to
       conform to valid	HTML syntax, you may optionally	type template tags in
       the form	of HTML	comments. This may be of use to	HTML authors who would
       like to validate	their templates' HTML syntax prior to HTML::Template
       processing, or who use DTD-savvy	editing	tools.

	 <!-- TMPL_VAR NAME=PARAM1 -->

       In order	to realize a dramatic savings in bandwidth, the	standard (non-
       comment)	tags will be used throughout this documentation.

EXPR EXTENSION
       This module supports an extension to HTML::Template which allows
       expressions in the template syntax which	was implemented	in
       HTML::Template::Expr. See HTML::Template::Expr for details.

       Expression support includes comparisons,	math operations, string
       operations and a	mechanism to allow you add your	own functions at
       runtime.	 The basic syntax is:

	  <TMPL_IF EXPR="banana_count >	10">
	    I've got a lot of bananas.
	  </TMPL_IF>

       This will output	"I've got a lot	of bananas" if you call:

	  $template->param(banana_count	=> 100);

       In your script.	<TMPL_VAR>s also work with expressions:

	  I'd like to have <TMPL_VAR EXPR="banana_count	* 2"> bananas.

       This will output	"I'd like to have 200 bananas."	with the same param()
       call as above.

BASIC SYNTAX
   Variables
       Variables are unquoted alphanumeric strings with	the same restrictions
       as variable names in HTML::Template.  Their values are set through
       param(),	just like normal HTML::Template	variables.  For	example, these
       two lines are equivalent:

	  <TMPL_VAR EXPR="foo">

	  <TMPL_VAR NAME="foo">

   Emiliano Bruni extension to Expr
       original	HTML::Template allows almost arbitrary chars in	parameter
       names, but original HTML::Template::Expr	(as to 0.04) allows variables
       in the 'EXPR' tag to be only m![A-Za-z_][A-Za-z0-9_]*!.

       With this extension, arbitrary chars can	be used	in variable name
       inside the 'EXPR' tag if	bracketed in ${}, as, for example,
       EXPR="${foo.bar}	eq 'a'".  Note that old	bracketing into	{} is
       considered obsolete, as it will clash with JSON assignments like	A = {
       "key" =>	"val" }.

       COMPATIBILITY WARNING.  Currently, this extension is not	present	in
       HTML::Template::Expr (as	of 0.04).

   INCLUDE extension to	Expr
       With this extension, you	can write something like <TMPL_INCLUDE
       EXPR="variable">
	or <TMPL_INCLUDE EXPR="function_call()">, or even <TMPL_INCLUDE
       EXPR="function_call(VAR1,VAR2,func2()) DEFAULT='some_file'">

       SECURITY	WARNING.  Using	of this	extension with untrasted values	of
       variables is a potential	security leak (as in <TMPL_INCLUDE
       EXPR="USER_INPUT"> with USER_INPUT='/etc/passwd').  Omit	it unless you
       know what you are doing.

       COMPATIBILITY WARNING.  Currently, this extension is not	present	in
       HTML::Template::Expr (as	of 0.04).

   Constants
       Numbers are unquoted strings of numbers and may have a single "." to
       indicate	a floating point number.  For example:

	  <TMPL_VAR EXPR="10 + 20.5">

       String constants	must be	enclosed in quotes, single or double.  For
       example:

	  <TMPL_VAR EXPR="sprintf('%d',	foo)">

       Note that the original parser of	HTML::Template::Expr is	currently
       (0.04) rather simple, so	if you need backward compatibility all
       compound	expressions must be parenthesized.

       Backward	compatible examples:

	  <TMPL_VAR EXPR="(10 +	foo) / bar">

	  <TMPL_IF EXPR="(foo %	10) > (bar + 1)">

       Nevertheless, in	HTML::Template::Pro, you can safely write things like

	  <TMPL_VAR EXPR="1+2*foo/bar^2	">

       with proper priority of operations.

       Pattern in a regular expression must be enclosed	with "/":

	  <TMPL_VAR EXPR="foo =~ /bar/">

COMPARISON
       Here's a	list of	supported comparison operators:

       o   Numeric Comparisons

	   o   <

	   o   >

	   o   ==

	   o   !=

	   o   >=

	   o   <=

	   o   <=>

       o   String Comparisons

	   o   gt

	   o   lt

	   o   eq

	   o   ne

	   o   ge

	   o   le

	   o   cmp

MATHEMATICS
       The basic operators are supported:

       o   +

       o   -

       o   *

       o   /

       o   %

       o   ^ (not supported in HTML::Template::Expr)

       There are also some mathy functions.  See the FUNCTIONS section below.

LOGIC
       Boolean logic is	available:

       o   && (synonym:	and)

       o   || (synonym:	or)

REGULAR	EXPRESSION SUPPORT
       regexp support is added to HTML::Template::Expr and HTML::Template::Pro
       by Stanislav Yadykin <tosick at altlinux.ru>.  Currently	it is not
       included	in official distribution of HTML::Template::Expr.

       Standard	regexp syntax:

       o   =~

       o   !~

FUNCTIONS
       The following functions are available to	be used	in expressions.	 See
       perldoc perlfunc	for details.

       o   sprintf

       o   substr (2 and 3 arg versions	only)

       o   lc

       o   lcfirst

       o   uc

       o   ucfirst

       o   length

       o   defined

       o   abs

       o   atan2

       o   cos

       o   exp

       o   hex

       o   int

       o   log

       o   oct

       o   rand

       o   sin

       o   sqrt

       o   srand

       All functions must be called using full parenthesis.  For example, this
       is a syntax error:

	  <TMPL_IF expr="defined foo">

       But this	is good:

	  <TMPL_IF expr="defined(foo)">

EXPR: DEFINING NEW FUNCTIONS
       You may also define functions of	your own.  See
       HTML::Template::PerlInterface for details.

AUTHOR
       Sam Tregar, sam@tregar.com (Main	text)

       I. Vlasenko, <viy@altlinux.org> (Pecularities of	HTML::Template::Pro)

LICENSE
	 HTML::Template	: A module for using HTML Templates with Perl
	 Copyright (C) 2000-2008 Sam Tregar (sam@tregar.com)

	 This module is	free software; you can redistribute it and/or modify it
	 under the terms of either:

	 a) the	GNU General Public License as published	by the Free Software
	 Foundation; either version 2, or (at your option) any later version,

	 or

	 b) the	"Artistic License" which comes with this module.

	 This program is distributed in	the hope that it will be useful,
	 but WITHOUT ANY WARRANTY; without even	the implied warranty of
	 MERCHANTABILITY or FITNESS FOR	A PARTICULAR PURPOSE.  See either
	 the GNU General Public	License	or the Artistic	License	for more details.

	 You should have received a copy of the	Artistic License with this
	 module, in the	file ARTISTIC.	If not,	I'll be	glad to	provide	one.

	 You should have received a copy of the	GNU General Public License
	 along with this program; if not, write	to the Free Software
	 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
	 USA

perl v5.32.1			  2010-09-06	     HTML::Template::SYNTAX(3)

NAME | SYNOPSIS | DESCRIPTION | TUTORIAL | MOTIVATION | THE TAGS | EXPR EXTENSION | BASIC SYNTAX | COMPARISON | MATHEMATICS | LOGIC | REGULAR EXPRESSION SUPPORT | FUNCTIONS | EXPR: DEFINING NEW FUNCTIONS | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::Template::SYNTAX&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help