| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <!-- start the processing --> |
| <!-- ====================================================================== --> |
| <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! --> |
| <!-- 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="dev@velocity.apache.org"> |
| |
| |
| |
| |
| <title>Velocity - VTL Reference</title> |
| |
| <link rel="stylesheet" href="./site.css" type="text/css"> |
| </head> |
| |
| <body> |
| |
| |
| <div id="container"> |
| <div id="body"> |
| <a name="AboutthisGuide"></a> |
| <h1>About this Guide</h1> |
| |
| <div class="subsection"> |
| <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> |
| </div> |
| <a name="References"></a> |
| <h1>References</h1> |
| |
| <div class="subsection"> |
| <a name="Variables"></a> |
| <h2>Variables</h2> |
| <div class="subsection"> |
| <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> |
| Shorthand notation: |
| <variable>$mud-Slinger_9</variable> |
| </li> |
| <li> |
| Silent Shorthand notation: |
| <variable>$!mud-Slinger_9</variable> |
| </li> |
| <li> |
| Formal notation: |
| <variable>${mud-Slinger_9}</variable> |
| </li> |
| <li> |
| Silent Formal notation: |
| <variable>$!{mud-Slinger_9}</variable> |
| </li> |
| </ul> |
| </div> |
| <a name="Properties"></a> |
| <h2>Properties</h2> |
| <div class="subsection"> |
| <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> |
| </div> |
| <a name="Methods"></a> |
| <h2>Methods</h2> |
| <div class="subsection"> |
| <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>optional 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> |
| </div> |
| <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> |
| </div> |
| <a name="Directives"></a> |
| <h1>Directives</h1> |
| |
| <div class="subsection"> |
| <a name="set-Establishesthevalueofareference"></a> |
| <h2>#set - Establishes the value of a reference</h2> |
| <div class="subsection"> |
| <p>
|
| Format:
|
| </p> |
| <p>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>set</strong> [ <strong>}</strong> ] <strong> ( $</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 list: #set( $monkey.Say = ["Not", $my, "fault"] ) |
| </li> |
| <li> |
| Object map: #set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"}) |
| </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> |
| </div> |
| <a name="#if/#elseif/#else - Output conditional on truth of statements"></a> |
| <h2>#if/#elseif/#else - Output conditional on truth of statements</h2> |
| <div class="subsection"> |
| <p>
|
| Format:
|
| </p> |
| <p>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>if</strong> [ <strong>}</strong> ] <strong>(</strong> [condition] <strong>)</strong> [output] [
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>elseif</strong> [ <strong>}</strong> ] <strong>( </strong>[condition] <strong>)</strong> [output] ]* [
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>else</strong> [ <strong>}</strong> ] [output] ]
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>end</strong> [ <strong>}</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 (showing different operators):
|
| </p> |
| <table> |
| <tr> |
| <th colspan="" rowspan=""> |
| Operator Name |
| </th> |
| <th colspan="" rowspan=""> |
| Symbol |
| </th> |
| <th colspan="" rowspan=""> |
| Alternative Symbol |
| </th> |
| <th colspan="" rowspan=""> |
| Example |
| </th> |
| </tr> |
| <tr> |
| <td colspan="" rowspan=""> |
| Equals Number |
| </td> |
| <td colspan="" rowspan=""> |
| == |
| </td> |
| <td colspan="" rowspan=""> |
| eq |
| </td> |
| <td colspan="" rowspan=""> |
| #if( $foo == 42 ) |
| </td> |
| </tr> |
| <tr> |
| <td colspan="" rowspan=""> |
| Equals String |
| </td> |
| <td colspan="" rowspan=""> |
| == |
| </td> |
| <td colspan="" rowspan=""> |
| eq |
| </td> |
| <td colspan="" rowspan=""> |
| #if( $foo == "bar" ) |
| </td> |
| </tr> |
| <tr> |
| <td colspan="" rowspan=""> |
| Object Equivalence |
| </td> |
| <td colspan="" rowspan=""> |
| == |
| </td> |
| <td colspan="" rowspan=""> |
| eq |
| </td> |
| <td colspan="" rowspan=""> |
| #if( $foo == $bar ) |
| </td> |
| </tr> |
| <tr> |
| <td colspan="" rowspan=""> |
| Not Equals |
| </td> |
| <td colspan="" rowspan=""> |
| != |
| </td> |
| <td colspan="" rowspan=""> |
| ne |
| </td> |
| <td colspan="" rowspan=""> |
| #if( $foo != $bar ) |
| </td> |
| </tr> |
| <tr> |
| <td colspan="" rowspan=""> |
| Greater Than |
| </td> |
| <td colspan="" rowspan=""> |
| > |
| </td> |
| <td colspan="" rowspan=""> |
| gt |
| </td> |
| <td colspan="" rowspan=""> |
| #if( $foo > 42 ) |
| </td> |
| </tr> |
| <tr> |
| <td colspan="" rowspan=""> |
| Less Than |
| </td> |
| <td colspan="" rowspan=""> |
| < |
| </td> |
| <td colspan="" rowspan=""> |
| lt |
| </td> |
| <td colspan="" rowspan=""> |
| #if( $foo < 42 ) |
| </td> |
| </tr> |
| <tr> |
| <td colspan="" rowspan=""> |
| Greater Than or Equal To |
| </td> |
| <td colspan="" rowspan=""> |
| >= |
| </td> |
| <td colspan="" rowspan=""> |
| ge |
| </td> |
| <td colspan="" rowspan=""> |
| #if( $foo >= 42 ) |
| </td> |
| </tr> |
| <tr> |
| <td colspan="" rowspan=""> |
| Less Than or Equal To |
| </td> |
| <td colspan="" rowspan=""> |
| <= |
| </td> |
| <td colspan="" rowspan=""> |
| le |
| </td> |
| <td colspan="" rowspan=""> |
| #if( $foo <= 42 ) |
| </td> |
| </tr> |
| <tr> |
| <td colspan="" rowspan=""> |
| Boolean NOT |
| </td> |
| <td colspan="" rowspan=""> |
| ! |
| </td> |
| <td colspan="" rowspan=""> |
| not |
| </td> |
| <td colspan="" rowspan=""> |
| #if( !$foo ) |
| </td> |
| </tr> |
| </table> |
| <p>Notes:</p> |
| <ol> |
| <li> |
| |
| The == operator can be used to compare numbers, strings, objects of the same class, or objects |
| of different classes. In the last case (when objects are of different classes), the toString() |
| method is called on each object and the resulting Strings are compared. |
| |
| </li> |
| <li> |
| |
| You can also use brackets to delimit directives. This is especially |
| useful when text immediately follows an |
| <code>#else</code> |
| directive. |
| |
| </li> |
| </ol> |
| <div class="source">
|
| #if( $foo == $bar)it's true!#{else}it's not!#end</li>
|
| </pre></div> |
| </div> |
| <a name="foreach-Loopsthroughalistofobjects"></a> |
| <h2>#foreach - Loops through a list of objects</h2> |
| <div class="subsection"> |
| <p>
|
| Format:
|
| </p> |
| <p>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>foreach</strong> [ <strong>}</strong> ] <strong>(</strong> <em>$ref</em> <strong>in</strong> <em>arg</em>
|
| <strong>)</strong> <em>statement</em>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>end</strong> [ <strong>}</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> |
| <div class="source">
|
| <table>
|
| #foreach( $customer in $customerList )
|
| <tr><td>$velocityCount</td><td>$customer.Name</td></tr>
|
| #end
|
| </table>
|
| </pre></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 <code>velocity.properties</code> file. Here's what the loop
|
| counter properties section of the <code>velocity.properties</code>
|
| file appears:
|
| </p> |
| <div class="source">
|
| # Default name of the loop counter
|
| # variable reference.
|
| directive.foreach.counter.name = velocityCount
|
|
|
| # Default starting value of the loop
|
| # counter variable reference.
|
| directive.foreach.counter.initial.value = 1
|
| </pre></div> |
| <p>
|
| Additionally, the maximum allowed number of loop iterations can be
|
| controlled engine-wide (an ability introduced in Velocity 1.5).
|
| By default, there is no limit:
|
| </p> |
| <div class="source">
|
| # The maximum allowed number of loops.
|
| directive.foreach.maxloops = -1
|
| </pre></div> |
| </div> |
| <a name="include-Renderslocalfile(s)thatarenotparsedbyVelocity"></a> |
| <h2>#include - Renders local file(s) that are not parsed by Velocity</h2> |
| <div class="subsection"> |
| <p>
|
| Format:
|
| </p> |
| <p>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>include</strong> [ <strong>}</strong> ] <strong>( </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> |
| </div> |
| <a name="parse-RendersalocaltemplatethatisparsedbyVelocity"></a> |
| <h2>#parse - Renders a local template that is parsed by Velocity</h2> |
| <div class="subsection"> |
| <p>
|
| Format:
|
| </p> |
| <p>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>parse</strong> [ <strong>}</strong> ] <strong>(</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> |
| </div> |
| <a name="stop-Stopsthetemplateengine"></a> |
| <h2>#stop - Stops the template engine</h2> |
| <div class="subsection"> |
| <p>
|
| Format:
|
| </p> |
| <p>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>stop</strong> [ <strong>}</strong> ]
|
| </p> |
| <p>
|
| Usage:
|
| </p> |
| <p>
|
| This will stop execution of the current template. This is good for
|
| debugging a template.
|
| </p> |
| </div> |
| <a name="evaluate"></a> |
| <h2>#evaluate - Dynamically evaluates a string or reference</h2> |
| <div class="subsection"> |
| <p>
|
| Format:
|
| </p> |
| <p>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>evaluate</strong> [ <strong>}</strong> ] <strong>( </strong>arg<strong> )</strong>
|
| </p> |
| <ul> |
| <li> |
| <em>arg</em> |
| - String literal or reference to be dynamically evaluated. |
| </li> |
| </ul> |
| <p>
|
| Examples:
|
| </p> |
| <ul> |
| <li> |
| String: #evaluate( 'string with VTL #if(true)will be displayed#end' ) |
| </li> |
| <li> |
| Variable: #include( $foo ) |
| </li> |
| </ul> |
| </div> |
| <a name="define"></a> |
| <h2>#define - Assigns a block of VTL to a reference</h2> |
| <div class="subsection"> |
| <p>
|
| Format:
|
| </p> |
| <p>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>define</strong> [ <strong>}</strong> ] <strong>( </strong><em>$ref</em><strong> )</strong>
|
| <em>statement</em>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>end</strong> [ <strong>}</strong> ]
|
|
|
| </p> |
| <ul> |
| <li> |
| <em>$ref</em> |
| - Reference that is assigned the VTL block as a value. |
| </li> |
| <li> |
| <em>statement</em> |
| - Statement that is assigned to the reference. |
| </li> |
| </ul> |
| <p>
|
| Example:
|
| </p> |
| <ul> |
| <li> |
| #define( $hello ) Hello $who #end #set( $who = "World!") $hello ## displays Hello World! |
| </li> |
| </ul> |
| </div> |
| <a name="macro-AllowsuserstodefineaVelocimacro(VM),arepeatedsegmentofaVTLtemplate,asrequired"></a> |
| <h2>#macro - Allows users to define a Velocimacro (VM), a repeated segment of a VTL template, as required</h2> |
| <div class="subsection"> |
| <p>
|
| Format:
|
| </p> |
| <p>
|
| <strong>#</strong> [ <strong>{</strong> ] <strong>macro</strong> [ <strong>}</strong> ] <strong>(</strong> vmname $arg1 [ $arg2 $arg3 ... $argn ]
|
| <strong>)</strong> [ VM VTL code... ] <strong>#</strong> [ <strong>{</strong> ] <strong>#end</strong> [ <strong>}</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 arguments, 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> |
| <div class="source">
|
| #vmname( $arg1 $arg2 )
|
| </pre></div> |
| <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> |
| </div> |
| </div> |
| <a name="Comments"></a> |
| <h1>Comments</h1> |
| |
| <div class="subsection"> |
| <p>
|
| Comments are not rendered at runtime.
|
| </p> |
| <a name="SingleLine"></a> |
| <h2>Single Line</h2> |
| <div class="subsection"> |
| <p>
|
| Example:
|
| </p> |
| <p>
|
| <strong>## This is a comment.</strong>
|
| </p> |
| </div> |
| <a name="MultiLine"></a> |
| <h2>Multi Line</h2> |
| <div class="subsection"> |
| <p>
|
| Example:
|
| </p> |
| <p>
|
| <strong>
|
| #*<br />
|
| This is a multiline comment.<br />
|
| This is the second line<br />
|
| *#
|
| </strong>
|
| </p> |
| </div> |
| </div> |
| </div> |
| |
| <div id="footer"> |
| Copyright © 1999-2007, <a href="http://www.apache.org/">The Apache Software Foundation</a>. |
| </div> |
| |
| </div> |
| |
| </body> |
| </html> |
| <!-- end the processing --> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
