dwww Home | Manual pages | Find package

Template::Manual::SyntUserpContributed Perl DocumTemplate::Manual::Syntax(3pm)

NAME
       Template::Manual::Syntax - Directive syntax, structure and semantics

Tag Styles
       Template directives are embedded between start and end markers tags.
       By default these tag markers are "[%" and "%]".

           [% 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 "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.

       You can also set the "INTERPOLATE" option to allow simple variable
       references to be embedded directly in templates, prefixed by a "$".

           # 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%])

Outline Tags
       As of version 2.26, the Template Toolkit supports "outline" tags.
       These have a designated marker at the start of a line ("%%" 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 "TAGS" directive to set
       the tag style to "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 "TAGS" back to the "default" value at some point later
       in the template if you want to disable them:

           [% TAGS default -%]

       You can set the "TAG_STYLE" configuration option if you want then
       enabled in all templates by default.  You can always use the "[% TAGS
       default %]" directive to disable them in any templates or parts of
       templates if necessary.

           my $tt = Template->new({
               TAG_STYLE => 'outline',
           });

       The "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 "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

Comments
       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.

           [%# 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>
           %]

Chomping Whitespace
       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.

           [% BLOCK foo -%]    # remove trailing newline
           This is block foo
           [%- END %]          # remove leading newline

Implicit Directives: GET and SET
       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:

           [% SET foo = 10 %]
           [% GET foo %]

       written as:

           [% foo = 10 %]
           [% foo %]

       You can also express simple logical statements as implicit "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 "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.

           [% stop = 'Clackett Lane Bus Depot' %]

           The bus will next stop at [% stop %]    # variable

           [% STOP %]                              # directive

Block Directives
       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.

           [% 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 %]

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 "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 "IF" block which returns
       '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 %]

Chaining Filters
       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.

           [% PROCESS somefile FILTER truncate(100) FILTER html %]

       The pipe character, "|", can also be used as an alias for "FILTER".

           [% PROCESS somefile | truncate(100) | html %]

Multiple Directive Blocks
       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.

           [% 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 %]

perl v5.36.0                      2022-10-20     Template::Manual::Syntax(3pm)

Generated by dwww version 1.15 on Wed Jun 26 05:31:13 CEST 2024.