3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
6
<title>Template::Manual::Directives</title>
7
<link rel="stylesheet" type="text/css" href="../css/blue.css" title="Clear Blue">
8
<link rel="alternate stylesheet" type="text/css" href="../css/orange.css" title="Clear Orange">
9
<link rel="alternate stylesheet" type="text/css" href="../css/green.css" title="Clear Green">
10
<link rel="alternate stylesheet" type="text/css" href="../css/purple.css" title="Clear Purple">
11
<link rel="alternate stylesheet" type="text/css" href="../css/grey.css" title="Clear Grey">
13
<link rel="stylesheet" type="text/css" href="../css/ie6.css" />
15
<link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
16
<script type="text/javascript" src="../js/tt2.js"></script>
17
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
18
<meta name="author" content="Andy Wardley">
23
<a href="../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
25
<li><a href="../manual/index.html">Manual</a></li>
26
<li class="last"><a href="../manual/Directives.html">Directives</a></li>
28
<div class="controls">
29
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
30
<span class="about">Click to view the menu. It's very nice.</span>
32
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
33
<span class="about">Click to hide the menu and go all widescreen!</span>
37
<a href="../manual/Syntax.html" title="Template::Manual::Syntax" class="go back">Back<span class="about"><h4>Template::Manual::Syntax</h4>Directive syntax, structure and semantics</span></a>
38
<a href="../manual/index.html" title="Template::Manual" class="go up">Up<span class="about"><h4>Template::Manual</h4>Template Toolkit User Manual</span></a>
39
<a href="../manual/Variables.html" title="Template::Manual::Variables" class="go next">Next<span class="about"><h4>Template::Manual::Variables</h4>Template variables and code bindings</span></a>
42
<h1 class="headline">Template::Manual::Directives</h1>
43
<h2 class="subhead">Template directives</h1>
48
<a href="../index.html" id="logo"></a>
51
<li class="l0 first"><a href="../manual/index.html" class="warm">Manual</a></li>
52
<li class="l1"><a href="../manual/Intro.html">Intro</a></li>
53
<li class="l1"><a href="../manual/Syntax.html">Syntax</a></li>
54
<li class="l1"><a href="../manual/Directives.html" class="warm">Directives</a></li>
55
<li class="l1"><a href="../manual/Variables.html">Variables</a></li>
56
<li class="l1"><a href="../manual/VMethods.html">VMethods</a></li>
57
<li class="l1"><a href="../manual/Config.html">Config</a></li>
58
<li class="l1"><a href="../manual/Filters.html">Filters</a></li>
59
<li class="l1"><a href="../manual/Plugins.html">Plugins</a></li>
60
<li class="l1"><a href="../manual/Internals.html">Internals</a></li>
61
<li class="l1"><a href="../manual/Views.html">Views</a></li>
62
<li class="l1"><a href="../manual/Credits.html">Credits</a></li>
63
<li class="l0"><a href="../modules/index.html">Modules</a></li>
64
<li class="l0"><a href="../tools/index.html">Tools</a></li>
65
<li class="l0 last"><a href="../tutorial/index.html">Tutorial</a></li>
67
<div class="foot"></div>
73
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
74
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
78
<li class=""><a href="#Accessing_and_Updating_Template_Variables">Accessing and Updating Template Variables</a></li>
79
<li class="sub"><a href="#section_GET">GET</a></li>
80
<li class="sub"><a href="#section_CALL">CALL</a></li>
81
<li class="sub"><a href="#section_SET">SET</a></li>
82
<li class="sub"><a href="#section_DEFAULT">DEFAULT</a></li>
83
<li class=""><a href="#Processing_Template_Files_and_Blocks">Processing Template Files and Blocks</a></li>
84
<li class="sub"><a href="#section_INSERT">INSERT</a></li>
85
<li class="sub"><a href="#section_INCLUDE">INCLUDE</a></li>
86
<li class="sub"><a href="#section_PROCESS">PROCESS</a></li>
87
<li class="sub"><a href="#section_WRAPPER">WRAPPER</a></li>
88
<li class="sub"><a href="#section_BLOCK">BLOCK</a></li>
89
<li class=""><a href="#Conditional_Processing">Conditional Processing</a></li>
90
<li class="sub"><a href="#section_IF_UNLESS_ELSIF_ELSE">IF / UNLESS / ELSIF / ELSE</a></li>
91
<li class="sub"><a href="#section_SWITCH_CASE">SWITCH / CASE</a></li>
92
<li class=""><a href="#Loop_Processing">Loop Processing</a></li>
93
<li class="sub"><a href="#section_FOREACH">FOREACH</a></li>
94
<li class="sub"><a href="#section_WHILE">WHILE</a></li>
95
<li class=""><a href="#Filters_Plugins_Macros_and_Perl">Filters, Plugins, Macros and Perl</a></li>
96
<li class="sub"><a href="#section_FILTER">FILTER</a></li>
97
<li class="sub"><a href="#section_USE">USE</a></li>
98
<li class="sub"><a href="#section_MACRO">MACRO</a></li>
99
<li class="sub"><a href="#section_PERL">PERL</a></li>
100
<li class="sub"><a href="#section_RAWPERL">RAWPERL</a></li>
101
<li class=""><a href="#Exception_Handling_and_Flow_Control">Exception Handling and Flow Control</a></li>
102
<li class="sub"><a href="#section_TRY_THROW_CATCH_FINAL">TRY / THROW / CATCH / FINAL</a></li>
103
<li class="sub"><a href="#section_NEXT">NEXT</a></li>
104
<li class="sub"><a href="#section_LAST">LAST</a></li>
105
<li class="sub"><a href="#section_RETURN">RETURN</a></li>
106
<li class="sub"><a href="#section_STOP">STOP</a></li>
107
<li class="sub"><a href="#section_CLEAR">CLEAR</a></li>
108
<li class=""><a href="#Miscellaneous">Miscellaneous</a></li>
109
<li class="sub"><a href="#section_META">META</a></li>
110
<li class="sub"><a href="#section_TAGS">TAGS</a></li>
111
<li class="sub"><a href="#section_DEBUG">DEBUG</a></li>
118
<div class="section">
120
<h1 id="Accessing_and_Updating_Template_Variables" onclick="switch_section(this)" title="Click title to show/hide section content.">Accessing and Updating Template Variables</h1>
121
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
124
<div class="subsection">
126
<h2 id="section_GET" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">GET</h2>
127
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
131
The <code>GET</code> directive retrieves and outputs the value of the
134
<pre>[% GET foo %]</pre>
136
The <code>GET</code> keyword is optional. A variable can be specified in
137
a directive tag by itself.
141
The variable can have an unlimited number of elements, each separated by
142
a dot. Each element can have arguments specified within parentheses.
149
See <a href="../manual/Variables.html">Template::Manual::Variables</a> for a full discussion on template
153
You can also specify expressions using the logical (<code>and</code>,
154
<code>or</code>, <code>not</code>, <code>?</code>, <code>:</code>) and
155
mathematic operators (<code>+</code>, <code>-</code>, <code>*</code>,
156
<code>/</code>, <code>%</code>, <code>mod</code>, <code>div</code>).
158
<pre>[% template.title or default.title %]
162
[% order.nitems ? checkout(order.total) : 'no items' %]</pre>
164
The <code>div</code> operator returns the integer result of division.
165
Both <code>%</code> and <code>mod</code> return the modulus (i.e.
166
remainder) of division.
168
<pre>[% 15 / 6 %] # 2.5
170
[% 15 mod 6 %] # 3</pre>
172
</div> <div class="subsection">
174
<h2 id="section_CALL" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">CALL</h2>
175
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
179
The <code>CALL</code> directive is similar to <code>GET</code> in
180
evaluating the variable named, but doesn't print the result returned.
181
This can be useful when a variable is bound to a sub-routine or object
182
method which you want to call but aren't interested in the value
185
<pre>[% CALL dbi.disconnect %]
187
[% CALL inc_page_counter(page_count) %]</pre>
189
</div> <div class="subsection">
191
<h2 id="section_SET" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">SET</h2>
192
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
196
The <code>SET</code> directive allows you to assign new values to
197
existing variables or create new temporary variables.
199
<pre>[% SET title = 'Hello World' %]</pre>
201
The <code>SET</code> keyword is also optional. [% title = 'Hello World'
205
Variables may be assigned the values of other variables, unquoted numbers
206
(2.718), literal text ('single quotes') or quoted text ("double quotes").
207
In the latter case, any variable references within the text will be
208
interpolated when the string is evaluated. Variables should be prefixed
209
by <code>$</code>, using curly braces to explicitly scope the variable
210
name where necessary.
212
<pre>[% foo = 'Foo' %] # literal value 'Foo'
213
[% bar = foo %] # value of variable 'foo'
214
[% cost = '$100' %] # literal value '$100'
215
[% item = "$bar: ${cost}.00" %] # value "Foo: $100.00"</pre>
217
Multiple variables may be assigned in the same directive and are
218
evaluated in the order specified. Thus, the above could have been
224
item = "$bar: ${cost}.00"
227
Simple expressions can also be used, as per <code>GET</code>.
231
thirty = twenty + ten
237
You can concatenate strings together using the <code>' _ '</code>
238
operator. In Perl 5, the <code>.</code> is used for string concatenation,
239
but in Perl 6, as in the Template Toolkit, the <code>.</code> will be
240
used as the method calling operator and <code>' _ '</code> will be used
241
for string concatenation. Note that the operator must be specified with
242
surrounding whitespace which, as Larry says, is construed as a feature:
244
<pre>[% copyright = '(C) Copyright' _ year _ ' ' _ author %]</pre>
246
You can, of course, achieve a similar effect with double quoted string
249
<pre>[% copyright = "(C) Copyright $year $author" %]</pre>
251
</div> <div class="subsection">
253
<h2 id="section_DEFAULT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">DEFAULT</h2>
254
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
258
The <code>DEFAULT</code> directive is similar to <code>SET</code> but
259
only updates variables that are currently undefined or have no "true"
260
value (in the Perl sense).
267
This can be particularly useful in common template components to ensure
268
that some sensible default are provided for otherwise undefined
272
title = 'Hello World'
277
<title>[% title %]</title>
279
<body bgcolor="[% bgcol %]">
285
<div class="section">
287
<h1 id="Processing_Template_Files_and_Blocks" onclick="switch_section(this)" title="Click title to show/hide section content.">Processing Template Files and Blocks</h1>
288
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
291
<div class="subsection">
293
<h2 id="section_INSERT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">INSERT</h2>
294
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
298
The <code>INSERT</code> directive is used to insert the contents of an
299
external file at the current position.
301
<pre>[% INSERT myfile %]</pre>
303
No attempt to parse or process the file is made. The contents, possibly
304
including any embedded template directives, are inserted intact.
307
The filename specified should be relative to one of the
308
<code>INCLUDE_PATH</code> directories. Absolute (i.e. starting with
309
<code>/</code>) and relative (i.e. starting with <code>.</code>)
310
filenames may be used if the <code>ABSOLUTE</code> and
311
<code>RELATIVE</code> options are set, respectively. Both these options
312
are disabled by default.
314
<pre>my $template = Template->new({
315
INCLUDE_PATH => '/here:/there',
318
$template->process('myfile');</pre>
322
<pre>[% INSERT foo %] # looks for /here/foo then /there/foo
323
[% INSERT /etc/passwd %] # file error: ABSOLUTE not set
324
[% INSERT ../secret %] # file error: RELATIVE not set</pre>
326
For convenience, the filename does not need to be quoted as long as it
327
contains only alphanumeric characters, underscores, dots or forward
328
slashes. Names containing any other characters should be quoted.
330
<pre>[% INSERT misc/legalese.txt %]
331
[% INSERT 'dos98/Program Files/stupid' %]</pre>
333
To evaluate a variable to specify a filename, you should explicitly
334
prefix it with a <code>$</code> or use double-quoted string
337
<pre>[% language = 'en'
338
legalese = 'misc/legalese.txt'
341
[% INSERT $legalese %] # misc/legalese.txt
342
[% INSERT "$language/$legalese" %] # en/misc/legalese.txt</pre>
344
Multiple files can be specified using <code>+</code> as a delimiter. All
345
files should be unquoted names or quoted strings. Any variables should be
346
interpolated into double-quoted strings.
348
<pre>[% INSERT legalese.txt + warning.txt %]
349
[% INSERT "$legalese" + warning.txt %] # requires quoting</pre>
351
</div> <div class="subsection">
353
<h2 id="section_INCLUDE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">INCLUDE</h2>
354
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
358
The <code>INCLUDE</code> directive is used to process and include the
359
output of another template file or block.
361
<pre>[% INCLUDE header %]</pre>
363
If a <code>BLOCK</code> of the specified name is defined in the same
364
file, or in a file from which the current template has been called (i.e.
365
a parent template) then it will be used in preference to any file of the
368
<pre>[% INCLUDE table %] # uses BLOCK defined below
376
If a <code>BLOCK</code> definition is not currently visible then the
377
template name should be a file relative to one of the
378
<code>INCLUDE_PATH</code> directories, or an absolute or relative file
379
name if the <code>ABSOLUTE</code>/<code>RELATIVE</code> options are
380
appropriately enabled. The <code>INCLUDE</code> directive automatically
381
quotes the filename specified, as per <code>INSERT</code> described
382
above. When a variable contains the name of the template for the
383
<code>INCLUDE</code> directive, it should be explicitly prefixed by
384
<code>$</code> or double-quoted
386
<pre>[% myheader = 'my/misc/header' %]
387
[% INCLUDE myheader %] # 'myheader'
388
[% INCLUDE $myheader %] # 'my/misc/header'
389
[% INCLUDE "$myheader" %] # 'my/misc/header'</pre>
391
Any template directives embedded within the file will be processed
392
accordingly. All variables currently defined will be visible and
393
accessible from within the included template.
395
<pre>[% title = 'Hello World' %]
403
<title>[% title %]</title></pre>
408
<title>Hello World</title>
412
Local variable definitions may be specified after the template name,
413
temporarily masking any existing variables. Insignificant whitespace is
414
ignored within directives so you can add variable definitions on the same
415
line, the next line or split across several line with comments
416
interspersed, if you prefer.
418
<pre>[% INCLUDE table %]
420
[% INCLUDE table title="Active Projects" %]
423
title = "Active Projects"
424
bgcolor = "#80ff00" # chartreuse
428
The <code>INCLUDE</code> directive localises (i.e. copies) all variables
429
before processing the template. Any changes made within the included
430
template will not affect variables in the including template.
434
foo is originally [% foo %]
436
foo is still [% foo %]
446
<pre>foo is originally 10
449
foo is still 10</pre>
451
Technical Note: the localisation of the stash (that is, the process by
452
which variables are copied before an <code>INCLUDE</code> to prevent
453
being overwritten) is only skin deep. The top-level variable namespace
454
(hash) is copied, but no attempt is made to perform a deep-copy of other
455
structures (hashes, arrays, objects, etc.) Therefore, a <code>foo</code>
456
variable referencing a hash will be copied to create a new
457
<code>foo</code> variable but which points to the same hash array. Thus,
458
if you update compound variables (e.g. <code>foo.bar</code>) then you
459
will change the original copy, regardless of any stash localisation. If
460
you're not worried about preserving variable values, or you trust the
461
templates you're including then you might prefer to use the
462
<code>PROCESS</code> directive which is faster by virtue of not
463
performing any localisation.
466
You can specify dotted variables as "local" variables to an
467
<code>INCLUDE</code> directive. However, be aware that because of the
468
localisation issues explained above (if you skipped the previous
469
Technical Note above then you might want to go back and read it or skip
470
this section too), the variables might not actualy be "local". If the
471
first element of the variable name already references a hash array then
472
the variable update will affect the original variable.
479
[% INCLUDE somefile foo.bar='Boz' %]
481
[% foo.bar %] # Boz</pre>
483
This behaviour can be a little unpredictable (and may well be improved
484
upon in a future version). If you know what you're doing with it and
485
you're sure that the variables in question are defined (nor not) as you
486
expect them to be, then you can rely on this feature to implement some
487
powerful "global" data sharing techniques. Otherwise, you might prefer to
488
steer well clear and always pass simple (undotted) variables as
489
parameters to <code>INCLUDE</code> and other similar directives.
492
If you want to process several templates in one go then you can specify
493
each of their names (quoted or unquoted names only, no unquoted
494
<code>$variables</code>) joined together by <code>+</code>. The
495
<code>INCLUDE</code> directive will then process them in order.
497
<pre>[% INCLUDE html/header + "site/$header" + site/menu
498
title = "My Groovy Web Site"
501
The variable stash is localised once and then the templates specified are
502
processed in order, all within that same variable context. This makes it
503
slightly faster than specifying several separate <code>INCLUDE</code>
504
directives (because you only clone the variable stash once instead of n
505
times), but not quite as "safe" because any variable changes in the first
506
file will be visible in the second, third and so on. This might be what
507
you want, of course, but then again, it might not.
510
</div> <div class="subsection">
512
<h2 id="section_PROCESS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PROCESS</h2>
513
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
517
The PROCESS directive is similar to <code>INCLUDE</code> but does not
518
perform any localisation of variables before processing the template. Any
519
changes made to variables within the included template will be visible in
520
the including template.
530
changed foo to [% foo %]
539
Parameters may be specified in the <code>PROCESS</code> directive, but
540
these too will become visible changes to current variable values.
550
this is bar, foo is [% foo %]
556
this is bar, foo is 20
559
The <code>PROCESS</code> directive is slightly faster than
560
<code>INCLUDE</code> because it avoids the need to localise (i.e. copy)
561
the variable stash before processing the template. As with
562
<code>INSERT</code> and <code>INCLUDE</code>, the first parameter does
563
not need to be quoted as long as it contains only alphanumeric
564
characters, underscores, periods or forward slashes. A <code>$</code>
565
prefix can be used to explicitly indicate a variable which should be
566
interpolated to provide the template name:
568
<pre>[% myheader = 'my/misc/header' %]
569
[% PROCESS myheader %] # 'myheader'
570
[% PROCESS $myheader %] # 'my/misc/header'</pre>
572
As with <code>INCLUDE</code>, multiple templates can be specified,
573
delimited by <code>+</code>, and are processed in order.
575
<pre>[% PROCESS html/header + my/header %]</pre>
577
</div> <div class="subsection">
579
<h2 id="section_WRAPPER" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">WRAPPER</h2>
580
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
584
It's not unusual to find yourself adding common headers and footers to
585
pages or sub-sections within a page. Something like this:
587
<pre>[% INCLUDE section/header
588
title = 'Quantum Mechanics'
590
Quantum mechanics is a very interesting subject wish
591
should prove easy for the layman to fully comprehend.
592
[% INCLUDE section/footer %]
594
[% INCLUDE section/header
595
title = 'Desktop Nuclear Fusion for under $50'
597
This describes a simple device which generates significant
598
sustainable electrical power from common tap water by process
600
[% INCLUDE section/footer %]</pre>
602
The individual template components being included might look like these:
608
<h2>[% title %]</h2></pre>
612
<pre></p></pre>
614
The <code>WRAPPER</code> directive provides a way of simplifying this a
615
little. It encloses a block up to a matching <code>END</code> directive,
616
which is first processed to generate some output. This is then passed to
617
the named template file or <code>BLOCK</code> as the <code>content</code>
620
<pre>[% WRAPPER section
621
title = 'Quantum Mechanics'
623
Quantum mechanics is a very interesting subject wish
624
should prove easy for the layman to fully comprehend.
628
title = 'Desktop Nuclear Fusion for under $50'
630
This describes a simple device which generates significant
631
sustainable electrical power from common tap water by process
635
The single 'section' template can then be defined as:
637
<pre><h2>[% title %]</h2>
642
Like other block directives, it can be used in side-effect notation:
644
<pre>[% INSERT legalese.txt WRAPPER big_bold_table %]</pre>
646
It's also possible to specify multiple templates to a
647
<code>WRAPPER</code> directive. The specification order indicates
648
outermost to innermost wrapper templates. For example, given the
649
following template block definitions:
651
<pre>[% BLOCK bold %]<b>[% content %]</b>[% END %]
652
[% BLOCK italic %]<i>[% content %]</i>[% END %]</pre>
656
<pre>[% WRAPPER bold+italic %]Hello World[% END %]</pre>
658
would generate the following output:
660
<pre><b><i>Hello World</i></b></pre>
662
</div> <div class="subsection">
664
<h2 id="section_BLOCK" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">BLOCK</h2>
665
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
669
The <code>BLOCK</code>...<code>END</code> construct can be used to define
670
template component blocks which can be processed with the
671
<code>INCLUDE</code>, <code>PROCESS</code> and <code>WRAPPER</code>
674
<pre>[% BLOCK tabrow %]
676
<td>[% name %]<td>
677
<td>[% email %]</td>
682
[% PROCESS tabrow name='Fred' email='fred@nowhere.com' %]
683
[% PROCESS tabrow name='Alan' email='alan@nowhere.com' %]
686
A <code>BLOCK</code> definition can be used before it is defined, as long
687
as the definition resides in the same file. The block definition itself
688
does not generate any output.
690
<pre>[% PROCESS tmpblk %]
692
[% BLOCK tmpblk %] This is OK [% END %]</pre>
694
You can use an anonymous <code>BLOCK</code> to capture the output of a
697
<pre>[% julius = BLOCK %]
698
And Caesar's spirit, ranging for revenge,
699
With Ate by his side come hot from hell,
700
Shall in these confines with a monarch's voice
701
Cry 'Havoc', and let slip the dogs of war;
702
That this foul deed shall smell above the earth
703
With carrion men, groaning for burial.
706
Like a named block, it can contain any other template directives which
707
are processed when the block is defined. The output generated by the
708
block is then assigned to the variable <code>julius</code>.
711
Anonymous <code>BLOCK</code>s can also be used to define block macros.
712
The enclosing block is processed each time the macro is called.
714
<pre>[% MACRO locate BLOCK %]
715
The [% animal %] sat on the [% place %].
718
[% locate(animal='cat', place='mat') %] # The cat sat on the mat
719
[% locate(animal='dog', place='log') %] # The dog sat on the log</pre>
724
<div class="section">
726
<h1 id="Conditional_Processing" onclick="switch_section(this)" title="Click title to show/hide section content.">Conditional Processing</h1>
727
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
730
<div class="subsection">
732
<h2 id="section_IF_UNLESS_ELSIF_ELSE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">IF / UNLESS / ELSIF / ELSE</h2>
733
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
737
The <code>IF</code> and <code>UNLESS</code> directives can be used to
738
process or ignore a block based on some run-time condition.
741
[% INCLUDE frameset %]
744
[% UNLESS text_mode %]
745
[% INCLUDE biglogo %]
748
Multiple conditions may be joined with <code>ELSIF</code> and/or
749
<code>ELSE</code> blocks.
751
<pre>[% IF age < 10 %]
752
Hello [% name %], does your mother know you're
753
using her AOL account?
754
[% ELSIF age < 18 %]
755
Sorry, you're not old enough to enter
756
(and too dumb to lie about your age)
761
The following conditional and boolean operators may be used:
763
<pre>== != < <= > >= && || ! and or not</pre>
765
Conditions may be arbitrarily complex and are evaluated with the same
766
precedence as in Perl. Parenthesis may be used to explicitly determine
769
<pre># ridiculously contrived complex example
770
[% IF (name == 'admin' || uid <= 0) && mode == 'debug' %]
772
[% ELSIF more > less %]
773
That's more or less correct.
776
The <code>and</code>, <code>or</code> and <code>not</code> operator are
777
provided as aliases for <code>&&</code>, <code>||</code> and
778
<code>!</code>, respectively. Unlike Perl, which treats <code>and</code>,
779
<code>or</code> and <code>not</code> as separate, lower-precedence
780
versions of the other operators, the Template Toolkit performs a
781
straightforward substitution of <code>and</code> for
782
<code>&&</code>, and so on. That means that <code>and</code>,
783
<code>or</code> and <code>not</code> have the same operator precedence as
784
<code>&&</code>, <code>||</code> and <code>!</code>.
787
</div> <div class="subsection">
789
<h2 id="section_SWITCH_CASE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">SWITCH / CASE</h2>
790
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
794
The <code>SWITCH</code> / <code>CASE</code> construct can be used to
795
perform a multi-way conditional test. The <code>SWITCH</code> directive
796
expects an expression which is first evaluated and then compared against
797
each CASE statement in turn. Each <code>CASE</code> directive should
798
contain a single value or a list of values which should match.
799
<code>CASE</code> may also be left blank or written as <code>[% CASE
800
DEFAULT %]</code> to specify a default match. Only one <code>CASE</code>
801
matches, there is no drop-through between <code>CASE</code> statements.
803
<pre>[% SWITCH myvar %]
806
[% CASE [ value2 value3 ] %] # multiple values
808
[% CASE myhash.keys %] # ditto
817
<div class="section">
819
<h1 id="Loop_Processing" onclick="switch_section(this)" title="Click title to show/hide section content.">Loop Processing</h1>
820
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
823
<div class="subsection">
825
<h2 id="section_FOREACH" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">FOREACH</h2>
826
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
830
The <code>FOREACH</code> directive will iterate through the items in a
831
list, processing the enclosed block for each one.
835
items => [ 'one', 'two', 'three' ],
840
[% FOREACH thing = [ foo 'Bar' "$foo Baz" ] %]
845
[% FOREACH i IN items %]
850
[% stuff = [ foo "$foo Bar" ] %]
851
[% FOREACH s IN stuff %]
871
You can use also use <code>IN</code> instead of <code>=</code> if you
874
<pre>[% FOREACH crook IN government %]</pre>
876
When the <code>FOREACH</code> directive is used without specifying a
877
target variable, any iterated values which are hash references will be
878
automatically imported.
881
{ id => 'tom', name => 'Thomas' },
882
{ id => 'dick', name => 'Richard' },
883
{ id => 'larry', name => 'Lawrence' },
887
[% FOREACH user IN userlist %]
888
[% user.id %] [% user.name %]
893
<pre>[% FOREACH userlist %]
897
Note that this particular usage creates a localised variable context to
898
prevent the imported hash keys from overwriting any existing variables.
899
The imported definitions and any other variables defined in such a
900
<code>FOREACH</code> loop will be lost at the end of the loop, when the
901
previous context and variable values are restored.
904
However, under normal operation, the loop variable remains in scope after
905
the <code>FOREACH</code> loop has ended (caveat: overwriting any variable
906
previously in scope). This is useful as the loop variable is secretly an
907
iterator object (see below) and can be used to analyse the last entry
908
processed by the loop.
911
The <code>FOREACH</code> directive can also be used to iterate through
912
the entries in a hash array. Each entry in the hash is returned in sorted
913
order (based on the key) as a hash array containing 'key' and 'value'
918
dick => 'Richard',
919
larry => 'Lawrence',
923
[% FOREACH u IN users %]
924
* [% u.key %] : [% u.value %]
929
<pre>* dick : Richard
931
* tom : Thomas </pre>
933
The <code>NEXT</code> directive starts the next iteration in the
934
<code>FOREACH</code> loop.
936
<pre>[% FOREACH user IN userlist %]
937
[% NEXT IF user.isguest %]
938
Name: [% user.name %] Email: [% user.email %]
941
The <code>LAST</code> directive can be used to prematurely exit the loop.
942
<code>BREAK</code> is also provided as an alias for <code>LAST</code>.
944
<pre>[% FOREACH match IN results.nsort('score').reverse %]
945
[% LAST IF match.score < 50 %]
946
[% match.score %] : [% match.url %]
949
The <code>FOREACH</code> directive is implemented using the <a href="../modules/Template/Iterator.html">Template::Iterator</a> module. A
950
reference to the iterator object for a <code>FOREACH</code> directive is
951
implicitly available in the <code>loop</code> variable. The following
952
methods can be called on the <code>loop</code> iterator.
954
<pre>size() number of elements in the list
955
max() index number of last element (size - 1)
956
index() index of current iteration from 0 to max()
957
count() iteration counter from 1 to size() (i.e. index() + 1)
958
first() true if the current iteration is the first
959
last() true if the current iteration is the last
960
prev() return the previous item in the list
961
next() return the next item in the list</pre>
963
See <a href="../modules/Template/Iterator.html">Template::Iterator</a> for further details.
968
<pre>[% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%]
969
[%- "<ul>\n" IF loop.first %]
970
<li>[% loop.count %]/[% loop.size %]: [% item %]
971
[%- "</ul>\n" IF loop.last %]
982
Nested loops will work as expected, with the <code>loop</code> variable
983
correctly referencing the innermost loop and being restored to any
984
previous value (i.e. an outer loop) at the end of the loop.
986
<pre>[% FOREACH group IN grouplist;
987
# loop => group iterator
988
"Groups:\n" IF loop.first;
990
FOREACH user IN group.userlist;
991
# loop => user iterator
992
"$loop.count: $user.name\n";
995
# loop => group iterator
996
"End of Groups\n" IF loop.last;
1000
The <code>iterator</code> plugin can also be used to explicitly create an
1001
iterator object. This can be useful within nested loops where you need to
1002
keep a reference to the outer iterator within the inner loop. The
1003
iterator plugin effectively allows you to create an iterator by a name
1004
other than <code>loop</code>. See <a href="../modules/Template/Plugin/Iterator.html">Template::Plugin::Iterator</a> for further details.
1006
<pre>[% USE giter = iterator(grouplist) %]
1008
[% FOREACH group IN giter %]
1009
[% FOREACH user IN group.userlist %]
1010
user #[% loop.count %] in
1011
group [% giter.count %] is
1012
named [% user.name %]
1016
</div> <div class="subsection">
1018
<h2 id="section_WHILE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">WHILE</h2>
1019
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
1023
The <code>WHILE</code> directive can be used to repeatedly process a
1024
template block while a conditional expression evaluates true. The
1025
expression may be arbitrarily complex as per <code>IF</code> /
1026
<code>UNLESS</code>.
1028
<pre>[% WHILE total < 100 %]
1030
[% total = calculate_new_total %]
1033
An assignment can be enclosed in parenthesis to evaluate the assigned
1036
<pre>[% WHILE (user = get_next_user_record) %]
1040
The <code>NEXT</code> directive can be used to start the next iteration
1041
of a <code>WHILE</code> loop and <code>BREAK</code> can be used to exit
1042
the loop, both as per <code>FOREACH</code>.
1045
The Template Toolkit uses a failsafe counter to prevent runaway
1046
<code>WHILE</code> loops which would otherwise never terminate. If the
1047
loop exceeds 1000 iterations then an <code>undef</code> exception will be
1048
thrown, reporting the error:
1050
<pre>WHILE loop terminated (> 1000 iterations)</pre>
1052
The <code>$Template::Directive::WHILE_MAX</code> variable controls this
1053
behaviour and can be set to a higher value if necessary.
1059
<div class="section">
1061
<h1 id="Filters_Plugins_Macros_and_Perl" onclick="switch_section(this)" title="Click title to show/hide section content.">Filters, Plugins, Macros and Perl</h1>
1062
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
1065
<div class="subsection">
1067
<h2 id="section_FILTER" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">FILTER</h2>
1068
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
1072
The <code>FILTER</code> directive can be used to post-process the output
1073
of a block. A number of standard filters are provided with the Template
1074
Toolkit. The <code>html</code> filter, for example, escapes the '<',
1075
'>' and '&' characters to prevent them from being interpreted as
1076
HTML tags or entity reference markers.
1078
<pre>[% FILTER html %]
1079
HTML text may have < and > characters embedded
1080
which you want converted to the correct HTML entities.
1085
<pre>HTML text may have &lt; and &gt; characters embedded
1086
which you want converted to the correct HTML entities.</pre>
1088
The <code>FILTER</code> directive can also follow various other non-block
1089
directives. For example:
1091
<pre>[% INCLUDE mytext FILTER html %]</pre>
1093
The <code>|</code> character can also be used as an alias for
1094
<code>FILTER</code>.
1096
<pre>[% INCLUDE mytext | html %]</pre>
1098
Multiple filters can be chained together and will be called in sequence.
1100
<pre>[% INCLUDE mytext FILTER html FILTER html_para %]</pre>
1104
<pre>[% INCLUDE mytext | html | html_para %]</pre>
1106
Filters come in two flavours, known as 'static' or 'dynamic'. A static
1107
filter is a simple subroutine which accepts a text string as the only
1108
argument and returns the modified text. The <code>html</code> filter is
1109
an example of a static filter, implemented as:
1111
<pre>sub html_filter {
1114
s/&/&amp;/g;
1121
Dynamic filters can accept arguments which are specified when the filter
1122
is called from a template. The <code>repeat</code> filter is such an
1123
example, accepting a numerical argument which specifies the number of
1124
times that the input text should be repeated.
1126
<pre>[% FILTER repeat(3) %]blah [% END %]</pre>
1130
<pre>blah blah blah</pre>
1132
These are implemented as filter 'factories'. The factory subroutine is
1133
passed a reference to the current <a href="../modules/Template/Context.html">Template::Context</a> object along
1134
with any additional arguments specified. It should then return a
1135
subroutine reference (e.g. a closure) which implements the filter. The
1136
<code>repeat</code> filter factory is implemented like this:
1138
<pre>sub repeat_filter_factory {
1139
my ($context, $iter) = @_;
1140
$iter = 1 unless defined $iter;
1144
$text = '' unless defined $text;
1145
return join('\n', $text) x $iter;
1149
The <code>FILTERS</code> option, described in <a href="../manual/Config.html">Template::Manual::Config</a>,
1150
allows custom filters to be defined when a Template object is
1151
instantiated. The <a
1152
href="#method_define_filter">Template::Context#define_filter()</a> method
1153
allows further filters to be defined at any time.
1156
When using a filter, it is possible to assign an alias to it for further
1157
use. This is most useful for dynamic filters that you want to re-use with
1158
the same configuration.
1160
<pre>[% FILTER echo = repeat(2) %]
1161
Is there anybody out there?
1165
Mother, should I build a wall?
1170
<pre>Is there anybody out there?
1171
Is there anybody out there?</pre>
1172
<pre>Mother, should I build a wall?
1173
Mother, should I build a wall?</pre>
1175
The <code>FILTER</code> directive automatically quotes the name of the
1176
filter. As with <code>INCLUDE</code> et al, you can use a variable to
1177
provide the name of the filter, prefixed by <code>$</code>.
1179
<pre>[% myfilter = 'html' %]
1180
[% FILTER $myfilter %] # same as [% FILTER html %]
1184
A template variable can also be used to define a static filter
1185
subroutine. However, the Template Toolkit will automatically call any
1186
subroutine bound to a variable and use the value returned. Thus, the
1187
above example could be implemented as:
1190
myfilter => sub { return 'html' },
1195
<pre>[% FILTER $myfilter %] # same as [% FILTER html %]
1199
To define a template variable that evaluates to a subroutine reference
1200
that can be used by the <code>FILTER</code> directive, you should create
1201
a subroutine that, when called automatically by the Template Toolkit,
1202
returns another subroutine reference which can then be used to perform
1203
the filter operation. Note that only static filters can be implemented in
1207
myfilter => sub { \&my_filter_sub },
1218
<pre>[% FILTER $myfilter %]
1222
Alternately, you can bless a subroutine reference into a class (any class
1223
will do) to fool the Template Toolkit into thinking it's an object rather
1224
than a subroutine. This will then bypass the automatic
1225
"call-a-subroutine-to-return-a-value" magic.
1228
myfilter => bless(\&my_filter_sub, 'anything_you_like'),
1233
<pre>[% FILTER $myfilter %]
1237
Filters bound to template variables remain local to the variable context
1238
in which they are defined. That is, if you define a filter in a
1239
<code>PERL</code> block within a template that is loaded via
1240
<code>INCLUDE</code>, then the filter definition will only exist until
1241
the end of that template when the stash is delocalised, restoring the
1242
previous variable state. If you want to define a filter which persists
1243
for the lifetime of the processor, or define additional dynamic filter
1244
factories, then you can call the <a
1245
href="#method_define_filter">Template::Context#define_filter()</a> method
1246
on the current <a href="../modules/Template/Context.html">Template::Context</a> object.
1249
See <a href="../manual/Filters.html">Template::Manual::Filters</a> for a complete list of available
1250
filters, their descriptions and examples of use.
1253
</div> <div class="subsection">
1255
<h2 id="section_USE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">USE</h2>
1256
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
1260
The <code>USE</code> directive can be used to load and initialise
1261
"plugin" extension modules.
1263
<pre>[% USE myplugin %]</pre>
1265
A plugin is a regular Perl module that conforms to a particular
1266
object-oriented interface, allowing it to be loaded into and used
1267
automatically by the Template Toolkit. For details of this interface and
1268
information on writing plugins, consult <a href="../modules/Template/Plugin.html">Template::Plugin</a>.
1271
A number of standard plugins are included with the Template Toolkit (see
1272
below and <a href="../manual/Plugins.html">Template::Manual::Plugins</a>). The names of these standard plugins
1273
are case insensitive.
1275
<pre>[% USE CGI %] # => Template::Plugin::CGI
1276
[% USE Cgi %] # => Template::Plugin::CGI
1277
[% USE cgi %] # => Template::Plugin::CGI</pre>
1279
You can also define further plugins using the <code>PLUGINS</code>
1282
<pre>my $tt = Template->new({
1284
foo => 'My::Plugin::Foo',
1285
bar => 'My::Plugin::Bar',
1289
The recommended convention is to specify these plugin names in lower
1290
case. The Template Toolkit first looks for an exact case-sensitive match
1291
and then tries the lower case conversion of the name specified.
1293
<pre>[% USE Foo %] # look for 'Foo' then 'foo'</pre>
1295
If you define all your <code>PLUGINS</code> with lower case names then
1296
they will be located regardless of how the user specifies the name in the
1297
<code>USE</code> directive. If, on the other hand, you define your
1298
<code>PLUGINS</code> with upper or mixed case names then the name
1299
specified in the <code>USE</code> directive must match the case exactly.
1302
If the plugin isn't defined in either the standard plugins
1303
(<code>$Template::Plugins::STD_PLUGINS</code>) or via the
1304
<code>PLUGINS</code> option, then the <code>PLUGIN_BASE</code> is
1308
In this case the plugin name <i>is</i> case-sensitive. It is appended to
1309
each of the <code>PLUGIN_BASE</code> module namespaces in turn (default:
1310
<code>Template::Plugin</code>) to construct a full module name which it
1311
attempts to locate and load. Any periods, '<code>.</code>', in the name
1312
will be converted to '<code>::</code>'.
1314
<pre>[% USE MyPlugin %] # => Template::Plugin::MyPlugin
1315
[% USE Foo.Bar %] # => Template::Plugin::Foo::Bar</pre>
1317
The <code>LOAD_PERL</code> option (disabled by default) provides a
1318
further way by which external Perl modules may be loaded. If a regular
1319
Perl module (i.e. not a <code>Template::Plugin::*</code> or other module
1320
relative to some <code>PLUGIN_BASE</code>) supports an object-oriented
1321
interface and a <code>new()</code> constructor then it can be loaded and
1322
instantiated automatically. The following trivial example shows how the
1323
IO::File module might be used.
1325
<pre>[% USE file = IO.File('/tmp/mydata') %]
1327
[% WHILE (line = file.getline) %]
1328
<!-- [% line %] -->
1331
Any additional parameters supplied in parenthesis after the plugin name
1332
will be also be passed to the <code>new()</code> constructor. A reference
1333
to the current <a href="../modules/Template/Context.html">Template::Context</a> object is passed as the first parameter.
1335
<pre>[% USE MyPlugin('foo', 123) %]</pre>
1339
<pre>Template::Plugin::MyPlugin->new($context, 'foo', 123);</pre>
1341
The only exception to this is when a module is loaded via the
1342
<code>LOAD_PERL</code> option. In this case the <code>$context</code>
1343
reference is <i>not</i> passed to the <code>new()</code> constructor.
1344
This is based on the assumption that the module is a regular Perl module
1345
rather than a Template Toolkit plugin so isn't expecting a context
1346
reference and wouldn't know what to do with it anyway.
1349
Named parameters may also be specified. These are collated into a hash
1350
which is passed by reference as the last parameter to the constructor, as
1351
per the general code calling interface.
1353
<pre>[% USE url('/cgi-bin/foo', mode='submit', debug=1) %]</pre>
1357
<pre>Template::Plugin::URL->new(
1360
{ mode => 'submit', debug => 1 }
1363
The plugin may represent any data type; a simple variable, hash, list or
1364
code reference, but in the general case it will be an object reference.
1365
Methods can be called on the object (or the relevant members of the
1366
specific data type) in the usual way:
1368
<pre>[% USE table(mydata, rows=3) %]
1370
[% FOREACH row IN table.rows %]
1372
[% FOREACH item IN row %]
1373
<td>[% item %]</td>
1378
An alternative name may be provided for the plugin by which it can be
1381
<pre>[% USE scores = table(myscores, cols=5) %]
1383
[% FOREACH row IN scores.rows %]
1387
You can use this approach to create multiple plugin objects with
1388
different configurations. This example shows how the <a
1389
href="#section_format">Template::Plugin::Format</a> plugin is used to
1390
create sub-routines bound to variables for formatting text as per
1391
<code>printf()</code>.
1393
<pre>[% USE bold = format('<b>%s</b>') %]
1394
[% USE ital = format('<i>%s</i>') %]
1395
[% bold('This is bold') %]
1396
[% ital('This is italic') %]</pre>
1400
<pre><b>This is bold</b>
1401
<i>This is italic</i></pre>
1403
This next example shows how the <a
1404
href="#section_URL">Template::Plugin::URL</a> plugin can be used to build
1405
dynamic URLs from a base part and optional query parameters.
1407
<pre>[% USE mycgi = URL('/cgi-bin/foo.pl', debug=1) %]
1408
<a href="[% mycgi %]">...
1409
<a href="[% mycgi(mode='submit') %]"...</pre>
1413
<pre><a href="/cgi-bin/foo.pl?debug=1">...
1414
<a href="/cgi-bin/foo.pl?mode=submit&debug=1">...</pre>
1416
The <a href="http://search.cpan.org/search?query=CGI&mode=all">Template::Plugin::CGI</a> plugin is
1417
an example of one which delegates to another Perl module. In this this
1418
case, to Lincoln Stein's <code>CGI</code> module. All of the methods
1419
provided by the <code>CGI</code> module are available via the plugin.
1423
CGI.checkbox_group( name = 'colours',
1424
values = [ 'red' 'green' 'blue' ] );
1425
CGI.popup_menu( name = 'items',
1426
values = [ 'foo' 'bar' 'baz' ] );
1430
See <a href="../manual/Plugins.html">Template::Manual::Plugins</a> for more information on the plugins
1431
distributed with the toolkit or available from CPAN.
1434
</div> <div class="subsection">
1436
<h2 id="section_MACRO" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">MACRO</h2>
1437
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
1441
The <code>MACRO</code> directive allows you to define a directive or
1442
directive block which is then evaluated each time the macro is called.
1444
<pre>[% MACRO header INCLUDE header %]</pre>
1446
Calling the macro as:
1448
<pre>[% header %]</pre>
1450
is then equivalent to:
1452
<pre>[% INCLUDE header %]</pre>
1454
Macros can be passed named parameters when called. These values remain
1457
<pre>[% header(title='Hello World') %] </pre>
1461
<pre>[% INCLUDE header title='Hello World' %]</pre>
1463
A <code>MACRO</code> definition may include parameter names. Values
1464
passed to the macros are then mapped to these local variables. Other
1465
named parameters may follow these.
1467
<pre>[% MACRO header(title) INCLUDE header %]
1468
[% header('Hello World') %]
1469
[% header('Hello World', bgcol='#123456') %]</pre>
1473
<pre>[% INCLUDE header title='Hello World' %]
1474
[% INCLUDE header title='Hello World' bgcol='#123456' %]</pre>
1476
Here's another example, defining a macro for display numbers in
1477
comma-delimited groups of 3, using the chunk and join virtual method.
1479
<pre>[% MACRO number(n) GET n.chunk(-3).join(',') %]
1480
[% number(1234567) %] # 1,234,567</pre>
1482
A <code>MACRO</code> may precede any directive and must conform to the
1483
structure of the directive.
1485
<pre>[% MACRO header IF frames %]
1486
[% INCLUDE frames/header %]
1488
[% INCLUDE header %]
1493
A <code>MACRO</code> may also be defined as an anonymous
1494
<code>BLOCK</code>. The block will be evaluated each time the macro is
1497
<pre>[% MACRO header BLOCK %]
1503
If you've got the <code>EVAL_PERL</code> option set, then you can even
1504
define a <code>MACRO</code> as a <code>PERL</code> block (see below):
1506
<pre>[% MACRO triple(n) PERL %]
1507
my $n = $stash->get('n');
1511
</div> <div class="subsection">
1513
<h2 id="section_PERL" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PERL</h2>
1514
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
1518
(for the advanced reader)
1521
The <code>PERL</code> directive is used to mark the start of a block
1522
which contains Perl code for evaluation. The <code>EVAL_PERL</code>
1523
option must be enabled for Perl code to be evaluated or a
1524
<code>perl</code> exception will be thrown with the message
1525
'<code>EVAL_PERL not set</code>'.
1528
Perl code is evaluated in the <code>Template::Perl</code> package. The
1529
<code>$context</code> package variable contains a reference to the
1530
current <a href="../modules/Template/Context.html">Template::Context</a> object. This can be used to access the
1531
functionality of the Template Toolkit to process other templates, load
1532
plugins, filters, etc. See <a href="../modules/Template/Context.html">Template::Context</a> for further details.
1535
print $context->include('myfile');
1538
The <a href="#section_$stash">$stash</a> variable contains a reference to
1539
the top-level stash object which manages template variables. Through
1540
this, variable values can be retrieved and updated. See <a href="../modules/Template/Stash.html">Template::Stash</a> for further
1544
$stash->set(foo => 'bar');
1545
print "foo value: ", $stash->get('foo');
1550
<pre>foo value: bar</pre>
1552
Output is generated from the <code>PERL</code> block by calling
1553
<code>print()</code>. Note that the <code>Template::Perl::PERLOUT</code>
1554
handle is selected (tied to an output buffer) instead of
1555
<code>STDOUT</code>.
1559
print PERLOUT "bar\n"; # OK, same as above
1560
print Template::Perl::PERLOUT "baz\n"; # OK, same as above
1561
print STDOUT "qux\n"; # WRONG!
1564
The <code>PERL</code> block may contain other template directives. These
1565
are processed before the Perl code is evaluated.
1567
<pre>[% name = 'Fred Smith' %]
1570
print "[% name %]\n";
1573
Thus, the Perl code in the above example is evaluated as:
1575
<pre>print "Fred Smith\n";</pre>
1577
Exceptions may be thrown from within <code>PERL</code> blocks using
1578
<code>die()</code>. They will be correctly caught by enclosing
1579
<code>TRY</code> blocks.
1583
die "nothing to live for\n";
1586
error: [% error.info %]
1589
output: error: nothing to live for
1592
</div> <div class="subsection">
1594
<h2 id="section_RAWPERL" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">RAWPERL</h2>
1595
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
1599
(for the very advanced reader)
1602
The Template Toolkit parser reads a source template and generates the
1603
text of a Perl subroutine as output. It then uses <code>eval()</code> to
1604
evaluate it into a subroutine reference. This subroutine is then called
1605
to process the template, passing a reference to the current <a href="../modules/Template/Context.html">Template::Context</a> object through
1606
which the functionality of the Template Toolkit can be accessed. The
1607
subroutine reference can be cached, allowing the template to be processed
1608
repeatedly without requiring any further parsing.
1611
For example, a template such as:
1613
<pre>[% PROCESS header %]
1614
The [% animal %] sat on the [% location %]
1615
[% PROCESS footer %]</pre>
1617
is converted into the following Perl subroutine definition:
1620
my $context = shift;
1621
my $stash = $context->stash;
1626
$output .= $context->process('header');
1628
$output .= $stash->get('animal');
1629
$output .= " sat on the ";
1630
$output .= $stash->get('location');
1631
$output .= $context->process('footer');
1635
$error = $context->catch($@, \$output);
1636
die $error unless $error->type eq 'return';
1642
To examine the Perl code generated, such as in the above example, set the
1643
<code>$Template::Parser::DEBUG</code> package variable to any true value.
1644
You can also set the <code>$Template::Directive::PRETTY</code> variable
1645
true to have the code formatted in a readable manner for human
1646
consumption. The source code for each generated template subroutine will
1647
be printed to <code>STDERR</code> on compilation (i.e. the first time a
1650
<pre>$Template::Parser::DEBUG = 1;
1651
$Template::Directive::PRETTY = 1;
1653
$template->process($file, $vars)
1654
|| die $template->error(), "\n";</pre>
1656
The <code>PERL</code> ... <code>END</code> construct allows Perl code to
1657
be embedded into a template when the <code>EVAL_PERL</code> option is
1658
set. It is evaluated at "runtime" using <code>eval()</code> each time the
1659
template subroutine is called. This is inherently flexible, but not as
1660
efficient as it could be, especially in a persistent server environment
1661
where a template may be processed many times.
1664
The <code>RAWPERL</code> directive allows you to write Perl code that is
1665
integrated directly into the generated Perl subroutine text. It is
1666
evaluated once at compile time and is stored in cached form as part of
1667
the compiled template subroutine. This makes <code>RAWPERL</code> blocks
1668
more efficient than <code>PERL</code> blocks.
1671
The downside is that you must code much closer to the metal. For example,
1672
in a <code>PERL</code> block you can call <a
1673
href="#method_print">print()</a> to generate some output.
1674
<code>RAWPERL</code> blocks don't afford such luxury. The code is
1675
inserted directly into the generated subroutine text and should conform
1676
to the convention of appending to the <code>$output</code> variable.
1678
<pre>[% PROCESS header %]
1681
$output .= "Some output\n";
1683
$output .= "Some more output\n";
1686
The critical section of the generated subroutine for this example would
1687
then look something like:
1691
$output .= $context->process('header');
1693
$output .= "Some output\n";
1695
$output .= "Some more output\n";
1700
As with <code>PERL</code> blocks, the <a
1701
href="#section_$context">Template::Context</a> and <a
1702
href="#section_$stash">Template::Stash</a> references are pre-defined and
1703
available for use within <code>RAWPERL</code> code.
1709
<div class="section">
1711
<h1 id="Exception_Handling_and_Flow_Control" onclick="switch_section(this)" title="Click title to show/hide section content.">Exception Handling and Flow Control</h1>
1712
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
1715
<div class="subsection">
1717
<h2 id="section_TRY_THROW_CATCH_FINAL" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">TRY / THROW / CATCH / FINAL</h2>
1718
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
1722
(more advanced material)
1725
The Template Toolkit supports fully functional, nested exception
1726
handling. The <code>TRY</code> directive introduces an exception handling
1727
scope which continues until the matching <code>END</code> directive. Any
1728
errors that occur within that block will be caught and can be handled by
1729
one of the <code>CATCH</code> blocks defined.
1735
[% INCLUDE someblock %]
1741
Errors are raised as exceptions (objects of the <a href="../modules/Template/Exception.html">Template::Exception</a> class)
1742
which contain two fields: <code>type</code> and <code>info</code>. The
1743
exception <code>type</code> is used to indicate the kind of error that
1744
occurred. It is a simple text string which can contain letters, numbers,
1745
'<code>_</code>' or '<code>.</code>'. The <code>info</code> field
1746
contains an error message indicating what actually went wrong. Within a
1747
catch block, the exception object is aliased to the <code>error</code>
1748
variable. You can access the <code>type</code> and <code>info</code>
1751
<pre>[% mydsn = 'dbi:MySQL:foobar' %]
1755
[% USE DBI(mydsn) %]
1757
ERROR! Type: [% error.type %]
1758
Info: [% error.info %]
1761
output (assuming a non-existant database called '<code>foobar</code>'):
1763
<pre>ERROR! Type: DBI
1764
Info: Unknown database "foobar"</pre>
1766
The <code>error</code> variable can also be specified by itself and will
1767
return a string of the form "<code>$type error - $info</code>".
1776
<pre>ERROR: DBI error - Unknown database "foobar"</pre>
1778
Each <code>CATCH</code> block may be specified with a particular
1779
exception type denoting the kind of error that it should catch. Multiple
1780
<code>CATCH</code> blocks can be provided to handle different types of
1781
exception that may be thrown in the <code>TRY</code> block. A
1782
<code>CATCH</code> block specified without any type, as in the previous
1783
example, is a default handler which will catch any otherwise uncaught
1784
exceptions. This can also be specified as <code>[% CATCH DEFAULT
1788
[% INCLUDE myfile %]
1789
[% USE DBI(mydsn) %]
1792
File Error! [% error.info %]
1794
[% INCLUDE database/error.html %]
1799
Remember that you can specify multiple directives within a single tag,
1800
each delimited by '<code>;</code>'. So the above example can be written
1808
"File Error! $error.info";
1810
INCLUDE database/error.html;
1816
The <code>DBI</code> plugin throws exceptions of the <code>DBI</code>
1817
type (in case that wasn't already obvious). The other specific exception
1818
caught here is of the <code>file</code> type.
1821
A <code>file</code> exception is automatically thrown by the Template
1822
Toolkit when it can't find a file, or fails to load, parse or process a
1823
file that has been requested by an <code>INCLUDE</code>,
1824
<code>PROCESS</code>, <code>INSERT</code> or <code>WRAPPER</code>
1825
directive. If <code>myfile</code> can't be found in the example above,
1826
the <code>[% INCLUDE myfile %]</code> directive will raise a
1827
<code>file</code> exception which is then caught by the <code>[% CATCH
1828
file %]</code> block. The output generated would be:
1830
<pre>File Error! myfile: not found</pre>
1832
Note that the <code>DEFAULT</code> option (disabled by default) allows
1833
you to specify a default file to be used any time a template file can't
1834
be found. This will prevent file exceptions from ever being raised when a
1835
non-existant file is requested (unless, of course, the
1836
<code>DEFAULT</code> file your specify doesn't exist). Errors encountered
1837
once the file has been found (i.e. read error, parse error) will be
1838
raised as file exceptions as per usual.
1841
Uncaught exceptions (i.e. if the <code>TRY</code> block doesn't have a
1842
type specific or default <code>CATCH</code> handler) may be caught by
1843
enclosing <code>TRY</code> blocks which can be nested indefinitely across
1844
multiple templates. If the error isn't caught at any level then
1845
processing will stop and the Template <a
1846
href="#method_process">Template#process()</a> method will return a false
1847
value to the caller. The relevant <a href="../modules/Template/Exception.html">Template::Exception</a> object can
1848
be retrieved by calling the <a href="#method_error">Template#error()</a>
1854
[% INCLUDE $user.header %]
1856
[% INCLUDE header %]
1860
[% INCLUDE database/error.html %]
1863
In this example, the inner <code>TRY</code> block is used to ensure that
1864
the first <code>INCLUDE</code> directive works as expected. We're using a
1865
variable to provide the name of the template we want to include,
1866
<code>user.header</code>, and it's possible this contains the name of a
1867
non-existant template, or perhaps one containing invalid template
1868
directives. If the <code>INCLUDE</code> fails with a <code>file</code>
1869
error then we <code>CATCH</code> it in the inner block and
1870
<code>INCLUDE</code> the default <code>header</code> file instead. Any
1871
<code>DBI</code> errors that occur within the scope of the outer
1872
<code>TRY</code> block will be caught in the relevant <code>CATCH</code>
1873
block, causing the <code>database/error.html</code> template to be
1874
processed. Note that included templates inherit all currently defined
1875
template variable so these error files can quite happily access the
1876
<error> variable to retrieve information about the currently caught
1877
exception. For example, the <code>database/error.html</code> template
1878
might look like this:
1880
<pre><h2>Database Error</h2>
1881
A database error has occurred: [% error.info %]</pre>
1883
You can also specify a <code>FINAL</code> block. This is always processed
1884
regardless of the outcome of the <code>TRY</code> and/or
1885
<code>CATCH</code> blocks. If an exception is uncaught then the
1886
<code>FINAL</code> block is processed before jumping to the enclosing
1887
block or returning to the caller.
1899
The output from the <code>TRY</code> block is left intact up to the point
1900
where an exception occurs. For example, this template:
1904
[% THROW food 'carrots' %]
1907
culinary delights: [% error.info %]
1910
generates the following output:
1912
<pre>This gets printed
1913
culinary delights: carrots</pre>
1915
The <code>CLEAR</code> directive can be used in a <code>CATCH</code> or
1916
<code>FINAL</code> block to clear any output created in the
1917
<code>TRY</code> block.
1921
[% THROW food 'carrots' %]
1925
culinary delights: [% error.info %]
1930
<pre>culinary delights: carrots</pre>
1932
Exception types are hierarchical, with each level being separated by the
1933
familiar dot operator. A <code>DBI.connect</code> exception is a more
1934
specific kind of <code>DBI</code> error. Similarly, an
1935
<code>example.error.barf</code> is a more specific kind of
1936
<code>example.error</code> type which itself is also a
1937
<code>example</code> error.
1940
A <code>CATCH</code> handler that specifies a general exception type
1941
(such as <code>DBI</code> or <code>example.error</code>) will also catch
1942
more specific types that have the same prefix as long as a more specific
1943
handler isn't defined. Note that the order in which <code>CATCH</code>
1944
handlers are defined is irrelevant; a more specific handler will always
1945
catch an exception in preference to a more generic or default one.
1950
INCLUDE database/error.html ;
1952
INCLUDE database/connect.html ;
1954
INCLUDE error.html ;
1958
In this example, a <code>DBI.connect</code> error has it's own handler, a
1959
more general <code>DBI</code> block is used for all other
1960
<code>DBI</code> or <code>DBI.*</code> errors and a default handler
1961
catches everything else.
1964
Exceptions can be raised in a template using the <code>THROW</code>
1965
directive. The first parameter is the exception type which doesn't need
1966
to be quoted (but can be, it's the same as <code>INCLUDE</code>) followed
1967
by the relevant error message which can be any regular value such as a
1968
quoted string, variable, etc.
1970
<pre>[% THROW food "Missing ingredients: $recipe.error" %]
1971
[% THROW user.login 'no user id: please login' %]
1972
[% THROW $myerror.type "My Error: $myerror.info" %]</pre>
1974
It's also possible to specify additional positional or named parameters
1975
to the <code>THROW</code> directive if you want to pass more than just a
1976
simple message back as the error info field.
1978
<pre>[% THROW food 'eggs' 'flour' msg='Missing Ingredients' %]</pre>
1980
In this case, the error <code>info</code> field will be a hash array
1981
containing the named arguments and an <code>args</code> item which
1982
contains a list of the positional arguments.
1984
<pre>type => 'food',
1986
msg => 'Missing Ingredients',
1987
args => ['eggs', 'flour'],
1990
In addition to specifying individual positional arguments as <code>[%
1991
error.info.args.n %]</code>, the <code>info</code> hash contains keys
1992
directly pointing to the positional arguments, as a convenient shortcut.
1994
<pre>[% error.info.0 %] # same as [% error.info.args.0 %]</pre>
1996
Exceptions can also be thrown from Perl code which you've bound to
1997
template variables, or defined as a plugin or other extension. To raise
1998
an exception, call <code>die()</code> passing a reference to a <a
1999
href="../modules/Template/Exception.html">Template::Exception</a>
2000
object as the argument. This will then be caught by any enclosing
2001
<code>TRY</code> blocks from where the code was called.
2003
<pre>use Template::Exception;
2007
# ... do something ...
2008
die Template::Exception->new('myerr.naughty',
2024
<pre>Error: myerr.naughty error - Bad, bad error</pre>
2026
The <code>info</code> field can also be a reference to another object or
2027
data structure, if required.
2029
<pre>die Template::Exception->new('myerror', {
2030
module => 'foo.pl',
2031
errors => [ 'bad permissions', 'naughty boy' ],
2034
Later, in a template:
2039
[% error.info.errors.size or 'no';
2040
error.info.errors.size == 1 ? ' error' : ' errors' %]
2041
in [% error.info.module %]:
2042
[% error.info.errors.join(', ') %].
2045
Generating the output:
2047
<pre>2 errors in foo.pl:
2048
bad permissions, naughty boy.</pre>
2050
You can also call <code>die()</code> with a single string, as is common
2051
in much existing Perl code. This will automatically be converted to an
2052
exception of the '<code>undef</code>' type (that's the literal string
2053
'<code>undef</code>', not the undefined value). If the string isn't
2054
terminated with a newline then Perl will append the familiar <code>" at
2055
$file line $line"</code> message.
2058
# ... do something ...
2059
die "I'm sorry, Dave, I can't do that\n";
2062
If you're writing a plugin, or some extension code that has the current
2063
<a href="../modules/Template/Context.html">Template::Context</a> in
2064
scope (you can safely skip this section if this means nothing to you)
2065
then you can also raise an exception by calling the context <a
2066
href="#method_throw">Template::Context#throw()</a> method. You can pass
2067
it an <a href="../modules/Template/Exception.html">Template::Exception</a> object reference, a pair of <code>($type,
2068
$info)</code> parameters or just an <code>$info</code> string to create
2069
an exception of '<code>undef</code>' type.
2071
<pre>$context->throw($e); # exception object
2072
$context->throw('Denied'); # 'undef' type
2073
$context->throw('user.passwd', 'Bad Password');</pre>
2075
</div> <div class="subsection">
2077
<h2 id="section_NEXT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">NEXT</h2>
2078
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
2082
The <code>NEXT</code> directive can be used to start the next iteration
2083
of a <code>FOREACH</code> or <code>WHILE</code> loop.
2085
<pre>[% FOREACH user IN users %]
2086
[% NEXT IF user.isguest %]
2087
Name: [% user.name %] Email: [% user.email %]
2090
</div> <div class="subsection">
2092
<h2 id="section_LAST" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">LAST</h2>
2093
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
2097
The <code>LAST</code> directive can be used to prematurely exit a
2098
<code>FOREACH</code> or <code>WHILE</code> loop.
2100
<pre>[% FOREACH user IN users %]
2101
Name: [% user.name %] Email: [% user.email %]
2102
[% LAST IF some.condition %]
2105
<code>BREAK</code> can also be used as an alias for <code>LAST</code>.
2108
</div> <div class="subsection">
2110
<h2 id="section_RETURN" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">RETURN</h2>
2111
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
2115
The <code>RETURN</code> directive can be used to stop processing the
2116
current template and return to the template from which it was called,
2117
resuming processing at the point immediately after the
2118
<code>INCLUDE</code>, <code>PROCESS</code> or <code>WRAPPER</code>
2119
directive. If there is no enclosing template then the Template <a
2120
href="#method_process">Template#process()</a> method will return to the
2121
calling code with a true value.
2124
[% INCLUDE half_wit %]
2127
[% BLOCK half_wit %]
2128
This is just half...
2136
This is just half...
2139
</div> <div class="subsection">
2141
<h2 id="section_STOP" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">STOP</h2>
2142
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
2146
The <code>STOP</code> directive can be used to indicate that the
2147
processor should stop gracefully without processing any more of the
2148
template document. This is a planned stop and the Template <a
2149
href="#method_process">Template#process()</a> method will return a
2150
<b>true</b> value to the caller. This indicates that the template was
2151
processed successfully according to the directives within it.
2153
<pre>[% IF something.terrible.happened %]
2154
[% INCLUDE fatal/error.html %]
2159
[% USE DBI(mydsn) %]
2161
[% CATCH DBI.connect %]
2162
<h1>Cannot connect to the database: [% error.info %]</h1>
2164
We apologise for the inconvenience.
2166
[% INCLUDE footer %]
2170
</div> <div class="subsection">
2172
<h2 id="section_CLEAR" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">CLEAR</h2>
2173
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
2177
The <code>CLEAR</code> directive can be used to clear the output buffer
2178
for the current enclosing block. It is most commonly used to clear the
2179
output generated from a <code>TRY</code> block up to the point where the
2183
blah blah blah # this is normally left intact
2184
[% THROW some 'error' %] # up to the point of error
2187
[% CLEAR %] # clear the TRY output
2188
[% error %] # print error string
2194
<div class="section">
2196
<h1 id="Miscellaneous" onclick="switch_section(this)" title="Click title to show/hide section content.">Miscellaneous</h1>
2197
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
2200
<div class="subsection">
2202
<h2 id="section_META" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">META</h2>
2203
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
2207
The <code>META</code> directive allows simple metadata items to be
2208
defined within a template. These are evaluated when the template is
2209
parsed and as such may only contain simple values (e.g. it's not possible
2210
to interpolate other variables values into <code>META</code> variables).
2213
title = 'The Cat in the Hat'
2214
author = 'Dr. Seuss'
2218
The <code>template</code> variable contains a reference to the main
2219
template being processed. These metadata items may be retrieved as
2220
attributes of the template.
2222
<pre><h1>[% template.title %]</h1>
2223
<h2>[% template.author %]</h2></pre>
2225
The <code>name</code> and <code>modtime</code> metadata items are
2226
automatically defined for each template to contain its name and
2227
modification time in seconds since the epoch.
2229
<pre>[% USE date %] # use Date plugin to format time
2231
[% template.name %] last modified
2232
at [% date.format(template.modtime) %]</pre>
2234
The <code>PRE_PROCESS</code> and <code>POST_PROCESS</code> options allow
2235
common headers and footers to be added to all templates. The
2236
<code>template</code> reference is correctly defined when these templates
2237
are processed, allowing headers and footers to reference metadata items
2238
from the main template.
2240
<pre>$template = Template->new({
2241
PRE_PROCESS => 'header',
2242
POST_PROCESS => 'footer',
2245
$template->process('cat_in_hat');</pre>
2251
<title>[% template.title %]</title>
2258
title = 'The Cat in the Hat'
2259
author = 'Dr. Seuss'
2264
The cat in the hat sat on the mat.</pre>
2269
&copy; [% template.year %] [% template.author %]
2273
The output generated from the above example is:
2277
<title>The Cat in the Hat</title>
2280
The cat in the hat sat on the mat.
2282
&copy; 2000 Dr. Seuss
2286
</div> <div class="subsection">
2288
<h2 id="section_TAGS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">TAGS</h2>
2289
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
2293
The <code>TAGS</code> directive can be used to set the
2294
<code>START_TAG</code> and <code>END_TAG</code> values on a per-template
2297
<pre>[% TAGS <+ +> %]
2299
<+ INCLUDE header +></pre>
2301
The TAGS directive may also be used to set a named <code>TAG_STYLE</code>
2303
<pre>[% TAGS html %]
2304
<!-- INCLUDE header --></pre>
2306
See the <a href="#section_TAGS">Template::Manual::Config#TAGS</a> and <a
2307
href="#section_TAG_STYLE">Template::Manual::Config#TAG_STYLE</a>
2308
configuration options for further details.
2311
</div> <div class="subsection">
2313
<h2 id="section_DEBUG" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">DEBUG</h2>
2314
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
2318
The <code>DEBUG</code> directive can be used to enable or disable
2319
directive debug messages within a template. The <code>DEBUG</code>
2320
configuration option must be set to include <code>DEBUG_DIRS</code> for
2321
the <code>DEBUG</code> directives to have any effect. If
2322
<code>DEBUG_DIRS</code> is not set then the parser will automatically
2323
ignore and remove any <code>DEBUG</code> directives.
2326
The <code>DEBUG</code> directive can be used with an <code>on</code> or
2327
<code>off</code> parameter to enable or disable directive debugging
2328
messages from that point forward. When enabled, the output of each
2329
directive in the generated output will be prefixed by a comment indicate
2330
the file, line and original directive text.
2333
directive debugging is on (assuming DEBUG option is set true)
2335
directive debugging is off</pre>
2337
The <code>format</code> parameter can be used to change the format of the
2340
<pre>[% DEBUG format '<!-- $file line $line : [% $text %] -->' %]</pre>
2347
<br class="clear" />
2348
<div class="pageinfo">
2349
/manual/Directives.html last modified 10:57:39 31-May-2007
2354
<a href="http://opensource.org/" class="osi"></a>
2355
<div class="controls">
2357
<a href="../manual/Syntax.html" title="Template::Manual::Syntax" class="go back">Back<span class="about"><h4>Template::Manual::Syntax</h4></span></a>
2358
<a href="../manual/index.html" title="Template::Manual" class="go up">Up<span class="about"><h4>Template::Manual</h4></span></a>
2359
<a href="../manual/Variables.html" title="Template::Manual::Variables" class="go next">Next<span class="about"><h4>Template::Manual::Variables</h4></span></a>
2362
<div class="copyright">
2363
Copyright © 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
2365
<div class="licence">
2366
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
2367
You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
2368
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
2373
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
2374
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
2375
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
2376
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
2377
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
added
removed
html/old/manual/Directives.html
