%PDF-
%PDF-
Mini Shell
Mini Shell
<!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">
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../css/ie6.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 last"><a href="../tutorial/index.html">Tutorial</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>[% PROCESS header %]
<h1>Hello World!</h1>
<a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
[% PROCESS footer %]</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>[% name %]</td>
<td>[% email %]</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>[% INCLUDE header
title = 'Hello World'
bgcol = '#ffffff'
%]
[%INCLUDE menu align='right'%]
Name: [% name %] ([%id%])</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>[%# this entire directive is ignored no
matter how many lines it wraps onto
%]</pre>
<p>
In any other position, it causes the remainder of the current line to be
treated as a comment.
</p>
<pre>[% # this is a comment
theta = 20 # so is this
rho = 30 # <aol>me too!</aol>
%]</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>[% BLOCK foo -%] # remove trailing newline
This is block foo
[%- END %] # 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>[% SET foo = 10 %]
[% GET foo %]</pre>
<p>
written as:
</p>
<pre>[% foo = 10 %]
[% foo %]</pre>
<p>
You can also express simple logical statements as implicit
<code>GET</code> directives:
</p>
<pre>[% title or template.title or 'Default Title' %]
[% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]</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>[% stop = 'Clackett Lane Bus Depot' %]
The bus will next stop at [% stop %] # variable
[% STOP %] # 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>[% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
* Item: [% item %]
[% END %]
[% BLOCK footer %]
Copyright 2000 [% me %]
[% INCLUDE company/logo %]
[% END %]
[% IF foo %]
[% FOREACH thing = foo.things %]
[% thing %]
[% END %]
[% ELSIF bar %]
[% INCLUDE barinfo %]
[% ELSE %]
do nothing...
[% END %]</pre>
<p>
Block directives can also be used in a convenient side-effect notation.
</p>
<pre>[% INCLUDE userinfo FOREACH user = userlist %]
[% INCLUDE debugtxt msg="file: $error.info"
IF debugging %]
[% "Danger Will Robinson" IF atrisk %]</pre>
<p>
versus:
</p>
<pre>[% FOREACH user = userlist %]
[% INCLUDE userinfo %]
[% END %]
[% IF debugging %]
[% INCLUDE debugtxt msg="file: $error.info" %]
[% END %]
[% IF atrisk %]
Danger Will Robinson
[% END %]</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>[% headtext = PROCESS header title="Hello World" %]
[% people = PROCESS userinfo FOREACH user = userlist %]</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>[% poem = BLOCK %]
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.
[% END %]</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>[% var = 'value' IF some_condition %] # does not work</pre>
<p>
In this case, the directive is interpreted as (spacing added for clarity)
</p>
<pre>[% var = IF some_condition %]
value
[% END %]</pre>
<p>
rather than
</p>
<pre>[% IF some_condition %]
[% var = 'value' %]
[% END %]</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>[% var = 'value' IF 0 %]</pre>
<p>
To achieve the expected behaviour, the directive should be written as:
</p>
<pre>[% SET var = 'value' IF some_condition %]</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>[% PROCESS somefile FILTER truncate(100) FILTER html %]</pre>
<p>
The pipe character, <code>|</code>, can also be used as an alias for
<code>FILTER</code>.
</p>
<pre>[% PROCESS somefile | truncate(100) | html %]</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>[% IF title;
INCLUDE header;
ELSE;
INCLUDE other/header title="Some Other Title";
END
%]</pre>
<p>
versus
</p>
<pre>[% IF title %]
[% INCLUDE header %]
[% ELSE %]
[% INCLUDE other/header title="Some Other Title" %]
[% END %]</pre>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
/manual/Syntax.html last modified 10:57:42 31-May-2007
</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-2007 <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>
Zerion Mini Shell 1.0