File: user-guide.xml

package info (click to toggle)
velocity 1.3.1-2
links: PTS
area: contrib
in suites: sarge
size: 4,164 kB
ctags: 2,922
sloc: java: 24,134; xml: 16,911; sh: 99; lisp: 53; makefile: 45
file content (2242 lines) | stat: -rw-r--r-- 66,666 bytes
<?xml version="1.0"?>

<document>

 <properties>
  <title>Velocity User Guide</title>
  <author email="jvanzyl@zenplex.com">Velocity Documentation Team</author>
  <author email="jcastura@kw.igs.net">John Castura</author>
 </properties>

<body>

<section name="Table of Contents">

<ol>
<li><a href="#About this Guide">About this Guide</a></li>
<li><a href="#What is Velocity?">What is Velocity?</a></li>
<li><a href="#What can Velocity do for me?">What can Velocity do for me?</a>
    <ol>
        <li><a href="#The Mud Store Example">The Mud Store example</a></li>
    </ol>
</li>
<li><a href="#Velocity Template Language (VTL): An
Introduction">Velocity Template Language (VTL): An Introduction</a></li>
<li><a href="#Hello Velocity World!">Hello Velocity World!</a></li>
<li><a href="#Comments">Comments</a></li>
<li><a href="#References">References</a>
    <ol>
        <li><a href="#Variables">Variables</a></li>
        <li><a href="#Properties">Properties</a></li>
        <li><a href="#Methods">Methods</a></li>
    </ol>
</li>
<li><a href="#Formal Reference Notation">Formal Reference Notation</a></li>
<li><a href="#Quiet Reference Notation">Quiet Reference Notation</a></li>
<li><a href="#Getting literal">Getting literal</a>
    <ol>
        <li><a href="#Currency">Currency</a></li>
        <li><a href="#Escaping Valid VTL References">Escaping Valid VTL References</a></li>
    </ol>
</li>
<li><a href="#Case Substitution">Case Substitution</a></li>
<li><a href="#Directives">Directives</a>
    <ol>
        <li><a href="#Set">Set</a></li>
        <li><a href="#String Literals">String Literals</a></li>
        <li><a href="#Conditionals">If-Else Statements</a>
            <ol>
                <li><a href="#Relational and Logical Operators">Relational and Logical
                Operators</a></li>
            </ol>
        </li>
        <li><a href="#Loops">Foreach Loops</a></li>
        <li><a href="#Include">Include</a></li>
        <li><a href="#Parse">Parse</a></li>
        <li><a href="#Stop">Stop</a></li>
        <li><a href="#Velocimacros">Velocimacros</a></li>
    </ol>
</li>
<li><a href="#Escaping VTL Directives">Escaping VTL Directives</a></li>
<li><a href="#VTL: Formatting Issues">VTL: Formatting Issues</a></li>
<li><a href="#Other Features and Miscellany">Other Features and Miscellany</a>
    <ol>
        <li><a href="#Math">Math</a></li>
        <li><a href="#Range Operator">Range Operator</a></li>
        <li><a href="#Advanced Issues: Escaping and !">Advanced Issues: Escaping and
        !</a></li>
        <li><a href="#Velocimacro Miscellany">Velocimacro Miscellany</a></li>
        <li><a href="#String Concatenation">String Concatenation</a></li>
    </ol>
</li>
<li><a href="#Feedback">Feedback</a></li>
</ol>

</section>

<section name="About this Guide">

 <p>
    The Velocity User Guide is intended to help page designers and
    content providers get acquainted with Velocity and the syntax of its
    simple yet powerful scripting language, the Velocity Template
    Language (VTL). Many of the examples in this guide deal with using
    Velocity to embed dynamic content in web sites, but all VTL examples
    are equally applicable to other pages and templates.
 </p>

 <p>
    Thanks for choosing Velocity!
 </p>

</section>

<section name="What is Velocity?">

 <p>
    Velocity is a Java-based template engine. It permits web page
    designers to reference methods defined in Java code. Web designers
    can work in parallel with Java programmers to develop web sites
    according to the Model-View-Controller (MVC) model, meaning that web
    page designers can focus solely on creating a well-designed site,
    and programmers can focus solely on writing top-notch code. Velocity
    separates Java code from the web pages, making the web site more
    maintainable over the long run and providing a viable alternative to
    <a href="http://java.sun.com/products/jsp/">Java Server Pages</a>
    (JSPs) or <a href="http://www.php.net/">PHP</a>.
 </p>

 <p>
    Velocity can be used to generate web pages, SQL, PostScript and
    other output from templates. It can be used either as a standalone
    utility for generating source code and reports, or as an integrated
    component of other systems. When complete, Velocity will provide
    template services for the <a
    href="http://java.apache.org/turbine/">Turbine</a> web application
    framework. Velocity+Turbine will provide a template service that
    will allow web applications to be developed according to a true MVC
    model.
 </p>

</section>

<section name="What can Velocity do for me?">
<subsection name="The Mud Store Example">
   <p>
    Suppose you are a page designer for an online store that specializes
    in selling mud. Let's call it "The Online Mud Store". Business is
    thriving. Customers place orders for various types and quantities of
    mud. They login to your site using their username and password,
    which allows them to view their orders and buy more mud. Right now,
    Terracotta Mud is on sale, which is very popular. A minority of your
    customers regularly buys Bright Red Mud, which is also on sale,
    though not as popular and usually relegated to the margin of your
    web page. Information about each customer is tracked in your
    database, so one day the question arises, Why not use Velocity to
    target special deals on mud to the customers who are most interested
    in those types of mud?
   </p>

   <p>
    Velocity makes it easy to customize web pages to your online
    visitors. As a web site designer at The Mud Room, you want to make
    the web page that the customer will see after logging into your
    site.
   </p>

   <p>
    You meet with software engineers at your company, and everyone has
    agreed that <em>$customer</em> will hold information pertaining to
    the customer currently logged in, that <em>$mudsOnSpecial</em> will
    be all the types mud on sale at present. The <em>$flogger</em>
    object contains methods that help with promotion. For the task at
    hand, let's concern ourselves only with these three references.
    Remember, you don't need to worry about how the software engineers
    extract the necessary information from the database, you just need
    to know that it works. This lets you get on with your job, and lets
    the software engineers get on with theirs.
   </p>

   <p>
    You could embed the following VTL statement in the web page:
   </p>

<source><![CDATA[
<HTML>
<BODY>
Hello $customer.Name!
<table>
#foreach( $mud in $mudsOnSpecial )
   #if ( $customer.hasPurchased($mud) )
      <tr>
        <td>
          $flogger.getPromo( $mud )
        </td>
      </tr>
   #end
#end
</table>
]]></source>

   <p>
    The exact details of the <em>foreach</em> statement will be
    described in greater depth shortly; what's important is the impact
    this short script can have on your web site. When a customer with a
    penchant for Bright Red Mud logs in, and Bright Red Mud is on sale,
    that is what this customer will see, prominently displayed. If
    another customer with a long history of Terracotta Mud purchases
    logs in, the notice of a Terracotta Mud sale will be front and
    center. The flexibility of Velocity is enormous and limited only by
    your creativity.
   </p>

   <p>
    Documented in the VTL Reference are the many other Velocity
    elements, which collectively give you the power and flexibility you
    need to make your web site a web <em>presence</em>. As you get more
    familiar with these elements, you will begin to unleash the power of
    Velocity.
   </p>

 </subsection>

</section>

