Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Template::Manual::SyntUser)Contributed Perl DocumenTemplate::Manual::Syntax(3)

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.24.1			  2014-04-24	   Template::Manual::Syntax(3)

NAME | Tag Styles | Outline Tags | Comments | Chomping Whitespace | Implicit Directives: GET and SET | Block Directives | Capturing Block Output | Chaining Filters | Multiple Directive Blocks

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Template::Manual::Syntax&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help