328 lines
9.0 KiB
Perl
328 lines
9.0 KiB
Perl
#============================================================= -*-perl-*-
|
|
#
|
|
# Template::Manual::Syntax
|
|
#
|
|
# AUTHOR
|
|
# Andy Wardley <abw@wardley.org>
|
|
#
|
|
# COPYRIGHT
|
|
# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
|
|
#
|
|
# This module is free software; you can redistribute it and/or
|
|
# modify it under the same terms as Perl itself.
|
|
#
|
|
#========================================================================
|
|
|
|
=head1 NAME
|
|
|
|
Template::Manual::Syntax - Directive syntax, structure and semantics
|
|
|
|
=head1 Tag Styles
|
|
|
|
Template directives are embedded between start and end markers tags.
|
|
By default these tag markers are C<[%> and C<%]>.
|
|
|
|
[% PROCESS header %]
|
|
|
|
<h1>Hello World!</h1>
|
|
<a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
|
|
|
|
[% PROCESS footer %]
|
|
|
|
You can change the tag characters using the C<START_TAG>, C<END_TAG> and
|
|
C<TAG_STYLE> configuration options. You can also use the C<TAGS> directive to
|
|
define a new tag style for the current template file.
|
|
|
|
You can also set the C<INTERPOLATE> option to allow simple variable references
|
|
to be embedded directly in templates, prefixed by a C<$>.
|
|
|
|
# INTERPOLATE = 0
|
|
<td>[% name %]</td>
|
|
<td>[% email %]</td>
|
|
|
|
# INTERPOLATE = 1
|
|
<td>$name</td>
|
|
<td>$email</td>
|
|
|
|
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.
|
|
|
|
[% INCLUDE header
|
|
title = 'Hello World'
|
|
bgcol = '#ffffff'
|
|
%]
|
|
|
|
[%INCLUDE menu align='right'%]
|
|
|
|
Name: [% name %] ([%id%])
|
|
|
|
=head1 Outline Tags
|
|
|
|
As of version 2.26, the Template Toolkit supports "outline" tags. These have
|
|
a designated marker at the start of a line (C<%%> by default) and continue to
|
|
the end of a line. The newline character at the end of the line is discarded
|
|
(aka "chomped").
|
|
|
|
So rather than writing something like this:
|
|
|
|
[% IF some.list.size -%]
|
|
<ul>
|
|
[% FOREACH item IN some.list -%]
|
|
<li>[% item.html %]</li>
|
|
[% END -%]
|
|
</ul>
|
|
[% END -%]
|
|
|
|
You can write it like this instead:
|
|
|
|
%% IF some.list.size
|
|
<ul>
|
|
%% FOREACH item IN some.list
|
|
<li>[% item.html %]</li>
|
|
%% END
|
|
</ul>
|
|
%% END
|
|
|
|
Outline tags aren't enabled by default. There are a numbers of ways you can
|
|
enable them. The first is to use the C<TAGS> directive to set the tag style
|
|
to C<outline> in any templates where you want to use them. This will enable
|
|
outline tags from that point on.
|
|
|
|
[% TAGS outline -%]
|
|
%% INCLUDE header
|
|
|
|
You can set the C<TAGS> back to the C<default> value at some point later in the
|
|
template if you want to disable them:
|
|
|
|
[% TAGS default -%]
|
|
|
|
You can set the C<TAG_STYLE> configuration option if you want then enabled in
|
|
all templates by default. You can always use the C<[% TAGS default %]>
|
|
directive to disable them in any templates or parts of templates if necessary.
|
|
|
|
my $tt = Template->new({
|
|
TAG_STYLE => 'outline',
|
|
});
|
|
|
|
The C<OUTLINE_TAG> option allows you to set the outline tag marker to something
|
|
else if you're not a fan of percent signs. Setting this option will
|
|
automatically enable outline tags.
|
|
|
|
my $tt = Template->new({
|
|
OUTLINE_TAG => '>>',
|
|
});
|
|
|
|
You can also use the C<TAGS> directive to define your own custom tags (start,
|
|
end and now optionally, outline) for a template or part of a template.
|
|
|
|
[% TAGS <* *> >> %]
|
|
>> INCLUDE header # outline tag
|
|
Hello <* name *> # inline tag
|
|
|
|
If you only specify a start and end tag then outline tags will be disabled.
|
|
|
|
[% TAGS <* *> %] # no outline tags
|
|
|
|
=head1 Comments
|
|
|
|
The C<#> 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.
|
|
|
|
[%# this entire directive is ignored no
|
|
matter how many lines it wraps onto
|
|
%]
|
|
|
|
In any other position, it causes the remainder of the current line to
|
|
be treated as a comment.
|
|
|
|
[% # this is a comment
|
|
theta = 20 # so is this
|
|
rho = 30 # <aol>me too!</aol>
|
|
%]
|
|
|
|
=head1 Chomping Whitespace
|
|
|
|
You can add C<-> or C<+> to the immediate start or end of a directive
|
|
tag to control the whitespace chomping options. See the C<PRE_CHOMP> and
|
|
C<POST_CHOMP> options for further details.
|
|
|
|
[% BLOCK foo -%] # remove trailing newline
|
|
This is block foo
|
|
[%- END %] # remove leading newline
|
|
|
|
=head1 Implicit Directives: GET and SET
|
|
|
|
The simplest directives are C<GET> and C<SET> which retrieve and update
|
|
variable values respectively. The C<GET> and C<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:
|
|
|
|
[% SET foo = 10 %]
|
|
[% GET foo %]
|
|
|
|
written as:
|
|
|
|
[% foo = 10 %]
|
|
[% foo %]
|
|
|
|
You can also express simple logical statements as implicit C<GET> directives:
|
|
|
|
[% title or template.title or 'Default Title' %]
|
|
|
|
[% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]
|
|
|
|
All other directives should start with a keyword specified in UPPER
|
|
CASE (but see the C<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 C<stop> which is
|
|
entirely separate from the C<STOP> directive.
|
|
|
|
[% stop = 'Clackett Lane Bus Depot' %]
|
|
|
|
The bus will next stop at [% stop %] # variable
|
|
|
|
[% STOP %] # directive
|
|
|
|
=head1 Block Directives
|
|
|
|
Directives such as C<FOREACH>, C<WHILE>, C<BLOCK>, C<FILTER>, etc., mark the
|
|
start of a block which may contain text or other directives up to the matching
|
|
C<END> directive. Blocks may be nested indefinitely. The C<IF>, C<UNLESS>,
|
|
C<ELSIF> and C<ELSE> directives also define blocks and may be grouped together
|
|
in the usual manner.
|
|
|
|
[% 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 %]
|
|
|
|
Block directives can also be used in a convenient side-effect notation.
|
|
|
|
[% INCLUDE userinfo FOREACH user = userlist %]
|
|
|
|
[% INCLUDE debugtxt msg="file: $error.info"
|
|
IF debugging %]
|
|
|
|
[% "Danger Will Robinson" IF atrisk %]
|
|
|
|
versus:
|
|
|
|
[% FOREACH user = userlist %]
|
|
[% INCLUDE userinfo %]
|
|
[% END %]
|
|
|
|
[% IF debugging %]
|
|
[% INCLUDE debugtxt msg="file: $error.info" %]
|
|
[% END %]
|
|
|
|
[% IF atrisk %]
|
|
Danger Will Robinson
|
|
[% END %]
|
|
|
|
=head1 Capturing Block Output
|
|
|
|
The output of a directive can be captured by simply assigning the directive
|
|
to a variable.
|
|
|
|
[% headtext = PROCESS header title="Hello World" %]
|
|
|
|
[% people = PROCESS userinfo FOREACH user = userlist %]
|
|
|
|
This can be used in conjunction with the C<BLOCK> directive for defining large
|
|
blocks of text or other content.
|
|
|
|
[% 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 %]
|
|
|
|
Note one important caveat of using this syntax in conjunction with side-effect
|
|
notation. The following directive does not behave as might be expected:
|
|
|
|
[% var = 'value' IF some_condition %] # does not work
|
|
|
|
In this case, the directive is interpreted as (spacing added for clarity)
|
|
|
|
[% var = IF some_condition %]
|
|
value
|
|
[% END %]
|
|
|
|
rather than
|
|
|
|
[% IF some_condition %]
|
|
[% var = 'value' %]
|
|
[% END %]
|
|
|
|
The variable is assigned the output of the C<IF> block which returns
|
|
C<'value'> if true, but nothing if false. In other words, the following
|
|
directive will always cause 'var' to be cleared.
|
|
|
|
[% var = 'value' IF 0 %]
|
|
|
|
To achieve the expected behaviour, the directive should be written as:
|
|
|
|
[% SET var = 'value' IF some_condition %]
|
|
|
|
=head1 Chaining Filters
|
|
|
|
Multiple C<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.
|
|
|
|
[% PROCESS somefile FILTER truncate(100) FILTER html %]
|
|
|
|
The pipe character, C<|>, can also be used as an alias for C<FILTER>.
|
|
|
|
[% PROCESS somefile | truncate(100) | html %]
|
|
|
|
=head1 Multiple Directive Blocks
|
|
|
|
Multiple directives can be included within a single tag when delimited
|
|
by semi-colons. Note however that the C<TAGS> directive must always
|
|
be specified in a tag by itself.
|
|
|
|
[% IF title;
|
|
INCLUDE header;
|
|
ELSE;
|
|
INCLUDE other/header title="Some Other Title";
|
|
END
|
|
%]
|
|
|
|
versus
|
|
|
|
[% IF title %]
|
|
[% INCLUDE header %]
|
|
[% ELSE %]
|
|
[% INCLUDE other/header title="Some Other Title" %]
|
|
[% END %]
|
|
|
|
=cut
|
|
|
|
# Local Variables:
|
|
# mode: perl
|
|
# perl-indent-level: 4
|
|
# indent-tabs-mode: nil
|
|
# End:
|
|
#
|
|
# vim: expandtab shiftwidth=4:
|