<section name="Velocity Template Language (VTL): An Introduction">

 <p>
    The Velocity Template Language (VTL) is meant to provide the
    easiest, simplest, and cleanest way to incorporate dynamic content
    in a web page. Even a web page developer with little or no
    programming experience should soon be capable of using VTL to
    incorporate dynamic content in a web site.
 </p>

 <p>
    VTL uses <em>references</em> to embed dynamic content in a web site,
    and a variable is one type of reference. Variables are one type of
    reference that can refer to something defined in the Java code, or
    it can get its value from a VTL <em>statement</em> in the web page
    itself. Here is an example of a VTL statement that could be embedded
    in an HTML document:
 </p>

<source><![CDATA[
#set( $a = "Velocity" )
]]></source>

 <p>
    This VTL statement, like all VTL statements, begins with the
    <em>#</em> character and contains a directive: <em>set</em>. When an
    online visitor requests your web page, the Velocity Templating
    Engine will search through your web page to find all <em>#</em>
    characters, then determine which mark the beginning of VTL
    statements, and which of the <em>#</em> characters that have nothing
    to do with VTL.
 </p>

 <p>
    The <em>#</em> character is followed by a directive, <em>set</em>.
    The <em>set</em> directive uses an expression (enclosed in brackets)
    -- an equation that assigns a <em>value</em> to a <em>variable</em>.
    The variable is listed on the left hand side and its value on the
    right hand side; the two are separated by an <em>=</em> character.
 </p>

 <p>
    In the example above, the variable is <em>$a</em> and the value is
    <em>Velocity</em>. This variable, like all references, begins with
    the <em>$</em> character. Values are always enclosed in quotes; with
    Velocity there is no confusion about data types, as only strings
    (text-based information) may be passed to variables.
 </p>

 <p>
    The following rule of thumb may be useful to better understand how
    Velocity works: <strong>References begin with <em>$</em> and are
    used to get something. Directives begin with <em>#</em> and are used
    to do something.</strong>
 </p>

 <p>
     In the example above, <em>#set</em> is used to assign a value to a
     variable. The variable, <em>$a</em>, can then be used in the
     template to output "Velocity".
 </p>

</section>

<section name="Hello Velocity World!">

 <p>
    Once a value has been assigned to a variable, you can reference the
    variable anywhere in your HTML document. In the following example, a
    value is assigned to <em>$foo</em> and later referenced.
 </p>

<source><![CDATA[
<html>
<body>
#set( $foo = "Velocity" )
Hello $foo World!
</body>
<html>
]]></source>

 <p>
    The result is a web page that prints "Hello Velocity World!".
 </p>

 <p>
    To make statements containing VTL directives more readable, we
    encourage you to start each VTL statement on a new line, although
    you are not required to do so. The <em>set</em> directive will be
    revisited in greater detail later on.
 </p>

</section>

<section name="Comments">

 <p>
    Comments allows descriptive text to be included that is not placed
    into the output of the template engine. Comments are a useful way of
    reminding yourself and explaining to others what your VTL statements
    are doing, or any other purpose you find useful. Below is an example
    of a comment in VTL.
 </p>

<source><![CDATA[
## This is a single line comment.
]]></source>

 <p>
    A single line comment begins with <em>##</em> and finishes at the
    end of the line. If you're going to write a few lines of commentary,
    there's no need to have numerous single line comments. Multi-line
    comments, which begin with <em>#*</em> and end with <em>*#</em>, are
    available to handle this scenario.
 </p>

<source><![CDATA[
This is text that is outside the multi-line comment.
Online visitors can see it.

#*
 Thus begins a multi-line comment. Online visitors won't
 see this text because the Velocity Templating Engine will
 ignore it.
*#

Here is text outside the multi-line comment; it is visible.
]]></source>

 <p>
    Here are a few examples to clarify how single line and multi-line
    comments work:
 </p>

<source><![CDATA[
This text is visible. ## This text is not.
This text is visible.
This text is visible. #* This text, as part of a multi-line comment,
is not visible. This text is not visible; it is also part of the
multi-line comment. This text still not visible. *# This text is outside
the comment, so it is visible.
## This text is not visible.
]]></source>

 <p>
    There is a third type of comment, the VTL comment block, which may
    be used to store such information as the document author and
    versioning information:
 </p>

<source><![CDATA[
#**
This is a VTL comment block and
may be used to store such information
as the document author and versioning
information:
@author
@version 5
*#
]]></source>

</section>

<section name="References">

 <p>
    There are three types of references in the VTL: variables,
    properties and methods. As a designer using the VTL, you and your
    engineers must come to an agreement on the specific names of
    references so you can use them correctly in your templates.
 </p>

 <p>
    Everything coming to and from a reference is treated as a String
    object. If there is an object that represents <em>$foo</em> (such as
    an Integer object), then Velocity will call its
    <code>.toString()</code> method to resolve the object into a String.
 </p>

 <p>
 <a name="Variables"><strong>Variables</strong></a>
 <br/>
    The shorthand notation of a variable consists of a leading "$"
    character followed by a VTL <em>Identifier</em>. A VTL Identifier
    must start with an alphabetic character (a .. z or A .. Z). The rest
    of the characters are limited to the following types of characters:
 </p>

 <p>
   <ul>
     <li>alphabetic (a .. z, A .. Z)</li>
     <li>numeric (0 .. 9)</li>
     <li>hyphen ("-")</li>
     <li>underscore ("_")</li>
   </ul>
 </p>

 <p>
    Here are some examples of valid variable references in the VTL:
 </p>

<source><![CDATA[
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1
]]></source>

 <p>
    When VTL references a variable, such as <em>$foo</em>, the variable
    can get its value from either a <em>set</em> directive in the
    template, or from the Java code. For example, if the Java variable
    <em>$foo</em> has the value <em>bar</em> at the time the template is
    requested, <em>bar</em> replaces all instances of <em>$foo</em> on
    the web page. Alternatively, if I include the statement
 </p>

<source><![CDATA[
#set( $foo = "bar" )
]]></source>

 <p>
    The output will be the same for all instances of <em>$foo</em> that
    follow this directive.
 </p>

 <p>
 <a name="Properties"><strong>Properties</strong></a>
 <br/>
    The second flavor of VTL references are properties, and properties
    have a distinctive format. The shorthand notation consists of a
    leading <em>$</em> character followed a VTL Identifier, followed by
    a dot character (".") and another VTL Identifier. These are examples
    of valid property references in the VTL:
 </p>

<source><![CDATA[
$customer.Address
$purchase.Total
]]></source>

 <p>
    Take the first example, <em>$customer.Address</em>. It can have two
    meanings. It can mean, Look in the hashtable identified as
    <em>customer</em> and return the value associated with the key
    <em>Address</em>. But <em>$customer.Address</em> can also be
    referring to a method (references that refer to methods will be
    discussed in the next section); <em>$customer.Address</em> could be
    an abbreviated way of writing <em>$customer.getAddress()</em>. When
    your page is requested, Velocity will determine which of these two
    possibilities makes sense, and then return the appropriate value.
 </p>

 <p>
 <a name="Methods"><strong>Methods</strong></a>
 <br/>
    A method is defined in the Java code and is capable of doing
    something useful, like running a calculation or arriving at a
    decision. Methods are references that consist of a leading "$"
    character followed a VTL Identifier, followed by a VTL <em>Method
    Body</em>. A VTL Method Body consists of a VTL Identifier followed
    by an left parenthesis character ("("), followed by an optional
    parameter list, followed by right parenthesis character (")"). These
    are examples of valid method references in the VTL:
 </p>

