1 #============================================================= -*-perl-*-
3 # Template::Manual::Directives
6 # Andy Wardley <abw@wardley.org>
9 # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
11 # This module is free software; you can redistribute it and/or
12 # modify it under the same terms as Perl itself.
14 #========================================================================
18 Template::Manual::Directives - Template directives
20 =head1 Accessing and Updating Template Variables
24 The C<GET> directive retrieves and outputs the value of the named variable.
28 The C<GET> keyword is optional. A variable can be specified in a directive
33 The variable can have an unlimited number of elements, each separated by a
34 dot. Each element can have arguments specified within parentheses.
41 See L<Template::Manual::Variables> for a full discussion on template
44 You can also specify expressions using the logical (C<and>, C<or>, C<not>, C<?>, C<:>) and
45 mathematic operators (C<+>, C<->, C<*>, C</>, C<%>, C<mod>, C<div>).
47 [% template.title or default.title %]
51 [% order.nitems ? checkout(order.total) : 'no items' %]
53 The C<div> operator returns the integer result of division. Both C<%> and
54 C<mod> return the modulus (i.e. remainder) of division.
62 The C<CALL> directive is similar to C<GET> in evaluating the variable named,
63 but doesn't print the result returned. This can be useful when a
64 variable is bound to a sub-routine or object method which you want to
65 call but aren't interested in the value returned.
67 [% CALL dbi.disconnect %]
69 [% CALL inc_page_counter(page_count) %]
73 The C<SET> directive allows you to assign new values to existing variables
74 or create new temporary variables.
76 [% SET title = 'Hello World' %]
78 The C<SET> keyword is also optional.
80 [% title = 'Hello World' %]
82 Variables may be assigned the values of other variables, unquoted
83 numbers (2.718), literal text ('single quotes') or quoted text
84 ("double quotes"). In the latter case, any variable references within
85 the text will be interpolated when the string is evaluated. Variables
86 should be prefixed by C<$>, using curly braces to explicitly scope
87 the variable name where necessary.
89 [% foo = 'Foo' %] # literal value 'Foo'
90 [% bar = foo %] # value of variable 'foo'
91 [% cost = '$100' %] # literal value '$100'
92 [% item = "$bar: ${cost}.00" %] # value "Foo: $100.00"
94 Multiple variables may be assigned in the same directive and are
95 evaluated in the order specified. Thus, the above could have been
101 item = "$bar: ${cost}.00"
104 Simple expressions can also be used, as per C<GET>.
108 thirty = twenty + ten
114 You can concatenate strings together using the C<' _ '> operator. In Perl 5,
115 the C<.> is used for string concatenation, but in Perl 6, as in the Template
116 Toolkit, the C<.> will be used as the method calling operator and C<' _ '> will
117 be used for string concatenation. Note that the operator must be
118 specified with surrounding whitespace which, as Larry says, is construed as
121 [% copyright = '(C) Copyright' _ year _ ' ' _ author %]
123 You can, of course, achieve a similar effect with double quoted string
126 [% copyright = "(C) Copyright $year $author" %]
130 The C<DEFAULT> directive is similar to C<SET> but only updates variables
131 that are currently undefined or have no "true" value (in the Perl
139 This can be particularly useful in common template components to
140 ensure that some sensible default are provided for otherwise
144 title = 'Hello World'
149 <title>[% title %]</title>
151 <body bgcolor="[% bgcol %]">
154 =head1 Processing Template Files and Blocks
158 The C<INSERT> directive is used to insert the contents of an external file
159 at the current position.
163 No attempt to parse or process the file is made. The contents,
164 possibly including any embedded template directives, are inserted
167 The filename specified should be relative to one of the C<INCLUDE_PATH>
168 directories. Absolute (i.e. starting with C</>) and relative
169 (i.e. starting with C<.>) filenames may be used if the C<ABSOLUTE> and
170 C<RELATIVE> options are set, respectively. Both these options are
173 my $template = Template->new({
174 INCLUDE_PATH => '/here:/there',
177 $template->process('myfile');
181 [% INSERT foo %] # looks for /here/foo then /there/foo
182 [% INSERT /etc/passwd %] # file error: ABSOLUTE not set
183 [% INSERT ../secret %] # file error: RELATIVE not set
185 For convenience, the filename does not need to be quoted as long as it
186 contains only alphanumeric characters, underscores, dots or forward
187 slashes. Names containing any other characters should be quoted.
189 [% INSERT misc/legalese.txt %]
190 [% INSERT 'dos98/Program Files/stupid' %]
192 To evaluate a variable to specify a filename, you should explicitly
193 prefix it with a C<$> or use double-quoted string interpolation.
196 legalese = 'misc/legalese.txt'
199 [% INSERT $legalese %] # misc/legalese.txt
200 [% INSERT "$language/$legalese" %] # en/misc/legalese.txt
202 Multiple files can be specified using C<+> as a delimiter. All files
203 should be unquoted names or quoted strings. Any variables should be
204 interpolated into double-quoted strings.
206 [% INSERT legalese.txt + warning.txt %]
207 [% INSERT "$legalese" + warning.txt %] # requires quoting
211 The C<INCLUDE> directive is used to process and include the output of
212 another template file or block.
216 If a C<BLOCK> of the specified name is defined in the same file, or in a file
217 from which the current template has been called (i.e. a parent template) then
218 it will be used in preference to any file of the same name.
220 [% INCLUDE table %] # uses BLOCK defined below
228 If a C<BLOCK> definition is not currently visible then the template name
229 should be a file relative to one of the C<INCLUDE_PATH> directories, or
230 an absolute or relative file name if the C<ABSOLUTE>/C<RELATIVE> options are
231 appropriately enabled. The C<INCLUDE> directive automatically quotes the
232 filename specified, as per C<INSERT> described above. When a variable
233 contains the name of the template for the C<INCLUDE> directive, it should
234 be explicitly prefixed by C<$> or double-quoted
236 [% myheader = 'my/misc/header' %]
237 [% INCLUDE myheader %] # 'myheader'
238 [% INCLUDE $myheader %] # 'my/misc/header'
239 [% INCLUDE "$myheader" %] # 'my/misc/header'
241 Any template directives embedded within the file will be processed
242 accordingly. All variables currently defined will be visible and
243 accessible from within the included template.
245 [% title = 'Hello World' %]
253 <title>[% title %]</title>
258 <title>Hello World</title>
262 Local variable definitions may be specified after the template name,
263 temporarily masking any existing variables. Insignificant whitespace
264 is ignored within directives so you can add variable definitions on the
265 same line, the next line or split across several line with comments
266 interspersed, if you prefer.
270 [% INCLUDE table title="Active Projects" %]
273 title = "Active Projects"
274 bgcolor = "#80ff00" # chartreuse
278 The C<INCLUDE> directive localises (i.e. copies) all variables before
279 processing the template. Any changes made within the included
280 template will not affect variables in the including template.
284 foo is originally [% foo %]
286 foo is still [% foo %]
301 Technical Note: the localisation of the stash (that is, the process by
302 which variables are copied before an C<INCLUDE> to prevent being
303 overwritten) is only skin deep. The top-level variable namespace
304 (hash) is copied, but no attempt is made to perform a deep-copy of
305 other structures (hashes, arrays, objects, etc.) Therefore, a C<foo>
306 variable referencing a hash will be copied to create a new C<foo>
307 variable but which points to the same hash array. Thus, if you update
308 compound variables (e.g. C<foo.bar>) then you will change the original
309 copy, regardless of any stash localisation. If you're not worried
310 about preserving variable values, or you trust the templates you're
311 including then you might prefer to use the C<PROCESS> directive which is
312 faster by virtue of not performing any localisation.
314 You can specify dotted variables as "local" variables to an C<INCLUDE> directive.
315 However, be aware that because of the localisation issues explained above (if
316 you skipped the previous Technical Note above then you might want to go back
317 and read it or skip this section too), the variables might not actualy be
318 "local". If the first element of the variable name already references a hash
319 array then the variable update will affect the original variable.
326 [% INCLUDE somefile foo.bar='Boz' %]
330 This behaviour can be a little unpredictable (and may well be improved
331 upon in a future version). If you know what you're doing with it and
332 you're sure that the variables in question are defined (nor not) as you
333 expect them to be, then you can rely on this feature to implement some
334 powerful "global" data sharing techniques. Otherwise, you might prefer
335 to steer well clear and always pass simple (undotted) variables as
336 parameters to C<INCLUDE> and other similar directives.
338 If you want to process several templates in one go then you can
339 specify each of their names (quoted or unquoted names only, no unquoted
340 C<$variables>) joined together by C<+>. The C<INCLUDE> directive
341 will then process them in order.
343 [% INCLUDE html/header + "site/$header" + site/menu
344 title = "My Groovy Web Site"
347 The variable stash is localised once and then the templates specified
348 are processed in order, all within that same variable context. This
349 makes it slightly faster than specifying several separate C<INCLUDE>
350 directives (because you only clone the variable stash once instead of
351 n times), but not quite as "safe" because any variable changes in the
352 first file will be visible in the second, third and so on. This
353 might be what you want, of course, but then again, it might not.
357 The PROCESS directive is similar to C<INCLUDE> but does not perform any
358 localisation of variables before processing the template. Any changes
359 made to variables within the included template will be visible in the
370 changed foo to [% foo %]
379 Parameters may be specified in the C<PROCESS> directive, but these too will
380 become visible changes to current variable values.
390 this is bar, foo is [% foo %]
396 this is bar, foo is 20
399 The C<PROCESS> directive is slightly faster than C<INCLUDE> because it
400 avoids the need to localise (i.e. copy) the variable stash before
401 processing the template. As with C<INSERT> and C<INCLUDE>, the first
402 parameter does not need to be quoted as long as it contains only
403 alphanumeric characters, underscores, periods or forward slashes.
404 A C<$> prefix can be used to explicitly indicate a variable which
405 should be interpolated to provide the template name:
407 [% myheader = 'my/misc/header' %]
408 [% PROCESS myheader %] # 'myheader'
409 [% PROCESS $myheader %] # 'my/misc/header'
411 As with C<INCLUDE>, multiple templates can be specified, delimited by
412 C<+>, and are processed in order.
414 [% PROCESS html/header + my/header %]
418 It's not unusual to find yourself adding common headers and footers to
419 pages or sub-sections within a page. Something like this:
421 [% INCLUDE section/header
422 title = 'Quantum Mechanics'
424 Quantum mechanics is a very interesting subject wish
425 should prove easy for the layman to fully comprehend.
426 [% INCLUDE section/footer %]
428 [% INCLUDE section/header
429 title = 'Desktop Nuclear Fusion for under $50'
431 This describes a simple device which generates significant
432 sustainable electrical power from common tap water by process
434 [% INCLUDE section/footer %]
436 The individual template components being included might look like these:
447 The C<WRAPPER> directive provides a way of simplifying this a little. It
448 encloses a block up to a matching C<END> directive, which is first processed
449 to generate some output. This is then passed to the named template file or
450 C<BLOCK> as the C<content> variable.
453 title = 'Quantum Mechanics'
455 Quantum mechanics is a very interesting subject wish
456 should prove easy for the layman to fully comprehend.
460 title = 'Desktop Nuclear Fusion for under $50'
462 This describes a simple device which generates significant
463 sustainable electrical power from common tap water by process
467 The single 'section' template can then be defined as:
474 Like other block directives, it can be used in side-effect notation:
476 [% INSERT legalese.txt WRAPPER big_bold_table %]
478 It's also possible to specify multiple templates to a C<WRAPPER> directive.
479 The specification order indicates outermost to innermost wrapper templates.
480 For example, given the following template block definitions:
482 [% BLOCK bold %]<b>[% content %]</b>[% END %]
483 [% BLOCK italic %]<i>[% content %]</i>[% END %]
487 [% WRAPPER bold+italic %]Hello World[% END %]
489 would generate the following output:
491 <b><i>Hello World</i></b>
495 The C<BLOCK>...C<END> construct can be used to define template component
496 blocks which can be processed with the C<INCLUDE>, C<PROCESS> and C<WRAPPER>
507 [% PROCESS tabrow name='Fred' email='fred@nowhere.com' %]
508 [% PROCESS tabrow name='Alan' email='alan@nowhere.com' %]
511 A C<BLOCK> definition can be used before it is defined, as long as the
512 definition resides in the same file. The block definition itself does
513 not generate any output.
517 [% BLOCK tmpblk %] This is OK [% END %]
519 You can use an anonymous C<BLOCK> to capture the output of a template
523 And Caesar's spirit, ranging for revenge,
524 With Ate by his side come hot from hell,
525 Shall in these confines with a monarch's voice
526 Cry 'Havoc', and let slip the dogs of war;
527 That this foul deed shall smell above the earth
528 With carrion men, groaning for burial.
531 Like a named block, it can contain any other template directives which
532 are processed when the block is defined. The output generated by the
533 block is then assigned to the variable C<julius>.
535 Anonymous C<BLOCK>s can also be used to define block macros. The
536 enclosing block is processed each time the macro is called.
538 [% MACRO locate BLOCK %]
539 The [% animal %] sat on the [% place %].
542 [% locate(animal='cat', place='mat') %] # The cat sat on the mat
543 [% locate(animal='dog', place='log') %] # The dog sat on the log
545 =head1 Conditional Processing
547 =head2 IF / UNLESS / ELSIF / ELSE
549 The C<IF> and C<UNLESS> directives can be used to process or ignore a
550 block based on some run-time condition.
553 [% INCLUDE frameset %]
556 [% UNLESS text_mode %]
557 [% INCLUDE biglogo %]
560 Multiple conditions may be joined with C<ELSIF> and/or C<ELSE> blocks.
563 Hello [% name %], does your mother know you're
564 using her AOL account?
566 Sorry, you're not old enough to enter
567 (and too dumb to lie about your age)
572 The following conditional and boolean operators may be used:
574 == != < <= > >= && || ! and or not
576 Conditions may be arbitrarily complex and are evaluated with the same
577 precedence as in Perl. Parenthesis may be used to explicitly
578 determine evaluation order.
580 # ridiculously contrived complex example
581 [% IF (name == 'admin' || uid <= 0) && mode == 'debug' %]
583 [% ELSIF more > less %]
584 That's more or less correct.
587 The C<and>, C<or> and C<not> operator are provided as aliases for
588 C<&&>, C<||> and C<!>, respectively. Unlike Perl, which treats
589 C<and>, C<or> and C<not> as separate, lower-precedence versions of the
590 other operators, the Template Toolkit performs a straightforward substitution
591 of C<and> for C<&&>, and so on. That means that C<and>, C<or> and C<not>
592 have the same operator precedence as C<&&>, C<||> and C<!>.
596 The C<SWITCH> / C<CASE> construct can be used to perform a multi-way
597 conditional test. The C<SWITCH> directive expects an expression which is
598 first evaluated and then compared against each CASE statement in turn.
599 Each C<CASE> directive should contain a single value or a list of values
600 which should match. C<CASE> may also be left blank or written as
601 C<[% CASE DEFAULT %]> to specify a default match. Only one C<CASE> matches,
602 there is no drop-through between C<CASE> statements.
607 [% CASE ['value2', 'value3'] %] # multiple values
609 [% CASE myhash.keys %] # ditto
615 =head1 Loop Processing
619 The C<FOREACH> directive will iterate through the items in a list, processing
620 the enclosed block for each one.
623 items = [ 'one', 'two', 'three' ]
627 [% FOREACH thing IN [ foo 'Bar' "$foo Baz" ] %]
632 [% FOREACH i IN items %]
637 [% stuff = [ foo "$foo Bar" ] %]
638 [% FOREACH s IN stuff %]
658 You can use also use C<=> instead of C<IN> if you prefer.
660 [% FOREACH i = items %]
662 When the C<FOREACH> directive is used without specifying a target variable,
663 any iterated values which are hash references will be automatically
667 { id => 'tom', name => 'Thomas' },
668 { id => 'dick', name => 'Richard' },
669 { id => 'larry', name => 'Lawrence' },
673 [% FOREACH user IN userlist %]
674 [% user.id %] [% user.name %]
679 [% FOREACH userlist %]
683 Note that this particular usage creates a localised variable context
684 to prevent the imported hash keys from overwriting any existing
685 variables. The imported definitions and any other variables defined
686 in such a C<FOREACH> loop will be lost at the end of the loop, when the
687 previous context and variable values are restored.
689 However, under normal operation, the loop variable remains in scope
690 after the C<FOREACH> loop has ended (caveat: overwriting any variable
691 previously in scope). This is useful as the loop variable is secretly
692 an iterator object (see below) and can be used to analyse the last
693 entry processed by the loop.
695 The C<FOREACH> directive can also be used to iterate through the entries
696 in a hash array. Each entry in the hash is returned in sorted order
697 (based on the key) as a hash array containing 'key' and 'value' items.
706 [% FOREACH u IN users %]
707 * [% u.key %] : [% u.value %]
716 The C<NEXT> directive starts the next iteration in the C<FOREACH> loop.
718 [% FOREACH user IN userlist %]
719 [% NEXT IF user.isguest %]
720 Name: [% user.name %] Email: [% user.email %]
723 The C<LAST> directive can be used to prematurely exit the loop. C<BREAK> is
724 also provided as an alias for C<LAST>.
726 [% FOREACH match IN results.nsort('score').reverse %]
727 [% LAST IF match.score < 50 %]
728 [% match.score %] : [% match.url %]
731 The C<FOREACH> directive is implemented using the L<Template::Iterator>
732 module. A reference to the iterator object for a C<FOREACH> directive is
733 implicitly available in the C<loop> variable. The following methods
734 can be called on the C<loop> iterator.
736 size() number of elements in the list
737 max() index number of last element (size - 1)
738 index() index of current iteration from 0 to max()
739 count() iteration counter from 1 to size() (i.e. index() + 1)
740 first() true if the current iteration is the first
741 last() true if the current iteration is the last
742 prev() return the previous item in the list
743 next() return the next item in the list
745 See L<Template::Iterator> for further details.
749 [% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%]
750 [%- "<ul>\n" IF loop.first %]
751 <li>[% loop.count %]/[% loop.size %]: [% item %]
752 [%- "</ul>\n" IF loop.last %]
763 Nested loops will work as expected, with the C<loop> variable correctly
764 referencing the innermost loop and being restored to any previous
765 value (i.e. an outer loop) at the end of the loop.
767 [% FOREACH group IN grouplist;
768 # loop => group iterator
769 "Groups:\n" IF loop.first;
771 FOREACH user IN group.userlist;
772 # loop => user iterator
773 "$loop.count: $user.name\n";
776 # loop => group iterator
777 "End of Groups\n" IF loop.last;
781 The C<iterator> plugin can also be used to explicitly create an
782 iterator object. This can be useful within nested loops where you
783 need to keep a reference to the outer iterator within the inner loop.
784 The iterator plugin effectively allows you to create an iterator by a
785 name other than C<loop>. See L<Template::Plugin::Iterator> for further
788 [% USE giter = iterator(grouplist) %]
790 [% FOREACH group IN giter %]
791 [% FOREACH user IN group.userlist %]
792 user #[% loop.count %] in
793 group [% giter.count %] is
794 named [% user.name %]
800 The C<WHILE> directive can be used to repeatedly process a template block
801 while a conditional expression evaluates true. The expression may
802 be arbitrarily complex as per C<IF> / C<UNLESS>.
804 [% WHILE total < 100 %]
806 [% total = calculate_new_total %]
809 An assignment can be enclosed in parenthesis to evaluate the assigned
812 [% WHILE (user = get_next_user_record) %]
816 The C<NEXT> directive can be used to start the next iteration of a
817 C<WHILE> loop and C<BREAK> can be used to exit the loop, both as per C<FOREACH>.
819 The Template Toolkit uses a failsafe counter to prevent runaway C<WHILE>
820 loops which would otherwise never terminate. If the loop exceeds 1000
821 iterations then an C<undef> exception will be thrown, reporting the
824 WHILE loop terminated (> 1000 iterations)
826 The C<$Template::Directive::WHILE_MAX> variable controls this behaviour
827 and can be set to a higher value if necessary.
829 =head1 Filters, Plugins, Macros and Perl
833 The C<FILTER> directive can be used to post-process the output of a
834 block. A number of standard filters are provided with the Template
835 Toolkit. The C<html> filter, for example, escapes the 'E<lt>', 'E<gt>'
836 and '&' characters to prevent them from being interpreted as HTML tags
837 or entity reference markers.
840 HTML text may have < and > characters embedded
841 which you want converted to the correct HTML entities.
846 HTML text may have < and > characters embedded
847 which you want converted to the correct HTML entities.
849 The C<FILTER> directive can also follow various other non-block directives.
852 [% INCLUDE mytext FILTER html %]
854 The C<|> character can also be used as an alias for C<FILTER>.
856 [% INCLUDE mytext | html %]
858 Multiple filters can be chained together and will be called in sequence.
860 [% INCLUDE mytext FILTER html FILTER html_para %]
864 [% INCLUDE mytext | html | html_para %]
866 Filters come in two flavours, known as 'static' or 'dynamic'. A
867 static filter is a simple subroutine which accepts a text string as
868 the only argument and returns the modified text. The C<html> filter is
869 an example of a static filter, implemented as:
881 Dynamic filters can accept arguments which are specified when the filter
882 is called from a template. The C<repeat> filter is such an example,
883 accepting a numerical argument which specifies the number of times
884 that the input text should be repeated.
886 [% FILTER repeat(3) %]blah [% END %]
892 These are implemented as filter 'factories'. The factory subroutine
893 is passed a reference to the current L<Template::Context> object along
894 with any additional arguments specified. It should then return a
895 subroutine reference (e.g. a closure) which implements the filter.
896 The C<repeat> filter factory is implemented like this:
898 sub repeat_filter_factory {
899 my ($context, $iter) = @_;
900 $iter = 1 unless defined $iter;
904 $text = '' unless defined $text;
905 return join('\n', $text) x $iter;
909 The C<FILTERS> option, described in L<Template::Manual::Config>, allows custom
910 filters to be defined when a Template object is instantiated. The
911 L<define_filter()|Template::Context#define_filter()> method allows further
912 filters to be defined at any time.
914 When using a filter, it is possible to assign an alias to it for
915 further use. This is most useful for dynamic filters that you want
916 to re-use with the same configuration.
918 [% FILTER echo = repeat(2) %]
919 Is there anybody out there?
923 Mother, should I build a wall?
928 Is there anybody out there?
929 Is there anybody out there?
931 Mother, should I build a wall?
932 Mother, should I build a wall?
934 The C<FILTER> directive automatically quotes the name of the filter. As
935 with C<INCLUDE> et al, you can use a variable to provide the name of the
936 filter, prefixed by C<$>.
938 [% myfilter = 'html' %]
939 [% FILTER $myfilter %] # same as [% FILTER html %]
943 A template variable can also be used to define a static filter
944 subroutine. However, the Template Toolkit will automatically call any
945 subroutine bound to a variable and use the value returned. Thus, the
946 above example could be implemented as:
949 myfilter => sub { return 'html' },
954 [% FILTER $myfilter %] # same as [% FILTER html %]
958 To define a template variable that evaluates to a subroutine reference
959 that can be used by the C<FILTER> directive, you should create a
960 subroutine that, when called automatically by the Template Toolkit,
961 returns another subroutine reference which can then be used to perform
962 the filter operation. Note that only static filters can be
963 implemented in this way.
966 myfilter => sub { \&my_filter_sub },
977 [% FILTER $myfilter %]
981 Alternately, you can bless a subroutine reference into a class (any
982 class will do) to fool the Template Toolkit into thinking it's an
983 object rather than a subroutine. This will then bypass the automatic
984 "call-a-subroutine-to-return-a-value" magic.
987 myfilter => bless(\&my_filter_sub, 'anything_you_like'),
992 [% FILTER $myfilter %]
996 Filters bound to template variables remain local to the variable context in
997 which they are defined. That is, if you define a filter in a C<PERL> block
998 within a template that is loaded via C<INCLUDE>, then the filter definition
999 will only exist until the end of that template when the stash is delocalised,
1000 restoring the previous variable state. If you want to define a filter which
1001 persists for the lifetime of the processor, or define additional dynamic
1002 filter factories, then you can call the
1003 L<define_filter()|Template::Context#define_filter()> method on the current
1004 L<Template::Context> object.
1006 See L<Template::Manual::Filters> for a complete list of available filters,
1007 their descriptions and examples of use.
1011 The C<USE> directive can be used to load and initialise "plugin"
1016 A plugin is a regular Perl module that conforms to a particular
1017 object-oriented interface, allowing it to be loaded into and used
1018 automatically by the Template Toolkit. For details of this interface
1019 and information on writing plugins, consult L<Template::Plugin>.
1021 A number of standard plugins are included with the Template Toolkit
1022 (see below and L<Template::Manual::Plugins>). The names of these
1023 standard plugins are case insensitive.
1025 [% USE CGI %] # => Template::Plugin::CGI
1026 [% USE Cgi %] # => Template::Plugin::CGI
1027 [% USE cgi %] # => Template::Plugin::CGI
1029 You can also define further plugins using the C<PLUGINS> option.
1031 my $tt = Template->new({
1033 foo => 'My::Plugin::Foo',
1034 bar => 'My::Plugin::Bar',
1038 The recommended convention is to specify these plugin names in lower
1039 case. The Template Toolkit first looks for an exact case-sensitive
1040 match and then tries the lower case conversion of the name specified.
1042 [% USE Foo %] # look for 'Foo' then 'foo'
1044 If you define all your C<PLUGINS> with lower case names then they will be
1045 located regardless of how the user specifies the name in the C<USE>
1046 directive. If, on the other hand, you define your C<PLUGINS> with upper
1047 or mixed case names then the name specified in the C<USE> directive must
1048 match the case exactly.
1050 If the plugin isn't defined in either the standard plugins
1051 (C<$Template::Plugins::STD_PLUGINS>) or via the C<PLUGINS> option, then
1052 the C<PLUGIN_BASE> is searched.
1054 In this case the plugin name I<is> case-sensitive. It is appended to
1055 each of the C<PLUGIN_BASE> module namespaces in turn (default:
1056 C<Template::Plugin>) to construct a full module name which it attempts
1057 to locate and load. Any periods, 'C<.>', in the name will be converted
1060 [% USE MyPlugin %] # => Template::Plugin::MyPlugin
1061 [% USE Foo.Bar %] # => Template::Plugin::Foo::Bar
1063 The C<LOAD_PERL> option (disabled by default) provides a further way by
1064 which external Perl modules may be loaded. If a regular Perl module
1065 (i.e. not a C<Template::Plugin::*> or other module relative to some
1066 C<PLUGIN_BASE>) supports an object-oriented interface and a C<new()>
1067 constructor then it can be loaded and instantiated automatically. The
1068 following trivial example shows how the IO::File module might be used.
1070 [% USE file = IO.File('/tmp/mydata') %]
1072 [% WHILE (line = file.getline) %]
1076 Any additional parameters supplied in parenthesis after the plugin
1077 name will be also be passed to the C<new()> constructor. A reference to
1078 the current L<Template::Context> object is passed as the first
1081 [% USE MyPlugin('foo', 123) %]
1085 Template::Plugin::MyPlugin->new($context, 'foo', 123);
1087 The only exception to this is when a module is loaded via the
1088 C<LOAD_PERL> option. In this case the C<$context> reference is I<not>
1089 passed to the C<new()> constructor. This is based on the assumption that
1090 the module is a regular Perl module rather than a Template Toolkit
1091 plugin so isn't expecting a context reference and wouldn't know what
1092 to do with it anyway.
1094 Named parameters may also be specified. These are collated into a
1095 hash which is passed by reference as the last parameter to the
1096 constructor, as per the general code calling interface.
1098 [% USE url('/cgi-bin/foo', mode='submit', debug=1) %]
1102 Template::Plugin::URL->new(
1105 { mode => 'submit', debug => 1 }
1108 The plugin may represent any data type; a simple variable, hash, list or
1109 code reference, but in the general case it will be an object reference.
1110 Methods can be called on the object (or the relevant members of the
1111 specific data type) in the usual way:
1113 [% USE table(mydata, rows=3) %]
1115 [% FOREACH row IN table.rows %]
1117 [% FOREACH item IN row %]
1123 An alternative name may be provided for the plugin by which it can be
1126 [% USE scores = table(myscores, cols=5) %]
1128 [% FOREACH row IN scores.rows %]
1132 You can use this approach to create multiple plugin objects with
1133 different configurations. This example shows how the
1134 L<format|Template::Plugin::Format> plugin is used to create
1135 sub-routines bound to variables for formatting text as per C<printf()>.
1137 [% USE bold = format('<b>%s</b>') %]
1138 [% USE ital = format('<i>%s</i>') %]
1139 [% bold('This is bold') %]
1140 [% ital('This is italic') %]
1145 <i>This is italic</i>
1147 This next example shows how the L<URL|Template::Plugin::URL> plugin can be
1148 used to build dynamic URLs from a base part and optional query parameters.
1150 [% USE mycgi = URL('/cgi-bin/foo.pl', debug=1) %]
1151 <a href="[% mycgi %]">...
1152 <a href="[% mycgi(mode='submit') %]"...
1156 <a href="/cgi-bin/foo.pl?debug=1">...
1157 <a href="/cgi-bin/foo.pl?mode=submit&debug=1">...
1159 The L<CGI|Template::Plugin::CGI> plugin is an example of one which delegates
1160 to another Perl module. In this this case, to Lincoln Stein's C<CGI> module.
1161 All of the methods provided by the C<CGI> module are available via the plugin.
1165 CGI.checkbox_group( name = 'colours',
1166 values = [ 'red' 'green' 'blue' ] );
1167 CGI.popup_menu( name = 'items',
1168 values = [ 'foo' 'bar' 'baz' ] );
1172 See L<Template::Manual::Plugins> for more information on the plugins
1173 distributed with the toolkit or available from CPAN.
1177 The C<MACRO> directive allows you to define a directive or directive block
1178 which is then evaluated each time the macro is called.
1180 [% MACRO header INCLUDE header %]
1182 Calling the macro as:
1186 is then equivalent to:
1188 [% INCLUDE header %]
1190 Macros can be passed named parameters when called. These values remain
1193 [% header(title='Hello World') %]
1197 [% INCLUDE header title='Hello World' %]
1199 A C<MACRO> definition may include parameter names. Values passed to the
1200 macros are then mapped to these local variables. Other named parameters
1203 [% MACRO header(title) INCLUDE header %]
1204 [% header('Hello World') %]
1205 [% header('Hello World', bgcol='#123456') %]
1209 [% INCLUDE header title='Hello World' %]
1210 [% INCLUDE header title='Hello World' bgcol='#123456' %]
1212 Here's another example, defining a macro for display numbers
1213 in comma-delimited groups of 3, using the chunk and join virtual
1216 [% MACRO number(n) GET n.chunk(-3).join(',') %]
1217 [% number(1234567) %] # 1,234,567
1219 A C<MACRO> may precede any directive and must conform to the structure
1222 [% MACRO header IF frames %]
1223 [% INCLUDE frames/header %]
1225 [% INCLUDE header %]
1230 A C<MACRO> may also be defined as an anonymous C<BLOCK>. The block will be
1231 evaluated each time the macro is called.
1233 [% MACRO header BLOCK %]
1239 If you've got the C<EVAL_PERL> option set, then you can even define a
1240 C<MACRO> as a C<PERL> block (see below):
1242 [% MACRO triple(n) PERL %]
1243 my $n = $stash->get('n');
1249 (for the advanced reader)
1251 The C<PERL> directive is used to mark the start of a block which contains
1252 Perl code for evaluation. The C<EVAL_PERL> option must be enabled for Perl
1253 code to be evaluated or a C<perl> exception will be thrown with the
1254 message 'C<EVAL_PERL not set>'.
1256 Perl code is evaluated in the C<Template::Perl> package. The C<$context>
1257 package variable contains a reference to the current L<Template::Context>
1258 object. This can be used to access the functionality of the Template
1259 Toolkit to process other templates, load plugins, filters, etc.
1260 See L<Template::Context> for further details.
1263 print $context->include('myfile');
1266 The L<$stash> variable contains a reference to the top-level stash object
1267 which manages template variables. Through this, variable values can
1268 be retrieved and updated. See L<Template::Stash> for further details.
1271 $stash->set(foo => 'bar');
1272 print "foo value: ", $stash->get('foo');
1279 Output is generated from the C<PERL> block by calling C<print()>. Note that
1280 the C<Template::Perl::PERLOUT> handle is selected (tied to an output
1281 buffer) instead of C<STDOUT>.
1285 print PERLOUT "bar\n"; # OK, same as above
1286 print Template::Perl::PERLOUT "baz\n"; # OK, same as above
1287 print STDOUT "qux\n"; # WRONG!
1290 The C<PERL> block may contain other template directives. These are
1291 processed before the Perl code is evaluated.
1293 [% name = 'Fred Smith' %]
1296 print "[% name %]\n";
1299 Thus, the Perl code in the above example is evaluated as:
1301 print "Fred Smith\n";
1303 Exceptions may be thrown from within C<PERL> blocks using C<die()>.
1304 They will be correctly caught by enclosing C<TRY> blocks.
1308 die "nothing to live for\n";
1311 error: [% error.info %]
1315 error: nothing to live for
1319 (for the very advanced reader)
1321 The Template Toolkit parser reads a source template and generates the
1322 text of a Perl subroutine as output. It then uses C<eval()> to evaluate
1323 it into a subroutine reference. This subroutine is then called to
1324 process the template, passing a reference to the current
1325 L<Template::Context> object through which the functionality of the
1326 Template Toolkit can be accessed. The subroutine reference can be
1327 cached, allowing the template to be processed repeatedly without
1328 requiring any further parsing.
1330 For example, a template such as:
1332 [% PROCESS header %]
1333 The [% animal %] sat on the [% location %]
1334 [% PROCESS footer %]
1336 is converted into the following Perl subroutine definition:
1339 my $context = shift;
1340 my $stash = $context->stash;
1345 $output .= $context->process('header');
1347 $output .= $stash->get('animal');
1348 $output .= " sat on the ";
1349 $output .= $stash->get('location');
1350 $output .= $context->process('footer');
1354 $error = $context->catch($@, \$output);
1355 die $error unless $error->type eq 'return';
1361 To examine the Perl code generated, such as in the above example, set
1362 the C<$Template::Parser::DEBUG> package variable to any true value. You
1363 can also set the C<$Template::Directive::PRETTY> variable true to have
1364 the code formatted in a readable manner for human consumption. The
1365 source code for each generated template subroutine will be printed to
1366 C<STDERR> on compilation (i.e. the first time a template is used).
1368 $Template::Parser::DEBUG = 1;
1369 $Template::Directive::PRETTY = 1;
1371 $template->process($file, $vars)
1372 || die $template->error(), "\n";
1374 The C<PERL> ... C<END> construct allows Perl code to be embedded into a
1375 template when the C<EVAL_PERL> option is set. It is evaluated at
1376 "runtime" using C<eval()> each time the template subroutine is called.
1377 This is inherently flexible, but not as efficient as it could be,
1378 especially in a persistent server environment where a template may be
1379 processed many times.
1381 The C<RAWPERL> directive allows you to write Perl code that is integrated
1382 directly into the generated Perl subroutine text. It is evaluated
1383 once at compile time and is stored in cached form as part of the
1384 compiled template subroutine. This makes C<RAWPERL> blocks more
1385 efficient than C<PERL> blocks.
1387 The downside is that you must code much closer to the metal. For example, in a
1388 C<PERL> block you can call L<print()> to generate some output. C<RAWPERL>
1389 blocks don't afford such luxury. The code is inserted directly into the
1390 generated subroutine text and should conform to the convention of appending to
1391 the C<$output> variable.
1393 [% PROCESS header %]
1396 $output .= "Some output\n";
1398 $output .= "Some more output\n";
1401 The critical section of the generated subroutine for this example would
1402 then look something like:
1406 $output .= $context->process('header');
1408 $output .= "Some output\n";
1410 $output .= "Some more output\n";
1415 As with C<PERL> blocks, the L<$context|Template::Context> and
1416 L<$stash|Template::Stash> references are pre-defined and available for use
1417 within C<RAWPERL> code.
1419 =head1 Exception Handling and Flow Control
1421 =head2 TRY / THROW / CATCH / FINAL
1423 (more advanced material)
1425 The Template Toolkit supports fully functional, nested exception
1426 handling. The C<TRY> directive introduces an exception handling scope
1427 which continues until the matching C<END> directive. Any errors that
1428 occur within that block will be caught and can be handled by one
1429 of the C<CATCH> blocks defined.
1435 [% INCLUDE someblock %]
1441 Errors are raised as exceptions (objects of the L<Template::Exception> class)
1442 which contain two fields: C<type> and C<info>. The exception C<type> is used
1443 to indicate the kind of error that occurred. It is a simple text string which
1444 can contain letters, numbers, 'C<_>' or 'C<.>'. The C<info> field contains an
1445 error message indicating what actually went wrong. Within a catch block, the
1446 exception object is aliased to the C<error> variable. You can access the C<type>
1447 and C<info> fields directly.
1449 [% mydsn = 'dbi:MySQL:foobar' %]
1453 [% USE DBI(mydsn) %]
1455 ERROR! Type: [% error.type %]
1456 Info: [% error.info %]
1459 output (assuming a non-existant database called 'C<foobar>'):
1462 Info: Unknown database "foobar"
1464 The C<error> variable can also be specified by itself and will return a
1465 string of the form "C<$type error - $info>".
1474 ERROR: DBI error - Unknown database "foobar"
1476 Each C<CATCH> block may be specified with a particular exception type
1477 denoting the kind of error that it should catch. Multiple C<CATCH>
1478 blocks can be provided to handle different types of exception that may
1479 be thrown in the C<TRY> block. A C<CATCH> block specified without any type,
1480 as in the previous example, is a default handler which will catch any
1481 otherwise uncaught exceptions. This can also be specified as
1482 C<[% CATCH DEFAULT %]>.
1485 [% INCLUDE myfile %]
1486 [% USE DBI(mydsn) %]
1489 File Error! [% error.info %]
1491 [% INCLUDE database/error.html %]
1496 Remember that you can specify multiple directives within a single tag,
1497 each delimited by 'C<;>'. So the above example can be written more
1505 "File Error! $error.info";
1507 INCLUDE database/error.html;
1513 The C<DBI> plugin throws exceptions of the C<DBI> type (in case that
1514 wasn't already obvious). The other specific exception caught here is
1515 of the C<file> type.
1517 A C<file> exception is automatically thrown by the Template Toolkit when it
1518 can't find a file, or fails to load, parse or process a file that has been
1519 requested by an C<INCLUDE>, C<PROCESS>, C<INSERT> or C<WRAPPER> directive.
1520 If C<myfile> can't be found in the example above, the C<[% INCLUDE myfile %]>
1521 directive will raise a C<file> exception which is then caught by the
1522 C<[% CATCH file %]> block. The output generated would be:
1524 File Error! myfile: not found
1526 Note that the C<DEFAULT> option (disabled by default) allows you to specify a
1527 default file to be used any time a template file can't be found. This will
1528 prevent file exceptions from ever being raised when a non-existant file is
1529 requested (unless, of course, the C<DEFAULT> file your specify doesn't exist).
1530 Errors encountered once the file has been found (i.e. read error, parse error)
1531 will be raised as file exceptions as per usual.
1533 Uncaught exceptions (i.e. if the C<TRY> block doesn't have a type specific or
1534 default C<CATCH> handler) may be caught by enclosing C<TRY> blocks which can
1535 be nested indefinitely across multiple templates. If the error isn't caught at
1536 any level then processing will stop and the Template
1537 L<process()|Template#process()> method will return a false value to the
1538 caller. The relevant L<Template::Exception> object can be retrieved by calling
1539 the L<error()|Template#error()> method.
1544 [% INCLUDE $user.header %]
1546 [% INCLUDE header %]
1550 [% INCLUDE database/error.html %]
1553 In this example, the inner C<TRY> block is used to ensure that the first
1554 C<INCLUDE> directive works as expected. We're using a variable to
1555 provide the name of the template we want to include, C<user.header>, and
1556 it's possible this contains the name of a non-existant template, or
1557 perhaps one containing invalid template directives. If the C<INCLUDE> fails
1558 with a C<file> error then we C<CATCH> it in the inner block and C<INCLUDE>
1559 the default C<header> file instead. Any C<DBI> errors that occur within
1560 the scope of the outer C<TRY> block will be caught in the relevant C<CATCH>
1561 block, causing the C<database/error.html> template to be processed.
1562 Note that included templates inherit all currently defined template
1563 variable so these error files can quite happily access the <error>
1564 variable to retrieve information about the currently caught exception.
1565 For example, the C<database/error.html> template might look like this:
1567 <h2>Database Error</h2>
1568 A database error has occurred: [% error.info %]
1570 You can also specify a C<FINAL> block. This is always processed
1571 regardless of the outcome of the C<TRY> and/or C<CATCH> blocks. If an
1572 exception is uncaught then the C<FINAL> block is processed before jumping
1573 to the enclosing block or returning to the caller.
1585 The output from the C<TRY> block is left intact up to the point where an
1586 exception occurs. For example, this template:
1590 [% THROW food 'carrots' %]
1593 culinary delights: [% error.info %]
1596 generates the following output:
1599 culinary delights: carrots
1601 The C<CLEAR> directive can be used in a C<CATCH> or C<FINAL> block to clear
1602 any output created in the C<TRY> block.
1606 [% THROW food 'carrots' %]
1610 culinary delights: [% error.info %]
1615 culinary delights: carrots
1617 Exception types are hierarchical, with each level being separated by
1618 the familiar dot operator. A C<DBI.connect> exception is a more
1619 specific kind of C<DBI> error. Similarly, an C<example.error.barf> is a
1620 more specific kind of C<example.error> type which itself is also a
1623 A C<CATCH> handler that specifies a general exception
1624 type (such as C<DBI> or C<example.error>) will also catch more specific
1625 types that have the same prefix as long as a more specific handler
1626 isn't defined. Note that the order in which C<CATCH> handlers are
1627 defined is irrelevant; a more specific handler will always catch an
1628 exception in preference to a more generic or default one.
1633 INCLUDE database/error.html ;
1635 INCLUDE database/connect.html ;
1637 INCLUDE error.html ;
1641 In this example, a C<DBI.connect> error has it's own handler, a more general
1642 C<DBI> block is used for all other C<DBI> or C<DBI.*> errors and a default
1643 handler catches everything else.
1645 Exceptions can be raised in a template using the C<THROW> directive. The
1646 first parameter is the exception type which doesn't need to be quoted
1647 (but can be, it's the same as C<INCLUDE>) followed by the relevant error
1648 message which can be any regular value such as a quoted string,
1651 [% THROW food "Missing ingredients: $recipe.error" %]
1652 [% THROW user.login 'no user id: please login' %]
1653 [% THROW $myerror.type "My Error: $myerror.info" %]
1655 It's also possible to specify additional positional or named
1656 parameters to the C<THROW> directive if you want to pass more than
1657 just a simple message back as the error info field.
1659 [% THROW food 'eggs' 'flour' msg='Missing Ingredients' %]
1661 In this case, the error C<info> field will be a hash array containing the
1662 named arguments and an C<args> item which contains a list of the positional
1667 msg => 'Missing Ingredients',
1668 args => ['eggs', 'flour'],
1671 In addition to specifying individual positional arguments as
1672 C<[% error.info.args.n %]>, the C<info> hash contains keys directly
1673 pointing to the positional arguments, as a convenient shortcut.
1675 [% error.info.0 %] # same as [% error.info.args.0 %]
1677 Exceptions can also be thrown from Perl code which you've bound to
1678 template variables, or defined as a plugin or other extension. To
1679 raise an exception, call C<die()> passing a reference to a
1680 L<Template::Exception> object as the argument. This will then be caught
1681 by any enclosing C<TRY> blocks from where the code was called.
1683 use Template::Exception;
1687 # ... do something ...
1688 die Template::Exception->new('myerr.naughty',
1704 Error: myerr.naughty error - Bad, bad error
1706 The C<info> field can also be a reference to another object or data
1707 structure, if required.
1709 die Template::Exception->new('myerror', {
1711 errors => [ 'bad permissions', 'naughty boy' ],
1714 Later, in a template:
1719 [% error.info.errors.size or 'no';
1720 error.info.errors.size == 1 ? ' error' : ' errors' %]
1721 in [% error.info.module %]:
1722 [% error.info.errors.join(', ') %].
1725 Generating the output:
1728 bad permissions, naughty boy.
1730 You can also call C<die()> with a single string, as is common in much
1731 existing Perl code. This will automatically be converted to an
1732 exception of the 'C<undef>' type (that's the literal string 'C<undef>',
1733 not the undefined value). If the string isn't terminated with a
1734 newline then Perl will append the familiar C<" at $file line $line">
1738 # ... do something ...
1739 die "I'm sorry, Dave, I can't do that\n";
1742 If you're writing a plugin, or some extension code that has the current
1743 L<Template::Context> in scope (you can safely skip this section if this means
1744 nothing to you) then you can also raise an exception by calling the context
1745 L<throw()|Template::Context#throw()> method. You can pass it an
1746 L<Template::Exception> object reference, a pair of C<($type, $info)>
1747 parameters or just an C<$info> string to create an exception of 'C<undef>' type.
1749 $context->throw($e); # exception object
1750 $context->throw('Denied'); # 'undef' type
1751 $context->throw('user.passwd', 'Bad Password');
1755 The C<NEXT> directive can be used to start the next iteration of a C<FOREACH>
1758 [% FOREACH user IN users %]
1759 [% NEXT IF user.isguest %]
1760 Name: [% user.name %] Email: [% user.email %]
1765 The C<LAST> directive can be used to prematurely exit a C<FOREACH> or C<WHILE>
1768 [% FOREACH user IN users %]
1769 Name: [% user.name %] Email: [% user.email %]
1770 [% LAST IF some.condition %]
1773 C<BREAK> can also be used as an alias for C<LAST>.
1777 The C<RETURN> directive can be used to stop processing the current template
1778 and return to the template from which it was called, resuming processing at
1779 the point immediately after the C<INCLUDE>, C<PROCESS> or C<WRAPPER>
1780 directive. If there is no enclosing template then the Template
1781 L<process()|Template#process()> method will return to the calling code with a
1785 [% INCLUDE half_wit %]
1788 [% BLOCK half_wit %]
1789 This is just half...
1797 This is just half...
1802 The C<STOP> directive can be used to indicate that the processor should stop
1803 gracefully without processing any more of the template document. This is a
1804 planned stop and the Template L<process()|Template#process()> method will
1805 return a B<true> value to the caller. This indicates that the template was
1806 processed successfully according to the directives within it.
1808 [% IF something.terrible.happened %]
1809 [% INCLUDE fatal/error.html %]
1814 [% USE DBI(mydsn) %]
1816 [% CATCH DBI.connect %]
1817 <h1>Cannot connect to the database: [% error.info %]</h1>
1819 We apologise for the inconvenience.
1821 [% INCLUDE footer %]
1827 The C<CLEAR> directive can be used to clear the output buffer for the current
1828 enclosing block. It is most commonly used to clear the output generated
1829 from a C<TRY> block up to the point where the error occurred.
1832 blah blah blah # this is normally left intact
1833 [% THROW some 'error' %] # up to the point of error
1836 [% CLEAR %] # clear the TRY output
1837 [% error %] # print error string
1840 =head1 Miscellaneous
1844 The C<META> directive allows simple metadata items to be defined within a
1845 template. These are evaluated when the template is parsed and as such may only
1846 contain simple values (e.g. it's not possible to interpolate other variables
1847 values into C<META> variables).
1850 title = 'The Cat in the Hat'
1851 author = 'Dr. Seuss'
1855 The C<template> variable contains a reference to the main template
1856 being processed. These metadata items may be retrieved as attributes
1859 <h1>[% template.title %]</h1>
1860 <h2>[% template.author %]</h2>
1862 The C<name> and C<modtime> metadata items are automatically defined for each
1863 template to contain its name and modification time in seconds since the epoch.
1865 [% USE date %] # use Date plugin to format time
1867 [% template.name %] last modified
1868 at [% date.format(template.modtime) %]
1870 The C<PRE_PROCESS> and C<POST_PROCESS> options allow common headers and
1871 footers to be added to all templates. The C<template> reference is
1872 correctly defined when these templates are processed, allowing headers
1873 and footers to reference metadata items from the main template.
1875 $template = Template->new({
1876 PRE_PROCESS => 'header',
1877 POST_PROCESS => 'footer',
1880 $template->process('cat_in_hat');
1886 <title>[% template.title %]</title>
1893 title = 'The Cat in the Hat'
1894 author = 'Dr. Seuss'
1899 The cat in the hat sat on the mat.
1904 © [% template.year %] [% template.author %]
1908 The output generated from the above example is:
1912 <title>The Cat in the Hat</title>
1915 The cat in the hat sat on the mat.
1917 © 2000 Dr. Seuss
1923 The C<TAGS> directive can be used to set the C<START_TAG> and C<END_TAG> values
1924 on a per-template file basis.
1928 <+ INCLUDE header +>
1930 The TAGS directive may also be used to set a named C<TAG_STYLE>
1933 <!-- INCLUDE header -->
1935 See the L<TAGS|Template::Manual::Config#TAGS> and L<TAG_STYLE|Template::Manual::Config#TAG_STYLE>
1936 configuration options for further details.
1940 The C<DEBUG> directive can be used to enable or disable directive debug
1941 messages within a template. The C<DEBUG> configuration option must be
1942 set to include C<DEBUG_DIRS> for the C<DEBUG> directives to have any effect.
1943 If C<DEBUG_DIRS> is not set then the parser will automatically ignore and
1944 remove any C<DEBUG> directives.
1946 The C<DEBUG> directive can be used with an C<on> or C<off> parameter to
1947 enable or disable directive debugging messages from that point
1948 forward. When enabled, the output of each directive in the generated
1949 output will be prefixed by a comment indicate the file, line and
1950 original directive text.
1953 directive debugging is on (assuming DEBUG option is set true)
1955 directive debugging is off
1957 The C<format> parameter can be used to change the format of the debugging
1960 [% DEBUG format '<!-- $file line $line : [% $text %] -->' %]
1966 # perl-indent-level: 4
1967 # indent-tabs-mode: nil
1970 # vim: expandtab shiftwidth=4: