click-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From take...@apache.org
Subject 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
Date Thu, 03 Jun 2010 16:44:58 GMT
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">
+&lt;HTML&gt;
+&lt;BODY&gt;
+Hello $customer.Name!
+&lt;table&gt;
+#foreach( $mud in $mudsOnSpecial )
+   #if ( $customer.hasPurchased($mud) )
+      &lt;tr&gt;
+        &lt;td&gt;
+          $flogger.getPromo( $mud )
+        &lt;/td&gt;
+      &lt;/tr&gt;
+   #end
+#end
+&lt;/table&gt;
+</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 = &quot;Velocity&quot; )
+</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">
+&lt;html&gt;
+&lt;body&gt;
+#set( $foo = &quot;Velocity&quot; )
+Hello $foo World!
+&lt;/body&gt;
+&lt;html&gt;
+</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 = &quot;bar&quot; )
+</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( &quot;My Home Page&quot; )
+$person.setAttributes( [&quot;Strange&quot;, &quot;Weird&quot;, &quot;Excited&quot;] )
+</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( [&quot;Earth&quot;, &quot;Mars&quot;, &quot;Neptune&quot;] )
+## Can't pass a parameter list with $sun.Planets
+
+$sisyphus.pushRock()
+## Velocity assumes I mean $sisyphus.getRock()
+
+$book.setTitle( &quot;Homage to Catalonia&quot; )
+## 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">
+&lt;input type=&quot;text&quot; name=&quot;email&quot; value=&quot;$email&quot;/&gt;
+</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">
+&lt;input type=&quot;text&quot; name=&quot;email&quot; value=&quot;$!email&quot;/&gt;
+</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">
+&lt;input type=&quot;text&quot; name=&quot;email&quot; value=&quot;$!{email}&quot;/&gt;
+</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 &amp;&amp; $foo.bar)#end      ## False and $foo.bar will not be evaluated
+#if ($foo &amp;&amp; $foo == &quot;bar&quot;)#end ## False and $foo == &quot;bar&quot; wil not be evaluated
+#if ($foo1 || $foo2)#end        ## False $foo1 and $foo2 are not defined</pre></div>
+																			<p>
+    Strict mode requires that comparisons of &lt;, &gt;, &gt;= or &lt;= 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(&quot;jon&quot;)
+## is the same as
+#set( $data.User = &quot;jon&quot; )
+
+$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 = &quot;monkey&quot; )
+#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 = &quot;monica&quot; ) ## 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 = [&quot;Not&quot;, $my, &quot;fault&quot;] ) ## ArrayList
+#set( $monkey.Map = {&quot;banana&quot; : &quot;good&quot;, &quot;roast beef&quot; : &quot;bad&quot;}) ## 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(&quot;name&quot;) )
+The result of the first query is $result
+
+#set( $result = $query.criteria(&quot;address&quot;) )
+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 = [&quot;name&quot;, &quot;address&quot;] )
+
+#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 = [&quot;name&quot;, &quot;address&quot;] )
+
+#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 = &quot;www&quot; )
+#set( $templateName = &quot;index.vm&quot; )
+#set( $template = &quot;$directoryRoot/$templateName&quot; )
+$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 = &quot;bar&quot; )
+$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 )
+   &lt;strong&gt;Velocity!&lt;/strong&gt;
+#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 &lt; 10 )
+    &lt;strong&gt;Go North&lt;/strong&gt;
+#elseif( $foo == 10 )
+    &lt;strong&gt;Go East&lt;/strong&gt;
+#elseif( $bar == 6 )
+    &lt;strong&gt;Go South&lt;/strong&gt;
+#else
+    &lt;strong&gt;Go West&lt;/strong&gt;
+#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 = &quot;deoxyribonucleic acid&quot;)
+#set ($bar = &quot;ribonucleic acid&quot;)
+
+#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 &amp;&amp; $bar )
+   &lt;strong&gt; This AND that&lt;/strong&gt;
+#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 )
+    &lt;strong&gt;This OR That&lt;/strong&gt;
+#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 )
+  &lt;strong&gt;NOT that&lt;/strong&gt;
+#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&lt;/li&gt;
+</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">
+&lt;ul&gt;
+#foreach( $product in $allProducts )
+    &lt;li&gt;$product&lt;/li&gt;
+#end
+&lt;/ul&gt;
+</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">
+&lt;ul&gt;
+#foreach( $key in $allProducts.keySet() )
+    &lt;li&gt;Key: $key -&gt; Value: $allProducts.get($key)&lt;/li&gt;
+#end
+&lt;/ul&gt;
+</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">
+&lt;table&gt;
+#foreach( $customer in $customerList )
+    &lt;tr&gt;&lt;td&gt;$velocityCount&lt;/td&gt;&lt;td&gt;$customer.Name&lt;/td&gt;&lt;/tr&gt;
+#end
+&lt;/table&gt;
+</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 &gt; 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( &quot;one.txt&quot; )
+</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( &quot;one.gif&quot;,&quot;two.txt&quot;,&quot;three.htm&quot; )
+</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( &quot;greetings.txt&quot;, $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( &quot;me.vm&quot; )
+</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( &quot;parsefoo.vm&quot; )
+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 &gt; 0 )
+    #parse( &quot;parsefoo.vm&quot; )
+#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 = &quot;abc&quot;)
+#set($select = &quot;1&quot;)
+#set($dynamicsource = &quot;$source$select&quot;)
+## $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 )
+&lt;tr&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;
+#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 )
+    &lt;tr&gt;&lt;td bgcolor=$color&gt;$something&lt;/td&gt;&lt;/tr&gt;
+#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 = [&quot;Superior&quot;,&quot;Michigan&quot;,&quot;Huron&quot;,&quot;Erie&quot;,&quot;Ontario&quot;] )
+#set( $color = &quot;blue&quot; )
+&lt;table&gt;
+    #tablerows( $color $greatlakes )
+&lt;/table&gt;
+</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">
+&lt;table&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Superior&lt;/td&gt;&lt;/tr&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Michigan&lt;/td&gt;&lt;/tr&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Huron&lt;/td&gt;&lt;/tr&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Erie&lt;/td&gt;&lt;/tr&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Ontario&lt;/td&gt;&lt;/tr&gt;
+&lt;/table&gt;
+</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 = [&quot;volva&quot;,&quot;stipe&quot;,&quot;annulus&quot;,&quot;gills&quot;,&quot;pileus&quot;] )
+#set( $cellbgcol = &quot;#CC00FF&quot; )
+&lt;table&gt;
+#tablerows( $cellbgcol $parts )
+&lt;/table&gt;
+</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">
+&lt;table&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;volva&lt;/td&gt;&lt;/tr&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;stipe&lt;/td&gt;&lt;/tr&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;annulus&lt;/td&gt;&lt;/tr&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;gills&lt;/td&gt;&lt;/tr&gt;
+    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;pileus&lt;/td&gt;&lt;/tr&gt;
+&lt;/table&gt;
+</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 = &quot;foo&quot; )
+$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 = &quot;foo&quot; )
+$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 = &quot;foo&quot; )
+\\$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 = &quot;gibbous&quot; )
+$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( &quot;a.txt&quot; ) renders as &lt;contents of a.txt&gt;
+#include( &quot;a.txt&quot; )
+
+## \#include( &quot;a.txt&quot; ) renders as #include( &quot;a.txt&quot; )
+\#include( &quot;a.txt&quot; )
+
+## \\#include ( &quot;a.txt&quot; ) renders as \&lt;contents of a.txt&gt;
+\\#include ( &quot;a.txt&quot; )
+</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 = [&quot;Munetaka&quot;,&quot;Koreyasu&quot;,&quot;Hisakira&quot;,&quot;Morikune&quot;] )
+#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=[&quot;$10 and &quot;,&quot;a pie&quot;])#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 = [&quot;$10 and &quot;,&quot;a pie&quot;] )
+#foreach( $a in $foo )
+$a
+#end
+please.
+</pre></div>
+																			<p>
+    or as
+    </p>
+																			<div class="source">
+Send me
+#set($foo       = [&quot;$10 and &quot;,&quot;a pie&quot;])
+                 #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 = &quot;bar&quot; )
+$\!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 = &quot;#bold('hello')&quot; )
+#center( $stuff )
+</pre></div>
+												<p>
+You can save a step...
+</p>
+												<div class="source">
+#center( &quot;#bold( 'hello' )&quot; )
+</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 = &quot;outerlala&quot;)
+   outer : $foo
+#end
+
+#set($bar = 'calltimelala')
+#outer( &quot;#inner($bar)&quot; )
+
+</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 )
+  &lt;tr bgcolor=$color&gt;&lt;td&gt;Hi&lt;/td&gt;&lt;/tr&gt;
+  &lt;tr bgcolor=$color&gt;&lt;td&gt;There&lt;/td&gt;&lt;/tr&gt;
+#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>&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>
+												<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 ...]


Mime
View raw message