<source><![CDATA[
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( "My Home Page" )
$person.setAttributes( ["Strange", "Weird", "Excited"] )
]]></source>

 <p>
    The first two examples -- <em>$customer.getAddress()</em> and
    <em>$purchase.getTotal()</em> -- may look similar to those used in
    the Properties section above, <em>$customer.Address</em> and
    <em>$purchase.Total</em>. If you guessed that these examples must be
    related some in some fashion, you are correct!
 </p>

 <p>
    VTL Properties can be used as a shorthand notation for VTL Methods.
    The Property <em>$customer.Address</em> has the exact same effect as
    using the Method <em>$customer.getAddress()</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>

 <p>
    The shorthand notation can be used for the following Methods
 </p>

<source><![CDATA[
$sun.getPlanets()
$annelid.getDirt()
$album.getPhoto()
]]></source>

 <p>
    We might expect these methods to return the names of planets
    belonging to the sun, feed our earthworm, or get a photograph from
    an album. Only the long notation works for the following Methods.
 </p>

<source><![CDATA[
$sun.getPlanet( ["Earth", "Mars", "Neptune"] )
## Can't pass a parameter list with $sun.Planets

$sisyphus.pushRock()
## Velocity assumes I mean $sisyphus.getRock()

$book.setTitle( "Homage to Catalonia" )
## Can't pass a parameter list
]]></source>

 <p>
    <a name="Formal Reference Notation"><strong>Formal Reference Notation</strong></a>
    <br/>
    Shorthand notation for references was used for the examples listed
    above, but there is also a formal notation for references, which is
    demonstrated below:
 </p>

<source><![CDATA[
${mudSlinger}
${customer.Address}
${purchase.getTotal()}
]]></source>

 <p>
    In almost all cases you will use the shorthand notation for
    references, but in some cases the formal notation is required for
    correct processing.
 </p>

 <p>
    Suppose you were constructing a sentence on the fly where
    <em>$vice</em> was to be used as the base word in the noun of a
    sentence. The goal is to allow someone to choose the base word and
    produce one of the two following results: "Jack is a pyromaniac." or
    "Jack is a kleptomaniac.". Using the shorthand notation would be
    inadequate for this task. Consider the following example:
 </p>

<source><![CDATA[
Jack is a $vicemaniac.
]]></source>

 <p>
    There is ambiguity here, and Velocity assumes that
    <em>$vicemaniac</em>, not <em>$vice</em>, is the Identifier that you
    mean to use. Finding no value for <em>$vicemaniac</em>, it will
    return <em>$vicemaniac</em>. Using formal notation can resolve this
    problem.
 </p>

<source><![CDATA[
Jack is a ${vice}maniac.
]]></source>

 <p>
    Now Velocity knows that <em>$vice</em>, not <em>$vicemaniac</em>, is
    the reference. Formal notation is often useful when references are
    directly adjacent to text in a template.
 </p>


 <p>
    <a name="Quiet Reference Notation"><strong>Quiet Reference Notation</strong></a>
    <br/>
    When Velocity encounters an undefined reference, its normal behavior
    is to output the image of the reference. For example, suppose the
    following reference appears as part of a VTL template.
 </p>

<source><![CDATA[
<input type="text" name="email" value="$email"/>
]]></source>

 <p>
    When the form initially loads, the variable reference
    <em>$email</em> has no value, but you prefer a blank text field to
    one with a value of "$email". Using the quiet reference notation
    circumvents Velocity's normal behavior; instead of using
    <em>$email</em> in the VTL you would use <em>$!email</em>. So the
    above example would look like the following:
 </p>

<source><![CDATA[
<input type="text" name="email" value="$!email"/>
]]></source>

 <p>
    Now when the form is initially loaded and <em>$email</em> still has
    no value, an empty string will be output instead of "$email".
 </p>

 <p>
    Formal and quiet reference notation can be used together, as
    demonstrated below.
 </p>

<source><![CDATA[
<input type="text" name="email" value="$!{email}"/>
]]></source>

</section>

<section name="Getting literal">

  <p>
    VTL uses special characters, such as <em>$</em> and <em>#</em>, to
    do its work, so some added care should be taken where using these
    characters in your templates. This section deals with escaping the
    <em>$</em> character.
  </p>

  <p>
    <a name="Currency"><strong>Currency</strong></a>
    <br/>
    There is no problem writing "I bought a 4 lb. sack of potatoes at
    the farmer's market for only $2.50!" As mentioned, a VTL identifier
    always begins with an upper- or lowercase letter, so $2.50 would not
    be mistaken for a reference.
  </p>

  <p>
    <a name="Escaping Valid VTL References"><strong>Escaping Valid VTL References</strong></a>
    <br/>
    Cases may arise where there is the potential for Velocity to get
    confused. <em>Escaping</em> special characters is the best way to
    handle VTL's special characters in your templates, and this can be
    done using the backslash ( <em>\</em> ) character.
  </p>

<source><![CDATA[
#set( $email = "foo" )
$email
]]></source>

  <p>
    If Velocity encounters  a reference in your VTL template to
    <em>$email</em>, it will search the Context for a corresponding
    value. Here the output will be <em>foo</em>, because <em>$email</em> is
    defined. If <em>$email</em> is not defined, the output will be
    <em>$email</em>.
  </p>

  <p>
    Suppose that <em>$email</em> is defined (for example, if it has the
    value <em>foo</em>), and that you want to output <em>$email</em>. There are a few
    ways of doing this, but the simplest is to use the escape character.
  </p>

<source><![CDATA[
## The following line defines $email in this template:
#set( $email = "foo" )
$email
\$email
\\$email
\\\$email
]]></source>

  <p>
     renders as
  </p>

<source><![CDATA[
foo
$email
\foo
\$email
]]></source>

  <p>
     Note that the <em>\</em> character bind to the <em>$</em>
     from the left. The bind-from-left rule causes <em>\\\$email</em> to
     render as <em>\\$email</em>. Compare these examples to those in
     which <em>$email</em> is not defined.
  </p>

<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>

  <p>
     renders as
  </p>

<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>

  <p>
     Notice Velocity handles references that are defined differently
     from those that have not been defined. Here is a set directive that
     gives <em>$foo</em> the value <em>gibbous</em>.
  </p>

<source><![CDATA[
#set( $foo = "gibbous" )
$moon = $foo
]]></source>

  <p>
    The output will be: <em>$moon = gibbous</em> -- where <em>$moon</em>
    is output as a literal because it is undefined and <em>gibbous</em>
    is output in place of <em>$foo</em>.
  </p>


  <p>
     It is also possible to escape VTL directives; this is described in
     more detail in the Directives section.
  </p>

</section>

<section name="Case Substitution">

    <p>
    Now that you are familiar with references, you can begin to apply
    them effectively in your templates. Velocity references take
    advantage of some Java principles that template designers will find
    easy to use. For example:
    </p>

