Syntax.html

[%#
  # IMPORTANT NOTE
  #   This documentation is generated automatically from source
  #   templates.  Any changes you make here may be lost.
  # 
  #   The 'docsrc' documentation source bundle is available for download
  #   from http://www.template-toolkit.org/docs.html and contains all
  #   the source templates, XML files, scripts, etc., from which the
  #   documentation for the Template Toolkit is built.
-%]
[% META book = 'Manual'
        page = 'Syntax'
%]
[%  WRAPPER toc;
	INCLUDE tocitem title="DESCRIPTION"
                         subs=["Tag Styles", "Comments", "Chomping Whitespace", "Implicit Directives: GET and SET", "Block Directives", "Capturing Block Output", "Chaining Filters", "Multiple Directive Blocks"];
	INCLUDE tocitem title="AUTHOR";
	INCLUDE tocitem title="VERSION";
	INCLUDE tocitem title="COPYRIGHT";
    END
%]
<!-- Pod to HTML conversion by the Template Toolkit version 2 -->
[% WRAPPER section
    title="DESCRIPTION"
-%]<p>
This section describes the syntax, structure and semantics of the
Template Toolkit directives and general presentation language.
</p>
[% WRAPPER subsection
   title = "Tag Styles"
-%]<p>
By default, template directives are embedded within the character sequences
'[% tt_start_tag %]' and '[% tt_end_tag %]'.  e.g.
</p>
<pre>    [% tt_start_tag %] PROCESS header [% tt_end_tag %]
  
    &lt;h1&gt;Hello World!&lt;/h1&gt;
    &lt;a href=&quot;[% tt_start_tag %] page.next [% tt_end_tag %]&quot;&gt;&lt;img src=&quot;[% tt_start_tag %] icon.next [% tt_end_tag %].gif&quot;&gt;&lt;/a&gt;
  
    [% tt_start_tag %] PROCESS footer [% tt_end_tag %]</pre>
<p>
You can change the tag characters using the START_TAG, END_TAG and
TAG_STYLE configuration options.  You can also use the TAGS directive
to define a new tag style for the current template file.
</p>
<p>
You can also set the INTERPOLATE option to allow simple variable
references to be embedded directly in templates, prefixed by a '$'.
</p>
<pre>    # INTERPOLATE =&gt; 0
    &lt;td&gt;[% tt_start_tag %] name [% tt_end_tag %]&lt;/td&gt;  &lt;td&gt;[% tt_start_tag %] email [% tt_end_tag %]&lt;/td&gt;</pre>
<pre>    # INTERPOLATE =&gt; 1
    &lt;td&gt;$name&lt;/td&gt;  &lt;td&gt;$email&lt;/td&gt;</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>    [% tt_start_tag %] INCLUDE header		   
       title = 'Hello World' 
       bgcol = '#ffffff' 
    [% tt_end_tag %]
  
    [% tt_start_tag %]INCLUDE menu align='right'[% tt_end_tag %]
  
    Name: [% tt_start_tag %] name [% tt_end_tag %]  ([% tt_start_tag %]id[% tt_end_tag %])</pre>
[%- END %]
[% WRAPPER subsection
   title = "Comments"
-%]<p>
The '#' 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>    [% tt_start_tag %]# this entire directive is ignored no
        matter how many lines it wraps onto
    [% tt_end_tag %]</pre>
<p>
In any other position, it causes the remainder of the current line to 
be treated as a comment.
</p>
<pre>    [% tt_start_tag %] # this is a comment
       theta = 20      # so is this
       rho   = 30      # &lt;aol&gt;me too!&lt;/aol&gt;
    [% tt_end_tag %]</pre>
[%- END %]
[% WRAPPER subsection
   title = "Chomping Whitespace"
-%]<p>
You can add '-' or '+' to the immediate start or end of a directive
tag to control the whitespace chomping options.  See the PRE_CHOMP and
POST_CHOMP options for further details.
</p>
<pre>    [% tt_start_tag %] BLOCK foo -[% tt_end_tag %]		# remove trailing newline
    This is block foo
    [% tt_start_tag %]- END [% tt_end_tag %]			# remove leading newline</pre>
[%- END %]
[% WRAPPER subsection
   title = "Implicit Directives: GET and SET"
-%]<p>
The simplest directives are GET and SET which retrieve and update
variable values respectively.  The GET and SET 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>    [% tt_start_tag %] SET foo = 10 [% tt_end_tag %]
    [% tt_start_tag %] GET foo [% tt_end_tag %]</pre>
<p>
written as:
</p>
<pre>    [% tt_start_tag %] foo = 10 [% tt_end_tag %]
    [% tt_start_tag %] foo [% tt_end_tag %]</pre>
