# click-commits mailing list archives

##### Site index · List index
Message view
Top
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 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
+ 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
+
+
+ Unless required by applicable law or agreed to in writing,
+ "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
+-->
+
+<!-- start the processing -->
+    <!-- ====================================================================== -->
+    <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+    <!-- Main Page Section -->
+    <!-- ====================================================================== -->
+    <html>
+            <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>
+
+
+        <body>
+
+
+			<div id="container">
+
+				<div id="body">
+																	<a name="user_guide_-_contents"></a>
+	<h1>User Guide - Contents</h1>
+
+	<div class="subsection">
+														<ol>
+			<li>
+					</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>
+					</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>
+					</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>
+
+	<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
+    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
+   </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>
+
+	<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
+ </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>
+    </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
+   </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>
+    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>
+    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
+</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>
+    </p>
+												<p>
+   There is a property, meant to be used in <i>development</i>,
+   not production :
+  </p>
+												<p>
+  </p>
+												<p>
+   which defaults to false.  When set to true <em>along with</em>
+   </p>
+												<p>
+   </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
+    </p>
+												<p>
+    Here is what a simple set of configuration properties would look like.
+    </p>
+												<div class="source">
+    </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