| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| |
| <!-- Content Stylesheet for Site --> |
| |
| |
| <!-- start the processing --> |
| <!-- ====================================================================== --> |
| <!-- Main Page Section --> |
| <!-- ====================================================================== --> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/> |
| |
| <meta name="author" value="Velocity Documentation Team"> |
| <meta name="email" value="jvanzyl@locus.apache.org"> |
| <meta name="author" value="John Castura"> |
| <meta name="email" value="jcastura@apache.org"> |
| |
| <title>Velocity - VTL Reference Guide</title> |
| </head> |
| |
| <body bgcolor="#ffffff" text="#000000" link="#525D76"> |
| <table border="0" width="100%" cellspacing="0"> |
| <!-- TOP IMAGE --> |
| <tr> |
| <td align="left"> |
| <a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif" border="0"/></a> |
| </td> |
| <td align="right"> |
| <a href="http://jakarta.apache.org/velocity/"><img src="./images/logo.gif" alt="Velocity" border="0"/></a> |
| </td> |
| </tr> |
| </table> |
| <table border="0" width="100%" cellspacing="4"> |
| <tr><td colspan="2"> |
| <hr noshade="" size="1"/> |
| </td></tr> |
| |
| <tr> |
| <!-- LEFT SIDE NAVIGATION --> |
| <td valign="top" nowrap="true"> |
| <p><strong>About</strong></p> |
| <ul> |
| <li> <a href="./index.html">Overview</a> |
| </li> |
| <li> <a href="./getting-started.html">Getting Started</a> |
| </li> |
| <li> <a href="./install.html">Install</a> |
| </li> |
| <li> <a href="./design.html">Design</a> |
| </li> |
| <li> <a href="./contributors.html">Contributors</a> |
| </li> |
| <li> <a href="./code-standards.html">Coding Standards</a> |
| </li> |
| <li> <a href="./license.html">License</a> |
| </li> |
| <li> <a href="./todo.html">TODO</a> |
| </li> |
| </ul> |
| <p><strong>Guides</strong></p> |
| <ul> |
| <li> <a href="./user-guide.html">User's Guide</a> |
| </li> |
| <li> <a href="./developer-guide.html">Developer's Guide</a> |
| </li> |
| <li> <a href="./vtl-reference-guide.html">VTL Reference Guide</a> |
| </li> |
| </ul> |
| <p><strong>Comparisons</strong></p> |
| <ul> |
| <li> <a href="./ymtd.html">YMTD</a> |
| </li> |
| <li> <a href="./differences.html">VM/WM Differences</a> |
| </li> |
| </ul> |
| <p><strong>Tools</strong></p> |
| <ul> |
| <li> <a href="./anakia.html">Anakia</a> |
| </li> |
| <li> <a href="./texen.html">Texen</a> |
| </li> |
| <li> <a href="./migration.html">Migration to Velocity</a> |
| </li> |
| </ul> |
| </td> |
| <td align="left" valign="top"> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#525D76"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>About this Guide</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| This guide is the definitive but imcomplete reference for |
| the Velocity Template Language (VTL). For more information, |
| please refer to the Velocity User Guide. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#525D76"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>References</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>Variables</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Notation: |
| <br /> |
| <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> ] |
| |
| <br /> |
| Examples: |
| <br /> |
| Normal notation: <variable>$mud-Slinger_9</variable><br /> |
| Silent notation: <variable>$!mud-Slinger_9</variable><br /> |
| Formal notation: <variable>${mud-Slinger_9}</variable><br /> |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>Properties</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Notation: |
| <br /> |
| <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> ] |
| <br /> |
| Examples: |
| <br /> |
| Regular Notation: $customer.Address<br /> |
| Formal Notation: ${purchase.Total}<br /> |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>Methods</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Notation: |
| <br /> |
| <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>] |
| <br /> |
| Examples: |
| <br /> |
| Regular Notation: $customer.getAddress()<br /> |
| Formal Notation: ${purchase.getTotal()}<br /> |
| Regular Notation with Parameter List: $page.setTitle( "My Home Page" )<br /> |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <em>get</em> |
| <em>set</em> |
| <em>$object.getMethod()</em> |
| <em>$object.setMethod()</em> |
| <em>$object.Method</em> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#525D76"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>Directives</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>#set - Establishes the value of a reference</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Format: |
| <br /> |
| <strong>#set( $</strong>ref <strong>=</strong> [ <strong>"</strong>, |
| <strong>'</strong> ]arg[ <strong>"</strong>, <strong>'</strong> ] ) |
| <br /> |
| Usage: |
| <br /> |
| <em>$ref</em> - The LHS of the assignment must be a variable reference or |
| a property reference. |
| <br /> |
| <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. |
| Examples of possible types are demonstrated: |
| <br /> |
| <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>Object array: #set( $monkey.Say = ["Not", $my, "fault"] )</li> |
| </ul> |
| The RHS can also be a simple arithmetic expression, such as:<br /> |
| <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> |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>#if / #elseif / #else - output conditional on truth of statements</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Format: |
| <br /> |
| <strong>#if(</strong> [condition] <strong>)</strong> [output] [ |
| <strong>#elseif( </strong>[condition] <strong>)</strong> [output] ]* [ |
| <strong>#else( </strong>[condition] <strong>)</strong> [output] ] |
| <strong>#end</strong> |
| <br /> |
| Usage: |
| <br /> |
| <em>condition</em> - If a boolean, considered true if it has a true false; |
| if not a boolean, considered true if not null. Examples of conditions are |
| listed below: |
| <br /> |
| <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> |
| </ul> |
| <em>output</em> - May contain VTL. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>#foreach - Loops through a list of objects</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Format: |
| <br /> |
| <strong>#foreach( $</strong>ref1 <strong>in $</strong>ref2 |
| <strong>)</strong> [ statement... ] <strong>#end</strong> |
| <br /> |
| Usage: |
| <br /> |
| <em>$ref1</em> - The first variable reference is the item.<br /> |
| <em>$ref2</em> - The second variable reference is the list that holds the |
| items.<br /> |
| <em>statement</em> - What is done each time Velocity finds a valid item |
| ($ref1) in the list ($ref2).<br /> |
| Velocity provides an easy way to get the loop counter so that you can do |
| something like the following:<br /> |
| </p> |
| <div align="left"> |
| <table cellspacing="4" cellpadding="0" border="0"> |
| <tr> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| </tr> |
| <tr> |
| <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#ffffff"><pre> |
| <table> |
| #foreach( $customer in $customerList ) |
| <tr><td> $velocityCounter </td><td> $customer.Name </td></tr> |
| #end </table> |
| </pre></td> |
| <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| </tr> |
| <tr> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| </tr> |
| </table> |
| </div> |
| <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 <filename>velocity.properties |
| </filename> file. Here's what the loop counter properties section of the |
| <filename>velocity.properties</filename> file appears: |
| </p> |
| <div align="left"> |
| <table cellspacing="4" cellpadding="0" border="0"> |
| <tr> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| </tr> |
| <tr> |
| <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#ffffff"><pre> |
| # Default name of the loop counter |
| # variable refernce. |
| counter.name = velocityCount |
| |
| # Default starting value of the loop |
| # counter variable reference. |
| counter.initial.value = 1 |
| </pre></td> |
| <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| </tr> |
| <tr> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| </tr> |
| </table> |
| </div> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>#include - Renders local file(s) that are not parsed by Velocity</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Format: |
| <br /> |
| <strong>#include( </strong>arg[, arg2, ... argn]<strong> )</strong> |
| <br /> |
| <em>arg</em> - Refers to a valid file under TEMPLATE_ROOT. Can be one of two types: |
| <br /> |
| <ul> |
| <li>String: #include( "disclaimer.txt", "opinion.txt" )</li> |
| <li>Variable: #include( $foo, $bar )</li> |
| </ul> |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>#parse - Renders a local template that is parsed by Velocity</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Format: |
| <br /> |
| <strong>#parse( </strong>arg<strong> )</strong> |
| <br /> |
| <em>arg</em> - Refers to a template under TEMPLATE_ROOT. Can be one of two types: |
| <br /> |
| <ul> |
| <li>String: #parse( "lecorbusier.vm" )</li> |
| <li>Variable: #parse( $foo )</li> |
| </ul> |
| <br /> |
| Recursion permitted. See <em>parse_directive.maxdepth</em> in |
| <filename>velocity.properties</filename> |
| to change from parse depth. (The default parse depth is 10.) |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>#stop - Stops the template engine</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Format: |
| <br /> |
| #stop |
| <br /> |
| Usage: |
| <br /> |
| Intended for debugging purposes. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <strong>#macro - Allows users to define a Velocimacro (VM), a repeated segment of a VTL template, as required</strong> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Format: |
| <br /> |
| <strong>#macro(</strong> vmname $arg1[, $arg2, $arg3, ... $argn ] |
| <strong>)</strong> [ VM VTL code... ] <strong>#end</strong> |
| <br /> |
| <em>vmname</em> - Name used to call the VM (<em>#vmname</em>)<br /> |
| <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. |
| <br /> |
| <em>[ VM VTL code... ]</em> - Any valid VTL code, anything you can put into |
| a template, can be put into a VM. |
| <br /> |
| |
| Once defined, the VM is used like any other VTL directive in a template. |
| </p> |
| <div align="left"> |
| <table cellspacing="4" cellpadding="0" border="0"> |
| <tr> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| </tr> |
| <tr> |
| <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#ffffff"><pre> |
| #vmname( $arg1 $arg2 ) |
| </pre></td> |
| <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| </tr> |
| <tr> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> |
| </tr> |
| </table> |
| </div> |
| <p> |
| VMs can be defined in one of three places: |
| <br /> |
| <i>Global library:</i> VMs pre-packaged with Velocity; available from any template<br /> |
| <i>Local library:</i> customized, user-defined, site-specific VMs; availabe from any template<br /> |
| <i>Inline:</i> found in regular templates, only usable when <em>velocimacro.permissions.allowInline=true</em> in <filename>velocity.properties</filename>. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| </blockquote> |
| </td></tr> |
| </table> |
| </td> |
| </tr> |
| |
| <!-- FOOTER --> |
| <tr><td colspan="2"> |
| <hr noshade="" size="1"/> |
| </td></tr> |
| <tr><td colspan="2"> |
| <div align="center"><font color="#525D76" size="-1"><em> |
| Copyright © 1999-2001, Apache Software Foundation |
| </em></font></div> |
| </td></tr> |
| </table> |
| </body> |
| </html> |
| <!-- end the processing --> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