<source><![CDATA[
$foo

$foo.getBar()
## is the same as
$foo.Bar

$data.getUser("jon")
## is the same as
$data.User("jon")

$data.getRequest().getServerName()
## is the same as
$data.Request.ServerName
## is the same as
${data.Request.ServerName}
]]></source>

    <p>
    These examples illustrate alternative uses for the same references.
    Velocity takes advantage of Java's introspection and bean features
    to resolve the reference names to both objects in the Context as
    well as the objects methods. It is possible to embed and evaluate
    references almost anywhere in your template.
    </p>

    <p>
    Velocity, which is modelled on the Bean specifications defined by
    Sun Microsystems, is case sensitive; however, its developers have
    strove to catch and correct user errors wherever possible.
    When the method <em>getFoo()</em> is referred to in a template
    by <code>$bar.foo</code>, Velocity will first try <code>$getfoo</code>.
    If this fails, it will then try <code>$getFoo</code>.
    Similarly, when a template refers to <code>$bar.Foo</code>, Velocity
    will try <em>$getFoo()</em> first and then try <em>getfoo()</em>.
    </p>

    <p>
    Note: <em>References to instance variables in a template are not
    resolved.</em> Only references to the attribute equivalents of
    JavaBean getter/setter methods are resolved
    (i.e. <code>$foo.Name</code> does resolve to the class Foo's
    <code>getName()</code> instance method, but not to a public
    <code>Name</code> instance variable of Foo).
    </p>

</section>


<section name="Directives">

 <p>
    References allow template designers to generate dynamic content for
    web sites, while <em>directives</em> -- easy to use script elements
    that can be used to creatively manipulate the output of Java code --
    permit web designers to truly take charge of the appearance and
    content of the web site.
 </p>

 <a name="Set"><strong>#set</strong></a>
 <p>
    The <em>#set</em> directive is used for setting the value of a
    reference. A value can be assigned to either a variable reference or
    a property reference, and this occurs in brackets, as demonstrated:
 </p>

<source><![CDATA[
#set( $primate = "monkey" )
#set( $customer.Behavior = $primate )
]]></source>

 <p>
    The left hand side (LHS) of the assignment must be a variable
    reference or a property reference. The right hand side (RHS) can be
    one of the following types:
 </p>

 <p>
    <ul>
        <li>Variable reference</li>
        <li>String literal</li>
        <li>Property reference</li>
        <li>Method reference</li>
        <li>Number literal</li>
        <li>ArrayList</li>
    </ul>
 </p>

 <p>
    These examples demonstrate each of the aforementioned types:
 </p>

<source><![CDATA[
#set( $monkey = $bill ) ## variable reference
#set( $monkey.Friend = "monica" ) ## string literal
#set( $monkey.Blame = $whitehouse.Leak ) ## property reference
#set( $monkey.Plan = $spindoctor.weave($web) ) ## method reference
#set( $monkey.Number = 123 ) ##number literal
#set( $monkey.Say = ["Not", $my, "fault"] ) ## ArrayList
]]></source>

 <p>
   NOTE: In the last example the elements defined with the
   [..] operator are accessible using the methods defined
   in the ArrayList class. So, for example, you could access
   the first element above using $monkey.Say.get(0).
 </p>


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

<source><![CDATA[
#set( $value = $foo + 1 )
#set( $value = $bar - 1 )
#set( $value = $foo * $bar )
#set( $value = $foo / $bar )
]]></source>

 <p>
    If the RHS is a property or method reference that evaluates to
    <em>null</em>, it will <b>not</b> be assigned to the LHS.  It is
    not possible to remove an existing reference from the context via
    this mechanism.  This can be confusing for
    newcomers to Velocity.  For example:
 </p>

<source><![CDATA[
#set( $result = $query.criteria("name") )
The result of the first query is $result

#set( $result = $query.criteria("address") )
The result of the second query is $result
]]></source>

  <p>
     If <em>$query.criteria("name")</em> returns the string
     "bill", and <em>$query.criteria("address")</em> returns
     <em>null</em>, the above VTL will render as the following:
 </p>

<source><![CDATA[
The result of the first query is bill

The result of the second query is bill
]]></source>

 <p>
     This tends to confuse newcomers who construct <em>#foreach</em>
     loops that attempt to <em>#set</em> a reference via a property or
     method reference, then immediately test that reference with an
     <em>#if</em> directive.  For example:
 </p>

<source><![CDATA[

#set( $criteria = ["name", "address"] )

#foreach( $criterion in $criteria )

    #set( $result = $query.criteria($criterion) )

    #if( $result )
        Query was successful
    #end

#end
]]></source>

 <p>
     In the above example, it would not be wise to rely on the
     evaluation of <em>$result</em> to determine if a query was
     successful.  After <em>$result</em> has been <em>#set</em> (added to
     the context), it cannot be set back to <em>null</em> (removed from
     the context).  The details of the <em>#if</em> and <em>#foreach</em>
     directives are covered later in this document.
 </p>

 <p>
   One solution to this would be to pre-set <em>$result</em>
   to <em>false</em>.  Then if the <em>$query.criteria()</em>
   call fails, you can check.
 </p>


<source><![CDATA[

#set( $criteria = ["name", "address"] )

#foreach( $criterion in $criteria )

    #set( $result = false )
    #set( $result = $query.criteria($criterion) )

    #if( $result )
        Query was successful
    #end

#end
]]></source>

 <p>
    Unlike some of the other Velocity directives, the <em>#set</em>
    directive does not have an <em>#end</em> statement.
 </p>

<a name="String Literals"><strong>String Literals</strong></a>

 <p>
    When using the <em>#set</em> directive, string literals that are
    enclosed in double quote characters will be parsed and rendered, as
    shown:
 </p>

<source><![CDATA[
#set( $directoryRoot = "www" )
#set( $templateName = "index.vm" )
#set( $template = "$directoryRoot/$templateName" )
$template
]]></source>

 <p>
  The output will be
 </p>

<source><![CDATA[
www/index.vm
]]></source>

 <p>
    However, when the string literal is enclosed in single quote
    characters, it will not be parsed:
 </p>

<source><![CDATA[
#set( $foo = "bar" )
$foo
#set( $blargh = '$foo' )
$blargh
]]></source>

  This renders as:

<source><![CDATA[
  bar
  $foo
]]></source>

 <p>
    By default, this feature of using single quotes to render unparsed
    text is available in Velocity. This default can be changed by
    editing <code>velocity.properties</code> such that
    <code>stringliterals.interpolate=false</code>.
 </p>
</section>


<section name="Conditionals">

    <strong>If / ElseIf / Else</strong>
    <p>
       The <em>#if</em> directive in Velocity allows for text to be
       included when the web page is generated, on the conditional that
       the if statement is true. For example:
    </p>

<source><![CDATA[
#if( $foo )
   <strong>Velocity!</strong>
#end
]]></source>

    <p>
      The variable <em>$foo</em> is evaluated to determine whether it is
      true, which will happen under one of two circumstances: (i)
      <em>$foo</em> is a boolean (true/false) which has a true value, or
      (ii) the value is not null.  Remember that the Velocity context only
      contains Objects, so when we say 'boolean', it will be represented
      as a Boolean (the class).  This is true even for methods that return
      <code>boolean</code> - the introspection infrastructure will return
      a <code>Boolean</code> of the same logical value.
    </p>

    <p>
       The content between the <em>#if</em>
      and the <em>#end</em> statements become the output if the
      evaluation is true. In this case, if <em>$foo</em> is true, the
      output will be: "Velocity!". Conversely, if <em>$foo</em> has a
      null value, or if it is a boolean false, the statement evaluates
      as false, and there is no output.
    </p>

    <p>
      An <em>#elseif</em> or <em>#else</em> element can be used with an
      <em>#if</em> element. Note that the Velocity Templating Engine
      will stop at the first expression that is found to be true. In the
      following example, suppose that <em>$foo</em> has a value of 15
      and <em>$bar</em> has a value of 6.
    </p>

