|
Template::Manual::Directives(3)User Contributed Perl DocumentationTemplate::Manual::Directives(3)
NAME
Template::Manual::Directives - Template directives
Accessing and Updating Template Variables
GET
The "GET" directive retrieves and outputs the value of the named variable.
[% GET foo %]
The "GET" keyword is optional. A variable can be specified in a directive tag by itself.
[% foo %]
The variable can have an unlimited number of elements, each separated by a dot. Each ele-
ment can have arguments specified within parentheses.
[% foo %]
[% bar.baz %]
[% biz.baz(10) %]
...etc...
See Template::Manual::Variables for a full discussion on template variables.
You can also specify expressions using the logical ("and", "or", "not", "?", ":") and
mathematic operators ("+", "-", "*", "/", "%", "mod", "div").
[% template.title or default.title %]
[% score * 100 %]
[% order.nitems ? checkout(order.total) : 'no items' %]
The "div" operator returns the integer result of division. Both "%" and "mod" return the
modulus (i.e. remainder) of division.
[% 15 / 6 %] # 2.5
[% 15 div 6 %] # 2
[% 15 mod 6 %] # 3
CALL
The "CALL" directive is similar to "GET" in evaluating the variable named, but doesn't
print the result returned. This can be useful when a variable is bound to a sub-routine
or object method which you want to call but aren't interested in the value returned.
[% CALL dbi.disconnect %]
[% CALL inc_page_counter(page_count) %]
SET
The "SET" directive allows you to assign new values to existing variables or create new
temporary variables.
[% SET title = 'Hello World' %]
The "SET" keyword is also optional.
[% title = 'Hello World' %]
Variables may be assigned the values of other variables, unquoted numbers (2.718), literal
text ('single quotes') or quoted text ("double quotes"). In the latter case, any variable
references within the text will be interpolated when the string is evaluated. Variables
should be prefixed by "$", using curly braces to explicitly scope the variable name where
necessary.
[% foo = 'Foo' %] # literal value 'Foo'
[% bar = foo %] # value of variable 'foo'
[% cost = '$100' %] # literal value '$100'
[% item = "$bar: ${cost}.00" %] # value "Foo: $100.00"
Multiple variables may be assigned in the same directive and are evaluated in the order
specified. Thus, the above could have been written:
[% foo = 'Foo'
bar = foo
cost = '$100'
item = "$bar: ${cost}.00"
%]
Simple expressions can also be used, as per "GET".
[% ten = 10
twenty = 20
thirty = twenty + ten
forty = 2 * twenty
fifty = 100 div 2
six = twenty mod 7
%]
You can concatenate strings together using the ' _ ' operator. In Perl 5, the "." is used
for string concatenation, but in Perl 6, as in the Template Toolkit, the "." will be used
as the method calling operator and ' _ ' will be used for string concatenation. Note that
the operator must be specified with surrounding whitespace which, as Larry says, is con-
strued as a feature:
[% copyright = '(C) Copyright' _ year _ ' ' _ author %]
You can, of course, achieve a similar effect with double quoted string interpolation.
[% copyright = "(C) Copyright $year $author" %]
DEFAULT
The "DEFAULT" directive is similar to "SET" but only updates variables that are currently
undefined or have no "true" value (in the Perl sense).
[% DEFAULT
name = 'John Doe'
id = 'jdoe'
%]
This can be particularly useful in common template components to ensure that some sensible
default are provided for otherwise undefined variables.
[% DEFAULT
title = 'Hello World'
bgcol = '#ffffff'
%]
[% title %]section/footer: The "WRAPPER" directive provides a way of simplifying this a little. It encloses a block up to a matching "END" directive, which is first processed to generate some output. This is then passed to the named template file or "BLOCK" as the "content" variable. [% WRAPPER section title = 'Quantum Mechanics' %] Quantum mechanics is a very interesting subject wish should prove easy for the layman to fully comprehend. [% END %] [% WRAPPER section title = 'Desktop Nuclear Fusion for under $50' %] This describes a simple device which generates significant sustainable electrical power from common tap water by process of nuclear fusion. [% END %] The single 'section' template can then be defined as:[% title %][% content %] Like other block directives, it can be used in side-effect notation: [% INSERT legalese.txt WRAPPER big_bold_table %] It's also possible to specify multiple templates to a "WRAPPER" directive. The specifica- tion order indicates outermost to innermost wrapper templates. For example, given the following template block definitions: [% BLOCK bold %][% content %][% END %] [% BLOCK italic %][% content %][% END %] the directive [% WRAPPER bold+italic %]Hello World[% END %] would generate the following output: Hello World BLOCK The "BLOCK"..."END" construct can be used to define template component blocks which can be processed with the "INCLUDE", "PROCESS" and "WRAPPER" directives. [% BLOCK tabrow %] | ||
| [% name %] | [% email %] |
We apologise for the inconvenience.
[% INCLUDE footer %] [% STOP %] [% END %] CLEAR The "CLEAR" directive can be used to clear the output buffer for the current enclosing block. It is most commonly used to clear the output generated from a "TRY" block up to the point where the error occurred. [% TRY %] blah blah blah # this is normally left intact [% THROW some 'error' %] # up to the point of error ... [% CATCH %] [% CLEAR %] # clear the TRY output [% error %] # print error string [% END %] Miscellaneous META The "META" directive allows simple metadata items to be defined within a template. These are evaluated when the template is parsed and as such may only contain simple values (e.g. it's not possible to interpolate other variables values into "META" variables). [% META title = 'The Cat in the Hat' author = 'Dr. Seuss' version = 1.23 %] The "template" variable contains a reference to the main template being processed. These metadata items may be retrieved as attributes of the template.