You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@click.apache.org by ta...@apache.org on 2010/06/03 18:44:58 UTC
svn commit: r951064 [4/5] - in
/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity:
VelocityUsersGuide.pdf developer-guide.html site.css user-guide.html
velocity.html vtl-reference-guide.html
Added: click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/user-guide.html
URL: http://svn.apache.org/viewvc/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/user-guide.html?rev=951064&view=auto
==============================================================================
--- click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/user-guide.html (added)
+++ click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/user-guide.html Thu Jun 3 16:44:58 2010
@@ -0,0 +1,2422 @@
+<!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 - Velocity User Guide</title>
+
+ <link rel="stylesheet" href="./site.css" type="text/css">
+ </head>
+
+ <body>
+
+
+ <div id="container">
+
+ <div id="body">
+ <a name="user_guide_-_contents"></a>
+ <h1>User Guide - Contents</h1>
+
+ <div class="subsection">
+ <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>
+ <li>
+ <a href="#propertylookuprules">Property Lookup Rules</a>
+ </li>
+ <li>
+ <a href="#rendering">Rendering</a>
+ </li>
+ </ol>
+
+
+ </li>
+ <li>
+ <a href="#formalreferencenotation">Formal Reference Notation</a>
+ </li>
+ <li>
+ <a href="#quietreferencenotation">Quiet Reference Notation</a>
+ </li>
+ <li>
+ <a href="#strictreferences">Strict References Setting</a>
+ </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="#stringliterals">Literals</a>
+ </li>
+ <li>
+ <a href="#conditionals">If-Else Statements</a>
+
+
+ <ol>
+ <li>
+ <a href="#relationalandlogicaloperators">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="#evaluate">Evaluate</a>
+ </li>
+ <li>
+ <a href="#define">Define</a>
+ </li>
+ <li>
+ <a href="#velocimacros">Velocimacros</a>
+ </li>
+ </ol>
+
+
+ </li>
+ <li>
+ <a href="#getting_literal">Getting literal</a>
+
+
+ <ol>
+ <li>
+ <a href="#currency">Currency</a>
+ </li>
+ <li>
+ <a href="#escapingvalidvtlreferences">Escaping Valid VTL References</a>
+ </li>
+ <li>
+ <a href="#escapinginvalidvtlreferences">Escaping Invalid VTL References</a>
+ </li>
+ <li>
+ <a href="#escaping_vtl_directives">Escaping VTL Directives</a>
+ </li>
+ </ol>
+
+
+ </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>
+ </div>
+ <a name="about_this_guide"></a>
+ <h1>About this Guide</h1>
+
+ <div class="subsection">
+ <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>
+ </div>
+ <a name="what_is_velocity"></a>
+ <h1>What is Velocity?</h1>
+
+ <div class="subsection">
+ <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>
+ </div>
+ <a name="what_can_velocity_do_for_me"></a>
+ <h1>What can Velocity do for me?</h1>
+
+ <div class="subsection">
+ <a name="the_mud_store_example"></a>
+ <h2>The Mud Store Example</h2>
+ <div class="subsection">
+ <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>
+ <div class="source">
+<HTML>
+<BODY>
+Hello $customer.Name!
+<table>
+#foreach( $mud in $mudsOnSpecial )
+ #if ( $customer.hasPurchased($mud) )
+ <tr>
+ <td>
+ $flogger.getPromo( $mud )
+ </td>
+ </tr>
+ #end
+#end
+</table>
+</pre></div>
+ <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>
+ </div>
+ </div>
+ <a name="velocity_template_language_vtl:_an_introduction"></a>
+ <h1>Velocity Template Language (VTL): An Introduction</h1>
+
+ <div class="subsection">
+ <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>
+ <div class="source">
+#set( $a = "Velocity" )
+</pre></div>
+ <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. String values are always enclosed in quotes, either
+ single or double quotes. Single quotes will ensure that the quoted value
+ will be assigned to the reference as is. Double quotes allow you to use
+ velocity references and directives to interpolate, such as "Hello $name",
+ where the <em>$name</em> will be replaced by the current value before
+ that string literal is assigned to the left hand side of the <em>=</em>
+ </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>
+ </div>
+ <a name="hello_velocity_world"></a>
+ <h1>Hello Velocity World!</h1>
+
+ <div class="subsection">
+ <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>
+ <div class="source">
+<html>
+<body>
+#set( $foo = "Velocity" )
+Hello $foo World!
+</body>
+<html>
+</pre></div>
+ <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>
+ </div>
+ <a name="comments"></a>
+ <h1>Comments</h1>
+
+ <div class="subsection">
+ <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>
+ <div class="source">
+## This is a single line comment.
+</pre></div>
+ <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>
+ <div class="source">
+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.
+</pre></div>
+ <p>
+ Here are a few examples to clarify how single line and multi-line
+ comments work:
+ </p>
+ <div class="source">
+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.
+</pre></div>
+ <p>
+ There is a third type of comment, the VTL comment block, which may
+ be used to store any sort of extra information you want to track
+ in the template (e.g. javadoc-style author and versioning information):
+ </p>
+ <div class="source">
+#**
+This is a VTL comment block and
+may be used to store such information
+as the document author and versioning
+information:
+@author
+@version 5
+*#
+</pre></div>
+ </div>
+ <a name="references"></a>
+ <h1>References</h1>
+
+ <div class="subsection">
+ <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>
+ <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>
+ <div class="source">
+$foo
+$mudSlinger
+$mud-slinger
+$mud_slinger
+$mudSlinger1
+</pre></div>
+ <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>
+ <div class="source">
+#set( $foo = "bar" )
+</pre></div>
+ <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>
+ <div class="source">
+$customer.Address
+$purchase.Total
+</pre></div>
+ <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>
+ <div class="source">
+$customer.getAddress()
+$purchase.getTotal()
+$page.setTitle( "My Home Page" )
+$person.setAttributes( ["Strange", "Weird", "Excited"] )
+</pre></div>
+ <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>
+ <div class="source">
+$sun.getPlanets()
+$annelid.getDirt()
+$album.getPhoto()
+</pre></div>
+ <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>
+ <div class="source">
+$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
+</pre></div>
+ <p>
+ As of Velocity 1.6, all array references are now "magically" treated as if
+ they are fixed-length lists. This means that you can call java.util.List methods
+ on array references. So, if you have a reference to an array (let's say
+ this one is a String[] with three values), you can do:
+ </p>
+ <div class="source">
+$myarray.isEmpty()
+
+$myarray.size()
+
+$myarray.get(2)
+
+$myarray.set(1, 'test')
+</pre></div>
+ <p>
+ Also new in Velocity 1.6 is support for vararg methods. A method like
+ <code>public void setPlanets(String... planets)</code> or even just
+ <code>public void setPlanets(String[] planets)</code> (if you are
+ using a pre-Java 5 JDK), can now accept
+ any number of arguments when called in a template.
+ </p>
+ <div class="source">
+$sun.setPlanets('Earth', 'Mars', 'Neptune')
+
+$sun.setPlanets('Mercury')
+
+$sun.setPlanets()
+## Will just pass in an empty, zero-length array
+</pre></div>
+ <p>
+ <a name="propertylookuprules"><strong>Property Lookup Rules</strong></a>
+ <br />
+ As was mentioned earlier, properties often refer to methods of the
+ parent object. Velocity is quite clever when figuring out which method
+ corresponds to a requested property. It tries out different alternatives
+ based on several established naming conventions. The exact lookup
+ sequence depends on whether or not the property name starts with
+ an upper-case letter. For lower-case names, such as
+ <em>$customer.address</em>, the sequence is
+ <ol>
+ <li>getaddress()</li>
+ <li>getAddress()</li>
+ <li>get("address")</li>
+ <li>isAddress()</li>
+ </ol>
+ For upper-case property names like <em>$customer.Address</em>, it is
+ slightly different:
+ <ol>
+ <li>getAddress()</li>
+ <li>getaddress()</li>
+ <li>get("Address")</li>
+ <li>isAddress()</li>
+ </ol>
+ </p>
+ <p>
+ <a name="rendering"><strong>Rendering</strong></a>
+ <br />
+ The final value resulting from each and every reference (whether variable,
+ property, or method) is converted to a String object when it is rendered
+ into the final output. 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="formalreferencenotation"><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>
+ <div class="source">
+${mudSlinger}
+${customer.Address}
+${purchase.getTotal()}
+</pre></div>
+ <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>
+ <div class="source">
+Jack is a $vicemaniac.
+</pre></div>
+ <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>
+ <div class="source">
+Jack is a ${vice}maniac.
+</pre></div>
+ <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="quietreferencenotation"><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>
+ <div class="source">
+<input type="text" name="email" value="$email"/>
+</pre></div>
+ <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>
+ <div class="source">
+<input type="text" name="email" value="$!email"/>
+</pre></div>
+ <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>
+ <div class="source">
+<input type="text" name="email" value="$!{email}"/>
+</pre></div>
+ </div>
+ <a name="strictreferences"></a>
+ <h1>Strict References Setting</h1>
+
+ <div class="subsection">
+ <p>
+ Velocity 1.6 introduces the concept of strict reference mode which
+ is activated by setting the velocity configuration property
+ 'runtime.references.strict' to true. The general intent of this
+ setting is to make Velocity behave more strictly in cases that are
+ undefined or ambiguous, similar to a programming language, which
+ may be more appropriate for some uses of Velocity. In such
+ undefined or ambiguous cases Velocity will throw an exception. The
+ following discussion outlines the cases that strict behavior is
+ different from traditional behavior.
+ </p>
+ <p>
+ With this setting references are required to be either placed
+ explicitly into the context or defined with a #set directive, or
+ Velocity will throw an exception. References that are in the
+ context with a value of null will not produce an exception.
+ Additionally, if an attempt is made to call a method or a property
+ on an object within a reference that does not define the specified
+ method or property then Velocity will throw an exception. This is
+ also true if there is an attempt to call a method or property on a
+ null value.
+ </p>
+ <p>
+ In the following examples $bar is defined but $foo is not, and all
+ these statements will throw an exception:
+ </p>
+ <div class="source">$foo ## Exception
+#set($bar = $foo) ## Exception
+#if($foo == $bar)#end ## Exception
+#foreach($item in $foo)#end ## Exception</pre></div>
+ <p>
+ Also, The following statements show examples in which Velocity will
+ throw an exception when attempting to call methods or properties
+ that do not exist. In these examples $bar contains an object that
+ defines a property 'foo' which returns a string, and 'retnull' which
+ returns null.
+ </p>
+ <div class="source">$bar.bogus ## $bar does not provide property bogus, Exception
+$bar.foo.bogus ## $bar.foo does not provide property bogus, Exception
+$bar.retnull.bogus ## cannot call a property on null, Exception</pre></div>
+ <p>
+ In general strict reference behavior is true for all situations
+ in which references are used except for a special case within the
+ #if directive. If a reference is used within a #if or #elseif directive
+ without any methods or properties, and if it is not being compared
+ to another value, then undefined references are allowed. This
+ behavior provides an easy way to test if a reference is defined
+ before using it in a template. In the following example where
+ $foo is not defined the statements will not throw an exception.
+ </p>
+ <div class="source">#if ($foo)#end ## False
+#if ( ! $foo)#end ## True
+#if ($foo && $foo.bar)#end ## False and $foo.bar will not be evaluated
+#if ($foo && $foo == "bar")#end ## False and $foo == "bar" wil not be evaluated
+#if ($foo1 || $foo2)#end ## False $foo1 and $foo2 are not defined</pre></div>
+ <p>
+ Strict mode requires that comparisons of <, >, >= or <= within an
+ #if directive make sense. Also, the argument to #foreach must be
+ iterable (this behavior can be modified with the property
+ directive.foreach.skip.invalid). Finally, undefined macro
+ references will also throw an exception in strict mode.
+ </p>
+ </div>
+ <a name="case_substitution"></a>
+ <h1>Case Substitution</h1>
+
+ <div class="subsection">
+ <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>
+ <div class="source">
+$foo
+
+$foo.getBar()
+## is the same as
+$foo.Bar
+
+$data.setUser("jon")
+## is the same as
+#set( $data.User = "jon" )
+
+$data.getRequest().getServerName()
+## is the same as
+$data.Request.ServerName
+## is the same as
+${data.Request.ServerName}
+</pre></div>
+ <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>
+ </div>
+ <a name="directives"></a>
+ <h1>Directives</h1>
+
+ <div class="subsection">
+ <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>
+ <p>
+ Directives always begin with a <code>#</code>. Like references, the name of the directive may be
+ bracketed by a <code>{</code> and a <code>}</code> symbol. This is useful with directives
+ that are immediately followed by text. For example the following produces an error:
+ </p>
+ <div class="source">
+#if($a==1)true enough#elseno way!#end
+</pre></div>
+ <p>
+ In such a case, use the brackets to separate <code>#else</code> from the rest of the line.
+ </p>
+ <div class="source">
+#if($a==1)true enough#{else}no way!#end
+</pre></div>
+ <p> </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>
+ <div class="source">
+#set( $primate = "monkey" )
+#set( $customer.Behavior = $primate )
+</pre></div>
+ <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>
+ <li>Map</li>
+ </ul>
+ </p>
+ <p>
+ These examples demonstrate each of the aforementioned types:
+ </p>
+ <div class="source">
+#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
+#set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"}) ## Map
+</pre></div>
+ <p>
+ NOTE: For the ArrayList 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>
+ Similarly, for the Map example, the elements defined within the
+ { } operator are accessible using the methods defined
+ in the Map class. So, for example, you could access
+ the first element above using $monkey.Map.get("banana") to return
+ a String 'good', or even $monkey.Map.banana to return the
+ same value.
+ </p>
+ <p>
+ The RHS can also be a simple arithmetic expression:
+ </p>
+ <div class="source">
+#set( $value = $foo + 1 )
+#set( $value = $bar - 1 )
+#set( $value = $foo * $bar )
+#set( $value = $foo / $bar )
+</pre></div>
+ <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.
+ Depending on how Velocity is configured, it is usually not
+ possible to remove an existing reference from the context via
+ this mechanism.
+ (Note that this can be permitted by changing one of the Velocity configuration properties).
+ This can be confusing for
+ newcomers to Velocity. For example:
+ </p>
+ <div class="source">
+#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
+</pre></div>
+ <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>
+ <div class="source">
+The result of the first query is bill
+
+The result of the second query is bill
+</pre></div>
+ <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>
+ <div class="source">
+
+#set( $criteria = ["name", "address"] )
+
+#foreach( $criterion in $criteria )
+
+ #set( $result = $query.criteria($criterion) )
+
+ #if( $result )
+ Query was successful
+ #end
+
+#end
+</pre></div>
+ <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>
+ <div class="source">
+
+#set( $criteria = ["name", "address"] )
+
+#foreach( $criterion in $criteria )
+
+ #set( $result = false )
+ #set( $result = $query.criteria($criterion) )
+
+ #if( $result )
+ Query was successful
+ #end
+
+#end
+</pre></div>
+ <p>
+ Unlike some of the other Velocity directives, the <em>#set</em>
+ directive does not have an <em>#end</em> statement.
+ </p>
+ <a name="stringliterals"><strong>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>
+ <div class="source">
+#set( $directoryRoot = "www" )
+#set( $templateName = "index.vm" )
+#set( $template = "$directoryRoot/$templateName" )
+$template
+</pre></div>
+ <p>
+ The output will be
+ </p>
+ <div class="source">
+www/index.vm
+</pre></div>
+ <p>
+ However, when the string literal is enclosed in single quote
+ characters, it will not be parsed:
+ </p>
+ <div class="source">
+#set( $foo = "bar" )
+$foo
+#set( $blargh = '$foo' )
+$blargh
+</pre></div>
+ <div class="source">
+ bar
+ $foo
+</pre></div>
+ <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>
+ <p>
+ Alternately, the <em>#literal</em> script element allows the
+ template designer to easily use large chunks of uninterpreted
+ content in VTL code. This can be especially useful in place of <a href="#EscapingVTLDirectives">escaping</a> multiple directives.
+ </p>
+ <div class="source">
+#literal()
+#foreach ($woogie in $boogie)
+ nothing will happen to $woogie
+#end
+#end
+</pre></div>
+ <p>
+ Renders as:
+ </p>
+ <div class="source">
+#foreach ($woogie in $boogie)
+ nothing will happen to $woogie
+#end
+</pre></div>
+ </div>
+ <a name="conditionals"></a>
+ <h1>Conditionals</h1>
+
+ <div class="subsection">
+ <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>
+ <div class="source">
+#if( $foo )
+ <strong>Velocity!</strong>
+#end
+</pre></div>
+ <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>
+ <div class="source">
+#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
+</pre></div>
+ <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>
+ <a name="relationalandlogicaloperators"><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>
+ <div class="source">
+#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
+</pre></div>
+ <p>Note that the semantics of <em>==</em> are slightly different than Java where <em>==</em>
+ can only be used to test object equality. In Velocity the equivalent operator
+ can be used to directly compare numbers, strings, or objects. When the objects
+ are of different classes, the string representations are obtained by calling
+ <code>toString()</code> for each object and then compared.
+ </p>
+ <p>
+ Velocity has logical AND, OR and NOT operators as well.
+ Below are examples demonstrating the use of the
+ logical AND, OR and NOT operators.
+ </p>
+ <div class="source">
+## logical AND
+
+#if( $foo && $bar )
+ <strong> This AND that</strong>
+#end
+
+</pre></div>
+ <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>
+ <div class="source">
+## logical OR
+
+#if( $foo || $bar )
+ <strong>This OR That</strong>
+#end
+</pre></div>
+ <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>
+ <div class="source">
+
+##logical NOT
+
+#if( !$foo )
+ <strong>NOT that</strong>
+#end
+
+</pre></div>
+ <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>
+ <p>There are text versions of all logical operators, including
+ <em>eq</em>, <em>ne</em>,
+ <em>and</em>, <em>or</em>, <em>not</em>, <em>gt</em>, <em>ge</em>, <em>lt</em>,
+ and <em>le</em>.
+ </p>
+ <p>One more useful note. When you wish to include text immediately following
+ a <em>#else</em> directive you will need to use curly brackets immediately surrounding
+ the directive to differentiate it from the following text.
+ (Any directive can be delimited by
+ curly brackets, although this is most useful for <em>#else</em>).
+ </p>
+ <div class="source">
+#if( $foo == $bar)it's true!#{else}it's not!#end</li>
+</pre></div>
+ </div>
+ <a name="loops"></a>
+ <h1>Loops</h1>
+
+ <div class="subsection">
+ <strong>Foreach Loop</strong>
+ <p>
+ The <em>#foreach</em> element allows for looping. For example:
+ </p>
+ <div class="source">
+<ul>
+#foreach( $product in $allProducts )
+ <li>$product</li>
+#end
+</ul>
+</pre></div>
+ <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>
+ <div class="source">
+<ul>
+#foreach( $key in $allProducts.keySet() )
+ <li>Key: $key -> Value: $allProducts.get($key)</li>
+#end
+</ul>
+</pre></div>
+ <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>
+ Velocity also now provides an easy way to tell if you are
+ on the last iteration of a loop:
+ </p>
+ <div class="source">
+#foreach( $customer in $customerList )
+ $customer.Name#if( $velocityHasNext ),#end
+#end
+</pre></div>
+ <p>
+ The default name for the "has next" variable reference, which is
+ specified in the velocity.properties file, is $velocityHasNext.
+ 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
+directive.foreach.iterator.name = velocityHasNext
+
+# Default starting value of the loop
+# counter variable reference.
+directive.foreach.counter.initial.value = 1
+</pre></div>
+ <p>
+ It's possible to set a maximum allowed number of times that a loop
+ may be executed. By default there is no max (indicated by a value of 0
+ or less), but this can be set to an arbitrary number in the
+ <code>velocity.properties</code> file. This is useful as a fail-safe.
+ </p>
+ <div class="source">
+# The maximum allowed number of loops.
+directive.foreach.maxloops = -1
+</pre></div>
+ <p>
+ If you want to stop looping in a foreach from within your template,
+ you can now use the #break directive to stop looping at any time:
+ </p>
+ <div class="source">
+## list first 5 customers only
+#foreach( $customer in $customerList )
+ #if( $velocityCount > 5 )
+ #break
+ #end
+ $customer.Name
+#end
+</pre></div>
+ </div>
+ <a name="include"></a>
+ <h1>Include</h1>
+
+ <div class="subsection">
+ <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>
+ <div class="source">
+#include( "one.txt" )
+</pre></div>
+ <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>
+ <div class="source">
+#include( "one.gif","two.txt","three.htm" )
+</pre></div>
+ <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>
+ <div class="source">
+#include( "greetings.txt", $seasonalstock )
+</pre></div>
+ </div>
+ <a name="parse"></a>
+ <h1>Parse</h1>
+
+ <div class="subsection">
+ <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>
+ <div class="source">
+#parse( "me.vm" )
+</pre></div>
+ <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>directive.parse.max.depth</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>directive.parse.max.depth</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>
+ <div class="source">
+Count down.
+#set( $count = 8 )
+#parse( "parsefoo.vm" )
+All done with dofoo.vm!
+</pre></div>
+ <p>
+ It would reference the template <code>parsefoo.vm</code>, which
+ might contain the following VTL:
+ </p>
+ <div class="source">
+$count
+#set( $count = $count - 1 )
+#if( $count > 0 )
+ #parse( "parsefoo.vm" )
+#else
+ All done with parsefoo.vm!
+#end
+</pre></div>
+ <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>
+ </div>
+ <a name="stop"></a>
+ <h1>Stop</h1>
+
+ <div class="subsection">
+ <p>
+ The <em>#stop</em> script element prevents any further text or references
+ in the page from being rendered. This is useful
+ for debugging purposes.
+ </p>
+ </div>
+ <a name="evaluate"></a>
+ <h1>Evaluate</h1>
+
+ <div class="subsection">
+ <p>
+ The <em>#evaluate</em> directive can be used to dynamically evaluate VTL. This allows
+ the template to evaluate a string that is created at render time. Such a string might be
+ used to internationalize the template or to include parts of a template from a database.
+ </p>
+ <p>The example below will display <code>abc</code>.
+ </p>
+ <div class="source">
+#set($source1 = "abc")
+#set($select = "1")
+#set($dynamicsource = "$source$select")
+## $dynamicsource is now the string '$source1'
+#evaluate($dynamicsource)
+</pre></div>
+ </div>
+ <a name="define"></a>
+ <h1>Define</h1>
+
+ <div class="subsection">
+ <p>
+ The <em>#define</em> directive lets one assign a block of VTL to a reference.
+ </p>
+ <p>The example below will display <code>Hello World!</code>.
+ </p>
+ <div class="source">
+#define( $block )Hello $who#end
+#set( $who = 'World!' )
+$block
+</pre></div>
+ </div>
+ <a name="velocimacros"></a>
+ <h1>Velocimacros</h1>
+
+ <div class="subsection">
+ <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>
+ <div class="source">
+#macro( d )
+<tr><td></td></tr>
+#end
+</pre></div>
+ <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>
+ <div class="source">
+#d()
+</pre></div>
+ <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>
+ <div class="source">
+#macro( tablerows $color $somelist )
+#foreach( $something in $somelist )
+ <tr><td bgcolor=$color>$something</td></tr>
+#end
+#end
+</pre></div>
+ <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>
+ <div class="source">
+#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
+#set( $color = "blue" )
+<table>
+ #tablerows( $color $greatlakes )
+</table>
+</pre></div>
+ <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>
+ <div class="source">
+<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>
+</pre></div>
+ <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>
+ <div class="source">
+#set( $parts = ["volva","stipe","annulus","gills","pileus"] )
+#set( $cellbgcol = "#CC00FF" )
+<table>
+#tablerows( $cellbgcol $parts )
+</table>
+</pre></div>
+ <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>
+ <div class="source">
+<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>
+</pre></div>
+ <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>
+ <div class="source">
+ #macro( callme $a )
+ $a $a $a
+ #end
+
+ #callme( $foo.bar() )
+ </pre></div>
+ <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>
+ <div class="source">
+ #set( $myval = $foo.bar() )
+ #callme( $myval )
+ </pre></div>
+ <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>
+ </div>
+ <a name="getting_literal"></a>
+ <h1>Getting literal</h1>
+
+ <div class="subsection">
+ <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 these
+ characters.
+ </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="escapingvalidvtlreferences"><strong>Escaping Valid VTL References</strong></a>
+ <br />
+ Cases may arise where you do not want to have a reference rendered by Velocity.
+ <em>Escaping</em> special characters is the best way to output
+ VTL's special characters in these situations, and this can be
+ done using the backslash ( <em>\</em> ) character <i>when those special
+ characters are part of a valid VTL reference</i>.
+ <a href="#escapinginvalidvtlreferences" style="text-decoration: none"><sup>*</sup></a>
+ </p>
+ <div class="source">
+#set( $email = "foo" )
+$email
+</pre></div>
+ <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.
+ Here is a demonstration:
+ </p>
+ <div class="source">## The following line defines $email in this template:
+#set( $email = "foo" )
+$email
+\$email
+</pre></div>
+ <p>
+ renders as
+ </p>
+ <div class="source">foo
+$email
+</pre></div>
+ <p>
+ If, for some reason, you need a backslash before either line above,
+ you can do the following:
+ </p>
+ <div class="source">## The following line defines $email in this template:
+#set( $email = "foo" )
+\\$email
+\\\$email
+</pre></div>
+ <p>
+ which renders as
+ </p>
+ <div class="source">\foo
+\$email
+</pre></div>
+ <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>
+ <div class="source">
+$email
+\$email
+\\$email
+\\\$email
+</pre></div>
+ <p>
+ renders as
+ </p>
+ <div class="source">
+$email
+\$email
+\\$email
+\\\$email
+</pre></div>
+ <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>
+ <div class="source">
+#set( $foo = "gibbous" )
+$moon = $foo
+</pre></div>
+ <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>
+ <a name="escapinginvalidvtlreferences"><strong>Escaping Invalid VTL References</strong></a>
+ <br />
+ Sometimes Velocity has trouble parsing your template when it encounters
+ an "invalid reference" that you never intended to be a reference at all.
+ <em>Escaping</em> special characters is, again, the best way to
+ handle these situations, but in these situations, the backslash will
+ likely fail you. Instead of simply trying to escape the problematic
+ <code>$</code> or <code>#</code>, you should probably just replace this:
+ </p>
+ <div class="source">
+${my:invalid:non:reference}
+</pre></div>
+ <p>with something like this</p>
+ <div class="source">
+#set( $D = '$' )
+${D}{my:invalid:non:reference}
+</pre></div>
+ <p>You can, of course, put your <code>$</code> or <code>#</code> string directly
+ into the context from your java code (e.g. <code>context.put("D","$");</code>)
+ to avoid the extra #set() directive in your template(s). Or, if you are using
+ <a href="http://velocity.apache.org/tools/devel/">VelocityTools</a>, you can
+ just use the EscapeTool like this:</p>
+ <div class="source">
+${esc.d}{my:invalid:non:reference}
+</pre></div>
+ <p>
+ Escaping of both valid and invalid VTL directives is
+ handled in much the same manner; this is described in
+ more detail in the Directives section.
+ </p>
+ <p>
+ <a name="escaping_vtl_directives"><strong>Escaping VTL Directives</strong></a>
+ <br />
+ VTL directives can be escaped with the backslash character ("\") in
+ a manner similar to valid VTL references.
+ </p>
+ <div class="source">
+## #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" )
+</pre></div>
+ <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>
+ <div class="source">
+#if( $jazz )
+ Vyacheslav Ganelin
+#end
+</pre></div>
+ <p>
+ If <em>$jazz</em> is true, the output is
+ </p>
+ <div class="source">
+Vyacheslav Ganelin
+</pre></div>
+ <p>
+ If <em>$jazz</em> is false, there is no output. Escaping script elements
+ alters the output. Consider the following case:
+ </p>
+ <div class="source">
+\#if( $jazz )
+ Vyacheslav Ganelin
+\#end
+</pre></div>
+ <p>
+ This causes the directives to be escaped, but the rendering of <em>$jazz</em>
+ proceeds as normal. So, if <em>$jazz</em> is true, the output is
+ </p>
+ <div class="source">
+ #if( true )
+ Vyacheslav Ganelin
+ #end
+ </pre></div>
+ <p>
+ Suppose backslashes precede script elements that are legitimately escaped:
+ </p>
+ <div class="source">
+\\#if( $jazz )
+ Vyacheslav Ganelin
+\\#end
+</pre></div>
+ <p>
+ In this case, if <em>$jazz</em> is true, the output is
+ </p>
+ <div class="source">
+\ Vyacheslav Ganelin
+\
+</pre></div>
+ <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, the output is
+ </p>
+ <div class="source">
+\
+</pre></div>
+ <p>
+ Note that
+ things start to break if script elements are not properly escaped.
+ </p>
+ <div class="source">
+\\\#if( $jazz )
+ Vyacheslave Ganelin
+\\#end
+</pre></div>
+ <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>
+ </div>
+ <a name="vtl:_formatting_issues"></a>
+ <h1>VTL: Formatting Issues</h1>
+
+ <div class="subsection">
+ <p>
+ Although VTL in this user guide is often displayed with newlines and
+ whitespaces, the VTL shown below
+ </p>
+ <div class="source">
+#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
+#foreach( $shogun in $imperial )
+ $shogun
+#end
+</pre></div>
+ <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>
+ <div class="source">
+Send me #set($foo=["$10 and ","a pie"])#foreach($a in $foo)$a#end please.
+</pre></div>
+ <p>
+ Velocity's behaviour is to gobble up excess whitespace. The
+ preceding directive can be written as:
+ </p>
+ <div class="source">
+Send me
+#set( $foo = ["$10 and ","a pie"] )
+#foreach( $a in $foo )
+$a
+#end
+please.
+</pre></div>
+ <p>
+ or as
+ </p>
+ <div class="source">
+Send me
+#set($foo = ["$10 and ","a pie"])
+ #foreach ($a in $foo )$a
+ #end please.
+</pre></div>
+ <p>
+ In each case the output will be the same.
+ </p>
+ </div>
+ <a name="other_features_and_miscellany"></a>
+ <h1>Other Features and Miscellany</h1>
+
+ <div class="subsection">
+ <a name="math"></a>
+ <h2>Math</h2>
+ <div class="subsection">
+ <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>
+ <div class="source">
+#set( $foo = $bar + 3 )
+#set( $foo = $bar - 4 )
+#set( $foo = $bar * 6 )
+#set( $foo = $bar / 2 )
+</pre></div>
+ <p>
+ When a division operation is performed between two integers, the result will be an
+ integer, as the fractional portion is discarded. Any remainder can be obtained by
+ using the modulus (<em>%</em>) operator.
+ </p>
+ <div class="source">
+#set( $foo = $bar % 5 )
+</pre></div>
+ </div>
+ <a name="range_operator"></a>
+ <h2>Range Operator</h2>
+ <div class="subsection">
+ <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>
+ <div class="source">
+[n..m]
+</pre></div>
+ <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>
+ <div class="source">
+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]
+</pre></div>
+ <p>
+ Produces the following output:
+ </p>
+ <div class="source">
+First example:
+1 2 3 4 5
+
+Second example:
+2 1 0 -1 -2
+
+Third example:
+0 1
+
+Fourth example:
+[1..3]
+</pre></div>
+ <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>
+ </div>
+ <a name="advanced_issues:_escaping_and_"></a>
+ <h2>Advanced Issues: Escaping and !</h2>
+ <div class="subsection">
+ <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>
+ <div class="source">
+#set( $foo = "bar" )
+$\!foo
+$\!{foo}
+$\\!foo
+$\\\!foo
+</pre></div>
+ <p>
+ This renders as:
+ </p>
+ <div class="source">
+$!foo
+$!{foo}
+$\!foo
+$\\!foo
+</pre></div>
+ <p>
+ Contrast this with regular escaping, where <em>\</em> precedes
+ <em>$</em>:
+ </p>
+ <div class="source">
+\$foo
+\$!foo
+\$!{foo}
+\\$!{foo}
+</pre></div>
+ <p>
+ This renders as:
+ </p>
+ <div class="source">
+$foo
+$!foo
+$!{foo}
+\bar
+</pre></div>
+ </div>
+ <a name="velocimacro_miscellany"></a>
+ <h2>Velocimacro Miscellany</h2>
+ <div class="subsection">
+ <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 its contents. So you
+could do something like
+</p>
+ <div class="source">
+#set($stuff = "#bold('hello')" )
+#center( $stuff )
+</pre></div>
+ <p>
+You can save a step...
+</p>
+ <div class="source">
+#center( "#bold( 'hello' )" )
+</pre></div>
+ <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>
+ <div class="source">
+
+#macro( inner $foo )
+ inner : $foo
+#end
+
+#macro( outer $foo )
+ #set($bar = "outerlala")
+ outer : $foo
+#end
+
+#set($bar = 'calltimelala')
+#outer( "#inner($bar)" )
+
+</pre></div>
+ <p>
+Where the output is
+</p>
+ <div class="source">
+Outer : inner : outerlala
+</pre></div>
+ <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>
+ <div class="source">
+#macro( foo $color )
+ <tr bgcolor=$color><td>Hi</td></tr>
+ <tr bgcolor=$color><td>There</td></tr>
+#end
+
+#foo( $bar.rowColor() )
+</pre></div>
+ <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>
+ <div class="source">
+#set($color = $bar.rowColor())
+#foo( $color )
+</pre></div>
+ <strong>Can I register Velocimacros via #parse() ? </strong>
+ <p>
+ <b>Yes! This became possible in Velocity 1.6.</b>
+ </p>
+ <p>
+ If you are using an earlier version, your 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><type>.resource.loader.cache = false</code>
+ </p>
+ <p>
+ (where <type> 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>
+ <div class="source">
+ file.resource.loader.path = templates
+ file.resource.loader.cache = false
+ velocimacro.library.autoreload = true
+ </pre></div>
+ <p>
+ Don't keep this on in production.
+ </p>
+ </div>
+ <a name="string_concatenation"></a>
+ <h2>String Concatenation</h2>
+ <div class="subsection">
+ <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
[... 92 lines stripped ...]