1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Template::Manual::Variables 3"
132 .TH Template::Manual::Variables 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
134 Template::Manual::Variables \- Template variables and code bindings
135 .SH "Template Variables"
136 .IX Header "Template Variables"
137 A reference to a hash array may be passed as the second argument to the
138 \&\fIprocess()\fR method, containing definitions of template
139 variables. The \f(CW\*(C`VARIABLES\*(C'\fR (a.k.a. \f(CW\*(C`PRE_DEFINE\*(C'\fR) option can also be used to
140 pre-define variables for all templates processed by the object.
143 \& my $tt = Template\->new({
146 \& release => 'Sahara',
153 \& serial_no => 271828,
158 \& $tt\->process('myfile', $vars);
161 \&\fImyfile\fR template:
164 \& This is version [% version %] ([% release %]).
165 \& Serial number: [% serial_no %]
171 \& This is version 3.14 (Sahara)
172 \& Serial number: 271828
175 Variable names may contain any alphanumeric characters or underscores. They
176 may be lower, upper or mixed case although the usual convention is to use
177 lower case. The case \fIis\fR significant however, and '\f(CW\*(C`foo\*(C'\fR', '\f(CW\*(C`Foo\*(C'\fR' and
178 \&'\f(CW\*(C`FOO\*(C'\fR' are all different variables. Upper case variable names are permitted,
179 but not recommended due to a possible conflict with an existing or future
180 reserved word. As of version 2.00, these are:
183 \& GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
184 \& IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
185 \& USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
186 \& TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
187 \& CLEAR TO STEP AND OR NOT MOD DIV END
190 The variable values may be of virtually any Perl type, including
191 simple scalars, references to lists, hash arrays, subroutines or
192 objects. The Template Toolkit will automatically apply the correct
193 procedure to accessing these values as they are used in the template.
199 \& article => 'The Third Shoe',
202 \& name => 'Mr. Blue',
203 \& email => 'blue@nowhere.org',
205 \& primes => [ 2, 3, 5, 7, 11, 13 ],
206 \& wizard => sub { return join(' ', 'Abracadabra!', @_) },
207 \& cgi => CGI\->new('mode=submit&debug=1'),
218 \& [% person.id %]: [% person.name %] <[% person.email %]>
222 \& [% primes.first %] \- [% primes.last %], including [% primes.3 %]
223 \& [% primes.size %] prime numbers: [% primes.join(', ') %]
228 \& [% wizard('Hocus Pocus!') %]
232 \& [% cgi.param('mode') %]
242 \& 314: Mr. Blue <blue@nowhere.org>
246 \& 2 \- 13, including 7
247 \& 6 prime numbers: 2, 3, 5, 7, 11, 13
252 \& Abracadabra! Hocus Pocus!
259 .IX Subsection "Scalar Values"
260 Regular scalar variables are accessed by simply specifying their name.
261 As these are just entries in the top-level variable hash they can be
262 considered special cases of hash array referencing as described below,
263 with the main namespace hash automatically implied.
268 .Sh "Hash Array References"
269 .IX Subsection "Hash Array References"
270 Members of hash arrays are accessed by specifying the hash reference
271 and key separated by the dot '\f(CW\*(C`.\*(C'\fR' operator.
277 \& 'home' => 'http://www.myserver.com/homepage.html',
279 \& 'this' => 'mypage.html',
280 \& 'next' => 'nextpage.html',
281 \& 'prev' => 'prevpage.html',
289 \& <a href="[% home %]">Home</a>
290 \& <a href="[% page.prev %]">Previous Page</a>
291 \& <a href="[% page.next %]">Next Page</a>
297 \& <a href="http://www.myserver.com/homepage.html">Home</a>
298 \& <a href="prevpage.html">Previous Page</a>
299 \& <a href="nextpage.html">Next Page</a>
302 Any key in a hash which starts with a '\f(CW\*(C`_\*(C'\fR' or '\f(CW\*(C`.\*(C'\fR' character will be
303 considered private and cannot be evaluated or updated from within a
304 template. The undefined value will be returned for any such variable
305 accessed which the Template Toolkit will silently ignore (unless the
306 \&\f(CW\*(C`DEBUG\*(C'\fR option is enabled).
312 \& message => 'Hello World!',
313 \& _secret => "On the Internet, no\-one knows you're a dog",
325 \& [% message %] # outputs "Hello World!"
326 \& [% _secret %] # no output
327 \& [% thing.public %] # outputs "123"
328 \& [% thing._private %] # no output
329 \& [% thing..hidden %] # ERROR: unexpected token (..)
332 You can disable this feature by setting the \f(CW$Template::Stash::PRIVATE\fR
333 package variable to a false value.
336 \& $Template::Stash::PRIVATE = undef; # now you can thing._private
339 To access a hash entry using a key stored in another variable, prefix
340 the key variable with '\f(CW\*(C`$\*(C'\fR' to have it interpolated before use (see
341 \&\*(L"Variable Interpolation\*(R").
344 \& [% pagename = 'next' %]
345 \& [% page.$pagename %] # same as [% page.next %]
348 When you assign to a variable that contains multiple namespace
349 elements (i.e. it has one or more '\f(CW\*(C`.\*(C'\fR' characters in the name),
350 any hashes required to represent intermediate namespaces will be
351 created automatically. In this following example, the \f(CW\*(C`product\*(C'\fR
352 variable automatically springs into life as a hash array unless
356 \& [% product.id = 'XYZ\-2000'
357 \& product.desc = 'Bogon Generator'
358 \& product.price = 666
363 \& The [% product.id %] [% product.desc %]
364 \& costs $[% product.price %].00
370 \& The XYZ\-2000 Bogon Generator
374 You can use Perl's familiar \f(CW\*(C`{\*(C'\fR ... \f(CW\*(C`}\*(C'\fR construct to explicitly create
375 a hash and assign it to a variable. Note that commas are optional
376 between key/value pairs and \f(CW\*(C`=\*(C'\fR can be used in place of \f(CW\*(C`=>\*(C'\fR.
379 \& # minimal TT style
382 \& desc = 'Bogon Generator'
391 \& id => 'XYZ\-2000',
392 \& desc => 'Bogon Generator',
397 .Sh "List References"
398 .IX Subsection "List References"
399 Items in lists are also accessed by use of the dot operator.
405 \& people => [ 'Tom', 'Dick', 'Larry' ],
412 \& [% people.0 %] # Tom
413 \& [% people.1 %] # Dick
414 \& [% people.2 %] # Larry
417 The \f(CW\*(C`FOREACH\*(C'\fR directive can be used to iterate through items in a list.
420 \& [% FOREACH person IN people %]
421 \& Hello [% person %]
433 Lists can be constructed in-situ using the regular anonymous list
434 \&\f(CW\*(C`[\*(C'\fR ... \f(CW\*(C`]\*(C'\fR construct. Commas between items are optional.
437 \& [% cols = [ 'red', 'green', 'blue' ] %]
441 \& [% FOREACH c IN cols %]
449 \& [% FOREACH c IN [ 'red', 'green', 'blue' ] %]
454 You can also create simple numerical sequences using the \f(CW\*(C`..\*(C'\fR range
458 \& [% n = [ 1 .. 4 ] %] # n is [ 1, 2, 3, 4 ]
464 \& z = [x..y] # z is [ 4, 5, 6, 7, 8 ]
468 .IX Subsection "Subroutines"
469 Template variables can contain references to Perl subroutines. When
470 the variable is used, the Template Toolkit will automatically call the
471 subroutine, passing any additional arguments specified. The return
472 value from the subroutine is used as the variable value and inserted
473 into the document output.
477 \& wizard => sub { return join(' ', 'Abracadabra!', @_) },
484 \& [% wizard %] # Abracadabra!
485 \& [% wizard('Hocus Pocus!') %] # Abracadabra! Hocus Pocus!
488 .IX Subsection "Objects"
489 Template variables can also contain references to Perl objects.
490 Methods are called using the dot operator to specify the method
491 against the object variable. Additional arguments can be specified
500 \& # hard coded CGI params for purpose of example
501 \& cgi => CGI\->new('mode=submit&debug=1'),
508 \& [% FOREACH p IN cgi.param %] # returns list of param keys
509 \& [% p %] => [% cgi.param(p) %] # fetch each param value
520 Object methods can also be called as lvalues. That is, they can appear on
521 the left side of an assignment. The method will be called passing the
522 assigning value as an argument.
525 \& [% myobj.method = 10 %]
531 \& [% myobj.method(10) %]
533 .Sh "Passing Parameters and Returning Values"
534 .IX Subsection "Passing Parameters and Returning Values"
535 Subroutines and methods will be passed any arguments specified in the
536 template. Any template variables in the argument list will first be
537 evaluated and their resultant values passed to the code.
541 \& mycode => sub { return 'received ' . join(', ', @_) },
549 \& [% mycode(foo, 20) %] # received 10, 20
552 Named parameters may also be specified. These are automatically collected
553 into a single hash array which is passed by reference as the \fBlast\fR
554 parameter to the sub\-routine. Named parameters can be specified using
555 either \f(CW\*(C`=>\*(C'\fR or \f(CW\*(C`=\*(C'\fR and can appear anywhere in the argument list.
559 \& myjoin => \e&myjoin,
565 \& # look for hash ref as last argument
566 \& my $params = ref $_[\-1] eq 'HASH' ? pop : { };
567 \& return join($params\->{ joint } || ' + ', @_);
574 \& [% myjoin(10, 20, 30) %]
575 \& [% myjoin(10, 20, 30, joint = ' \- ' %]
576 \& [% myjoin(joint => ' * ', 10, 20, 30 %]
587 Parenthesised parameters may be added to any element of a variable,
588 not just those that are bound to code or object methods. At present,
589 parameters will be ignored if the variable isn't \*(L"callable\*(R" but are
590 supported for future extensions. Think of them as \*(L"hints\*(R" to that
591 variable, rather than just arguments passed to a function.
595 \& [% r(100, 99, s, t, v) %] # outputs "Romeo"
598 User code should return a value for the variable it represents. This
599 can be any of the Perl data types described above: a scalar, or
600 reference to a list, hash, subroutine or object. Where code returns a
601 list of multiple values the items will automatically be folded into a
602 list reference which can be accessed as per normal.
606 \& # either is OK, first is recommended
607 \& items1 => sub { return [ 'foo', 'bar', 'baz' ] },
608 \& items2 => sub { return ( 'foo', 'bar', 'baz' ) },
615 \& [% FOREACH i IN items1 %]
621 \& [% FOREACH i IN items2 %]
626 .IX Subsection "Error Handling"
627 Errors can be reported from user code by calling \f(CW\*(C`die()\*(C'\fR. Errors raised
628 in this way are caught by the Template Toolkit and converted to
629 structured exceptions which can be handled from within the template.
630 A reference to the exception object is then available as the \f(CW\*(C`error\*(C'\fR
636 \& die "a sick error has occurred\en";
645 \& [% barf %] # calls sub which throws error via die()
647 \& [% error.info %] # outputs "a sick error has occurred\en"
651 Error messages thrown via \f(CW\*(C`die()\*(C'\fR are converted to exceptions of type
652 \&\f(CW\*(C`undef\*(C'\fR (the literal string \*(L"undef\*(R" rather than the undefined value).
653 Exceptions of user-defined types can be thrown by calling \f(CW\*(C`die()\*(C'\fR with
654 a reference to a Template::Exception object.
657 \& use Template::Exception;
663 \& ...do something...
664 \& die Template::Exception\->new( badpwd => 'password too silly' );
674 \& [% CATCH badpwd %]
675 \& Bad password: [% error.info %]
677 \& Some other '[% error.type %]' error: [% error.info %]
681 The exception types \f(CW\*(C`stop\*(C'\fR and \f(CW\*(C`return\*(C'\fR are used to implement the
682 \&\f(CW\*(C`STOP\*(C'\fR and \f(CW\*(C`RETURN\*(C'\fR directives. Throwing an exception as:
685 \& die (Template::Exception\->new('stop'));
688 has the same effect as the directive:
693 .SH "Virtual Methods"
694 .IX Header "Virtual Methods"
695 The Template Toolkit implements a number of \*(L"virtual methods\*(R" which
696 can be applied to scalars, hashes or lists. For example:
699 \& [% mylist = [ 'foo', 'bar', 'baz' ] %]
700 \& [% newlist = mylist.sort %]
703 Here \f(CW\*(C`mylist\*(C'\fR is a regular reference to a list, and 'sort' is
704 a virtual method that returns a new list of the items in sorted
705 order. You can chain multiple virtual methods together. For
709 \& [% mylist.sort.join(', ') %]
712 Here the \f(CW\*(C`join\*(C'\fR virtual method is called to join the sorted list into
713 a single string, generating the following output:
719 See Template::Manual::VMethods for details of all the virtual
721 .SH "Variable Interpolation"
722 .IX Header "Variable Interpolation"
723 The Template Toolkit uses \f(CW\*(C`$\*(C'\fR consistently to indicate that a variable
724 should be interpolated in position. Most frequently, you see this in
725 double-quoted strings:
728 \& [% fullname = "$honorific $firstname $surname" %]
731 Or embedded in plain text when the \f(CW\*(C`INTERPOLATE\*(C'\fR option is set:
734 \& Dear $honorific $firstname $surname,
737 The same rules apply within directives. If a variable is prefixed
738 with a \f(CW\*(C`$\*(C'\fR then it is replaced with its value before being used. The
739 most common use is to retrieve an element from a hash where the key is
740 stored in a variable.
744 \& [% users.$uid %] # same as 'userlist.abw'
747 Curly braces can be used to delimit interpolated variable names where
751 \& [% users.${me.id}.name %]
754 Directives such as \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR, etc., that accept a template name
755 as the first argument, will automatically quote it for convenience.
758 \& [% INCLUDE foo/bar.txt %]
761 The above example is equivalent to:
764 \& [% INCLUDE "foo/bar.txt" %]
767 To \f(CW\*(C`INCLUDE\*(C'\fR a template whose name is stored in a variable, simply
768 prefix the variable name with \f(CW\*(C`$\*(C'\fR to have it interpolated.
771 \& [% myfile = 'header' %]
772 \& [% INCLUDE $myfile %]
775 This is equivalent to:
778 \& [% INCLUDE header %]
781 Note also that a variable containing a reference to a Template::Document
782 object can also be processed in this way.
786 \& header => Template::Document\->new({ ... }),
793 \& [% INCLUDE $header %]
795 .SH "Local and Global Variables"
796 .IX Header "Local and Global Variables"
797 Any simple variables that you create, or any changes you make to
798 existing variables, will only persist while the template is being
799 processed. The top-level variable hash is copied before processing
800 begins and any changes to variables are made in this copy, leaving the
803 The same thing happens when you \f(CW\*(C`INCLUDE\*(C'\fR another template. The current
804 namespace hash is cloned to prevent any variable changes made in the included
805 template from interfering with existing variables. The \f(CW\*(C`PROCESS\*(C'\fR option bypasses
806 the localisation step altogether making it slightly faster, but requiring
807 greater attention to the possibility of side effects caused by creating or
808 changing any variables within the processed template.
811 \& [% BLOCK change_name %]
812 \& [% name = 'bar' %]
817 \& [% name = 'foo' %]
818 \& [% INCLUDE change_name %]
820 \& [% PROCESS change_name %]
824 Dotted compound variables behave slightly differently because the
825 localisation process is only skin deep. The current variable
826 namespace hash is copied, but no attempt is made to perform a
827 deep-copy of other structures within it (hashes, arrays, objects,
828 etc). A variable referencing a hash, for example, will be copied to
829 create a new reference but which points to the same hash. Thus, the
830 general rule is that simple variables (undotted variables) are
831 localised, but existing complex structures (dotted variables) are not.
834 \& [% BLOCK all_change %]
835 \& [% x = 20 %] # changes copy
836 \& [% y.z = 'zulu' %] # changes original
842 \& y = { z => 'zebra' }
844 \& [% INCLUDE all_change %]
845 \& [% x %] # still '10'
846 \& [% y.z %] # now 'zulu'
849 If you create a complex structure such as a hash or list reference
850 within a local template context then it will cease to exist when
851 the template is finished processing.
854 \& [% BLOCK new_stuff %]
855 \& [% # define a new 'y' hash array in local context
856 \& y = { z => 'zulu' }
863 \& [% INCLUDE new_stuff %]
864 \& [% x %] # outputs '10'
865 \& [% y %] # nothing, y is undefined
868 Similarly, if you update an element of a compound variable which
869 \&\fIdoesn't\fR already exists then a hash will be created automatically
870 and deleted again at the end of the block.
873 \& [% BLOCK new_stuff %]
874 \& [% y.z = 'zulu' %]
878 However, if the hash \fIdoes\fR already exist then you will modify the
879 original with permanent effect. To avoid potential confusion, it is
880 recommended that you don't update elements of complex variables from
881 within blocks or templates included by another.
883 If you want to create or update truly global variables then you can
884 use the 'global' namespace. This is a hash array automatically created
885 in the top-level namespace which all templates, localised or otherwise
886 see the same reference to. Changes made to variables within this
887 hash are visible across all templates.
890 \& [% global.version = 123 %]
892 .SH "Compile Time Constant Folding"
893 .IX Header "Compile Time Constant Folding"
894 In addition to variables that get resolved each time a template is
895 processed, you can also define variables that get resolved just once
896 when the template is compiled. This generally results in templates
897 processing faster because there is less work to be done.
899 To define compile-time constants, specify a \f(CW\*(C`CONSTANTS\*(C'\fR hash as a
900 constructor item as per \f(CW\*(C`VARIABLES\*(C'\fR. The \f(CW\*(C`CONSTANTS\*(C'\fR hash can contain any
901 kind of complex, nested, or dynamic data structures, just like regular
905 \& my $tt = Template\->new({
908 \& release => 'skyrocket',
910 \& back => '#ffffff',
911 \& fore => '#000000',
913 \& myobj => My::Object\->new(),
914 \& mysub => sub { ... },
920 Within a template, you access these variables using the \f(CW\*(C`constants\*(C'\fR
924 \& Version [% constants.version %] ([% constants.release %])
925 \& Background: [% constants.col.back %]
928 When the template is compiled, these variable references are replaced
929 with the corresponding value. No further variable lookup is then
930 required when the template is processed.
932 You can call subroutines, object methods, and even virtual methods on
936 \& [% constants.mysub(10, 20) %]
937 \& [% constants.myobj(30, 40) %]
938 \& [% constants.col.keys.sort.join(', ') %]
941 One important proviso is that any arguments you pass to subroutines
942 or methods must also be literal values or compile time constants.
944 For example, these are both fine:
947 \& # literal argument
948 \& [% constants.col.keys.sort.join(', ') %]
952 \& # constant argument
953 \& [% constants.col.keys.sort.join(constants.joint) %]
956 But this next example will raise an error at parse time because
957 \&\f(CW\*(C`joint\*(C'\fR is a runtime variable and cannot be determined at compile
961 \& # ERROR: runtime variable argument!
962 \& [% constants.col.keys.sort.join(joint) %]
965 The \f(CW\*(C`CONSTANTS_NAMESPACE\*(C'\fR option can be used to provide a different
966 namespace prefix for constant variables. For example:
969 \& my $tt = Template\->new({
974 \& CONSTANTS_NAMESPACE => 'const',
978 Constants would then be referenced in templates as:
981 \& [% const.version %]
983 .SH "Special Variables"
984 .IX Header "Special Variables"
985 A number of special variables are automatically defined by the Template
988 .IX Subsection "template"
989 The \f(CW\*(C`template\*(C'\fR variable contains a reference to the main template being
990 processed, in the form of a Template::Document object. This variable is
991 correctly defined within \f(CW\*(C`PRE_PROCESS\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR
992 templates, allowing standard headers, footers, etc., to access metadata items
993 from the main template. The \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`modtime\*(C'\fR metadata items are
994 automatically provided, giving the template name and modification time in
995 seconds since the epoch.
997 Note that the \f(CW\*(C`template\*(C'\fR variable always references the top-level
998 template, even when processing other template components via \f(CW\*(C`INCLUDE\*(C'\fR,
999 \&\f(CW\*(C`PROCESS\*(C'\fR, etc.
1001 .IX Subsection "component"
1002 The \f(CW\*(C`component\*(C'\fR variable is like \f(CW\*(C`template\*(C'\fR but always contains a
1003 reference to the current, innermost template component being processed.
1004 In the main template, the \f(CW\*(C`template\*(C'\fR and \f(CW\*(C`component\*(C'\fR variable will
1005 reference the same Template::Document object. In any other template
1006 component called from the main template, the \f(CW\*(C`template\*(C'\fR variable
1007 will remain unchanged, but \f(CW\*(C`component\*(C'\fR will contain a new reference
1008 to the current component.
1010 This example should demonstrate the difference:
1013 \& $template\->process('foo')
1014 \& || die $template\->error(), "\en";
1017 \&\fIfoo\fR template:
1020 \& [% template.name %] # foo
1021 \& [% component.name %] # foo
1022 \& [% PROCESS footer %]
1025 \&\fIfooter\fR template:
1028 \& [% template.name %] # foo
1029 \& [% component.name %] # footer
1032 Additionally, the \f(CW\*(C`component\*(C'\fR variable has two special fields:
1033 \&\f(CW\*(C`caller\*(C'\fR and \f(CW\*(C`callers\*(C'\fR. \f(CW\*(C`caller\*(C'\fR contains the name of the template
1034 that called the current template (or undef if the values of \f(CW\*(C`template\*(C'\fR
1035 and \f(CW\*(C`component\*(C'\fR are the same). \f(CW\*(C`callers\*(C'\fR contains a reference to a
1036 list of all the templates that have been called on the road to calling
1037 the current component template (like a call stack), with the
1038 outer-most template first.
1042 \&\fIouter.tt2\fR template:
1045 \& [% component.name %] # 'outer.tt2'
1046 \& [% component.caller %] # undef
1047 \& [% component.callers %] # undef
1048 \& [% PROCESS 'middle.tt2' %]
1051 \&\fImiddle.tt2\fR template:
1054 \& [% component.name %] # 'middle.tt2'
1055 \& [% component.caller %] # 'outer.tt2'
1056 \& [% component.callers %] # [ 'outer.tt2' ]
1057 \& [% PROCESS 'inner.tt2' %]
1060 \&\fIinner.tt2\fR template:
1063 \& [% component.name %] # 'inner.tt2'
1064 \& [% component.caller %] # 'middle.tt2'
1065 \& [% component.callers %] # [ 'outer.tt2', 'middle.tt2' ]
1068 .IX Subsection "loop"
1069 Within a \f(CW\*(C`FOREACH\*(C'\fR loop, the \f(CW\*(C`loop\*(C'\fR variable references the
1070 Template::Iterator object responsible for controlling the loop.
1073 \& [% FOREACH item = [ 'foo', 'bar', 'baz' ] \-%]
1074 \& [% "Items:\en" IF loop.first \-%]
1075 \& [% loop.count %]/[% loop.size %]: [% item %]
1079 .IX Subsection "error"
1080 Within a \f(CW\*(C`CATCH\*(C'\fR block, the \f(CW\*(C`error\*(C'\fR variable contains a reference to the
1081 Template::Exception object thrown from within the \f(CW\*(C`TRY\*(C'\fR block. The
1082 \&\f(CW\*(C`type\*(C'\fR and \f(CW\*(C`info\*(C'\fR methods can be called or the variable itself can
1083 be printed for automatic stringification into a message of the form
1084 "\f(CW\*(C`$type error \- $info\*(C'\fR". See Template::Exception for further details.
1094 .IX Subsection "content"
1095 The \f(CW\*(C`WRAPPER\*(C'\fR method captures the output from a template block and then
1096 includes a named template, passing the captured output as the 'content'
1100 \& [% WRAPPER box %]
1101 \& Be not afeard; the isle is full of noises,
1102 \& Sounds and sweet airs, that give delight and hurt not.
1108 \& <blockquote class="prose">
1113 .SH "Compound Variables"
1114 .IX Header "Compound Variables"
1115 Compound 'dotted' variables may contain any number of separate
1116 elements. Each element may evaluate to any of the permitted variable
1117 types and the processor will then correctly use this value to evaluate
1118 the rest of the variable. Arguments may be passed to any of the
1119 intermediate elements.
1122 \& [% myorg.people.sort('surname').first.fullname %]
1125 Intermediate variables may be used and will behave entirely as expected.
1128 \& [% sorted = myorg.people.sort('surname') %]
1129 \& [% sorted.first.fullname %]
1132 This simplified dotted notation has the benefit of hiding the
1133 implementation details of your data. For example, you could implement
1134 a data structure as a hash array one day and then change it to an
1135 object the next without requiring any change to the templates.
projects / catagits/Gitalist.git / blob