xdocs/vtl-reference-guide.xml - velocity-engine - Git at Google

 <?xml version="1.0"?>

 <document>

  <properties>
   <title>VTL Reference Guide</title>
   <author email="jvanzyl@zenplex.com">Velocity Documentation Team</author>
   <author email="jcastura@apache.org">John Castura</author>
  </properties>

 <body>

 <section name="About this Guide">
 <p>
     This guide is the reference for the Velocity Template Language
     (VTL). For more information, please also refer to the <a
     href="user-guide.html">Velocity User Guide</a>.
 </p>

 </section>

 <section name="References">
     <subsection name="Variables">
     <p>
     Notation:
     </p>

     <p>
     <strong>$</strong> [ <strong>!</strong> ][ <strong>{</strong> ][
     <strong>a..z</strong>, <strong>A..Z</strong> ][ <strong>a..z</strong>,
     <strong>A..Z</strong>, <strong>0..9</strong>, <strong>-</strong>,
     <strong>_</strong> ][ <strong>}</strong> ]
     </p>

     <p>
     Examples:
     </p>

     <ul>
         <li>Normal notation: <variable>$mud-Slinger_9</variable></li>
         <li>Silent notation: <variable>$!mud-Slinger_9</variable></li>
         <li>Formal notation: <variable>${mud-Slinger_9}</variable></li>
     </ul>
   </subsection>

   <subsection name="Properties">
     <p>
     Notation:
     </p>

     <p>
       <strong>$</strong> [ <strong>{</strong> ][ <strong>a..z</strong>,
       <strong>A..Z</strong> ][ <strong>a..z</strong>, <strong>A..Z</strong>,
       <strong>0..9</strong>, <strong>-</strong>, <strong>_</strong> ]*
       <strong>.</strong>[<strong>a..z</strong>, <strong>A..Z</strong> ][
       <strong>a..z</strong>, <strong>A-Z</strong>, <strong>0..9</strong>,
       <strong>-</strong>, <strong>_</strong> ]* [ <strong>}</strong> ]
     </p>

     <p>
     Examples:
     </p>

     <ul>
         <li>Regular Notation: $customer.Address</li>
         <li>Formal Notation: ${purchase.Total}</li>
     </ul>
   </subsection>

   <subsection name="Methods">
     <p>
     Notation:
     </p>

     <p>
       <strong>$</strong> [ <strong>{</strong> ][ <strong>a..z</strong>,
       <strong>A..Z</strong> ][ <strong>a..z</strong>, <strong>A..Z</strong>,
       <strong>0..9</strong>, <strong>-</strong>, <strong>_</strong> ]*
       <strong>.</strong>[ <strong>a..z</strong>, <strong>A..Z</strong> ][
       <strong>a..z</strong>, <strong>A..Z</strong>, <strong>0..9</strong>,
       <strong>-</strong>, <strong>_</strong> ]*<strong>(</strong> [
       <i>opional parameter list...</i> ] <strong>)</strong> [
       <strong> } </strong>]
     </p>

     <p>
     Examples:
     </p>

     <ul>
       <li>Regular Notation: $customer.getAddress()</li>
       <li>Formal Notation: ${purchase.getTotal()}</li>
       <li>Regular Notation with Parameter List: $page.setTitle( "My Home
       Page" )</li>
     </ul>
   </subsection>

   <p>
   VTL Properties can be used as a shorthand notation for VTL Methods
   that take <em>get</em> and <em>set</em>. Either
   <em>$object.getMethod()</em> or <em>$object.setMethod()</em> can be
   abbreviated as <em>$object.Method</em>. It is generally preferable to
   use a Property when available. The main difference between Properties
   and Methods is that you can specify a parameter list to a Method.
   </p>

 </section>

 <section name="Directives">
   <subsection name="#set - Establishes the value of a reference">
     <p>
     Format:
     </p>

     <p>
     <strong>#set( $</strong>ref <strong>=</strong> [ <strong>"</strong>,
     <strong>'</strong> ]arg[ <strong>"</strong>, <strong>'</strong> ] )
     </p>

     <p>
     Usage:
     </p>

     <ul>
     <li><em>$ref</em> - The LHS of the assignment must be a variable
     reference or a property reference.</li>
     <li><em>arg</em> - The RHS of the assignment, <em>arg</em> is parsed
     if enclosed in double quotes, and not parsed if enclosed in single
     quotes.  If the RHS evaluates to <em>null</em>, it is <b>not</b>
     assigned to the LHS.</li>
     </ul>

     <p>
     Examples:
     </p>

     <ul>
       <li>Variable reference: #set( $monkey = "bill" )</li>
       <li>String literal: #set( $monkey.Friend = "monica" )</li>
       <li>Property reference: #set( $monkey.Blame = $whitehouse.Leak
       )</li>
       <li>Method reference: #set( $monkey.Plan = $spindoctor.weave($web)
       )</li>
       <li>Number literal: #set( $monkey.Number = 123 )</li>
       <li>Range operator: #set( $monkey.Numbers = [1..3] )</li>
       <li>Object array: #set( $monkey.Say = ["Not", $my, "fault"] )</li>
     </ul>

     <p>
     The RHS can also be a simple arithmetic expression, such as:
     </p>

     <ul>
       <li>Addition: #set( $value = $foo + 1 )</li>
       <li>Subtraction: #set( $value = $bar - 1 )</li>
       <li>Multiplication: #set( $value = $foo * $bar )</li>
       <li>Division: #set( $value = $foo / $bar )</li>
       <li>Remainder: #set( $value = $foo % $bar )</li>
     </ul>
   </subsection>

   <subsection name="#if / #elseif / #else - output conditional on truth
   of statements">
     <p>
     Format:
     </p>

     <p>
     <strong>#if(</strong> [condition] <strong>)</strong> [output] [
     <strong>#elseif( </strong>[condition] <strong>)</strong> [output] ]* [
     <strong>#else</strong> [output] ]
     <strong>#end</strong>
     </p>

     <p>
     Usage:
     </p>

     <ul>
     <li><em>condition</em> - If a boolean, considered true if it has a
     true false; if not a boolean, considered true if not null.</li>
     <li><em>output</em> - May contain VTL.</li>
     </ul>

     <p>
     Examples:
     </p>

     <ul>
        <li>Equivalent Operator: #if( $foo == $bar )</li>
        <li>Greater Than: #if( $foo > 42 )</li>
        <li>Less Than: #if( $foo &lt; 42 )</li>
        <li>Greater Than or Equal To: #if( $foo >= 42 )</li>
        <li>Less Than or Equal To: #if( $foo &lt;= 42 )</li>
        <li>Equals Number: #if( $foo == 42 )</li>
        <li>Equals String: #if( $foo == "bar" )</li>
        <li>Boolean NOT: #if( !$foo )</li>
     </ul>
   </subsection>

   <subsection name="#foreach - Loops through a list of objects">
     <p>
     Format:
     </p>

     <p>
     <strong>#foreach(</strong> <em>$ref</em> <strong>in</strong> <em>arg</em>
     <strong>)</strong> <em>statement</em> <strong>#end</strong>
     </p>

     <p>
     Usage:
     </p>

     <ul>
     <li><em>$ref</em> - The first variable reference is the item.</li>

     <li><em>arg</em> - May be one of the following: a reference to a
         list (i.e. object array, collection, or map), an array list, or
         the range operator.</li>

     <li>
     <em>statement</em> - What is output each time Velocity finds a
     valid item in the list denoted above as <i>arg</i>.  This output is
     any valid VTL and is rendered each iteration of the loop.
     </li>

     </ul>

     <p>
     Examples of the #foreach(), omitting the statement block :
     </p>

     <ul>
       <li>Reference: #foreach ( $item in $items )</li>
       <li>Array list: #foreach ( $item in ["Not", $my, "fault"] )</li>
       <li>Range operator: #foreach ( $item in [1..3] )</li>
     </ul>

     <p>
     Velocity provides an easy way to get the loop counter so that you
     can do something like the following:
     </p>

 <source><![CDATA[
 <table>
 #foreach( $customer in $customerList )
     <tr><td>$velocityCount</td><td>$customer.Name</td></tr>
 #end
 </table>
 ]]></source>

     <p>
     The default name for the loop counter variable reference, which is
     specified in the velocity.properties file, is $velocityCount. By
     default the counter starts at 1, but this can be set to either 0 or
     1 in the <code>velocity.properties</code> file. Here's what the loop
     counter properties section of the <code>velocity.properties</code>
     file appears:
     </p>

 <source><![CDATA[
 # Default name of the loop counter
 # variable refernce.
 counter.name = velocityCount

 # Default starting value of the loop
 # counter variable reference.
 counter.initial.value = 1
 ]]></source>

   </subsection>

   <subsection name="#include - Renders local file(s) that are not
                     parsed by Velocity">
     <p>
     Format:
     </p>

     <p>
     <strong>#include( </strong>arg[, arg2, ... argn]<strong> )</strong>
     </p>

     <ul>
     <li><em>arg</em> - Refers to a valid file under TEMPLATE_ROOT.</li>
     </ul>

     <p>
     Examples:
     </p>

     <ul>
       <li>String: #include( "disclaimer.txt", "opinion.txt" )</li>
       <li>Variable: #include( $foo, $bar )</li>
     </ul>
   </subsection>

   <subsection name="#parse - Renders a local template that is parsed by
                     Velocity">
     <p>
     Format:
     </p>

     <p>
     <strong>#parse(</strong> arg <strong>)</strong>
     </p>

     <ul>
     <li><em>arg</em> - Refers to a template under TEMPLATE_ROOT.</li>
     </ul>

     <p>
     Examples:
     </p>

     <ul>
       <li>String: #parse( "lecorbusier.vm" )</li>
       <li>Variable: #parse( $foo )</li>
     </ul>

     <p>
     Recursion permitted. See <em>parse_directive.maxdepth</em> in
     <code>velocity.properties</code>
     to change from parse depth. (The default parse depth is 10.)
     </p>
   </subsection>

   <subsection name="#stop - Stops the template engine">
     <p>
     Format:
     </p>

     <p>
     <strong>#stop</strong>
     </p>

     <p>
     Usage:
     </p>

     <p>
     This will stop execution of the current template. This is good for
     debugging a template.
     </p>
   </subsection>

   <subsection name="#macro - Allows users to define a Velocimacro (VM),
         a repeated segment of a VTL template, as required">
     <p>
     Format:
     </p>

     <p>
     <strong>#macro(</strong> vmname $arg1[, $arg2, $arg3, ... $argn ]
     <strong>)</strong> [ VM VTL code... ] <strong>#end</strong>
     </p>

     <ul>
     <li><em>vmname</em> - Name used to call the VM
     (<em>#vmname</em>)</li>
     <li><em>$arg1 $arg2 [ ... ]</em> - Arguments to the VM. There can be
     any number of argumentss, but the number used at invocation must
     match the number specified in the definition.</li>
     <li><em>[ VM VTL code... ]</em> - Any valid VTL code, anything you
     can put into a template, can be put into a VM.</li>
     </ul>

     <p>
     Once defined, the VM is used like any other VTL directive in a
     template.
     </p>

 <source><![CDATA[
 #vmname( $arg1 $arg2 )
 ]]></source>

     <p>
     VMs can be defined in one of two places:
     </p>

     <ol>
     <li><i>Template library:</i> can be either VMs pre-packaged with
     Velocity or custom-made, user-defined, site-specific VMs;
      available from any template</li>
     <li><i>Inline:</i> found in regular templates, only usable when
     <em>velocimacro.permissions.allowInline=true</em> in
     <code>velocity.properties</code>.</li>
     </ol>
   </subsection>


 </section>

 <section name="Comments">
     <p>
     Comments are not rendered at runtime.
     </p>

     <subsection name="Single Line">
     <p>
     Example:
     </p>

     <p>
     <strong>## This is a comment.</strong>
     </p>

     </subsection>
     <subsection name="Multi Line">
     <p>
     Example:
     </p>

     <p>
     <strong>
     #*<br/>
     This is a multiline comment.<br/>
     This is the second line<br/>
     *#
     </strong>
     </p>

     </subsection>
 </section>

 </body>
 </document>
	<?xml version="1.0"?>

	<document>

	<properties>
	<title>VTL Reference Guide</title>
	<author email="jvanzyl@zenplex.com">Velocity Documentation Team</author>
	<author email="jcastura@apache.org">John Castura</author>
	</properties>

	<body>

	<section name="About this Guide">
	<p>
	This guide is the reference for the Velocity Template Language
	(VTL). For more information, please also refer to the <a
	href="user-guide.html">Velocity User Guide</a>.
	</p>

	</section>

	<section name="References">
	<subsection name="Variables">
	<p>
	Notation:
	</p>

	<p>
	<strong>$</strong> [ <strong>!</strong> ][ <strong>{</strong> ][
	<strong>a..z</strong>, <strong>A..Z</strong> ][ <strong>a..z</strong>,
	<strong>A..Z</strong>, <strong>0..9</strong>, <strong>-</strong>,
	<strong>_</strong> ][ <strong>}</strong> ]
	</p>

	<p>
	Examples:
	</p>

	<ul>
	<li>Normal notation: <variable>$mud-Slinger_9</variable></li>
	<li>Silent notation: <variable>$!mud-Slinger_9</variable></li>
	<li>Formal notation: <variable>${mud-Slinger_9}</variable></li>
	</ul>
	</subsection>

	<subsection name="Properties">
	<p>
	Notation:
	</p>

	<p>
	<strong>$</strong> [ <strong>{</strong> ][ <strong>a..z</strong>,
	<strong>A..Z</strong> ][ <strong>a..z</strong>, <strong>A..Z</strong>,
	<strong>0..9</strong>, <strong>-</strong>, <strong>_</strong> ]*
	<strong>.</strong>[<strong>a..z</strong>, <strong>A..Z</strong> ][
	<strong>a..z</strong>, <strong>A-Z</strong>, <strong>0..9</strong>,
	<strong>-</strong>, <strong>_</strong> ]* [ <strong>}</strong> ]
	</p>

	<p>
	Examples:
	</p>

	<ul>
	<li>Regular Notation: $customer.Address</li>
	<li>Formal Notation: ${purchase.Total}</li>
	</ul>
	</subsection>

	<subsection name="Methods">
	<p>
	Notation:
	</p>

	<p>
	<strong>$</strong> [ <strong>{</strong> ][ <strong>a..z</strong>,
	<strong>A..Z</strong> ][ <strong>a..z</strong>, <strong>A..Z</strong>,
	<strong>0..9</strong>, <strong>-</strong>, <strong>_</strong> ]*
	<strong>.</strong>[ <strong>a..z</strong>, <strong>A..Z</strong> ][
	<strong>a..z</strong>, <strong>A..Z</strong>, <strong>0..9</strong>,
	<strong>-</strong>, <strong>_</strong> ]*<strong>(</strong> [
	<i>opional parameter list...</i> ] <strong>)</strong> [
	<strong> } </strong>]
	</p>

	<p>
	Examples:
	</p>

	<ul>
	<li>Regular Notation: $customer.getAddress()</li>
	<li>Formal Notation: ${purchase.getTotal()}</li>
	<li>Regular Notation with Parameter List: $page.setTitle( "My Home
	Page" )</li>
	</ul>
	</subsection>

	<p>
	VTL Properties can be used as a shorthand notation for VTL Methods
	that take <em>get</em> and <em>set</em>. Either
	<em>$object.getMethod()</em> or <em>$object.setMethod()</em> can be
	abbreviated as <em>$object.Method</em>. It is generally preferable to
	use a Property when available. The main difference between Properties
	and Methods is that you can specify a parameter list to a Method.
	</p>

	</section>

	<section name="Directives">
	<subsection name="#set - Establishes the value of a reference">
	<p>
	Format:
	</p>

	<p>
	<strong>#set( $</strong>ref <strong>=</strong> [ <strong>"</strong>,
	<strong>'</strong> ]arg[ <strong>"</strong>, <strong>'</strong> ] )
	</p>

	<p>
	Usage:
	</p>

	<ul>
	<li><em>$ref</em> - The LHS of the assignment must be a variable
	reference or a property reference.</li>
	<li><em>arg</em> - The RHS of the assignment, <em>arg</em> is parsed
	if enclosed in double quotes, and not parsed if enclosed in single
	quotes. If the RHS evaluates to <em>null</em>, it is <b>not</b>
	assigned to the LHS.</li>
	</ul>

	<p>
	Examples:
	</p>

	<ul>
	<li>Variable reference: #set( $monkey = "bill" )</li>
	<li>String literal: #set( $monkey.Friend = "monica" )</li>
	<li>Property reference: #set( $monkey.Blame = $whitehouse.Leak
	)</li>
	<li>Method reference: #set( $monkey.Plan = $spindoctor.weave($web)
	)</li>
	<li>Number literal: #set( $monkey.Number = 123 )</li>
	<li>Range operator: #set( $monkey.Numbers = [1..3] )</li>
	<li>Object array: #set( $monkey.Say = ["Not", $my, "fault"] )</li>
	</ul>

	<p>
	The RHS can also be a simple arithmetic expression, such as:
	</p>

	<ul>
	<li>Addition: #set( $value = $foo + 1 )</li>
	<li>Subtraction: #set( $value = $bar - 1 )</li>
	<li>Multiplication: #set( $value = $foo * $bar )</li>
	<li>Division: #set( $value = $foo / $bar )</li>
	<li>Remainder: #set( $value = $foo % $bar )</li>
	</ul>
	</subsection>

	<subsection name="#if / #elseif / #else - output conditional on truth
	of statements">
	<p>
	Format:
	</p>

	<p>
	<strong>#if(</strong> [condition] <strong>)</strong> [output] [
	<strong>#elseif( </strong>[condition] <strong>)</strong> [output] ]* [
	<strong>#else</strong> [output] ]
	<strong>#end</strong>
	</p>

	<p>
	Usage:
	</p>

	<ul>
	<li><em>condition</em> - If a boolean, considered true if it has a
	true false; if not a boolean, considered true if not null.</li>
	<li><em>output</em> - May contain VTL.</li>
	</ul>

	<p>
	Examples:
	</p>

	<ul>
	<li>Equivalent Operator: #if( $foo == $bar )</li>
	<li>Greater Than: #if( $foo > 42 )</li>
	<li>Less Than: #if( $foo < 42 )</li>
	<li>Greater Than or Equal To: #if( $foo >= 42 )</li>
	<li>Less Than or Equal To: #if( $foo <= 42 )</li>
	<li>Equals Number: #if( $foo == 42 )</li>
	<li>Equals String: #if( $foo == "bar" )</li>
	<li>Boolean NOT: #if( !$foo )</li>
	</ul>
	</subsection>

	<subsection name="#foreach - Loops through a list of objects">
	<p>
	Format:
	</p>

	<p>
	<strong>#foreach(</strong> <em>$ref</em> <strong>in</strong> <em>arg</em>
	<strong>)</strong> <em>statement</em> <strong>#end</strong>
	</p>

	<p>
	Usage:
	</p>

	<ul>
	<li><em>$ref</em> - The first variable reference is the item.</li>

	<li><em>arg</em> - May be one of the following: a reference to a
	list (i.e. object array, collection, or map), an array list, or
	the range operator.</li>

	<li>
	<em>statement</em> - What is output each time Velocity finds a
	valid item in the list denoted above as <i>arg</i>. This output is
	any valid VTL and is rendered each iteration of the loop.
	</li>

	</ul>

	<p>
	Examples of the #foreach(), omitting the statement block :
	</p>

	<ul>
	<li>Reference: #foreach ( $item in $items )</li>
	<li>Array list: #foreach ( $item in ["Not", $my, "fault"] )</li>
	<li>Range operator: #foreach ( $item in [1..3] )</li>
	</ul>

	<p>
	Velocity provides an easy way to get the loop counter so that you
	can do something like the following:
	</p>

	<source><![CDATA[
	<table>
	#foreach( $customer in $customerList )
	<tr><td>$velocityCount</td><td>$customer.Name</td></tr>
	#end
	</table>
	]]></source>

	<p>
	The default name for the loop counter variable reference, which is
	specified in the velocity.properties file, is $velocityCount. By
	default the counter starts at 1, but this can be set to either 0 or
	1 in the <code>velocity.properties</code> file. Here's what the loop
	counter properties section of the <code>velocity.properties</code>
	file appears:
	</p>

	<source><![CDATA[
	# Default name of the loop counter
	# variable refernce.
	counter.name = velocityCount

	# Default starting value of the loop
	# counter variable reference.
	counter.initial.value = 1
	]]></source>

	</subsection>

	<subsection name="#include - Renders local file(s) that are not
	parsed by Velocity">
	<p>
	Format:
	</p>

	<p>
	<strong>#include( </strong>arg[, arg2, ... argn]<strong> )</strong>
	</p>

	<ul>
	<li><em>arg</em> - Refers to a valid file under TEMPLATE_ROOT.</li>
	</ul>

	<p>
	Examples:
	</p>

	<ul>
	<li>String: #include( "disclaimer.txt", "opinion.txt" )</li>
	<li>Variable: #include( $foo, $bar )</li>
	</ul>
	</subsection>

	<subsection name="#parse - Renders a local template that is parsed by
	Velocity">
	<p>
	Format:
	</p>

	<p>
	<strong>#parse(</strong> arg <strong>)</strong>
	</p>

	<ul>
	<li><em>arg</em> - Refers to a template under TEMPLATE_ROOT.</li>
	</ul>

	<p>
	Examples:
	</p>

	<ul>
	<li>String: #parse( "lecorbusier.vm" )</li>
	<li>Variable: #parse( $foo )</li>
	</ul>

	<p>
	Recursion permitted. See <em>parse_directive.maxdepth</em> in
	<code>velocity.properties</code>
	to change from parse depth. (The default parse depth is 10.)
	</p>
	</subsection>

	<subsection name="#stop - Stops the template engine">
	<p>
	Format:
	</p>

	<p>
	<strong>#stop</strong>
	</p>

	<p>
	Usage:
	</p>

	<p>
	This will stop execution of the current template. This is good for
	debugging a template.
	</p>
	</subsection>

	<subsection name="#macro - Allows users to define a Velocimacro (VM),
	a repeated segment of a VTL template, as required">
	<p>
	Format:
	</p>

	<p>
	<strong>#macro(</strong> vmname $arg1[, $arg2, $arg3, ... $argn ]
	<strong>)</strong> [ VM VTL code... ] <strong>#end</strong>
	</p>

	<ul>
	<li><em>vmname</em> - Name used to call the VM
	(<em>#vmname</em>)</li>
	<li><em>$arg1 $arg2 [ ... ]</em> - Arguments to the VM. There can be
	any number of argumentss, but the number used at invocation must
	match the number specified in the definition.</li>
	<li><em>[ VM VTL code... ]</em> - Any valid VTL code, anything you
	can put into a template, can be put into a VM.</li>
	</ul>

	<p>
	Once defined, the VM is used like any other VTL directive in a
	template.
	</p>

	<source><![CDATA[
	#vmname( $arg1 $arg2 )
	]]></source>

	<p>
	VMs can be defined in one of two places:
	</p>

	<ol>
	<li><i>Template library:</i> can be either VMs pre-packaged with
	Velocity or custom-made, user-defined, site-specific VMs;
	available from any template</li>
	<li><i>Inline:</i> found in regular templates, only usable when
	<em>velocimacro.permissions.allowInline=true</em> in
	<code>velocity.properties</code>.</li>
	</ol>
	</subsection>


	</section>

	<section name="Comments">
	<p>
	Comments are not rendered at runtime.
	</p>

	<subsection name="Single Line">
	<p>
	Example:
	</p>

	<p>
	<strong>## This is a comment.</strong>
	</p>

	</subsection>
	<subsection name="Multi Line">
	<p>
	Example:
	</p>

	<p>
	<strong>
	#*<br/>
	This is a multiline comment.<br/>
	This is the second line<br/>
	*#
	</strong>
	</p>

	</subsection>
	</section>

	</body>
	</document>