1Template::Manual::VariaUbsleers(C3o)ntributed Perl DocumTeenmtpaltaitoen::Manual::Variables(3)
2
6 Template::Manual::Variables - Template variables and code bindings
7
9 Template Variables
10 A reference to a hash array may be passed as the second argument to the
12 process() method, containing definitions of template variables. The
13 VARIABLES (a.k.a. PRE_DEFINE) option can also be used to pre-define
14 variables for all templates processed by the object.
15 my $tt = Template->new({
17 VARIABLES => {
18 version => 3.14,
19 release => 'Sahara',
20 },
21 });
22 my $vars = {
24 serial_no => 271828,
25 };
26 $tt->process('myfile', $vars);
28 'myfile':
30 This is version [% version %] ([% release %]).
32 Serial number: [% serial_no %]
33 output:
35 This is version 3.14 (Sahara)
37 Serial number: 271828
38 Variable names may contain any alphanumeric characters or underscores.
40 They may be lower, upper or mixed case although the usual convention is
41 to use lower case. The case is significant however, and 'foo', 'Foo'
42 and 'FOO' are all different variables. Upper case variable names are
43 permitted, but not recommended due to a possible conflict with an
44 existing or future reserved word. As of version 2.00, these are:
45 GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
47 IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
48 USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
49 TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
50 CLEAR TO STEP AND OR NOT MOD DIV END
51 The variable values may be of virtually any Perl type, including simple
53 scalars, references to lists, hash arrays, subroutines or objects. The
54 Template Toolkit will automatically apply the correct procedure to
55 accessing these values as they are used in the template.
56 Example:
58 my $vars = {
60 article => 'The Third Shoe',
61 person => {
62 id => 314,
63 name => 'Mr. Blue',
64 email => 'blue@nowhere.org',
65 },
66 primes => [ 2, 3, 5, 7, 11, 13 ],
67 wizard => sub { return join(' ', 'Abracadabra!', @_) },
68 cgi => CGI->new('mode=submit&debug=1'),
69 };
70 template:
72 [% article %]
74 [% person.id %]: [% person.name %] <[% person.email %]>
76 [% primes.first %] - [% primes.last %], including [% primes.3 %]
78 [% primes.size %] prime numbers: [% primes.join(', ') %]
79 [% wizard %]
81 [% wizard('Hocus Pocus!') %]
82 [% cgi.param('mode') %]
84 output:
86 The Third Shoe
88 314: Mr. Blue <blue@nowhere.org>
90 2 - 13, including 7
92 6 prime numbers: 2, 3, 5, 7, 11, 13
93 Abracadabra!
95 Abracadabra! Hocus Pocus!
96 submit
98 Scalar Values
100 Regular scalar variables are accessed by simply specifying their name.
102 As these are just entries in the top-level variable hash they can be
103 considered special cases of hash array referencing as described below,
104 with the main namespace hash automatically implied.
105 [% article %]
107 Hash Array References
109 Members of hash arrays are accessed by specifying the hash reference
111 and key separated by the dot '.' operator.
112 my $vars = {
114 'home' => 'http://www.myserver.com/homepage.html',
115 'page' => {
116 'this' => 'mypage.html',
117 'next' => 'nextpage.html',
118 'prev' => 'prevpage.html',
119 },
120 };
121 template:
123 <a href="[% home %]">Home</a>
125 <a href="[% page.prev %]">Previous Page</a>
126 <a href="[% page.next %]">Next Page</a>
127 output:
129 <a href="http://www.myserver.com/homepage.html">Home</a>
131 <a href="prevpage.html">Previous Page</a>
132 <a href="nextpage.html">Next Page</a>
133 Any key in a hash which starts with a '_' or '.' character will be con‐
135 sidered private and cannot be evaluated or updated from within a tem‐
136 plate. The undefined value will be returned for any such variable
137 accessed which the Template Toolkit will silently ignore (unless the
138 DEBUG option is enabled).
139 my $vars = {
141 message => 'Hello World!',
142 _secret => "On the Internet, no-one knows you're a dog",
143 thing => {
144 public => 123,
145 _private => 456,
146 '.hidden' => 789,
147 },
148 };
149 template:
151 [% message %] # outputs "Hello World!"
153 [% _secret %] # no output
154 [% thing.public %] # outputs "123"
155 [% thing._private %] # no output
156 [% thing..hidden %] # ERROR: unexpected token (..)
157 You can disable this feature by setting the $Template::Stash::PRIVATE
159 package variable to a false value.
160 $Template::Stash::PRIVATE = undef; # now you can thing._private
162 To access a hash entry using a key stored in another variable, prefix
164 the key variable with '$' to have it interpolated before use (see
165 "Variable Interpolation").
166 [% pagename = 'next' %]
168 [% page.$pagename %] # same as [% page.next %]
169 When you assign to a variable that contains multiple namespace elements
171 (i.e. it has one or more '.' characters in the name), any hashes
172 required to represent intermediate namespaces will be created automati‐
173 cally. In this following example, the 'product' variable automatically
174 springs into life as a hash array unless otherwise defined.
175 [% product.id = 'XYZ-2000'
177 product.desc = 'Bogon Generator'
178 product.price = 666
179 %]
180 The [% product.id %] [% product.desc %]
182 costs $[% product.price %].00
183 output:
185 The XYZ-2000 Bogon Generator
187 costs $666.00
188 You can use Perl's familiar '{' ... '}' construct to explicitly create
190 a hash and assign it to a variable. Note that commas are optional
191 between key/value pairs and '=' can be used in place of '=>'.
192 [% product = {
194 id => 'XYZ-2000',
195 desc => 'Bogon Generator',
196 price => 666,
197 }
198 %]
199 List References
201 Items in lists are also accessed by use of the dot operator.
203 my $vars = {
205 'people' => [ 'Tom', 'Dick', 'Larry' ],
206 };
207 template:
209 [% people.0 %] # Tom
211 [% people.1 %] # Dick
212 [% people.2 %] # Larry
213 The FOREACH directive can be used to iterate through items in a list.
215 [% FOREACH person = people %]
217 Hello [% person %]
218 [% END %]
219 output:
221 Hello Tom
223 Hello Dick
224 Hello Larry
225 Lists can be constructed in-situ using the regular anonymous list '['
227 ... ']' construct. Commas between items are optional.
228 [% cols = [ 'red', 'green', 'blue' ] %]
230 [% FOREACH c = cols %]
232 ...
233 or:
235 [% FOREACH c = [ 'red', 'green', 'blue' ] %]
237 ...
238 You can also create simple numerical sequences using the familiar '..'
240 operator:
241 [% n = [ 1 .. 4 ] %] # n is [ 1, 2, 3, 4 ]
243 [% x = 4
245 y = 8
246 z = [x..y] # z is [ 4, 5, 6, 7, 8 ]
247 %]
248 Subroutines
250 Template variables can contain references to Perl subroutines. When
252 the variable is used, the Template Toolkit will automatically call the
253 subroutine, passing any additional arguments specified. The return
254 value from the subroutine is used as the variable value and inserted
255 into the document output.
256 my $vars = {
258 wizard => sub { return join(' ', 'Abracadabra!', @_) },
259 };
260 template:
262 [% wizard %] # Abracadabra!
264 [% wizard('Hocus Pocus!') %] # Abracadabra! Hocus Pocus!
265 Objects
267 Template variables can also contain references to Perl objects. Meth‐
269 ods are called using the dot operator to specify the method against the
270 object variable. Additional arguments can be specified as with subrou‐
271 tines.
272 use CGI;
274 ...
276 my $vars = {
278 # hard coded CGI params for purpose of example
279 cgi => CGI->new('mode=submit&debug=1'),
280 };
281 template:
283 [% FOREACH p = cgi.param %] # returns list of param keys
285 [% p %] => [% cgi.param(p) %] # fetch each param value
286 [% END %]
287 output:
289 mode => submit
291 debug => 1
292 Object methods can also be called as lvalues. That is, they can appear
294 on the left side of an assignment. The method will be called passing
295 the assigning value as an argument.
296 [% myobj.method = 10 %]
298 equivalent to:
300 [% myobj.method(10) %]
302 Parameters and Return Values
304 Subroutines and methods will be passed any arguments specified in the
306 template. Any template variables in the argument list will first be
307 evaluated and their resultant values passed to the code.
308 my $vars = {
310 mycode => sub { return 'received ' . join(', ', @_) },
311 };
312 template:
314 [% foo = 10 %]
316 [% mycode(foo, 20) %] # received 10, 20
317 Named parameters may also be specified. These are automatically col‐
319 lected into a single hash array which is passed by reference as the
320 last parameter to the sub-routine. Named parameters can be specified
321 using either '=>' or '=' and can appear anywhere in the argument list.
322 my $vars = {
324 myjoin => \&myjoin,
325 };
326 sub myjoin {
328 # look for hash ref as last argument
329 my $params = ref $_[-1] eq 'HASH' ? pop : { };
330 return join($params->{ joint } ⎪⎪ ' + ', @_);
331 }
332 template:
334 [% myjoin(10, 20, 30) %]
336 [% myjoin(10, 20, 30, joint = ' - ' %]
337 [% myjoin(joint => ' * ', 10, 20, 30 %]
338 output:
340 10 + 20 + 30
342 10 - 20 - 30
343 10 * 20 * 30
344 Parenthesised parameters may be added to any element of a variable, not
346 just those that are bound to code or object methods. At present,
347 parameters will be ignored if the variable isn't "callable" but are
348 supported for future extensions. Think of them as "hints" to that
349 variable, rather than just arguments passed to a function.
350 [% r = 'Romeo' %]
352 [% r(100, 99, s, t, v) %] # outputs "Romeo"
353 User code should return a value for the variable it represents. This
355 can be any of the Perl data types described above: a scalar, or refer‐
356 ence to a list, hash, subroutine or object. Where code returns a list
357 of multiple values the items will automatically be folded into a list
358 reference which can be accessed as per normal.
359 my $vars = {
361 # either is OK, first is recommended
362 items1 => sub { return [ 'foo', 'bar', 'baz' ] },
363 items2 => sub { return ( 'foo', 'bar', 'baz' ) },
364 };
365 template:
367 [% FOREACH i = items1 %]
369 ...
370 [% END %]
371 [% FOREACH i = items2 %]
373 ...
374 [% END %]
375 Error Handling
377 Errors can be reported from user code by calling die(). Errors raised
379 in this way are caught by the Template Toolkit and converted to struc‐
380 tured exceptions which can be handled from within the template. A ref‐
381 erence to the exception object is then available as the 'error' vari‐
382 able.
383 my $vars = {
385 barf => sub {
386 die "a sick error has occurred\n";
387 },
388 };
389 template:
391 [% TRY %]
393 [% barf %] # calls sub which throws error via die()
394 [% CATCH %]
395 [% error.info %] # outputs "a sick error has occurred\n"
396 [% END %]
397 Error messages thrown via die() are converted to exceptions of type
399 'undef'. Exceptions of user-defined types can be thrown by calling
400 die() with a reference to a Template::Exception object.
401 use Template::Exception;
403 ...
405 my $vars = {
407 login => sub {
408 ...
409 die Template::Exception->new('badpwd',
410 'password too silly');
411 },
412 };
413 template:
415 [% TRY %]
417 [% login %]
418 [% CATCH badpwd %]
419 Bad password: [% error.info %]
420 [% CATCH %]
421 Some other '[% error.type %]' error: [% error.info %]
422 [% END %]
423 The exception types 'stop' and 'return' are used to implement the STOP
425 and RETURN directives. Throwing an exception as:
426 die (Template::Exception->new('stop'));
428 has the same effect as the directive:
430 [% STOP %]
432 Subroutines and methods can also raise errors by returning a list or
434 reference to a list containing the undefined value (undef) followed by
435 an exception object or error message. This is supported for backwards
436 compatibility with version 1 but may be deprecated in some future ver‐
437 sion.
438 my $vars = {
440 # currently equivalent
441 barf => sub {
442 die "I'm sorry Dave, I can't do that";
443 },
444 yack => sub {
445 return (undef, "I'm sorry Dave, I can't do that");
446 },
447 };
448 Virtual Methods
450 The Template Toolkit implements a number of "virtual methods" which can
452 be applied to scalars, hashes or lists. For example:
453 [% mylist = [ 'foo', 'bar', 'baz' ] %]
455 [% newlist = mylist.sort %]
456 Here 'mylist' is a regular reference to a list, and 'sort' is a virtual
458 method that returns a new list of the items in sorted order. You can
459 chain multiple virtual methods together. For example:
460 [% mylist.sort.join(', ') %]
462 Here the 'join' virtual method is called to join the sorted list into a
464 single string, generating the following output:
465 bar, baz, foo
467 See Template::Manual::VMethods for details of all the virtual methods
469 available.
470 Variable Interpolation
472 The Template Toolkit uses '$' consistently to indicate that a variable
474 should be interpolated in position. Most frequently, you see this in
475 double-quoted strings:
476 [% fullname = "$honorific $firstname $surname" %]
478 Or embedded in plain text when the INTERPOLATE option is set:
480 Dear $honorific $firstname $surname,
482 The same rules apply within directives. If a variable is prefixed with
484 a '$' then it is replaced with its value before being used. The most
485 common use is to retrieve an element from a hash where the key is
486 stored in a variable.
487 [% uid = 'abw' %]
489 [% userlist.$uid %] # same as 'userlist.abw'
490 Curly braces can be used to delimit interpolated variable names where
492 necessary.
493 [% userlist.${me.id}.name %]
495 Directives such as INCLUDE, PROCESS, etc., that accept a template name
497 as the first argument, will automatically quote it for convenience.
498 [% INCLUDE foo/bar.txt %]
500 equivalent to:
502 [% INCLUDE "foo/bar.txt" %]
504 To INCLUDE a template whose name is stored in a variable, simply prefix
506 the variable name with '$' to have it interpolated.
507 [% myfile = 'header' %]
509 [% INCLUDE $myfile %]
510 equivalent to:
512 [% INCLUDE header %]
514 Note also that a variable containing a reference to a Template::Docu‐
516 ment object can also be processed in this way.
517 my $vars = {
519 header => Template::Document->new({ ... }),
520 };
521 template:
523 [% INCLUDE $header %]
525 Local and Global Variables
527 Any simple variables that you create, or any changes you make to exist‐
529 ing variables, will only persist while the template is being processed.
530 The top-level variable hash is copied before processing begins and any
531 changes to variables are made in this copy, leaving the original
532 intact. The same thing happens when you INCLUDE another template. The
533 current namespace hash is cloned to prevent any variable changes made
534 in the included template from interfering with existing variables. The
535 PROCESS option bypasses the localisation step altogether making it
536 slightly faster, but requiring greater attention to the possibility of
537 side effects caused by creating or changing any variables within the
538 processed template.
539 [% BLOCK change_name %]
541 [% name = 'bar' %]
542 [% END %]
543 [% name = 'foo' %]
545 [% INCLUDE change_name %]
546 [% name %] # foo
547 [% PROCESS change_name %]
548 [% name %] # bar
549 Dotted compound variables behave slightly differently because the
551 localisation process is only skin deep. The current variable namespace
552 hash is copied, but no attempt is made to perform a deep-copy of other
553 structures within it (hashes, arrays, objects, etc). A variable refer‐
554 encing a hash, for example, will be copied to create a new reference
555 but which points to the same hash. Thus, the general rule is that sim‐
556 ple variables (undotted variables) are localised, but existing complex
557 structures (dotted variables) are not.
558 [% BLOCK all_change %]
560 [% x = 20 %] # changes copy
561 [% y.z = 'zulu' %] # changes original
562 [% END %]
563 [% x = 10
565 y = { z => 'zebra' }
566 %]
567 [% INCLUDE all_change %]
568 [% x %] # still '10'
569 [% y.z %] # now 'zulu'
570 If you create a complex structure such as a hash or list reference
572 within a local template context then it will cease to exist when the
573 template is finished processing.
574 [% BLOCK new_stuff %]
576 [% # define a new 'y' hash array in local context
577 y = { z => 'zulu' }
578 %]
579 [% END %]
580 [% x = 10 %]
582 [% INCLUDE new_stuff %]
583 [% x %] # outputs '10'
584 [% y %] # nothing, y is undefined
585 Similarly, if you update an element of a compound variable which
587 doesn't already exists then a hash will be created automatically and
588 deleted again at the end of the block.
589 [% BLOCK new_stuff %]
591 [% y.z = 'zulu' %]
592 [% END %]
593 However, if the hash does already exist then you will modify the origi‐
595 nal with permanent effect. To avoid potential confusion, it is recom‐
596 mended that you don't update elements of complex variables from within
597 blocks or templates included by another.
598 If you want to create or update truly global variables then you can use
600 the 'global' namespace. This is a hash array automatically created in
601 the top-level namespace which all templates, localised or otherwise see
602 the same reference to. Changes made to variables within this hash are
603 visible across all templates.
604 [% global.version = 123 %]
606 Compile Time Constant Folding
608 In addition to variables that get resolved each time a template is pro‐
610 cessed, you can also define variables that get resolved just once when
611 the template is compiled. This generally results in templates process‐
612 ing faster because there is less work to be done.
613 To define compile-time constants, specify a CONSTANTS hash as a con‐
615 structor item as per VARIABLES. The CONSTANTS hash can contain any
616 kind of complex, nested, or dynamic data structures, just like regular
617 variables.
618 my $tt = Template->new({
620 CONSTANTS => {
621 version => 3.14,
622 release => 'skyrocket',
623 col => {
624 back => '#ffffff',
625 fore => '#000000',
626 },
627 myobj => My::Object->new(),
628 mysub => sub { ... },
629 joint => ', ',
630 },
631 });
632 Within a template, you access these variables using the 'constants'
634 namespace prefix.
635 Version [% constants.version %] ([% constants.release %])
637 Background: [% constants.col.back %]
639 When the template is compiled, these variable references are replaced
641 with the corresponding value. No further variable lookup is then
642 required when the template is processed.
643 You can call subroutines, object methods, and even virtual methods on
645 constant variables.
646 [% constants.mysub(10, 20) %]
648 [% constants.myobj(30, 40) %]
649 [% constants.col.keys.sort.join(', ') %]
650 One important proviso is that any arguments you pass to subroutines or
652 methods must also be literal values or compile time constants.
653 For example, these are both fine:
655 # literal argument
657 [% constants.col.keys.sort.join(', ') %]
658 # constant argument
660 [% constants.col.keys.sort.join(constants.joint) %]
661 But this next example will raise an error at parse time because 'joint'
663 is a runtime variable and cannot be determined at compile time.
664 # ERROR: runtime variable argument!
666 [% constants.col.keys.sort.join(joint) %]
667 The CONSTANTS_NAMESPACE option can be used to provide a different
669 namespace prefix for constant variables. For example:
670 my $tt = Template->new({
672 CONSTANTS => {
673 version => 3.14,
674 # ...etc...
675 },
676 CONSTANTS_NAMESPACE => 'const',
677 });
678 Constants would then be referenced in templates as:
680 [% const.version %]
682 Special Variables
684 A number of special variables are automatically defined by the Template
686 Toolkit.
687 template
689 The 'template' variable contains a reference to the main template
690 being processed, in the form of a Template::Document object. This
691 variable is correctly defined within PRE_PROCESS, PROCESS and
692 POST_PROCESS templates, allowing standard headers, footers, etc.,
693 to access metadata items from the main template. The 'name' and
694 'modtime' metadata items are automatically provided, giving the
695 template name and modification time in seconds since the epoch.
696 Note that the 'template' variable always references the top-level
698 template, even when processing other template components via
699 INCLUDE, PROCESS, etc.
700 component
702 The 'component' variable is like 'template' but always contains a
703 reference to the current, innermost template component being pro‐
704 cessed. In the main template, the 'template' and 'component' vari‐
705 able will reference the same Template::Document object. In any
706 other template component called from the main template, the 'tem‐
707 plate' variable will remain unchanged, but 'component' will contain
708 a new reference to the current component.
709 This example should demonstrate the difference:
711 $template->process('foo')
713 ⎪⎪ die $template->error(), "\n";
714 'foo':
716 [% template.name %] # foo
718 [% component.name %] # foo
719 [% PROCESS footer %]
720 'footer':
722 [% template.name %] # foo
724 [% component.name %] # footer
725 Additionally, the 'component' variable has two special fields:
727 'caller' and 'callers'. 'caller' contains the name of the template
728 that called the current template (or undef if the values of 'tem‐
729 plate' and 'component' are the same). 'callers' contains a refer‐
730 ence to a list of all the templates that have been called on the
731 road to calling the current component template (like a call stack),
732 with the outer-most template first.
733 Here's an example:
735 'outer.tt2':
737 [% component.name %] # 'outer.tt2'
739 [% component.caller %] # undef
740 [% component.callers %] # undef
741 [% PROCESS 'middle.tt2' %]
742 'middle.tt2':
744 [% component.name %] # 'middle.tt2'
746 [% component.caller %] # 'outer.tt2'
747 [% component.callers %] # [ 'outer.tt2' ]
748 [% PROCESS 'inner.tt2' %]
749 'inner.tt2':
751 [% component.name %] # 'inner.tt2'
753 [% component.caller %] # 'middle.tt2'
754 [% component.callers %] # [ 'outer.tt2', 'middle.tt2' ]
755 loop
757 Within a FOREACH loop, the 'loop' variable references the Tem‐
758 plate::Iterator object responsible for controlling the loop.
759 [% FOREACH item = [ 'foo', 'bar', 'baz' ] -%]
761 [% "Items:\n" IF loop.first -%]
762 [% loop.count %]/[% loop.size %]: [% item %]
763 [% END %]
764 error
766 Within a CATCH block, the 'error' variable contains a reference to
767 the Template::Exception object thrown from within the TRY block.
768 The 'type' and 'info' methods can be called or the variable itself
769 can be printed for automatic stringification into a message of the
770 form "$type error - $info". See Template::Exception for further
771 details.
772 [% TRY %]
774 ...
775 [% CATCH %]
776 [% error %]
777 [% END %]
778 content
780 The WRAPPER method captures the output from a template block and
781 then includes a named template, passing the captured output as the
782 'content' variable.
783 [% WRAPPER box %]
785 Be not afeard; the isle is full of noises,
786 Sounds and sweet airs, that give delight and hurt not.
787 [% END %]
788 [% BLOCK box %]
790 <table border=1>
791 <tr>
792 <td>
793 [% content %]
794 </td>
795 </tr>
796 </table>
797 [% END %]
798 Compound Variables
800 Compound 'dotted' variables may contain any number of separate ele‐
802 ments. Each element may evaluate to any of the permitted variable
803 types and the processor will then correctly use this value to evaluate
804 the rest of the variable. Arguments may be passed to any of the inter‐
805 mediate elements.
806 [% myorg.people.sort('surname').first.fullname %]
808 Intermediate variables may be used and will behave entirely as
810 expected.
811 [% sorted = myorg.people.sort('surname') %]
813 [% sorted.first.fullname %]
814 This simplified dotted notation has the benefit of hiding the implemen‐
816 tation details of your data. For example, you could implement a data
817 structure as a hash array one day and then change it to an object the
818 next without requiring any change to the templates.
819
821 Andy Wardley <abw@wardley.org>
822 <http://wardley.org/⎪http://wardley.org/>
824
826 Template Toolkit version 2.18, released on 09 February 2007.
827
829 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
830 This module is free software; you can redistribute it and/or modify it
832 under the same terms as Perl itself.
833perl v5.8.8 2007-02-09 Template::Manual::Variables(3)