<p>
You can also express simple logical statements as implicit GET directives:
</p>
<pre>    [% tt_start_tag %] title or template.title or 'Default Title' [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] mode == 'graphics' ? &quot;Graphics Mode Enabled&quot; : &quot;Text Mode&quot; [% tt_end_tag %]</pre>
<p>
All other directives should start with a keyword specified in UPPER
CASE (but see the ANYCASE 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 'stop' which is
entirely separate from the STOP directive.
</p>
<pre>    [% tt_start_tag %] stop = 'Clackett Lane Bus Depot' [% tt_end_tag %]</pre>
<pre>    The bus will next stop at [% tt_start_tag %] stop [% tt_end_tag %]    # variable</pre>
<pre>    [% tt_start_tag %] STOP [% tt_end_tag %]                              # directive</pre>
[%- END %]
[% WRAPPER subsection
   title = "Block Directives"
-%]<p>
Directives such as FOREACH, WHILE, BLOCK, FILTER, etc., mark the start
of a block which may contain text or other directives up to the
matching END directive.  Blocks may be nested indefinitely.  The
IF, UNLESS, ELSIF and ELSE directives also define blocks and may be
grouped together in the usual manner.
</p>
<pre>    [% tt_start_tag %] FOREACH item = [ 'foo' 'bar' 'baz' ] [% tt_end_tag %]
       * Item: [% tt_start_tag %] item [% tt_end_tag %]
    [% tt_start_tag %] END [% tt_end_tag %]
  
    [% tt_start_tag %] BLOCK footer [% tt_end_tag %]
       Copyright 2000 [% tt_start_tag %] me [% tt_end_tag %]
       [% tt_start_tag %] INCLUDE company/logo [% tt_end_tag %]
    [% tt_start_tag %] END [% tt_end_tag %]
  
    [% tt_start_tag %] IF foo [% tt_end_tag %]
       [% tt_start_tag %] FOREACH thing = foo.things [% tt_end_tag %]
	  [% tt_start_tag %] thing [% tt_end_tag %]
       [% tt_start_tag %] END [% tt_end_tag %]
    [% tt_start_tag %] ELSIF bar [% tt_end_tag %]
       [% tt_start_tag %] INCLUDE barinfo [% tt_end_tag %]
    [% tt_start_tag %] ELSE [% tt_end_tag %]
       do nothing...
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
Block directives can also be used in a convenient side-effect notation.
</p>
<pre>    [% tt_start_tag %] INCLUDE userinfo FOREACH user = userlist [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] INCLUDE debugtxt msg=&quot;file: $error.info&quot; 
         IF debugging [% tt_end_tag %] </pre>
<pre>    [% tt_start_tag %] &quot;Danger Will Robinson&quot; IF atrisk [% tt_end_tag %]</pre>
<p>
versus:
</p>
<pre>    [% tt_start_tag %] FOREACH user = userlist [% tt_end_tag %]
       [% tt_start_tag %] INCLUDE userinfo [% tt_end_tag %]
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] IF debugging [% tt_end_tag %]
       [% tt_start_tag %] INCLUDE debugtxt msg=&quot;file: $error.info&quot; [% tt_end_tag %]
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] IF atrisk [% tt_end_tag %]
    Danger Will Robinson
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
[%- END %]
[% WRAPPER subsection
   title = "Capturing Block Output"
-%]<p>
The output of a directive can be captured by simply assigning the directive
to a variable.
</p>
<pre>    [% tt_start_tag %] headtext = PROCESS header title=&quot;Hello World&quot; [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] people = PROCESS userinfo FOREACH user = userlist [% tt_end_tag %]</pre>
<p>
This can be used in conjunction with the BLOCK directive for defining large 
blocks of text or other content.
</p>
<pre>    [% tt_start_tag %] poem = BLOCK [% tt_end_tag %]
       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.
    [% tt_start_tag %] END [% tt_end_tag %]</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>    [% tt_start_tag %] var = 'value' IF some_condition [% tt_end_tag %]</pre>
<p>
In this case, the directive is interpreted as (spacing added for clarity)
</p>
<pre>    [% tt_start_tag %] var = IF some_condition [% tt_end_tag %]
       value
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
rather than
</p>
<pre>    [% tt_start_tag %] IF some_condition [% tt_end_tag %]
       [% tt_start_tag %] var = 'value' [% tt_end_tag %]
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
The variable is assigned the output of the IF block which returns
'value' if true, but nothing if false.  In other words, the following
directive will always cause 'var' to be cleared.
</p>
<pre>    [% tt_start_tag %] var = 'value' IF 0 [% tt_end_tag %]</pre>
<p>
To achieve the expected behaviour, the directive should be written as:
</p>
<pre>    [% tt_start_tag %] SET var = 'value' IF some_condition [% tt_end_tag %]</pre>
[%- END %]
[% WRAPPER subsection
   title = "Chaining Filters"
-%]<p>
Multiple FILTER 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>    [% tt_start_tag %] PROCESS somefile FILTER truncate(100) FILTER html [% tt_end_tag %]</pre>
<p>
The pipe character, '|', can also be used as an alias for FILTER.
</p>
<pre>    [% tt_start_tag %] PROCESS somefile | truncate(100) | html [% tt_end_tag %]</pre>
[%- END %]
[% WRAPPER subsection
   title = "Multiple Directive Blocks"
-%]<p>
Multiple directives can be included within a single tag when delimited
by semi-colons, ';'.  Note however that the TAGS directive must always
be specified in a tag by itself.
</p>
<pre>    [% tt_start_tag %] IF title; 
          INCLUDE header; 
       ELSE; 
	  INCLUDE other/header  title=&quot;Some Other Title&quot;;
       END
    [% tt_end_tag %]</pre>
<p>
versus
</p>
<pre>    [% tt_start_tag %] IF title [% tt_end_tag %]
       [% tt_start_tag %] INCLUDE header [% tt_end_tag %]
    [% tt_start_tag %] ELSE [% tt_end_tag %]
       [% tt_start_tag %] INCLUDE other/header  title=&quot;Some Other Title&quot; [% tt_end_tag %]
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
[%- END %]
[%- END %]
[% WRAPPER section
    title="AUTHOR"
-%]<p>
Andy Wardley &lt;abw@kfs.org&gt;
</p>
<p>
[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
</p>
[%- END %]
[% WRAPPER section
    title="VERSION"
-%]<p>
Template Toolkit version 2.05, released on 11 September 2001.
</p>
[%- END %]
[% WRAPPER section
    title="COPYRIGHT"
-%]<pre>  Copyright (C) 1996-2001 Andy Wardley.  All Rights Reserved.
  Copyright (C) 1998-2001 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
</p>
[%- END %]