Your IP : 3.135.220.255
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html>
<head>
<title>Template::Manual::Syntax</title>
<link rel="stylesheet" type="text/css" href="../css/blue.css" title="Clear Blue">
<link rel="alternate stylesheet" type="text/css" href="../css/orange.css" title="Clear Orange">
<link rel="alternate stylesheet" type="text/css" href="../css/green.css" title="Clear Green">
<link rel="alternate stylesheet" type="text/css" href="../css/purple.css" title="Clear Purple">
<link rel="alternate stylesheet" type="text/css" href="../css/grey.css" title="Clear Grey">
<link rel="alternate stylesheet" type="text/css" href="../css/print.css" title="Print">
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../css/ie6.css" />
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="../css/ie7.css" />
<![endif]-->
<link rel="stylesheet" type="text/css" href="../css/print.css" media="print">
<script type="text/javascript" src="../js/tt2.js"></script>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="author" content="Andy Wardley">
</head>
<body id="body">
<div id="layout">
<div id="header">
<a href="../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
<ul id="trail">
<li><a href="../manual/index.html">Manual</a></li>
<li class="last"><a href="../manual/Syntax.html">Syntax</a></li>
</ul>
<div class="controls">
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
<span class="about">Click to view the menu. It's very nice.</span>
</a>
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
<span class="about">Click to hide the menu and go all widescreen!</span>
</a>
<div class="pager">
<a href="../manual/Intro.html" title="Template::Manual::Intro" class="go back">Back<span class="about"><h4>Template::Manual::Intro</h4>Introduction to the Template Toolkit</span></a>
<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>
<a href="../manual/Directives.html" title="Template::Manual::Directives" class="go next">Next<span class="about"><h4>Template::Manual::Directives</h4>Template directives</span></a>
</div>
</div>
<h1 class="headline">Template::Manual::Syntax</h1>
<h2 class="subhead">Directive syntax, structure and semantics</h1>
</div>
<div id="page">
<div id="sidebar">
<a href="../index.html" id="logo"></a>
<div id="menu">
<ul class="menu">
<li class="l0 first"><a href="../manual/index.html" class="warm">Manual</a></li>
<li class="l1"><a href="../manual/Intro.html">Intro</a></li>
<li class="l1"><a href="../manual/Syntax.html" class="warm">Syntax</a></li>
<li class="l1"><a href="../manual/Directives.html">Directives</a></li>
<li class="l1"><a href="../manual/Variables.html">Variables</a></li>
<li class="l1"><a href="../manual/VMethods.html">VMethods</a></li>
<li class="l1"><a href="../manual/Config.html">Config</a></li>
<li class="l1"><a href="../manual/Filters.html">Filters</a></li>
<li class="l1"><a href="../manual/Plugins.html">Plugins</a></li>
<li class="l1"><a href="../manual/Internals.html">Internals</a></li>
<li class="l1"><a href="../manual/Views.html">Views</a></li>
<li class="l1"><a href="../manual/Credits.html">Credits</a></li>
<li class="l0"><a href="../modules/index.html">Modules</a></li>
<li class="l0"><a href="../tools/index.html">Tools</a></li>
<li class="l0"><a href="../tutorial/index.html">Tutorial</a></li>
<li class="l0 last"><a href="../faq/index.html">FAQ</a></li>
</ul>
<div class="foot"></div>
</div>
</div>
<div id="content">
<div class="section">
<div class="head">
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<ul class="toc">
<li class=""><a href="#Tag_Styles">Tag Styles</a></li>
<li class=""><a href="#Comments">Comments</a></li>
<li class=""><a href="#Chomping_Whitespace">Chomping Whitespace</a></li>
<li class=""><a href="#Implicit_Directives_GET_and_SET">Implicit Directives: GET and SET</a></li>
<li class=""><a href="#Block_Directives">Block Directives</a></li>
<li class=""><a href="#Capturing_Block_Output">Capturing Block Output</a></li>
<li class=""><a href="#Chaining_Filters">Chaining Filters</a></li>
<li class=""><a href="#Multiple_Directive_Blocks">Multiple Directive Blocks</a></li>
</ul>
</div>
</div>
<div class="pod">
<div class="section">
<div class="head">
<h1 id="Tag_Styles" onclick="switch_section(this)" title="Click title to show/hide section content.">Tag Styles</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
By default, template directives are embedded within the character
sequences <code>[%</code> and <code>%]</code>.
</p>
<pre><span class="tt">[% PROCESS header %]</span>
<h1>Hello World!</h1>
<a href="<span class="tt">[% page.next %]</span>"><img src="<span class="tt">[% icon.next %]</span>.gif"></a>
<span class="tt">[% PROCESS footer %]</span></pre>
<p>
You can change the tag characters using the <code>START_TAG</code>,
<code>END_TAG</code> and <code>TAG_STYLE</code> configuration options.
You can also use the <code>TAGS</code> directive to define a new tag
style for the current template file.
</p>
<p>
You can also set the <code>INTERPOLATE</code> option to allow simple
variable references to be embedded directly in templates, prefixed by a
<code>$</code>.
</p>
<pre># INTERPOLATE = 0
<td><span class="tt">[% name %]</span></td>
<td><span class="tt">[% email %]</span></td>
# INTERPOLATE = 1
<td>$name</td>
<td>$email</td></pre>
<p>
Directives may be embedded anywhere in a line of text and can be split
across several lines. Insignificant whitespace is generally ignored
within the directive.
</p>
<pre><span class="tt">[% INCLUDE header
title = 'Hello World'
bgcol = '#ffffff'
%]</span>
<span class="tt">[%INCLUDE menu align='right'%]</span>
Name: <span class="tt">[% name %]</span> (<span class="tt">[%id%]</span>)</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Comments" onclick="switch_section(this)" title="Click title to show/hide section content.">Comments</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>#</code> character is used to indicate comments within a
directive. When placed immediately inside the opening directive tag, it
causes the entire directive to be ignored.
</p>
<pre><span class="tt">[%# this entire directive is ignored no
matter how many lines it wraps onto
%]</span></pre>
<p>
In any other position, it causes the remainder of the current line to be
treated as a comment.
</p>
<pre><span class="tt">[% # this is a comment
theta = 20 # so is this
rho = 30 # <aol>me too!</aol>
%]</span></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Chomping_Whitespace" onclick="switch_section(this)" title="Click title to show/hide section content.">Chomping Whitespace</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
You can add <code>-</code> or <code>+</code> to the immediate start or
end of a directive tag to control the whitespace chomping options. See
the <code>PRE_CHOMP</code> and <code>POST_CHOMP</code> options for
further details.
</p>
<pre><span class="tt">[% BLOCK foo -%]</span> # remove trailing newline
This is block foo
<span class="tt">[%- END %]</span> # remove leading newline</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Implicit_Directives_GET_and_SET" onclick="switch_section(this)" title="Click title to show/hide section content.">Implicit Directives: GET and SET</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The simplest directives are <code>GET</code> and <code>SET</code> which
retrieve and update variable values respectively. The <code>GET</code>
and <code>SET</code> keywords are actually optional as the parser is
smart enough to see them for what they really are (but note the caveat
below on using side-effect notation). Thus, you'll generally see:
</p>
<pre><span class="tt">[% SET foo = 10 %]</span>
<span class="tt">[% GET foo %]</span></pre>
<p>
written as:
</p>
<pre><span class="tt">[% foo = 10 %]</span>
<span class="tt">[% foo %]</span></pre>
<p>
You can also express simple logical statements as implicit
<code>GET</code> directives:
</p>
<pre><span class="tt">[% title or template.title or 'Default Title' %]</span>
<span class="tt">[% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]</span></pre>
<p>
All other directives should start with a keyword specified in UPPER CASE
(but see the <code>ANYCASE</code> option). All directives keywords are in
UPPER CASE to make them visually distinctive and to distinguish them from
variables of the same name but different case. It is perfectly valid, for
example, to define a variable called <code>stop</code> which is entirely
separate from the <code>STOP</code> directive.
</p>
<pre><span class="tt">[% stop = 'Clackett Lane Bus Depot' %]</span>
The bus will next stop at <span class="tt">[% stop %]</span> # variable
<span class="tt">[% STOP %]</span> # directive</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Block_Directives" onclick="switch_section(this)" title="Click title to show/hide section content.">Block Directives</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Directives such as <code>FOREACH</code>, <code>WHILE</code>,
<code>BLOCK</code>, <code>FILTER</code>, etc., mark the start of a block
which may contain text or other directives up to the matching
<code>END</code> directive. Blocks may be nested indefinitely. The
<code>IF</code>, <code>UNLESS</code>, <code>ELSIF</code> and
<code>ELSE</code> directives also define blocks and may be grouped
together in the usual manner.
</p>
<pre><span class="tt">[% FOREACH item = [ 'foo' 'bar' 'baz' ] %]</span>
* Item: <span class="tt">[% item %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% BLOCK footer %]</span>
Copyright 2000 <span class="tt">[% me %]</span>
<span class="tt">[% INCLUDE company/logo %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% IF foo %]</span>
<span class="tt">[% FOREACH thing = foo.things %]</span>
<span class="tt">[% thing %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% ELSIF bar %]</span>
<span class="tt">[% INCLUDE barinfo %]</span>
<span class="tt">[% ELSE %]</span>
do nothing...
<span class="tt">[% END %]</span></pre>
<p>
Block directives can also be used in a convenient side-effect notation.
</p>
<pre><span class="tt">[% INCLUDE userinfo FOREACH user = userlist %]</span>
<span class="tt">[% INCLUDE debugtxt msg="file: $error.info"
IF debugging %]</span>
<span class="tt">[% "Danger Will Robinson" IF atrisk %]</span></pre>
<p>
versus:
</p>
<pre><span class="tt">[% FOREACH user = userlist %]</span>
<span class="tt">[% INCLUDE userinfo %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% IF debugging %]</span>
<span class="tt">[% INCLUDE debugtxt msg="file: $error.info" %]</span>
<span class="tt">[% END %]</span>
<span class="tt">[% IF atrisk %]</span>
Danger Will Robinson
<span class="tt">[% END %]</span></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Capturing_Block_Output" onclick="switch_section(this)" title="Click title to show/hide section content.">Capturing Block Output</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The output of a directive can be captured by simply assigning the
directive to a variable.
</p>
<pre><span class="tt">[% headtext = PROCESS header title="Hello World" %]</span>
<span class="tt">[% people = PROCESS userinfo FOREACH user = userlist %]</span></pre>
<p>
This can be used in conjunction with the <code>BLOCK</code> directive for
defining large blocks of text or other content.
</p>
<pre><span class="tt">[% poem = BLOCK %]</span>
The boy stood on the burning deck,
His fleece was white as snow.
A rolling stone gathers no moss,
And Keith is sure to follow.
<span class="tt">[% END %]</span></pre>
<p>
Note one important caveat of using this syntax in conjunction with
side-effect notation. The following directive does not behave as might be
expected:
</p>
<pre><span class="tt">[% var = 'value' IF some_condition %]</span> # does not work</pre>
<p>
In this case, the directive is interpreted as (spacing added for clarity)
</p>
<pre><span class="tt">[% var = IF some_condition %]</span>
value
<span class="tt">[% END %]</span></pre>
<p>
rather than
</p>
<pre><span class="tt">[% IF some_condition %]</span>
<span class="tt">[% var = 'value' %]</span>
<span class="tt">[% END %]</span></pre>
<p>
The variable is assigned the output of the <code>IF</code> block which
returns <code>'value'</code> if true, but nothing if false. In other
words, the following directive will always cause 'var' to be cleared.
</p>
<pre><span class="tt">[% var = 'value' IF 0 %]</span></pre>
<p>
To achieve the expected behaviour, the directive should be written as:
</p>
<pre><span class="tt">[% SET var = 'value' IF some_condition %]</span></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Chaining_Filters" onclick="switch_section(this)" title="Click title to show/hide section content.">Chaining Filters</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Multiple <code>FILTER</code> directives can be chained together in
sequence. They are called in the order defined, piping the output of one
into the input of the next.
</p>
<pre><span class="tt">[% PROCESS somefile FILTER truncate(100) FILTER html %]</span></pre>
<p>
The pipe character, <code>|</code>, can also be used as an alias for
<code>FILTER</code>.
</p>
<pre><span class="tt">[% PROCESS somefile | truncate(100) | html %]</span></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Multiple_Directive_Blocks" onclick="switch_section(this)" title="Click title to show/hide section content.">Multiple Directive Blocks</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Multiple directives can be included within a single tag when delimited by
semi-colons. Note however that the <code>TAGS</code> directive must
always be specified in a tag by itself.
</p>
<pre><span class="tt">[% IF title;
INCLUDE header;
ELSE;
INCLUDE other/header title="Some Other Title";
END
%]</span></pre>
<p>
versus
</p>
<pre><span class="tt">[% IF title %]</span>
<span class="tt">[% INCLUDE header %]</span>
<span class="tt">[% ELSE %]</span>
<span class="tt">[% INCLUDE other/header title="Some Other Title" %]</span>
<span class="tt">[% END %]</span></pre>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
<a href="http://template-toolkit.org/docs/manual/Syntax.html">http://template-toolkit.org/docs/manual/Syntax.html</a>
</div>
</div>
<div id="footer">
<a href="http://opensource.org/" class="osi"></a>
<div class="controls">
<div class="pager">
<a href="../manual/Intro.html" title="Template::Manual::Intro" class="go back">Back<span class="about"><h4>Template::Manual::Intro</h4></span></a>
<a href="../manual/index.html" title="Template::Manual" class="go up">Up<span class="about"><h4>Template::Manual</h4></span></a>
<a href="../manual/Directives.html" title="Template::Manual::Directives" class="go next">Next<span class="about"><h4>Template::Manual::Directives</h4></span></a>
</div>
</div>
<div class="copyright">
Copyright © 1996-2012 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
</div>
<div class="licence">
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
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>
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
</div>
</div>
<div id="palette">
<ul>
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
</ul>
</div>
</div> </body>
</html>