<source><![CDATA[
#if( $foo < 10 )
    <strong>Go North</strong>
#elseif( $foo == 10 )
    <strong>Go East</strong>
#elseif( $bar == 6 )
    <strong>Go South</strong>
#else
    <strong>Go West</strong>
#end
]]></source>

    <p>In this example, <em>$foo</em> is greater than 10, so the first
    two comparisons fail.  Next <em>$bar</em> is compared to 6, which is
    true, so the output is <strong>Go South</strong>.
    </p>

    <p>
    Please note that currently, Velocity's numeric comparisons are constrained
    to Integers - anything else will evaluate to <em>false</em>.  The only exception
    to this is equality '==', where Velocity requires that the objects on each
    side of the '==' is of the <em>same</em> class.
    </p>

    <p>
    <a name="Relational and Logical Operators"><strong>Relational and Logical Operators</strong></a>
    </p>

    <p>
    Velocity uses the equivalent operator to determine the relationships between variables.
    Here is a simple example to illustrate how the equivalent operator is used.
    </p>

<source><![CDATA[
#set ($foo = "deoxyribonucleic acid")
#set ($bar = "ribonucleic acid")

#if ($foo == $bar)
  In this case it's clear they aren't equivalent. So...
#else
  They are not equivalent and this will be the output.
#end
]]></source>

    <p>
      Velocity has logical AND, OR and NOT operators as well.
      For further information, please see the
      <a href="vtl-reference-guide.html">VTL Reference Guide</a>
      Below are examples demonstrating the use of the
      logical AND, OR and NOT operators.
    </p>

<source><![CDATA[

## logical AND

#if( $foo && $bar )
   <strong> This AND that</strong>
#end

]]></source>

    <p>
      The <em>#if()</em> directive will only evaluate to true
      if both <em>$foo</em>
      and <em>$bar</em> are true. If <em>$foo</em> is false, the
      expression will evaluate to false; <em>$bar</em> will not be
      evaluated. If <em>$foo</em> is true, the Velocity Templating
      Engine will then check the value of <em>$bar</em>; if
      <em>$bar</em> is true, then the entire expression is true and
      <strong>This AND that</strong> becomes the output. If
      <em>$bar</em> is false, then there will be no output as the entire
      expression is false.
    </p>

    <p>
      Logical OR operators work the same way, except only one of the
      references need evaluate to true in order for the entire
      expression to be considered true. Consider the following example.
    </p>

<source><![CDATA[

## logical OR

#if( $foo || $bar )
    <strong>This OR That</strong>
#end
]]></source>

    <p>
      If <em>$foo</em> is true, the Velocity Templating Engine has no
      need to look at <em>$bar</em>; whether <em>$bar</em> is true or
      false, the expression will be true, and <strong>This OR That</strong>
      will be output. If <em>$foo</em> is false,
      however, <em>$bar</em> must be checked. In this case, if
      <em>$bar</em> is also false, the expression evaluates to false and
      there is no output. On the other hand, if <em>$bar</em> is true,
      then the entire expression is true, and the output is
      <strong>This OR That</strong>
    </p>

    <p>
    With logical NOT operators, there is only one argument :
    </p>

<source><![CDATA[

##logical NOT

#if( !$foo )
  <strong>NOT that</strong>
#end

]]></source>

    <p>
    Here, the if <em>$foo</em> is true, then <em>!$foo</em> evaluates to
    false, and there is no output.  If <em>$foo</em> is false, then
    <em>!$foo</em> evaluates to true and <strong>NOT that</strong> will be
    output.  Be careful not to confuse this with the <em>quiet reference $!foo</em>
    which is something altogether different.
    </p>


 </section>

<section name="Loops">

   <strong>Foreach Loop</strong>

    <p>
      The <em>#foreach</em> element allows for looping. For example:
    </p>

<source><![CDATA[
<ul>
#foreach( $product in $allProducts )
    <li>$product</li>
#end
</ul>
]]></source>

    <p>
    This <em>#foreach</em> loop causes the <em>$allProducts</em> list
    (the object) to be looped over for all of the products (targets) in
    the list. Each time through the loop, the value from
    <em>$allProducts</em> is placed into the <em>$product</em> variable.
    </p>

    <p>
    The contents of the <em>$allProducts</em> variable is a Vector, a
    Hashtable or an Array. The value assigned to the <em>$product</em>
    variable is a Java Object and can be referenced from a variable as
    such. For example, if <em>$product</em> was really a Product class
    in Java, its name could be retrieved by referencing the
    <em>$product.Name</em> method (ie: <em>$Product.getName()</em>).
    </p>

    <p>
    Lets say that <em>$allProducts</em> is a Hashtable. If you wanted to
    retrieve the key values for the Hashtable as well as the objects
    within the Hashtable, you can use code like this:
    </p>

<source><![CDATA[
<ul>
#foreach( $key in $allProducts.keySet() )
    <li>Key: $key -> Value: $allProducts.get($key)</li>
#end
</ul>
]]></source>

    <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 reference.
directive.foreach.counter.name = velocityCount

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

 </section>

<section name="Include">

    <p>
    The <em>#include</em> script element allows the template designer to
    import a local file, which is then inserted into the location where
    the <em>#include</em> directive is defined. The contents of the file
    are not rendered through the template engine. For security reasons,
    the file to be included may only be under TEMPLATE_ROOT.
    </p>

<source><![CDATA[
#include( "one.txt" )
]]></source>

    <p>
    The file to which the <em>#include</em> directive refers is enclosed
    in quotes. If more than one file will be included, they should be
    separated by commas.
    </p>

<source><![CDATA[
#include( "one.gif","two.txt","three.htm" )
]]></source>

    <p>
    The file being included need not be referenced by name; in fact, it
    is often preferable to use a variable instead of a filename. This
    could be useful for targeting output according to criteria
    determined when the page request is submitted. Here is an example
    showing both a filename and a variable.
    </p>

<source><![CDATA[
#include( "greetings.txt", $seasonalstock )
]]></source>

 </section>

<section name="Parse">

    <p>
    The <em>#parse</em> script element allows the template designer to
    import a local file that contains VTL. Velocity will parse the VTL
    and render the template specified.
    </p>

<source><![CDATA[
#parse( "me.vm" )
]]></source>

    <p>
    Like the <em>#include</em> directive, <em>#parse</em> can take a
    variable rather than a template. Any templates to which
    <em>#parse</em> refers must be included under TEMPLATE_ROOT. Unlike
    the <em>#include</em> directive, <em>#parse</em> will only take a
    single argument.
    </p>

    <p>
    VTL templates can have <em>#parse</em> statements referring to
    templates that in turn have <em>#parse</em> statements. By default
    set to 10, the <em>parse_directive.maxdepth</em> line of the
    <code>velocity.properties</code> allows users to customize maximum
    number of <em>#parse</em> referrals that can occur from a single
    template. (Note: If the <em>parse_directive.maxdepth</em> property
    is absent from the <code>velocity.properties</code> file, Velocity
    will set this default to 10.) Recursion is permitted, for example,
    if the template <code>dofoo.vm</code> contains the following lines:
    </p>

<source><![CDATA[
Count down.
#set( $count = 8 )
#parse( "parsefoo.vm" )
All done with dofoo.vm!
]]></source>

    <p>
    It would reference the template <code>parsefoo.vm</code>, which
    might contain the following VTL:
    </p>

