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

FreeBSD Manual Pages

  
 
  

home | help
Template::Manual::VariUsersContributed Perl DocuTemplate::Manual::Variables(3)

NAME
       Template::Manual::Variables - Template variables	and code bindings

Template Variables
       A reference to a	hash array may be passed as the	second argument	to the
       process() method, containing definitions	of template variables. The
       "VARIABLES" (a.k.a. "PRE_DEFINE") option	can also be used to pre-define
       variables for all templates processed by	the object.

	   my $tt = Template->new({
	       VARIABLES => {
		   version => 3.14,
		   release => 'Sahara',
	       },
	   });

	   my $vars = {
	       serial_no => 271828,
	   };

	   $tt->process('myfile', $vars);

       myfile template:

	   This	is version [% version %] ([% release %]).
	   Serial number: [% serial_no %]

       Generated Output:

	   This	is version 3.14	(Sahara)
	   Serial number: 271828

       Variable	names may contain any alphanumeric characters or underscores.
       They may	be lower, upper	or mixed case although the usual convention is
       to use lower case. The case is significant however, and '"foo"',
       '"Foo"' and '"FOO"' are all different variables.	Upper case variable
       names are permitted, but	not recommended	due to a possible conflict
       with an existing	or future reserved word.  As of	version	2.00, these
       are:

	   GET CALL SET	DEFAULT	INSERT INCLUDE PROCESS WRAPPER
	   IF UNLESS ELSE ELSIF	FOR FOREACH WHILE SWITCH CASE
	   USE PLUGIN FILTER MACRO PERL	RAWPERL	BLOCK META
	   TRY THROW CATCH FINAL NEXT LAST BREAK RETURN	STOP
	   CLEAR TO STEP AND OR	NOT MOD	DIV END

       The variable values may be of virtually any Perl	type, including	simple
       scalars,	references to lists, hash arrays, subroutines or objects.  The
       Template	Toolkit	will automatically apply the correct procedure to
       accessing these values as they are used in the template.

       Example data:

	   my $vars = {
	       article => 'The Third Shoe',
	       person  => {
		   id	 => 314,
		   name	 => 'Mr. Blue',
		   email => 'blue@nowhere.org',
	       },
	       primes  => [ 2, 3, 5, 7,	11, 13 ],
	       wizard  => sub {	return join(' ', 'Abracadabra!', @_) },
	       cgi     => CGI->new('mode=submit&debug=1'),
	   };

       Example template:

	   [% article %]

	   [% person.id	%]: [% person.name %] <[% person.email %]>

	   [% primes.first %] -	[% primes.last %], including [%	primes.3 %]
	   [% primes.size %] prime numbers: [% primes.join(', ') %]

	   [% wizard %]
	   [% wizard('Hocus Pocus!') %]

	   [% cgi.param('mode')	%]

       Generated output:

	   The Third Shoe

	   314:	Mr. Blue <blue@nowhere.org>

	   2 - 13, including 7
	   6 prime numbers: 2, 3, 5, 7,	11, 13

	   Abracadabra!
	   Abracadabra!	Hocus Pocus!

	   submit

   Scalar Values
       Regular scalar variables	are accessed by	simply specifying their	name.
       As these	are just entries in the	top-level variable hash	they can be
       considered special cases	of hash	array referencing as described below,
       with the	main namespace hash automatically implied.

	   [% article %]

   Hash	Array References
       Members of hash arrays are accessed by specifying the hash reference
       and key separated by the	dot '"."' operator.

       Example data:

	   my $vars = {
	       'home' => 'http://www.myserver.com/homepage.html',
	       'page' => {
		   'this' => 'mypage.html',
		   'next' => 'nextpage.html',
		   'prev' => 'prevpage.html',
	       },
	   };

       Example template:

	   <a href="[% home %]">Home</a>
	   <a href="[% page.prev %]">Previous Page</a>
	   <a href="[% page.next %]">Next Page</a>

       Generated output:

	   <a href="http://www.myserver.com/homepage.html">Home</a>
	   <a href="prevpage.html">Previous Page</a>
	   <a href="nextpage.html">Next	Page</a>

       Any key in a hash which starts with a '"_"' or '"."' character will be
       considered private and cannot be	evaluated or updated from within a
       template.  The undefined	value will be returned for any such variable
       accessed	which the Template Toolkit will	silently ignore	(unless	the
       "DEBUG" option is enabled).

       Example data:

	   my $vars = {
	       message => 'Hello World!',
	       _secret => "On the Internet, no-one knows you're	a dog",
	       thing   => {
		   public    =>	123,
		   _private  =>	456,
		   '.hidden' =>	789,
	       },
	   };

       Example template:

	   [% message %]	   # outputs "Hello World!"
	   [% _secret %]	   # no	output
	   [% thing.public %]	   # outputs "123"
	   [% thing._private %]	   # no	output
	   [% thing..hidden %]	   # ERROR: unexpected token (..)

       You can disable this feature by setting the $Template::Stash::PRIVATE
       package variable	to a false value.

	   $Template::Stash::PRIVATE = undef;	# now you can thing._private

       To access a hash	entry using a key stored in another variable, prefix
       the key variable	with '"$"' to have it interpolated before use (see
       "Variable Interpolation").

	   [% pagename = 'next'	%]
	   [% page.$pagename %]	      #	same as	[% page.next %]

       When you	assign to a variable that contains multiple namespace elements
       (i.e. it	has one	or more	'"."' characters in the	name), any hashes
       required	to represent intermediate namespaces will be created
       automatically.  In this following example, the "product"	variable
       automatically springs into life as a hash array unless otherwise
       defined.

	   [% product.id    = 'XYZ-2000'
	      product.desc  = 'Bogon Generator'
	      product.price = 666
	   %]

	   The [% product.id %]	[% product.desc	%]
	   costs $[% product.price %].00

       Generated output:

	   The XYZ-2000	Bogon Generator
	   costs $666.00

       You can use Perl's familiar "{" ... "}" construct to explicitly create
       a hash and assign it to a variable.  Note that commas are optional
       between key/value pairs and "=" can be used in place of "=>".

	   # minimal TT	style
	   [% product =	{
		id    =	'XYZ-2000'
		desc  =	'Bogon Generator'
		price =	666
	      }
	   %]

	   # perl style
	   [% product =	{
		id    => 'XYZ-2000',
		desc  => 'Bogon	Generator',
		price => 666,
	      }
	   %]

   List	References
       Items in	lists are also accessed	by use of the dot operator.

       Example data:

	   my $vars = {
	       people => [ 'Tom', 'Dick', 'Larry' ],
	   };

       Example template:

	   [% people.0 %]	   # Tom
	   [% people.1 %]	   # Dick
	   [% people.2 %]	   # Larry

       The "FOREACH" directive can be used to iterate through items in a list.

	   [% FOREACH person IN	people %]
	   Hello [% person %]
	   [% END %]

       Generated output:

	   Hello Tom
	   Hello Dick
	   Hello Larry

       Lists can be constructed	in-situ	using the regular anonymous list "["
       ... "]" construct.  Commas between items	are optional.

	   [% cols = [ 'red', 'green', 'blue' ]	%]

	   [% FOREACH c	IN cols	%]
	      [% c %]
	   [% END %]

       or:

	   [% FOREACH c	IN [ 'red', 'green', 'blue' ] %]
	      [% c %]
	   [% END %]

       You can also create simple numerical sequences using the	".." range
       operator:

	   [% n	= [ 1 .. 4 ] %]	   # n is [ 1, 2, 3, 4 ]

	   [% x	= 4
	      y	= 8
	      z	= [x..y]	   # z is [ 4, 5, 6, 7,	8 ]
	   %]

   Subroutines
       Template	variables can contain references to Perl subroutines.  When
       the variable is used, the Template Toolkit will automatically call the
       subroutine, passing any additional arguments specified.	The return
       value from the subroutine is used as the	variable value and inserted
       into the	document output.

	   my $vars = {
	       wizard  => sub {	return join(' ', 'Abracadabra!', @_) },
	   };

       Example template:

	   [% wizard %]			   # Abracadabra!
	   [% wizard('Hocus Pocus!') %]	   # Abracadabra! Hocus	Pocus!

   Objects
       Template	variables can also contain references to Perl objects.
       Methods are called using	the dot	operator to specify the	method against
       the object variable.  Additional	arguments can be specified as with
       subroutines.

	   use CGI;

	   my $vars = {
	       # hard coded CGI	params for purpose of example
	       cgi  => CGI->new('mode=submit&debug=1'),
	   };

       Example template:

	   [% FOREACH p	IN cgi.param %]	    # returns list of param keys
	   [% p	%] => [% cgi.param(p) %]   # fetch each	param value
	   [% END %]

       Generated output:

	   mode	=> submit
	   debug => 1

       Object methods can also be called as lvalues.  That is, they can	appear
       on the left side	of an assignment.  The method will be called passing
       the assigning value as an argument.

	   [% myobj.method = 10	%]

       equivalent to:

	   [% myobj.method(10) %]

   Passing Parameters and Returning Values
       Subroutines and methods will be passed any arguments specified in the
       template.  Any template variables in the	argument list will first be
       evaluated and their resultant values passed to the code.

	   my $vars = {
	       mycode => sub { return 'received	' . join(', ', @_) },
	   };

       template:

	   [% foo = 10 %]
	   [% mycode(foo, 20) %]       # received 10, 20

       Named parameters	may also be specified.	These are automatically
       collected into a	single hash array which	is passed by reference as the
       last parameter to the sub-routine.  Named parameters can	be specified
       using either "=>" or "="	and can	appear anywhere	in the argument	list.

	   my $vars = {
	       myjoin => \&myjoin,
	   };

	   sub myjoin {
	       # look for hash ref as last argument
	       my $params = ref	$_[-1] eq 'HASH' ? pop : { };
	       return join($params->{ joint } || ' + ',	@_);
	   }

       Example template:

	   [% myjoin(10, 20, 30) %]
	   [% myjoin(10, 20, 30, joint = ' - ' %]
	   [% myjoin(joint => '	* ', 10, 20, 30	%]

       Generated output:

	   10 +	20 + 30
	   10 -	20 - 30
	   10 *	20 * 30

       Parenthesised parameters	may be added to	any element of a variable, not
       just those that are bound to code or object methods.  At	present,
       parameters will be ignored if the variable isn't	"callable" but are
       supported for future extensions.	 Think of them as "hints" to that
       variable, rather	than just arguments passed to a	function.

	   [% r	= 'Romeo' %]
	   [% r(100, 99, s, t, v) %]	   # outputs "Romeo"

       User code should	return a value for the variable	it represents. This
       can be any of the Perl data types described above: a scalar, or
       reference to a list, hash, subroutine or	object.	 Where code returns a
       list of multiple	values the items will automatically be folded into a
       list reference which can	be accessed as per normal.

	   my $vars = {
	       # either	is OK, first is	recommended
	       items1 => sub { return [	'foo', 'bar', 'baz' ] },
	       items2 => sub { return (	'foo', 'bar', 'baz' ) },
	   };

       Example template:

	   [% FOREACH i	IN items1 %]
	      ...
	   [% END %]

	   [% FOREACH i	IN items2 %]
	      ...
	   [% END %]

   Error Handling
       Errors can be reported from user	code by	calling	"die()".  Errors
       raised in this way are caught by	the Template Toolkit and converted to
       structured exceptions which can be handled from within the template.  A
       reference to the	exception object is then available as the "error"
       variable.

	   my $vars = {
	       barf => sub {
		   die "a sick error has occurred\n";
	       },
	   };

       Example template:

	   [% TRY %]
	      [% barf %]       # calls sub which throws	error via die()
	   [% CATCH %]
	      [% error.info %]	   # outputs "a	sick error has occurred\n"
	   [% END %]

       Error messages thrown via "die()" are converted to exceptions of	type
       "undef" (the literal string "undef" rather than the undefined value).
       Exceptions of user-defined types	can be thrown by calling "die()" with
       a reference to a	Template::Exception object.

	   use Template::Exception;

	   my $vars = {
	       login =>	sub {
		   ...do something...
		   die Template::Exception->new( badpwd	=> 'password too silly'	);
	       },
	   };

       Example template:

	   [% TRY %]
	      [% login %]
	   [% CATCH badpwd %]
	      Bad password: [% error.info %]
	   [% CATCH %]
	      Some other '[% error.type	%]' error: [% error.info %]
	   [% END %]

       The exception types "stop" and "return" are used	to implement the
       "STOP" and "RETURN" directives.	Throwing an exception as:

	   die (Template::Exception->new('stop'));

       has the same effect as the directive:

	   [% STOP %]

Virtual	Methods
       The Template Toolkit implements a number	of "virtual methods" which can
       be applied to scalars, hashes or	lists.	For example:

	   [% mylist = [ 'foo',	'bar', 'baz' ] %]
	   [% newlist =	mylist.sort %]

       Here "mylist" is	a regular reference to a list, and 'sort' is a virtual
       method that returns a new list of the items in sorted order.  You can
       chain multiple virtual methods together.	 For example:

	   [% mylist.sort.join(', ') %]

       Here the	"join" virtual method is called	to join	the sorted list	into a
       single string, generating the following output:

	   bar,	baz, foo

       See Template::Manual::VMethods for details of all the virtual methods
       available.

Variable Interpolation
       The Template Toolkit uses "$" consistently to indicate that a variable
       should be interpolated in position.  Most frequently, you see this in
       double-quoted strings:

	   [% fullname = "$honorific $firstname	$surname" %]

       Or embedded in plain text when the "INTERPOLATE"	option is set:

	   Dear	$honorific $firstname $surname,

       The same	rules apply within directives.	If a variable is prefixed with
       a "$" then it is	replaced with its value	before being used.  The	most
       common use is to	retrieve an element from a hash	where the key is
       stored in a variable.

	   [% uid = 'abw' %]
	   [% users.$uid %]	    # same as 'users.abw'

       Curly braces can	be used	to delimit interpolated	variable names where
       necessary.

	   [% users.${me.id}.name %]

       Directives such as "INCLUDE", "PROCESS",	etc., that accept a template
       name as the first argument, will	automatically quote it for
       convenience.

	   [% INCLUDE foo/bar.txt %]

       The above example is equivalent to:

	   [% INCLUDE "foo/bar.txt" %]

       To "INCLUDE" a template whose name is stored in a variable, simply
       prefix the variable name	with "$" to have it interpolated.

	   [% myfile = 'header'	%]
	   [% INCLUDE $myfile %]

       This is equivalent to:

	   [% INCLUDE header %]

       Note also that a	variable containing a reference	to a
       Template::Document object can also be processed in this way.

	   my $vars = {
	       header => Template::Document->new({ ... }),
	   };

       Example template:

	   [% INCLUDE $header %]

Local and Global Variables
       Any simple variables that you create, or	any changes you	make to
       existing	variables, will	only persist while the template	is being
       processed.  The top-level variable hash is copied before	processing
       begins and any changes to variables are made in this copy, leaving the
       original	intact.

       The same	thing happens when you "INCLUDE" another template. The current
       namespace hash is cloned	to prevent any variable	changes	made in	the
       included	template from interfering with existing	variables. The
       "PROCESS" option	bypasses the localisation step altogether making it
       slightly	faster,	but requiring greater attention	to the possibility of
       side effects caused by creating or changing any variables within	the
       processed template.

	   [% BLOCK change_name	%]
	      [% name =	'bar' %]
	   [% END %]

	   [% name = 'foo' %]
	   [% INCLUDE change_name %]
	   [% name %]		   # foo
	   [% PROCESS change_name %]
	   [% name %]		   # bar

       Dotted compound variables behave	slightly differently because the
       localisation process is only skin deep.	The current variable namespace
       hash is copied, but no attempt is made to perform a deep-copy of	other
       structures within it (hashes, arrays, objects, etc).  A variable
       referencing a hash, for example,	will be	copied to create a new
       reference but which points to the same hash.  Thus, the general rule is
       that simple variables (undotted variables) are localised, but existing
       complex structures (dotted variables) are not.

	   [% BLOCK all_change %]
	      [% x = 20	%]	   # changes copy
	      [% y.z = 'zulu' %]       # changes original
	   [% END %]

	   [% x	= 10
	      y	= { z => 'zebra' }
	   %]
	   [% INCLUDE all_change %]
	   [% x	%]	       # still '10'
	   [% y.z %]		   # now 'zulu'

       If you create a complex structure such as a hash	or list	reference
       within a	local template context then it will cease to exist when	the
       template	is finished processing.

	   [% BLOCK new_stuff %]
	      [% # define a new	'y' hash array in local	context
		 y = { z => 'zulu' }
	      %]
	   [% END %]

	   [% x	= 10 %]
	   [% INCLUDE new_stuff	%]
	   [% x	%]	       # outputs '10'
	   [% y	%]	       # nothing, y is undefined

       Similarly, if you update	an element of a	compound variable which
       doesn't already exists then a hash will be created automatically	and
       deleted again at	the end	of the block.

	   [% BLOCK new_stuff %]
	      [% y.z = 'zulu' %]
	   [% END %]

       However,	if the hash does already exist then you	will modify the
       original	with permanent effect.	To avoid potential confusion, it is
       recommended that	you don't update elements of complex variables from
       within blocks or	templates included by another.

       If you want to create or	update truly global variables then you can use
       the 'global' namespace.	This is	a hash array automatically created in
       the top-level namespace which all templates, localised or otherwise see
       the same	reference to.  Changes made to variables within	this hash are
       visible across all templates.

	   [% global.version = 123 %]

Compile	Time Constant Folding
       In addition to variables	that get resolved each time a template is
       processed, you can also define variables	that get resolved just once
       when the	template is compiled.  This generally results in templates
       processing faster because there is less work to be done.

       To define compile-time constants, specify a "CONSTANTS" hash as a
       constructor item	as per "VARIABLES".  The "CONSTANTS" hash can contain
       any kind	of complex, nested, or dynamic data structures,	just like
       regular variables.

	   my $tt = Template->new({
	       CONSTANTS => {
		   version => 3.14,
		   release => 'skyrocket',
		   col	   => {
		       back => '#ffffff',
		       fore => '#000000',
		   },
		   myobj => My::Object->new(),
		   mysub => sub	{ ... },
		   joint => ', ',
	       },
	   });

       Within a	template, you access these variables using the "constants"
       namespace prefix.

	   Version [% constants.version	%] ([% constants.release %])
	   Background: [% constants.col.back %]

       When the	template is compiled, these variable references	are replaced
       with the	corresponding value.  No further variable lookup is then
       required	when the template is processed.

       You can call subroutines, object	methods, and even virtual methods on
       constant	variables.

	   [% constants.mysub(10, 20) %]
	   [% constants.myobj(30, 40) %]
	   [% constants.col.keys.sort.join(', ') %]

       One important proviso is	that any arguments you pass to subroutines or
       methods must also be literal values or compile time constants.

       For example, these are both fine:

	   # literal argument
	   [% constants.col.keys.sort.join(', ') %]

	   # constant argument
	   [% constants.col.keys.sort.join(constants.joint) %]

       But this	next example will raise	an error at parse time because "joint"
       is a runtime variable and cannot	be determined at compile time.

	   # ERROR: runtime variable argument!
	   [% constants.col.keys.sort.join(joint) %]

       The "CONSTANTS_NAMESPACE" option	can be used to provide a different
       namespace prefix	for constant variables.	 For example:

	   my $tt = Template->new({
	       CONSTANTS => {
		   version => 3.14,
		   # ...etc...
	       },
	       CONSTANTS_NAMESPACE => 'const',
	   });

       Constants would then be referenced in templates as:

	   [% const.version %]

Special	Variables
       A number	of special variables are automatically defined by the Template
       Toolkit.

   template
       The "template" variable contains	a reference to the main	template being
       processed, in the form of a Template::Document object. This variable is
       correctly defined within	"PRE_PROCESS", "PROCESS" and "POST_PROCESS"
       templates, allowing standard headers, footers, etc., to access metadata
       items from the main template. The "name"	and "modtime" metadata items
       are automatically provided, giving the template name and	modification
       time in seconds since the epoch.

       Note that the "template"	variable always	references the top-level
       template, even when processing other template components	via "INCLUDE",
       "PROCESS", etc.

   component
       The "component" variable	is like	"template" but always contains a
       reference to the	current, innermost template component being processed.
       In the main template, the "template" and	"component" variable will
       reference the same Template::Document object.  In any other template
       component called	from the main template,	the "template" variable	will
       remain unchanged, but "component" will contain a	new reference to the
       current component.

       This example should demonstrate the difference:

	   $template->process('foo')
	       || die $template->error(), "\n";

       foo template:

	   [% template.name %]	       # foo
	   [% component.name %]	       # foo
	   [% PROCESS footer %]

       footer template:

	   [% template.name %]	       # foo
	   [% component.name %]	       # footer

       Additionally, the "component" variable has two special fields: "caller"
       and "callers".  "caller"	contains the name of the template that called
       the current template (or	undef if the values of "template" and
       "component" are the same).  "callers" contains a	reference to a list of
       all the templates that have been	called on the road to calling the
       current component template (like	a call stack), with the	outer-most
       template	first.

       Here's an example:

       outer.tt2 template:

	   [% component.name %]	       # 'outer.tt2'
	   [% component.caller %]      # undef
	   [% component.callers	%]     # undef
	   [% PROCESS 'middle.tt2' %]

       middle.tt2 template:

	   [% component.name %]	       # 'middle.tt2'
	   [% component.caller %]      # 'outer.tt2'
	   [% component.callers	%]     # [ 'outer.tt2' ]
	   [% PROCESS 'inner.tt2' %]

       inner.tt2 template:

	   [% component.name %]	       # 'inner.tt2'
	   [% component.caller %]      # 'middle.tt2'
	   [% component.callers	%]     # [ 'outer.tt2',	'middle.tt2' ]

   loop
       Within a	"FOREACH" loop,	the "loop" variable references the
       Template::Iterator object responsible for controlling the loop.

	   [% FOREACH item = [ 'foo', 'bar', 'baz' ] -%]
	      [% "Items:\n" IF loop.first -%]
	      [% loop.count %]/[% loop.size %]:	[% item	%]
	   [% END %]

   error
       Within a	"CATCH"	block, the "error" variable contains a reference to
       the Template::Exception object thrown from within the "TRY" block.  The
       "type" and "info" methods can be	called or the variable itself can be
       printed for automatic stringification into a message of the form
       ""$type error - $info"".	 See Template::Exception for further details.

	   [% TRY %]
	      ...
	   [% CATCH %]
	      [% error %]
	   [% END %]

   content
       The "WRAPPER" method captures the output	from a template	block and then
       includes	a named	template, passing the captured output as the 'content'
       variable.

	   [% WRAPPER box %]
	   Be not afeard; the isle is full of noises,
	   Sounds and sweet airs, that give delight and	hurt not.
	   [% END %]

	   [% BLOCK box	%]
	   <blockquote class="prose">
	     [%	content	%]
	   </blockquote>
	   [% END %]

Compound Variables
       Compound	'dotted' variables may contain any number of separate
       elements.  Each element may evaluate to any of the permitted variable
       types and the processor will then correctly use this value to evaluate
       the rest	of the variable.  Arguments may	be passed to any of the
       intermediate elements.

	   [% myorg.people.sort('surname').first.fullname %]

       Intermediate variables may be used and will behave entirely as
       expected.

	   [% sorted = myorg.people.sort('surname') %]
	   [% sorted.first.fullname %]

       This simplified dotted notation has the benefit of hiding the
       implementation details of your data.  For example, you could implement
       a data structure	as a hash array	one day	and then change	it to an
       object the next without requiring any change to the templates.

perl v5.32.1			  2020-03-30	Template::Manual::Variables(3)

NAME | Template Variables | Virtual Methods | Variable Interpolation | Local and Global Variables | Compile Time Constant Folding | Special Variables | Compound Variables

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

home | help