<source><![CDATA[
$count
#set( $count = $count - 1 )
#if( $count > 0 )
    #parse( "parsefoo.vm" )
#else
    All done with parsefoo.vm!
#end
]]></source>

    <p>
    After "Count down." is displayed, Velocity passes through
    <code>parsefoo.vm</code>, counting down from 8. When the count
    reaches 0, it will display the "All done with parsefoo.vm!" message.
    At this point, Velocity will return to <code>dofoo.vm</code> and
    output the "All done with dofoo.vm!" message.
    </p>

 </section>


<section name="Stop">

    <p>
    The <em>#stop</em> script element allows the template designer to
    stop the execution of the template engine and return. This is useful
    for debugging purposes.
    </p>

<source><![CDATA[
#stop
]]></source>
 </section>

<section name="Velocimacros">

    <p>
    The <em>#macro</em> script element allows template designers to
    define a repeated segment of a VTL template. Velocimacros are very
    useful in a wide range of scenarios both simple and complex. This
    Velocimacro, created for the sole purpose of saving keystrokes and
    minimizing typographic errors, provides an introduction to the
    concept of Velocimacros.
    </p>

<source><![CDATA[
#macro( d )
<tr><td></td></tr>
#end
]]></source>

    <p>
    The Velocimacro being defined in this example is <em>d</em>, and it
    can be called in a manner analogous to any other VTL directive:
    </p>

<source><![CDATA[
#d()
]]></source>

    <p>
    When this template is called, Velocity would replace <em>#d()</em>
    with a row containing a single, empty data cell.
    </p>

    <p>
    A Velocimacro could take any number of arguments -- even zero
    arguments, as demonstrated in the first example, is an option -- but
    when the Velocimacro is invoked, it must be called with the same
    number of arguments with which it was defined. Many Velocimacros are
    more involved than the one defined above. Here is a Velocimacro that
    takes two arguments, a color and an array.
    </p>

<source><![CDATA[
#macro( tablerows $color $somelist )
#foreach( $something in $somelist )
    <tr><td bgcolor=$color>$something</td></tr>
#end
#end
]]></source>

    <p>
    The Velocimacro being defined in this example, <em>tablerows</em>,
    takes two arguments. The first argument takes the place of
    <em>$color</em>, and the second argument takes the place of
    <em>$somelist</em>.
    </p>

    <p>
    Anything that can be put into a VTL template can go into the body of
    a Velocimacro. The <em>tablerows</em> Velocimacro is a
    <em>foreach</em> statement. There are two <em>#end</em> statements
    in the definition of the <em>#tablerows</em> Velocimacro; the first
    belongs to the <em>#foreach</em>, the second ends the Velocimacro
    definition.
    </p>

<source><![CDATA[
#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $color = "blue" )
<table>
    #tablerows( $color $greatlakes )
</table>
]]></source>

    <p>
    Notice that <em>$greatlakes</em> takes the place of
    <em>$somelist</em>. When the <em>#tablerows</em> Velocimacro is
    called in this situation, the following output is generated:
    </p>

<source><![CDATA[
<table>
    <tr><td bgcolor="blue">Superior</td></tr>
    <tr><td bgcolor="blue">Michigan</td></tr>
    <tr><td bgcolor="blue">Huron</td></tr>
    <tr><td bgcolor="blue">Erie</td></tr>
    <tr><td bgcolor="blue">Ontario</td></tr>
</table>
]]></source>

    <p>
    Velocimacros can be defined <em>inline</em> in a Velocity template,
    meaning that it is unavailable to other Velocity templates on the
    same web site. Defining a Velocimacro such that it can be shared by
    all templates has obvious advantages: it reduces the need to
    redefine the Velocimacro on numerous templates, saving work and
    reducing the chance of error, and ensures that a single change to a
    macro available to more than one template.
    </p>

    <p>
    Were the <em>#tablerows($color $list)</em> Velocimacro defined in a
    Velocimacros template library, this macro could be used on any of
    the regular templates. It could be used many times and for many
    different purposes. In the template <code>mushroom.vm</code> devoted
    to all things fungi, the <em>#tablerows</em> Velocimacro could be
    invoked to list the parts of a typical mushroom:
    </p>

<source><![CDATA[
#set( $parts = ["volva","stipe","annulus","gills","pileus"] )
#set( $cellbgcol = "#CC00FF" )
<table>
#tablerows( $cellbgcol $parts )
</table>
]]></source>

    <p>
    When fulfilling a request for <code>mushroom.vm</code>, Velocity
    would find the <em>#tablerows</em> Velocimacro in the template
    library (defined in the <code>velocity.properties</code> file) and
    generate the following output:
    </p>

<source><![CDATA[
<table>
    <tr><td bgcolor="#CC00FF">volva</td></tr>
    <tr><td bgcolor="#CC00FF">stipe</td></tr>
    <tr><td bgcolor="#CC00FF">annulus</td></tr>
    <tr><td bgcolor="#CC00FF">gills</td></tr>
    <tr><td bgcolor="#CC00FF">pileus</td></tr>
</table>
]]></source>

  <strong>Velocimacro Arguments</strong>

  <p>
   Velocimacros can take as arguments any of the following
   VTL elements :
  </p>

  <ul>
    <li>
      Reference : anything that starts with '$'
    </li>
    <li>
      String literal : something like "$foo" or 'hello'
    </li>
    <li>
      Number literal : 1, 2 etc
    </li>
    <li>
      IntegerRange : [ 1..2] or [$foo .. $bar]
    </li>
    <li>
      ObjectArray : [ "a", "b", "c"]
    </li>
    <li>
       boolean value true
    </li>
    <li>
       boolean value false
    </li>
  </ul>

   <p>
     When passing references as arguments to Velocimacros,
     please note that references are passed 'by name'.
     This means that their value is 'generated' at each
     use inside the Velocimacro.  This feature allows you
     to pass references with method calls and have the
     method called at each use.  For example, when calling
     the following Velocimacro as shown
   </p>

   <source><![CDATA[
     #macro( callme $a )
         $a $a $a
     #end

     #callme( $foo.bar() )
   ]]></source>

    <p>
       results in the method bar() of the reference $foo
       being called 3 times.
    </p>

    <p>
       At first glance, this feature appears surprising, but
       when you take into consideration the original motivation
       behind Velocimacros -- to eliminate cut'n'paste duplication
       of commonly used VTL -- it makes sense.  It allows you to
       do things like pass stateful objects, such as an object
       that generates colors in a repeating sequence for
       coloring table rows, into the Velocimacro.
    </p>

    <p>
       If you need to circumvent this feature, you can always
       just get the value from the method as a new reference
       and pass that :
    </p>

    <source><![CDATA[
     #set( $myval = $foo.bar() )
     #callme( $myval )
   ]]></source>


    <strong>Velocimacro Properties</strong>

    <p>
    Several lines in the <code>velocity.properties</code> file allow for
    flexible implementation of Velocimacros.  Note that these are also
    documented in the <a href="developer-guide.html">Developer Guide</a>.
    </p>

    <p>
    <code>velocimacro.library</code> - A comma-separated list of all
    Velocimacro template libraries. By default, Velocity looks for
    a single library: <em>VM_global_library.vm</em>. The configured template path
    is used to find the Velocimacro libraries.
    </p>

    <p>
    <code>velocimacro.permissions.allow.inline</code> - This property,
    which has possible values of true or false, determines whether
    Velocimacros can be defined in regular templates. The default,
    true, allows template designers to define Velocimacros in the
    templates themselves.
    </p>

    <p>
    <code>velocimacro.permissions.allow.inline.to.replace.global</code> -
     With possible values of true or false,
    this property allows the user to specify if a  Velocimacro defined
    inline in a template can replace a globally defined template, one
    that was loaded on startup via the <code>velocimacro.library</code>
    property. The default, <code>false</code>, prevents
    Velocimacros defined inline in a template from replacing those
    defined in the template libraries loaded at startup.
    </p>

   <p>
    <code>velocimacro.permissions.allow.inline.local.scope</code> - This
    property, with possible values of true or false, defaulting to false,
    controls if Velocimacros defined inline are 'visible' only to the
    defining template.  In other words, with this property set to true,
    a template can define inline VMs that are usable only by the defining
    template.  You can use this for fancy VM tricks - if a global VM calls
    another global VM, with inline scope, a template can define a
    private implementation of the second VM that will be called by the
    first VM when invoked by that template.  All other templates
    are unaffected.
    </p>

    <p>
    <code>velocimacro.context.localscope</code> - This property has the
    possible values true or false, and the default is false.  When true,
    any modifications to the context via #set() within a Velocimacro
    are considered 'local' to the Velocimacro, and will not
    permanently affect the context.
    </p>

    <p>
    <code>velocimacro.library.autoreload</code> - This property
     controls Velocimacro library autoloading. The default value
    is <code>false</code>.  When set to <code>true</code>
    the source Velocimacro library for an invoked Velocimacro will be checked
    for changes, and reloaded if necessary.  This allows you to change and
    test Velocimacro libraries without having to restart your application or
    servlet container, just like you can with regular templates.
    This mode only works when caching is <i>off</i>
    in the resource loaders (e.g. <code>file.resource.loader.cache = false</code> ).
    This feature is intended for development, not for production.
    </p>

    <strong>Velocimacro Trivia</strong>

    <p>
    Currently, Velocimacros must be defined before they are first
    used in a template.  This means that your #macro() declarations
    should come before using the Velocimacros.
    </p>

    <p>
    This is important to remember if you try to #parse()
    a template containing inline #macro() directives.  Because
    the #parse() happens at runtime, and the parser decides if
    a VM-looking element in the template is a VM at parsetime,
    #parse()-ing a set of VM declarations won't work as expected.
    To get around this, simply use the <code>velocimacro.library</code>
    facility to have Velocity load your VMs at startup.
    </p>
 </section>

<section name="Escaping VTL Directives">
  <p>
    VTL directives can be escaped with the backslash character ("\") in
    a manner similar to valid VTL references.
  </p>

<source><![CDATA[
## #include( "a.txt" ) renders as <contents of a.txt>
#include( "a.txt" )

## \#include( "a.txt" ) renders as \#include( "a.txt" )
\#include( "a.txt" )

## \\#include ( "a.txt" ) renders as \<contents of a.txt>
\\#include ( "a.txt" )
]]></source>

  <p>
  Extra care should be taken when escaping VTL directives that contain
  multiple script elements in a single directive (such as in an
  if-else-end statements). Here is a typical VTL if-statement:
  </p>

<source><![CDATA[
#if( $jazz )
    Vyacheslav Ganelin
#end
]]></source>

  <p>
  If <em>$jazz</em> is true, the output is
  </p>
<source><![CDATA[
Vyacheslav Ganelin
]]></source>

  <p>
  If <em>$jazz</em> is false, there is no output. Escaping script elements
  alters the output. Consider the following case:
  </p>

<source><![CDATA[
\#if( $jazz )
    Vyacheslav Ganelin
\#end
]]></source>

  <p>
  Whether <em>$jazz</em> is true or false, the output will be
  </p>

 <source><![CDATA[
 #if($ jazz )
     Vyacheslav Ganelin
 #end
 ]]></source>

  <p>
  In fact, because all script elements
  are escaped, <em>$jazz</em> is never evaluated for it's boolean value.
  Suppose
  backslashes precede script elements that are legitimately escaped:
  </p>

<source><![CDATA[
\\#if( $jazz )
   Vyacheslav Ganelin
\\#end
]]></source>

  <p>
  In this case, if <em>$jazz</em> is true, the output is
  </p>

<source><![CDATA[
\ Vyacheslav Ganelin
\
]]></source>

  <p>
  To understand this, note that the <code>#if( arg ) </code> when
  ended by a newline (return) will omit the newline from the output.
  Therefore, the body of the <code>#if()</code>
  block follows the first '\', rendered
  from the '\\' preceding the <code>#if()</code>.
   The last \ is on a different
  line than the text because there is a newline after 'Ganelin', so
  the final \\, preceding the <code>#end</code> is part of the
  body of the block.
  </p>

  <p>
  If <em>$jazz</em> is false, there is no output. Note that
  things start to break if script elements are not properly escaped.
  </p>

<source><![CDATA[
\\\#if( $jazz )
    Vyacheslave Ganelin
\\#end
]]></source>

  <p>
  Here the <em>#if</em> is escaped, but there is an <em>#end</em>
  remaining; having too many endings will cause a parsing error.
  </p>

 </section>

<section name="VTL: Formatting Issues">

    <p>
    Although VTL in this user guide is often displayed with newlines and
    whitespaces, the VTL shown below
    </p>

<source><![CDATA[
#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
#foreach( $shogun in $imperial )
    $shogun
#end
]]></source>

    <p>
    is equally valid as the following snippet that Geir Magnusson Jr.
    posted to the Velocity user mailing list to illustrate a completely
    unrelated point:
    </p>

<source><![CDATA[
Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.
]]></source>

    <p>
    Velocity's behaviour is to gobble up excess whitespace. The
    preceding directive can be written as:
    </p>

<source><![CDATA[
Send me
#set( $foo = ["$10 and ","a cake"] )
#foreach( $a in $foo )
$a
#end
please.
]]></source>

    <p>
    or as
    </p>

<source><![CDATA[
Send me
#set($foo       = ["$10 and ","a cake"])
                 #foreach           ($a in $foo )$a
         #end please.
]]></source>

    <p>
    In each case the output will be the same.
    </p>

</section>

<section name="Other Features and Miscellany">

<subsection name="Math">

  <p>
    Velocity has a handful of built-in mathematical functions that can
    be used in templates with the <em>set</em> directive. The following
    equations are examples of addition, subtraction, multiplication and
    division, respectively:
  </p>

<source><![CDATA[
#set( $foo = $bar + 3 )
#set( $foo = $bar - 4 )
#set( $foo = $bar * 6 )
#set( $foo = $bar / 2 )
]]></source>

  <p>
    When a division operation is performed, the result will be an
    integer. Any remainder can be obtained by using the modulus
    (<em>%</em>) operator.
  </p>

<source><![CDATA[
#set( $foo = $bar % 5 )
]]></source>

  <p>
    Only integers (...-2, -1, 0, 1, 2...) are permissible when
    performing mathematical equations in Velocity; when a non-integer is
    used, it is logged and a null will be returned as the output.
  </p>

  </subsection>

<subsection name="Range Operator">

  <p>
    The range operator can be used in conjunction with <em>#set</em> and
    <em>#foreach</em> statements. Useful for its ability to produce an
    object array containing integers, the range operator has the
    following construction:
  </p>

<source><![CDATA[
[n..m]
]]></source>

  <p>
    Both <em>n</em> and <em>m</em> must either be or produce integers.
    Whether <em>m</em> is greater than or less than <em>n</em> will not
    matter; in this case the range will simply count down. Examples
    showing the use of the range operator as provided below:
  </p>

<source><![CDATA[
First example:
#foreach( $foo in [1..5] )
$foo
#end

Second example:
#foreach( $bar in [2..-2] )
$bar
#end

Third example:
#set( $arr = [0..1] )
#foreach( $i in $arr )
$i
#end

Fourth example:
[1..3]
]]></source>

  <p>
    Produces the following output:
  </p>

<source><![CDATA[
First example:
1 2 3 4 5

Second example:
2 1 0 -1 -2

Third example:
0 1

Fourth example:
[1..3]
]]></source>

  <p>
    Note that the range operator only produces the array when used in
    conjunction with <em>#set</em> and <em>#foreach</em> directives, as
    demonstrated in the fourth example.
  </p>

  <p>
    Web page designers concerned with making tables a standard size, but
    where some will not have enough data to fill the table, will find
    the range operator particularly useful.
  </p>

  </subsection>

<subsection name="Advanced Issues: Escaping and !">

  <p>
    When a reference is silenced with the <em>!</em> character and the
    <em>!</em> character preceded by an <em>\</em> escape character, the
    reference is handled in a special way. Note the differences between
    regular escaping, and the special case where <em>\</em> precedes
    <em>!</em> follows it:
  </p>

<source><![CDATA[
#set( $foo = "bar" )
$\!foo
$\!{foo}
$\\!foo
$\\\!foo
]]></source>

  <p>
   This renders as:
  </p>

<source><![CDATA[
$!foo
$!{foo}
$\!foo
$\\!foo
]]></source>

  <p>
   Contrast this with regular escaping, where <em>\</em> precedes
   <em>$</em>:
  </p>

<source><![CDATA[
\$foo
\$!foo
\$!{foo}
\\$!{foo}
]]></source>

  <p>
    This renders as:
  </p>

<source><![CDATA[
\$foo
\$!foo
\$!{foo}
\bar
]]></source>

 </subsection>

<subsection name="Velocimacro Miscellany">

<p>
This section is a mini-FAQ on topics relating to Velocimacros.  This
section will change over time, so it's worth checking for new information
from time to time.
</p>

<p>
Note : Throughout this section, 'Velocimacro' will commonly be abbreviated
as 'VM'.
</p>

<strong>Can I use a directive or another VM as an argument to a VM?</strong>

<p>
Example : <code>#center( #bold("hello") )</code>
</p>

<p>
No.  A directive isn't a valid argument to a directive, and for most practical
purposes, a VM is a directive.
</p>

<p>
<i>However...</i>, there are things you can do. One easy solution is to take
advantage of the fact that 'doublequote' (") renders it's contents. So you
could do something like
</p>

<source><![CDATA[
#set($stuff = "#bold('hello')" )
#center( $stuff )
]]></source>

<p>
You can save a step...
</p>

<source><![CDATA[
#center( "#bold( 'hello' )" )
]]></source>

<p>
Please note that in the latter example the arg
is evaluated <i>inside</i> the VM, not at the
calling level.  In other words, the argument to
the VM is passed in in its entirety and evaluated within the VM
it was passed into. This allows you to do things like :
</p>

<source><![CDATA[

#macro( inner $foo )
  inner : $foo
#end

#macro( outer $foo )
   #set($bar = "outerlala")
   outer : $foo
#end

#set($bar = 'calltimelala')
#outer( "#inner($bar)" )

]]></source>

<p>
Where the output is
</p>

<source><![CDATA[
Outer : inner : outerlala
]]></source>

<p>
because the evaluation of the "#inner($bar)" happens inside #outer(), so the
$bar value set inside #outer() is the one that's used.
</p>

<p>
This is an intentional and jealously guarded feature - args are passed 'by
name' into VMs, so you can hand VMs things like stateful references such as
</p>

<source><![CDATA[
#macro( foo $color )
  <tr bgcolor=$color><td>Hi</td></tr>
  <tr bgcolor=$color><td>There</td></tr>
#end

#foo( $bar.rowColor() )
]]></source>

<p>
And have rowColor() called repeatedly, rather than just once.  To avoid that,
invoke the method outside of the VM, and pass the value into the VM.
</p>

<source><![CDATA[
#set($color = $bar.rowColor())
#foo( $color )
]]></source>


<strong>Can I register Velocimacros via #parse() ? </strong>

    <p>
    Currently, Velocimacros must be defined before they are first
    used in a template.  This means that your #macro() declarations
    should come before using the Velocimacros.
    </p>

    <p>
    This is important to remember if you try to #parse()
    a template containing inline #macro() directives.  Because
    the #parse() happens at runtime, and the parser decides if
    a VM-looking element in the template is a VM at parsetime,
    #parse()-ing a set of VM declarations won't work as expected.
    To get around this, simply use the <code>velocimacro.library</code>
    facility to have Velocity load your VMs at startup.
    </p>


<strong>What is Velocimacro Autoreloading?</strong>

  <p>
   There is a property, meant to be used in <i>development</i>,
   not production :
  </p>

  <p>
  <code>velocimacro.library.autoreload</code>
  </p>

   <p>
   which defaults to false.  When set to true <em>along with</em>
   </p>

   <p>
   <code>&lt;type&gt;.resource.loader.cache = false</code>
   </p>

    <p>
    (where &lt;type&gt; is the name of the resource loader that you
    are using, such as 'file') then the Velocity engine will automatically
    reload changes to your Velocimacro library files when you make them,
    so you do not have to dump the servlet engine (or application) or do
    other tricks to have your Velocimacros reloaded.
    </p>

    <p>
    Here is what a simple set of configuration properties would look like.
    </p>

    <source><![CDATA[
    file.resource.loader.path = templates
    file.resource.loader.cache = false
    velocimacro.library.autoreload = true
    ]]></source>

    <p>
    Don't keep this on in production.
    </p>

</subsection>

<subsection name="String Concatenation">

    <p>
    A common question that developers ask is
    <i>How do I do String concatenation?  Is there any
    analogue to the '+' operator in Java?</i>.
   </p>

   <p>
    To do concatenation of references in VTL, you
    just have to 'put them together'.  The context of
    where you want to put them together does matter, so
    we will illustrate with some examples.
   </p>

   <p>
    In the regular 'schmoo' of a template (when you are mixing
    it in with regular content) :
   </p>

   <source><![CDATA[
       #set( $size = "Big" )
       #set( $name = "Ben" )

      The clock is $size$name.
   ]]></source>

   <p>
     and the output will render as 'The clock is BigBen'.
     For more interesting cases, such as when you want to concatenate
     strings to pass to a method, or to set a new reference, just
     do
   </p>

   <source><![CDATA[
      #set( $size = "Big" )
      #set( $name = "Ben" )

      #set($clock = "$size$name" )

      The clock is $clock.
    ]]></source>

    <p>
     Which will result in the same output.  As a final example, when
     you want to mix in 'static' strings with your references, you may
     need to use 'formal references' :
    </p>

    <source><![CDATA[
      #set( $size = "Big" )
      #set( $name = "Ben" )

      #set($clock = "${size}Tall$name" )

      The clock is $clock.
    ]]></source>

    <p>
      Now the output is 'The clock is BigTallBen'.  The
      formal notation is needed so the parser knows you
      mean to use the reference '$size' versus '$sizeTall'
      which it would if the '{}' weren't there.
    </p>
</subsection>

</section>

<section name="Feedback">

  <p>
    If you encounter any mistakes in this manual or have
    other feedback related to the Velocity User Guide, please
    email the
    <a href="mailto:velocity-user@jakarta.apache.org">Velocity user list</a>.
    Thanks!
  </p>

</section>

</body>
</document>