| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <!-- start the processing --> |
| <!-- ====================================================================== --> |
| <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! --> |
| <!-- Main Page Section --> |
| <!-- ====================================================================== --> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/> |
| |
| <meta name="author" value="Velocity Documentation Team"> |
| <meta name="email" value="dev@velocity.apache.org"> |
| |
| |
| |
| |
| <title>Velocity - Velocity User Guide</title> |
| |
| <link rel="stylesheet" href="./site.css" type="text/css"> |
| </head> |
| |
| <body> |
| |
| |
| <div id="container"> |
| |
| <div id="body"> |
| <a name="user_guide_-_contents"></a> |
| <h1>User Guide - Contents</h1> |
| |
| <div class="subsection"> |
| <ol> |
| <li> |
| <a href="#about_this_guide">About this Guide</a> |
| </li> |
| <li> |
| <a href="#what_is_velocity">What is Velocity?</a> |
| </li> |
| <li> |
| <a href="#what_can_velocity_do_for_me">What can Velocity do for me?</a> |
| |
| |
| <ol> |
| <li> |
| <a href="#the_mud_store_example">The Mud Store example</a> |
| </li> |
| </ol> |
| |
| |
| </li> |
| <li> |
| <a href="#velocity_template_language_vtl:_an_introduction">Velocity Template Language (VTL): An Introduction</a> |
| </li> |
| <li> |
| <a href="#hello_velocity_world">Hello Velocity World!</a> |
| </li> |
| <li> |
| <a href="#comments">Comments</a> |
| </li> |
| <li> |
| <a href="#references">References</a> |
| |
| |
| <ol> |
| <li> |
| <a href="#variables">Variables</a> |
| </li> |
| <li> |
| <a href="#properties">Properties</a> |
| </li> |
| <li> |
| <a href="#methods">Methods</a> |
| </li> |
| <li> |
| <a href="#propertylookuprules">Property Lookup Rules</a> |
| </li> |
| <li> |
| <a href="#rendering">Rendering</a> |
| </li> |
| </ol> |
| |
| |
| </li> |
| <li> |
| <a href="#formalreferencenotation">Formal Reference Notation</a> |
| </li> |
| <li> |
| <a href="#quietreferencenotation">Quiet Reference Notation</a> |
| </li> |
| <li> |
| <a href="#strictreferences">Strict References Setting</a> |
| </li> |
| <li> |
| <a href="#case_substitution">Case Substitution</a> |
| </li> |
| <li> |
| <a href="#directives">Directives</a> |
| |
| |
| <ol> |
| <li> |
| <a href="#set">Set</a> |
| </li> |
| <li> |
| <a href="#stringliterals">Literals</a> |
| </li> |
| <li> |
| <a href="#conditionals">If-Else Statements</a> |
| |
| |
| <ol> |
| <li> |
| <a href="#relationalandlogicaloperators">Relational and Logical
|
| Operators</a> |
| </li> |
| </ol> |
| |
| |
| </li> |
| <li> |
| <a href="#loops">Foreach Loops</a> |
| </li> |
| <li> |
| <a href="#include">Include</a> |
| </li> |
| <li> |
| <a href="#parse">Parse</a> |
| </li> |
| <li> |
| <a href="#stop">Stop</a> |
| </li> |
| <li> |
| <a href="#evaluate">Evaluate</a> |
| </li> |
| <li> |
| <a href="#define">Define</a> |
| </li> |
| <li> |
| <a href="#velocimacros">Velocimacros</a> |
| </li> |
| </ol> |
| |
| |
| </li> |
| <li> |
| <a href="#getting_literal">Getting literal</a> |
| |
| |
| <ol> |
| <li> |
| <a href="#currency">Currency</a> |
| </li> |
| <li> |
| <a href="#escapingvalidvtlreferences">Escaping Valid VTL References</a> |
| </li> |
| <li> |
| <a href="#escapinginvalidvtlreferences">Escaping Invalid VTL References</a> |
| </li> |
| <li> |
| <a href="#escaping_vtl_directives">Escaping VTL Directives</a> |
| </li> |
| </ol> |
| |
| |
| </li> |
| <li> |
| <a href="#vtl:_formatting_issues">VTL: Formatting Issues</a> |
| </li> |
| <li> |
| <a href="#other_features_and_miscellany">Other Features and Miscellany</a> |
| |
| |
| <ol> |
| <li> |
| <a href="#math">Math</a> |
| </li> |
| <li> |
| <a href="#range_operator">Range Operator</a> |
| </li> |
| <li> |
| <a href="#advanced_issues:_escaping_and_">Advanced Issues: Escaping and
|
| !</a> |
| </li> |
| <li> |
| <a href="#velocimacro_miscellany">Velocimacro Miscellany</a> |
| </li> |
| <li> |
| <a href="#string_concatenation">String Concatenation</a> |
| </li> |
| </ol> |
| |
| |
| </li> |
| <li> |
| <a href="#feedback">Feedback</a> |
| </li> |
| </ol> |
| </div> |
| <a name="about_this_guide"></a> |
| <h1>About this Guide</h1> |
| |
| <div class="subsection"> |
| <p>
|
| The Velocity User Guide is intended to help page designers and
|
| content providers get acquainted with Velocity and the syntax of its
|
| simple yet powerful scripting language, the Velocity Template
|
| Language (VTL). Many of the examples in this guide deal with using
|
| Velocity to embed dynamic content in web sites, but all VTL examples
|
| are equally applicable to other pages and templates.
|
| </p> |
| <p>
|
| Thanks for choosing Velocity!
|
| </p> |
| </div> |
| <a name="what_is_velocity"></a> |
| <h1>What is Velocity?</h1> |
| |
| <div class="subsection"> |
| <p>
|
| Velocity is a Java-based template engine. It permits web page
|
| designers to reference methods defined in Java code. Web designers
|
| can work in parallel with Java programmers to develop web sites
|
| according to the Model-View-Controller (MVC) model, meaning that web
|
| page designers can focus solely on creating a well-designed site,
|
| and programmers can focus solely on writing top-notch code. Velocity
|
| separates Java code from the web pages, making the web site more
|
| maintainable over the long run and providing a viable alternative to
|
| <a href="http://java.sun.com/products/jsp/">Java Server Pages</a>
|
| (JSPs) or <a href="http://www.php.net/">PHP</a>.
|
| </p> |
| <p>
|
| Velocity can be used to generate web pages, SQL, PostScript and
|
| other output from templates. It can be used either as a standalone
|
| utility for generating source code and reports, or as an integrated
|
| component of other systems. When complete, Velocity will provide
|
| template services for the <a href="http://java.apache.org/turbine/">Turbine</a> web application
|
| framework. Velocity+Turbine will provide a template service that
|
| will allow web applications to be developed according to a true MVC
|
| model.
|
| </p> |
| </div> |
| <a name="what_can_velocity_do_for_me"></a> |
| <h1>What can Velocity do for me?</h1> |
| |
| <div class="subsection"> |
| <a name="the_mud_store_example"></a> |
| <h2>The Mud Store Example</h2> |
| <div class="subsection"> |
| <p>
|
| Suppose you are a page designer for an online store that specializes
|
| in selling mud. Let's call it "The Online Mud Store". Business is
|
| thriving. Customers place orders for various types and quantities of
|
| mud. They login to your site using their username and password,
|
| which allows them to view their orders and buy more mud. Right now,
|
| Terracotta Mud is on sale, which is very popular. A minority of your
|
| customers regularly buys Bright Red Mud, which is also on sale,
|
| though not as popular and usually relegated to the margin of your
|
| web page. Information about each customer is tracked in your
|
| database, so one day the question arises, Why not use Velocity to
|
| target special deals on mud to the customers who are most interested
|
| in those types of mud?
|
| </p> |
| <p>
|
| Velocity makes it easy to customize web pages to your online
|
| visitors. As a web site designer at The Mud Room, you want to make
|
| the web page that the customer will see after logging into your
|
| site.
|
| </p> |
| <p>
|
| You meet with software engineers at your company, and everyone has
|
| agreed that <em>$customer</em> will hold information pertaining to
|
| the customer currently logged in, that <em>$mudsOnSpecial</em> will
|
| be all the types mud on sale at present. The <em>$flogger</em>
|
| object contains methods that help with promotion. For the task at
|
| hand, let's concern ourselves only with these three references.
|
| Remember, you don't need to worry about how the software engineers
|
| extract the necessary information from the database, you just need
|
| to know that it works. This lets you get on with your job, and lets
|
| the software engineers get on with theirs.
|
| </p> |
| <p>
|
| You could embed the following VTL statement in the web page:
|
| </p> |
| <div class="source">
|
| <HTML>
|
| <BODY>
|
| Hello $customer.Name!
|
| <table>
|
| #foreach( $mud in $mudsOnSpecial )
|
| #if ( $customer.hasPurchased($mud) )
|
| <tr>
|
| <td>
|
| $flogger.getPromo( $mud )
|
| </td>
|
| </tr>
|
| #end
|
| #end
|
| </table>
|
| </pre></div> |
| <p>
|
| The exact details of the <em>foreach</em> statement will be
|
| described in greater depth shortly; what's important is the impact
|
| this short script can have on your web site. When a customer with a
|
| penchant for Bright Red Mud logs in, and Bright Red Mud is on sale,
|
| that is what this customer will see, prominently displayed. If
|
| another customer with a long history of Terracotta Mud purchases
|
| logs in, the notice of a Terracotta Mud sale will be front and
|
| center. The flexibility of Velocity is enormous and limited only by
|
| your creativity.
|
| </p> |
| <p>
|
| Documented in the VTL Reference are the many other Velocity
|
| elements, which collectively give you the power and flexibility you
|
| need to make your web site a web <em>presence</em>. As you get more
|
| familiar with these elements, you will begin to unleash the power of
|
| Velocity.
|
| </p> |
| </div> |
| </div> |
| <a name="velocity_template_language_vtl:_an_introduction"></a> |
| <h1>Velocity Template Language (VTL): An Introduction</h1> |
| |
| <div class="subsection"> |
| <p>
|
| The Velocity Template Language (VTL) is meant to provide the
|
| easiest, simplest, and cleanest way to incorporate dynamic content
|
| in a web page. Even a web page developer with little or no
|
| programming experience should soon be capable of using VTL to
|
| incorporate dynamic content in a web site.
|
| </p> |
| <p>
|
| VTL uses <em>references</em> to embed dynamic content in a web site,
|
| and a variable is one type of reference. Variables are one type of
|
| reference that can refer to something defined in the Java code, or
|
| it can get its value from a VTL <em>statement</em> in the web page
|
| itself. Here is an example of a VTL statement that could be embedded
|
| in an HTML document:
|
| </p> |
| <div class="source">
|
| #set( $a = "Velocity" )
|
| </pre></div> |
| <p>
|
| This VTL statement, like all VTL statements, begins with the
|
| <em>#</em> character and contains a directive: <em>set</em>. When an
|
| online visitor requests your web page, the Velocity Templating
|
| Engine will search through your web page to find all <em>#</em>
|
| characters, then determine which mark the beginning of VTL
|
| statements, and which of the <em>#</em> characters that have nothing
|
| to do with VTL.
|
| </p> |
| <p>
|
| The <em>#</em> character is followed by a directive, <em>set</em>.
|
| The <em>set</em> directive uses an expression (enclosed in brackets)
|
| -- an equation that assigns a <em>value</em> to a <em>variable</em>.
|
| The variable is listed on the left hand side and its value on the
|
| right hand side; the two are separated by an <em>=</em> character.
|
| </p> |
| <p>
|
| In the example above, the variable is <em>$a</em> and the value is
|
| <em>Velocity</em>. This variable, like all references, begins with
|
| the <em>$</em> character. String values are always enclosed in quotes, either
|
| single or double quotes. Single quotes will ensure that the quoted value
|
| will be assigned to the reference as is. Double quotes allow you to use
|
| velocity references and directives to interpolate, such as "Hello $name",
|
| where the <em>$name</em> will be replaced by the current value before
|
| that string literal is assigned to the left hand side of the <em>=</em>
|
| </p> |
| <p>
|
| The following rule of thumb may be useful to better understand how
|
| Velocity works: <strong>References begin with <em>$</em> and are
|
| used to get something. Directives begin with <em>#</em> and are used
|
| to do something.</strong>
|
| </p> |
| <p>
|
| In the example above, <em>#set</em> is used to assign a value to a
|
| variable. The variable, <em>$a</em>, can then be used in the
|
| template to output "Velocity".
|
| </p> |
| </div> |
| <a name="hello_velocity_world"></a> |
| <h1>Hello Velocity World!</h1> |
| |
| <div class="subsection"> |
| <p>
|
| Once a value has been assigned to a variable, you can reference the
|
| variable anywhere in your HTML document. In the following example, a
|
| value is assigned to <em>$foo</em> and later referenced.
|
| </p> |
| <div class="source">
|
| <html>
|
| <body>
|
| #set( $foo = "Velocity" )
|
| Hello $foo World!
|
| </body>
|
| <html>
|
| </pre></div> |
| <p>
|
| The result is a web page that prints "Hello Velocity World!".
|
| </p> |
| <p>
|
| To make statements containing VTL directives more readable, we
|
| encourage you to start each VTL statement on a new line, although
|
| you are not required to do so. The <em>set</em> directive will be
|
| revisited in greater detail later on.
|
| </p> |
| </div> |
| <a name="comments"></a> |
| <h1>Comments</h1> |
| |
| <div class="subsection"> |
| <p>
|
| Comments allows descriptive text to be included that is not placed
|
| into the output of the template engine. Comments are a useful way of
|
| reminding yourself and explaining to others what your VTL statements
|
| are doing, or any other purpose you find useful. Below is an example
|
| of a comment in VTL.
|
| </p> |
| <div class="source">
|
| ## This is a single line comment.
|
| </pre></div> |
| <p>
|
| A single line comment begins with <em>##</em> and finishes at the
|
| end of the line. If you're going to write a few lines of commentary,
|
| there's no need to have numerous single line comments. Multi-line
|
| comments, which begin with <em>#*</em> and end with <em>*#</em>, are
|
| available to handle this scenario.
|
| </p> |
| <div class="source">
|
| This is text that is outside the multi-line comment.
|
| Online visitors can see it.
|
|
|
| #*
|
| Thus begins a multi-line comment. Online visitors won't
|
| see this text because the Velocity Templating Engine will
|
| ignore it.
|
| *#
|
|
|
| Here is text outside the multi-line comment; it is visible.
|
| </pre></div> |
| <p>
|
| Here are a few examples to clarify how single line and multi-line
|
| comments work:
|
| </p> |
| <div class="source">
|
| This text is visible. ## This text is not.
|
| This text is visible.
|
| This text is visible. #* This text, as part of a multi-line
|
| comment, is not visible. This text is not visible; it is also
|
| part of the multi-line comment. This text still not
|
| visible. *# This text is outside the comment, so it is visible.
|
| ## This text is not visible.
|
| </pre></div> |
| <p>
|
| There is a third type of comment, the VTL comment block, which may
|
| be used to store any sort of extra information you want to track
|
| in the template (e.g. javadoc-style author and versioning information):
|
| </p> |
| <div class="source">
|
| #**
|
| This is a VTL comment block and
|
| may be used to store such information
|
| as the document author and versioning
|
| information:
|
| @author
|
| @version 5
|
| *#
|
| </pre></div> |
| </div> |
| <a name="references"></a> |
| <h1>References</h1> |
| |
| <div class="subsection"> |
| <p>
|
| There are three types of references in the VTL: variables,
|
| properties and methods. As a designer using the VTL, you and your
|
| engineers must come to an agreement on the specific names of
|
| references so you can use them correctly in your templates.
|
| </p> |
| <p>
|
| <a name="variables"><strong>Variables</strong></a>
|
| <br />
|
| The shorthand notation of a variable consists of a leading "$"
|
| character followed by a VTL <em>Identifier</em>. A VTL Identifier
|
| must start with an alphabetic character (a .. z or A .. Z). The rest
|
| of the characters are limited to the following types of characters:
|
| </p> |
| <p>
|
| <ul>
|
| <li>alphabetic (a .. z, A .. Z)</li>
|
| <li>numeric (0 .. 9)</li>
|
| <li>hyphen ("-")</li>
|
| <li>underscore ("_")</li>
|
| </ul>
|
| </p> |
| <p>
|
| Here are some examples of valid variable references in the VTL:
|
| </p> |
| <div class="source">
|
| $foo
|
| $mudSlinger
|
| $mud-slinger
|
| $mud_slinger
|
| $mudSlinger1
|
| </pre></div> |
| <p>
|
| When VTL references a variable, such as <em>$foo</em>, the variable
|
| can get its value from either a <em>set</em> directive in the
|
| template, or from the Java code. For example, if the Java variable
|
| <em>$foo</em> has the value <em>bar</em> at the time the template is
|
| requested, <em>bar</em> replaces all instances of <em>$foo</em> on
|
| the web page. Alternatively, if I include the statement
|
| </p> |
| <div class="source">
|
| #set( $foo = "bar" )
|
| </pre></div> |
| <p>
|
| The output will be the same for all instances of <em>$foo</em> that
|
| follow this directive.
|
| </p> |
| <p>
|
| <a name="properties"><strong>Properties</strong></a>
|
| <br />
|
| The second flavor of VTL references are properties, and properties
|
| have a distinctive format. The shorthand notation consists of a
|
| leading <em>$</em> character followed a VTL Identifier, followed by
|
| a dot character (".") and another VTL Identifier. These are examples
|
| of valid property references in the VTL:
|
| </p> |
| <div class="source">
|
| $customer.Address
|
| $purchase.Total
|
| </pre></div> |
| <p>
|
| Take the first example, <em>$customer.Address</em>. It can have two
|
| meanings. It can mean, Look in the hashtable identified as
|
| <em>customer</em> and return the value associated with the key
|
| <em>Address</em>. But <em>$customer.Address</em> can also be
|
| referring to a method (references that refer to methods will be
|
| discussed in the next section); <em>$customer.Address</em> could be
|
| an abbreviated way of writing <em>$customer.getAddress()</em>. When
|
| your page is requested, Velocity will determine which of these two
|
| possibilities makes sense, and then return the appropriate value.
|
| </p> |
| <p>
|
| <a name="methods"><strong>Methods</strong></a>
|
| <br />
|
| A method is defined in the Java code and is capable of doing
|
| something useful, like running a calculation or arriving at a
|
| decision. Methods are references that consist of a leading "$"
|
| character followed a VTL Identifier, followed by a VTL <em>Method
|
| Body</em>. A VTL Method Body consists of a VTL Identifier followed
|
| by an left parenthesis character ("("), followed by an optional
|
| parameter list, followed by right parenthesis character (")"). These
|
| are examples of valid method references in the VTL:
|
| </p> |
| <div class="source">
|
| $customer.getAddress()
|
| $purchase.getTotal()
|
| $page.setTitle( "My Home Page" )
|
| $person.setAttributes( ["Strange", "Weird", "Excited"] )
|
| </pre></div> |
| <p>
|
| The first two examples -- <em>$customer.getAddress()</em> and
|
| <em>$purchase.getTotal()</em> -- may look similar to those used in
|
| the Properties section above, <em>$customer.Address</em> and
|
| <em>$purchase.Total</em>. If you guessed that these examples must be
|
| related some in some fashion, you are correct!
|
| </p> |
| <p>
|
| VTL Properties can be used as a shorthand notation for VTL Methods.
|
| The Property <em>$customer.Address</em> has the exact same effect as
|
| using the Method <em>$customer.getAddress()</em>. It is generally
|
| preferable to use a Property when available. The main difference
|
| between Properties and Methods is that you can specify a parameter
|
| list to a Method.
|
| </p> |
| <p>
|
| The shorthand notation can be used for the following Methods
|
| </p> |
| <div class="source">
|
| $sun.getPlanets()
|
| $annelid.getDirt()
|
| $album.getPhoto()
|
| </pre></div> |
| <p>
|
| We might expect these methods to return the names of planets
|
| belonging to the sun, feed our earthworm, or get a photograph from
|
| an album. Only the long notation works for the following Methods.
|
| </p> |
| <div class="source">
|
| $sun.getPlanet( ["Earth", "Mars", "Neptune"] )
|
| ## Can't pass a parameter list with $sun.Planets
|
|
|
| $sisyphus.pushRock()
|
| ## Velocity assumes I mean $sisyphus.getRock()
|
|
|
| $book.setTitle( "Homage to Catalonia" )
|
| ## Can't pass a parameter
|
| </pre></div> |
| <p>
|
| As of Velocity 1.6, all array references are now "magically" treated as if
|
| they are fixed-length lists. This means that you can call java.util.List methods
|
| on array references. So, if you have a reference to an array (let's say
|
| this one is a String[] with three values), you can do:
|
| </p> |
| <div class="source">
|
| $myarray.isEmpty()
|
|
|
| $myarray.size()
|
|
|
| $myarray.get(2)
|
|
|
| $myarray.set(1, 'test')
|
| </pre></div> |
| <p>
|
| Also new in Velocity 1.6 is support for vararg methods. A method like
|
| <code>public void setPlanets(String... planets)</code> or even just
|
| <code>public void setPlanets(String[] planets)</code> (if you are
|
| using a pre-Java 5 JDK), can now accept
|
| any number of arguments when called in a template.
|
| </p> |
| <div class="source">
|
| $sun.setPlanets('Earth', 'Mars', 'Neptune')
|
|
|
| $sun.setPlanets('Mercury')
|
|
|
| $sun.setPlanets()
|
| ## Will just pass in an empty, zero-length array
|
| </pre></div> |
| <p>
|
| <a name="propertylookuprules"><strong>Property Lookup Rules</strong></a>
|
| <br />
|
| As was mentioned earlier, properties often refer to methods of the
|
| parent object. Velocity is quite clever when figuring out which method
|
| corresponds to a requested property. It tries out different alternatives
|
| based on several established naming conventions. The exact lookup
|
| sequence depends on whether or not the property name starts with
|
| an upper-case letter. For lower-case names, such as
|
| <em>$customer.address</em>, the sequence is
|
| <ol>
|
| <li>getaddress()</li>
|
| <li>getAddress()</li>
|
| <li>get("address")</li>
|
| <li>isAddress()</li>
|
| </ol>
|
| For upper-case property names like <em>$customer.Address</em>, it is
|
| slightly different:
|
| <ol>
|
| <li>getAddress()</li>
|
| <li>getaddress()</li>
|
| <li>get("Address")</li>
|
| <li>isAddress()</li>
|
| </ol>
|
| </p> |
| <p>
|
| <a name="rendering"><strong>Rendering</strong></a>
|
| <br />
|
| The final value resulting from each and every reference (whether variable,
|
| property, or method) is converted to a String object when it is rendered
|
| into the final output. If there is an object that represents <em>$foo</em>
|
| (such as an Integer object), then Velocity will call its
|
| <code>.toString()</code> method to resolve the object into a String.
|
| </p> |
| <p>
|
| <a name="formalreferencenotation"><strong>Formal Reference Notation</strong></a>
|
| <br />
|
| Shorthand notation for references was used for the examples listed
|
| above, but there is also a formal notation for references, which is
|
| demonstrated below:
|
| </p> |
| <div class="source">
|
| ${mudSlinger}
|
| ${customer.Address}
|
| ${purchase.getTotal()}
|
| </pre></div> |
| <p>
|
| In almost all cases you will use the shorthand notation for
|
| references, but in some cases the formal notation is required for
|
| correct processing.
|
| </p> |
| <p>
|
| Suppose you were constructing a sentence on the fly where
|
| <em>$vice</em> was to be used as the base word in the noun of a
|
| sentence. The goal is to allow someone to choose the base word and
|
| produce one of the two following results: "Jack is a pyromaniac." or
|
| "Jack is a kleptomaniac.". Using the shorthand notation would be
|
| inadequate for this task. Consider the following example:
|
| </p> |
| <div class="source">
|
| Jack is a $vicemaniac.
|
| </pre></div> |
| <p>
|
| There is ambiguity here, and Velocity assumes that
|
| <em>$vicemaniac</em>, not <em>$vice</em>, is the Identifier that you
|
| mean to use. Finding no value for <em>$vicemaniac</em>, it will
|
| return <em>$vicemaniac</em>. Using formal notation can resolve this
|
| problem.
|
| </p> |
| <div class="source">
|
| Jack is a ${vice}maniac.
|
| </pre></div> |
| <p>
|
| Now Velocity knows that <em>$vice</em>, not <em>$vicemaniac</em>, is
|
| the reference. Formal notation is often useful when references are
|
| directly adjacent to text in a template.
|
| </p> |
| <p>
|
| <a name="quietreferencenotation"><strong>Quiet Reference Notation</strong></a>
|
| <br />
|
| When Velocity encounters an undefined reference, its normal behavior
|
| is to output the image of the reference. For example, suppose the
|
| following reference appears as part of a VTL template.
|
| </p> |
| <div class="source">
|
| <input type="text" name="email" value="$email"/>
|
| </pre></div> |
| <p>
|
| When the form initially loads, the variable reference
|
| <em>$email</em> has no value, but you prefer a blank text field to
|
| one with a value of "$email". Using the quiet reference notation
|
| circumvents Velocity's normal behavior; instead of using
|
| <em>$email</em> in the VTL you would use <em>$!email</em>. So the
|
| above example would look like the following:
|
| </p> |
| <div class="source">
|
| <input type="text" name="email" value="$!email"/>
|
| </pre></div> |
| <p>
|
| Now when the form is initially loaded and <em>$email</em> still has
|
| no value, an empty string will be output instead of "$email".
|
| </p> |
| <p>
|
| Formal and quiet reference notation can be used together, as
|
| demonstrated below.
|
| </p> |
| <div class="source">
|
| <input type="text" name="email" value="$!{email}"/>
|
| </pre></div> |
| </div> |
| <a name="strictreferences"></a> |
| <h1>Strict References Setting</h1> |
| |
| <div class="subsection"> |
| <p>
|
| Velocity 1.6 introduces the concept of strict reference mode which
|
| is activated by setting the velocity configuration property
|
| 'runtime.references.strict' to true. The general intent of this
|
| setting is to make Velocity behave more strictly in cases that are
|
| undefined or ambiguous, similar to a programming language, which
|
| may be more appropriate for some uses of Velocity. In such
|
| undefined or ambiguous cases Velocity will throw an exception. The
|
| following discussion outlines the cases that strict behavior is
|
| different from traditional behavior.
|
| </p> |
| <p>
|
| With this setting references are required to be either placed
|
| explicitly into the context or defined with a #set directive, or
|
| Velocity will throw an exception. References that are in the
|
| context with a value of null will not produce an exception.
|
| Additionally, if an attempt is made to call a method or a property
|
| on an object within a reference that does not define the specified
|
| method or property then Velocity will throw an exception. This is
|
| also true if there is an attempt to call a method or property on a
|
| null value.
|
| </p> |
| <p>
|
| In the following examples $bar is defined but $foo is not, and all
|
| these statements will throw an exception:
|
| </p> |
| <div class="source">$foo ## Exception
|
| #set($bar = $foo) ## Exception
|
| #if($foo == $bar)#end ## Exception
|
| #foreach($item in $foo)#end ## Exception</pre></div> |
| <p>
|
| Also, The following statements show examples in which Velocity will
|
| throw an exception when attempting to call methods or properties
|
| that do not exist. In these examples $bar contains an object that
|
| defines a property 'foo' which returns a string, and 'retnull' which
|
| returns null.
|
| </p> |
| <div class="source">$bar.bogus ## $bar does not provide property bogus, Exception
|
| $bar.foo.bogus ## $bar.foo does not provide property bogus, Exception
|
| $bar.retnull.bogus ## cannot call a property on null, Exception</pre></div> |
| <p>
|
| In general strict reference behavior is true for all situations
|
| in which references are used except for a special case within the
|
| #if directive. If a reference is used within a #if or #elseif directive
|
| without any methods or properties, and if it is not being compared
|
| to another value, then undefined references are allowed. This
|
| behavior provides an easy way to test if a reference is defined
|
| before using it in a template. In the following example where
|
| $foo is not defined the statements will not throw an exception.
|
| </p> |
| <div class="source">#if ($foo)#end ## False
|
| #if ( ! $foo)#end ## True
|
| #if ($foo && $foo.bar)#end ## False and $foo.bar will not be evaluated
|
| #if ($foo && $foo == "bar")#end ## False and $foo == "bar" wil not be evaluated
|
| #if ($foo1 || $foo2)#end ## False $foo1 and $foo2 are not defined</pre></div> |
| <p>
|
| Strict mode requires that comparisons of <, >, >= or <= within an
|
| #if directive make sense. Also, the argument to #foreach must be
|
| iterable (this behavior can be modified with the property
|
| directive.foreach.skip.invalid). Finally, undefined macro
|
| references will also throw an exception in strict mode.
|
| </p> |
| </div> |
| <a name="case_substitution"></a> |
| <h1>Case Substitution</h1> |
| |
| <div class="subsection"> |
| <p>
|
| Now that you are familiar with references, you can begin to apply
|
| them effectively in your templates. Velocity references take
|
| advantage of some Java principles that template designers will find
|
| easy to use. For example:
|
| </p> |
| <div class="source">
|
| $foo
|
|
|
| $foo.getBar()
|
| ## is the same as
|
| $foo.Bar
|
|
|
| $data.setUser("jon")
|
| ## is the same as
|
| #set( $data.User = "jon" )
|
|
|
| $data.getRequest().getServerName()
|
| ## is the same as
|
| $data.Request.ServerName
|
| ## is the same as
|
| ${data.Request.ServerName}
|
| </pre></div> |
| <p>
|
| These examples illustrate alternative uses for the same references.
|
| Velocity takes advantage of Java's introspection and bean features
|
| to resolve the reference names to both objects in the Context as
|
| well as the objects methods. It is possible to embed and evaluate
|
| references almost anywhere in your template.
|
| </p> |
| <p>
|
| Velocity, which is modelled on the Bean specifications defined by
|
| Sun Microsystems, is case sensitive; however, its developers have
|
| strove to catch and correct user errors wherever possible.
|
| When the method <em>getFoo()</em> is referred to in a template
|
| by <code>$bar.foo</code>, Velocity will first try <code>$getfoo</code>.
|
| If this fails, it will then try <code>$getFoo</code>.
|
| Similarly, when a template refers to <code>$bar.Foo</code>, Velocity
|
| will try <em>$getFoo()</em> first and then try <em>getfoo()</em>.
|
| </p> |
| <p>
|
| Note: <em>References to instance variables in a template are not
|
| resolved.</em> Only references to the attribute equivalents of
|
| JavaBean getter/setter methods are resolved
|
| (i.e. <code>$foo.Name</code> does resolve to the class Foo's
|
| <code>getName()</code> instance method, but not to a public
|
| <code>Name</code> instance variable of Foo).
|
| </p> |
| </div> |
| <a name="directives"></a> |
| <h1>Directives</h1> |
| |
| <div class="subsection"> |
| <p>
|
| References allow template designers to generate dynamic content for
|
| web sites, while <em>directives</em> -- easy to use script elements
|
| that can be used to creatively manipulate the output of Java code --
|
| permit web designers to truly take charge of the appearance and
|
| content of the web site.
|
| </p> |
| <p>
|
| Directives always begin with a <code>#</code>. Like references, the name of the directive may be
|
| bracketed by a <code>{</code> and a <code>}</code> symbol. This is useful with directives
|
| that are immediately followed by text. For example the following produces an error:
|
| </p> |
| <div class="source">
|
| #if($a==1)true enough#elseno way!#end
|
| </pre></div> |
| <p>
|
| In such a case, use the brackets to separate <code>#else</code> from the rest of the line.
|
| </p> |
| <div class="source">
|
| #if($a==1)true enough#{else}no way!#end
|
| </pre></div> |
| <p> </p> |
| <a name="set"><strong>#set</strong></a> |
| <p>
|
| The <em>#set</em> directive is used for setting the value of a
|
| reference. A value can be assigned to either a variable reference or
|
| a property reference, and this occurs in brackets, as demonstrated:
|
| </p> |
| <div class="source">
|
| #set( $primate = "monkey" )
|
| #set( $customer.Behavior = $primate )
|
| </pre></div> |
| <p>
|
| The left hand side (LHS) of the assignment must be a variable
|
| reference or a property reference. The right hand side (RHS) can be
|
| one of the following types:
|
| </p> |
| <p>
|
| <ul>
|
| <li>Variable reference</li>
|
| <li>String literal</li>
|
| <li>Property reference</li>
|
| <li>Method reference</li>
|
| <li>Number literal</li>
|
| <li>ArrayList</li>
|
| <li>Map</li>
|
| </ul>
|
| </p> |
| <p>
|
| These examples demonstrate each of the aforementioned types:
|
| </p> |
| <div class="source">
|
| #set( $monkey = $bill ) ## variable reference
|
| #set( $monkey.Friend = "monica" ) ## string literal
|
| #set( $monkey.Blame = $whitehouse.Leak ) ## property reference
|
| #set( $monkey.Plan = $spindoctor.weave($web) ) ## method reference
|
| #set( $monkey.Number = 123 ) ##number literal
|
| #set( $monkey.Say = ["Not", $my, "fault"] ) ## ArrayList
|
| #set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"}) ## Map
|
| </pre></div> |
| <p>
|
| NOTE: For the ArrayList example the elements defined with the
|
| [..] operator are accessible using the methods defined
|
| in the ArrayList class. So, for example, you could access
|
| the first element above using $monkey.Say.get(0).
|
| </p> |
| <p>
|
| Similarly, for the Map example, the elements defined within the
|
| { } operator are accessible using the methods defined
|
| in the Map class. So, for example, you could access
|
| the first element above using $monkey.Map.get("banana") to return
|
| a String 'good', or even $monkey.Map.banana to return the
|
| same value.
|
| </p> |
| <p>
|
| The RHS can also be a simple arithmetic expression:
|
| </p> |
| <div class="source">
|
| #set( $value = $foo + 1 )
|
| #set( $value = $bar - 1 )
|
| #set( $value = $foo * $bar )
|
| #set( $value = $foo / $bar )
|
| </pre></div> |
| <p>
|
| If the RHS is a property or method reference that evaluates to
|
| <em>null</em>, it will <b>not</b> be assigned to the LHS.
|
| Depending on how Velocity is configured, it is usually not
|
| possible to remove an existing reference from the context via
|
| this mechanism.
|
| (Note that this can be permitted by changing one of the Velocity configuration properties).
|
| This can be confusing for
|
| newcomers to Velocity. For example:
|
| </p> |
| <div class="source">
|
| #set( $result = $query.criteria("name") )
|
| The result of the first query is $result
|
|
|
| #set( $result = $query.criteria("address") )
|
| The result of the second query is $result
|
| </pre></div> |
| <p>
|
| If <em>$query.criteria("name")</em> returns the string
|
| "bill", and <em>$query.criteria("address")</em> returns
|
| <em>null</em>, the above VTL will render as the following:
|
| </p> |
| <div class="source">
|
| The result of the first query is bill
|
|
|
| The result of the second query is bill
|
| </pre></div> |
| <p>
|
| This tends to confuse newcomers who construct <em>#foreach</em>
|
| loops that attempt to <em>#set</em> a reference via a property or
|
| method reference, then immediately test that reference with an
|
| <em>#if</em> directive. For example:
|
| </p> |
| <div class="source">
|
|
|
| #set( $criteria = ["name", "address"] )
|
|
|
| #foreach( $criterion in $criteria )
|
|
|
| #set( $result = $query.criteria($criterion) )
|
|
|
| #if( $result )
|
| Query was successful
|
| #end
|
|
|
| #end
|
| </pre></div> |
| <p>
|
| In the above example, it would not be wise to rely on the
|
| evaluation of <em>$result</em> to determine if a query was
|
| successful. After <em>$result</em> has been <em>#set</em> (added to
|
| the context), it cannot be set back to <em>null</em> (removed from
|
| the context). The details of the <em>#if</em> and <em>#foreach</em>
|
| directives are covered later in this document.
|
| </p> |
| <p>
|
| One solution to this would be to pre-set <em>$result</em>
|
| to <em>false</em>. Then if the <em>$query.criteria()</em>
|
| call fails, you can check.
|
| </p> |
| <div class="source">
|
|
|
| #set( $criteria = ["name", "address"] )
|
|
|
| #foreach( $criterion in $criteria )
|
|
|
| #set( $result = false )
|
| #set( $result = $query.criteria($criterion) )
|
|
|
| #if( $result )
|
| Query was successful
|
| #end
|
|
|
| #end
|
| </pre></div> |
| <p>
|
| Unlike some of the other Velocity directives, the <em>#set</em>
|
| directive does not have an <em>#end</em> statement.
|
| </p> |
| <a name="stringliterals"><strong>Literals</strong></a> |
| <p>
|
| When using the <em>#set</em> directive, string literals that are
|
| enclosed in double quote characters will be parsed and rendered, as
|
| shown:
|
| </p> |
| <div class="source">
|
| #set( $directoryRoot = "www" )
|
| #set( $templateName = "index.vm" )
|
| #set( $template = "$directoryRoot/$templateName" )
|
| $template
|
| </pre></div> |
| <p>
|
| The output will be
|
| </p> |
| <div class="source">
|
| www/index.vm
|
| </pre></div> |
| <p>
|
| However, when the string literal is enclosed in single quote
|
| characters, it will not be parsed:
|
| </p> |
| <div class="source">
|
| #set( $foo = "bar" )
|
| $foo
|
| #set( $blargh = '$foo' )
|
| $blargh
|
| </pre></div> |
| <div class="source">
|
| bar
|
| $foo
|
| </pre></div> |
| <p>
|
| By default, this feature of using single quotes to render unparsed
|
| text is available in Velocity. This default can be changed by
|
| editing <code>velocity.properties</code> such that
|
| <code>stringliterals.interpolate=false</code>.
|
| </p> |
| <p>
|
| Alternately, the <em>#literal</em> script element allows the
|
| template designer to easily use large chunks of uninterpreted
|
| content in VTL code. This can be especially useful in place of <a href="#EscapingVTLDirectives">escaping</a> multiple directives.
|
| </p> |
| <div class="source">
|
| #literal()
|
| #foreach ($woogie in $boogie)
|
| nothing will happen to $woogie
|
| #end
|
| #end
|
| </pre></div> |
| <p>
|
| Renders as:
|
| </p> |
| <div class="source">
|
| #foreach ($woogie in $boogie)
|
| nothing will happen to $woogie
|
| #end
|
| </pre></div> |
| </div> |
| <a name="conditionals"></a> |
| <h1>Conditionals</h1> |
| |
| <div class="subsection"> |
| <strong>If / ElseIf / Else</strong> |
| <p>
|
| The <em>#if</em> directive in Velocity allows for text to be
|
| included when the web page is generated, on the conditional that
|
| the if statement is true. For example:
|
| </p> |
| <div class="source">
|
| #if( $foo )
|
| <strong>Velocity!</strong>
|
| #end
|
| </pre></div> |
| <p>
|
| The variable <em>$foo</em> is evaluated to determine whether it is
|
| true, which will happen under one of two circumstances: (i)
|
| <em>$foo</em> is a boolean (true/false) which has a true value, or
|
| (ii) the value is not null. Remember that the Velocity context only
|
| contains Objects, so when we say 'boolean', it will be represented
|
| as a Boolean (the class). This is true even for methods that return
|
| <code>boolean</code> - the introspection infrastructure will return
|
| a <code>Boolean</code> of the same logical value.
|
| </p> |
| <p>
|
| The content between the <em>#if</em>
|
| and the <em>#end</em> statements become the output if the
|
| evaluation is true. In this case, if <em>$foo</em> is true, the
|
| output will be: "Velocity!". Conversely, if <em>$foo</em> has a
|
| null value, or if it is a boolean false, the statement evaluates
|
| as false, and there is no output.
|
| </p> |
| <p>
|
| An <em>#elseif</em> or <em>#else</em> element can be used with an
|
| <em>#if</em> element. Note that the Velocity Templating Engine
|
| will stop at the first expression that is found to be true. In the
|
| following example, suppose that <em>$foo</em> has a value of 15
|
| and <em>$bar</em> has a value of 6.
|
| </p> |
| <div class="source">
|
| #if( $foo < 10 )
|
| <strong>Go North</strong>
|
| #elseif( $foo == 10 )
|
| <strong>Go East</strong>
|
| #elseif( $bar == 6 )
|
| <strong>Go South</strong>
|
| #else
|
| <strong>Go West</strong>
|
| #end
|
| </pre></div> |
| <p>In this example, <em>$foo</em> is greater than 10, so the first
|
| two comparisons fail. Next <em>$bar</em> is compared to 6, which is
|
| true, so the output is <strong>Go South</strong>.
|
| </p> |
| <p>
|
| <a name="relationalandlogicaloperators"><strong>Relational and Logical Operators</strong></a>
|
| </p> |
| <p>
|
| Velocity uses the equivalent operator to determine the relationships between variables.
|
| Here is a simple example to illustrate how the equivalent operator is used.
|
| </p> |
| <div class="source">
|
| #set ($foo = "deoxyribonucleic acid")
|
| #set ($bar = "ribonucleic acid")
|
|
|
| #if ($foo == $bar)
|
| In this case it's clear they aren't equivalent. So...
|
| #else
|
| They are not equivalent and this will be the output.
|
| #end
|
| </pre></div> |
| <p>Note that the semantics of <em>==</em> are slightly different than Java where <em>==</em>
|
| can only be used to test object equality. In Velocity the equivalent operator
|
| can be used to directly compare numbers, strings, or objects. When the objects
|
| are of different classes, the string representations are obtained by calling
|
| <code>toString()</code> for each object and then compared.
|
| </p> |
| <p>
|
| Velocity has logical AND, OR and NOT operators as well.
|
| Below are examples demonstrating the use of the
|
| logical AND, OR and NOT operators.
|
| </p> |
| <div class="source">
|
| ## logical AND
|
|
|
| #if( $foo && $bar )
|
| <strong> This AND that</strong>
|
| #end
|
|
|
| </pre></div> |
| <p>
|
| The <em>#if()</em> directive will only evaluate to true
|
| if both <em>$foo</em>
|
| and <em>$bar</em> are true. If <em>$foo</em> is false, the
|
| expression will evaluate to false; <em>$bar</em> will not be
|
| evaluated. If <em>$foo</em> is true, the Velocity Templating
|
| Engine will then check the value of <em>$bar</em>; if
|
| <em>$bar</em> is true, then the entire expression is true and
|
| <strong>This AND that</strong> becomes the output. If
|
| <em>$bar</em> is false, then there will be no output as the entire
|
| expression is false.
|
| </p> |
| <p>
|
| Logical OR operators work the same way, except only one of the
|
| references need evaluate to true in order for the entire
|
| expression to be considered true. Consider the following example.
|
| </p> |
| <div class="source">
|
| ## logical OR
|
|
|
| #if( $foo || $bar )
|
| <strong>This OR That</strong>
|
| #end
|
| </pre></div> |
| <p>
|
| If <em>$foo</em> is true, the Velocity Templating Engine has no
|
| need to look at <em>$bar</em>; whether <em>$bar</em> is true or
|
| false, the expression will be true, and <strong>This OR That</strong>
|
| will be output. If <em>$foo</em> is false,
|
| however, <em>$bar</em> must be checked. In this case, if
|
| <em>$bar</em> is also false, the expression evaluates to false and
|
| there is no output. On the other hand, if <em>$bar</em> is true,
|
| then the entire expression is true, and the output is
|
| <strong>This OR That</strong>
|
| </p> |
| <p>
|
| With logical NOT operators, there is only one argument :
|
| </p> |
| <div class="source">
|
|
|
| ##logical NOT
|
|
|
| #if( !$foo )
|
| <strong>NOT that</strong>
|
| #end
|
|
|
| </pre></div> |
| <p>
|
| Here, the if <em>$foo</em> is true, then <em>!$foo</em> evaluates to
|
| false, and there is no output. If <em>$foo</em> is false, then
|
| <em>!$foo</em> evaluates to true and <strong>NOT that</strong> will be
|
| output. Be careful not to confuse this with the <em>quiet reference $!foo</em>
|
| which is something altogether different.
|
| </p> |
| <p>There are text versions of all logical operators, including
|
| <em>eq</em>, <em>ne</em>,
|
| <em>and</em>, <em>or</em>, <em>not</em>, <em>gt</em>, <em>ge</em>, <em>lt</em>,
|
| and <em>le</em>.
|
| </p> |
| <p>One more useful note. When you wish to include text immediately following
|
| a <em>#else</em> directive you will need to use curly brackets immediately surrounding
|
| the directive to differentiate it from the following text.
|
| (Any directive can be delimited by
|
| curly brackets, although this is most useful for <em>#else</em>).
|
| </p> |
| <div class="source">
|
| #if( $foo == $bar)it's true!#{else}it's not!#end</li>
|
| </pre></div> |
| </div> |
| <a name="loops"></a> |
| <h1>Loops</h1> |
| |
| <div class="subsection"> |
| <strong>Foreach Loop</strong> |
| <p>
|
| The <em>#foreach</em> element allows for looping. For example:
|
| </p> |
| <div class="source">
|
| <ul>
|
| #foreach( $product in $allProducts )
|
| <li>$product</li>
|
| #end
|
| </ul>
|
| </pre></div> |
| <p>
|
| This <em>#foreach</em> loop causes the <em>$allProducts</em> list
|
| (the object) to be looped over for all of the products (targets) in
|
| the list. Each time through the loop, the value from
|
| <em>$allProducts</em> is placed into the <em>$product</em> variable.
|
| </p> |
| <p>
|
| The contents of the <em>$allProducts</em> variable is a Vector, a
|
| Hashtable or an Array. The value assigned to the <em>$product</em>
|
| variable is a Java Object and can be referenced from a variable as
|
| such. For example, if <em>$product</em> was really a Product class
|
| in Java, its name could be retrieved by referencing the
|
| <em>$product.Name</em> method (ie: <em>$Product.getName()</em>).
|
| </p> |
| <p>
|
| Lets say that <em>$allProducts</em> is a Hashtable. If you wanted to
|
| retrieve the key values for the Hashtable as well as the objects
|
| within the Hashtable, you can use code like this:
|
| </p> |
| <div class="source">
|
| <ul>
|
| #foreach( $key in $allProducts.keySet() )
|
| <li>Key: $key -> Value: $allProducts.get($key)</li>
|
| #end
|
| </ul>
|
| </pre></div> |
| <p>
|
| Velocity provides an easy way to get the loop counter so that you
|
| can do something like the following:
|
| </p> |
| <div class="source">
|
| <table>
|
| #foreach( $customer in $customerList )
|
| <tr><td>$velocityCount</td><td>$customer.Name</td></tr>
|
| #end
|
| </table>
|
| </pre></div> |
| <p>
|
| Velocity also now provides an easy way to tell if you are
|
| on the last iteration of a loop:
|
| </p> |
| <div class="source">
|
| #foreach( $customer in $customerList )
|
| $customer.Name#if( $velocityHasNext ),#end
|
| #end
|
| </pre></div> |
| <p>
|
| The default name for the "has next" variable reference, which is
|
| specified in the velocity.properties file, is $velocityHasNext.
|
| The default name for the loop counter variable reference, which is
|
| specified in the velocity.properties file, is $velocityCount. By
|
| default the counter starts at 1, but this can be set to either 0 or
|
| 1 in the <code>velocity.properties</code> file. Here's what the loop
|
| counter properties section of the <code>velocity.properties</code>
|
| file appears:
|
| </p> |
| <div class="source">
|
| # Default name of the loop counter
|
| # variable reference.
|
| directive.foreach.counter.name = velocityCount
|
| directive.foreach.iterator.name = velocityHasNext
|
|
|
| # Default starting value of the loop
|
| # counter variable reference.
|
| directive.foreach.counter.initial.value = 1
|
| </pre></div> |
| <p>
|
| It's possible to set a maximum allowed number of times that a loop
|
| may be executed. By default there is no max (indicated by a value of 0
|
| or less), but this can be set to an arbitrary number in the
|
| <code>velocity.properties</code> file. This is useful as a fail-safe.
|
| </p> |
| <div class="source">
|
| # The maximum allowed number of loops.
|
| directive.foreach.maxloops = -1
|
| </pre></div> |
| <p>
|
| If you want to stop looping in a foreach from within your template,
|
| you can now use the #break directive to stop looping at any time:
|
| </p> |
| <div class="source">
|
| ## list first 5 customers only
|
| #foreach( $customer in $customerList )
|
| #if( $velocityCount > 5 )
|
| #break
|
| #end
|
| $customer.Name
|
| #end
|
| </pre></div> |
| </div> |
| <a name="include"></a> |
| <h1>Include</h1> |
| |
| <div class="subsection"> |
| <p>
|
| The <em>#include</em> script element allows the template designer to
|
| import a local file, which is then inserted into the location where
|
| the <em>#include</em> directive is defined. The contents of the file
|
| are not rendered through the template engine. For security reasons,
|
| the file to be included may only be under TEMPLATE_ROOT.
|
| </p> |
| <div class="source">
|
| #include( "one.txt" )
|
| </pre></div> |
| <p>
|
| The file to which the <em>#include</em> directive refers is enclosed
|
| in quotes. If more than one file will be included, they should be
|
| separated by commas.
|
| </p> |
| <div class="source">
|
| #include( "one.gif","two.txt","three.htm" )
|
| </pre></div> |
| <p>
|
| The file being included need not be referenced by name; in fact, it
|
| is often preferable to use a variable instead of a filename. This
|
| could be useful for targeting output according to criteria
|
| determined when the page request is submitted. Here is an example
|
| showing both a filename and a variable.
|
| </p> |
| <div class="source">
|
| #include( "greetings.txt", $seasonalstock )
|
| </pre></div> |
| </div> |
| <a name="parse"></a> |
| <h1>Parse</h1> |
| |
| <div class="subsection"> |
| <p>
|
| The <em>#parse</em> script element allows the template designer to
|
| import a local file that contains VTL. Velocity will parse the VTL
|
| and render the template specified.
|
| </p> |
| <div class="source">
|
| #parse( "me.vm" )
|
| </pre></div> |
| <p>
|
| Like the <em>#include</em> directive, <em>#parse</em> can take a
|
| variable rather than a template. Any templates to which
|
| <em>#parse</em> refers must be included under TEMPLATE_ROOT. Unlike
|
| the <em>#include</em> directive, <em>#parse</em> will only take a
|
| single argument.
|
| </p> |
| <p>
|
| VTL templates can have <em>#parse</em> statements referring to
|
| templates that in turn have <em>#parse</em> statements. By default
|
| set to 10, the <em>directive.parse.max.depth</em> line of the
|
| <code>velocity.properties</code> allows users to customize maximum
|
| number of <em>#parse</em> referrals that can occur from a single
|
| template. (Note: If the <em>directive.parse.max.depth</em> property
|
| is absent from the <code>velocity.properties</code> file, Velocity
|
| will set this default to 10.) Recursion is permitted, for example,
|
| if the template <code>dofoo.vm</code> contains the following lines:
|
| </p> |
| <div class="source">
|
| Count down.
|
| #set( $count = 8 )
|
| #parse( "parsefoo.vm" )
|
| All done with dofoo.vm!
|
| </pre></div> |
| <p>
|
| It would reference the template <code>parsefoo.vm</code>, which
|
| might contain the following VTL:
|
| </p> |
| <div class="source">
|
| $count
|
| #set( $count = $count - 1 )
|
| #if( $count > 0 )
|
| #parse( "parsefoo.vm" )
|
| #else
|
| All done with parsefoo.vm!
|
| #end
|
| </pre></div> |
| <p>
|
| After "Count down." is displayed, Velocity passes through
|
| <code>parsefoo.vm</code>, counting down from 8. When the count
|
| reaches 0, it will display the "All done with parsefoo.vm!" message.
|
| At this point, Velocity will return to <code>dofoo.vm</code> and
|
| output the "All done with dofoo.vm!" message.
|
| </p> |
| </div> |
| <a name="stop"></a> |
| <h1>Stop</h1> |
| |
| <div class="subsection"> |
| <p>
|
| The <em>#stop</em> script element prevents any further text or references
|
| in the page from being rendered. This is useful
|
| for debugging purposes.
|
| </p> |
| </div> |
| <a name="evaluate"></a> |
| <h1>Evaluate</h1> |
| |
| <div class="subsection"> |
| <p>
|
| The <em>#evaluate</em> directive can be used to dynamically evaluate VTL. This allows
|
| the template to evaluate a string that is created at render time. Such a string might be
|
| used to internationalize the template or to include parts of a template from a database.
|
| </p> |
| <p>The example below will display <code>abc</code>.
|
| </p> |
| <div class="source">
|
| #set($source1 = "abc")
|
| #set($select = "1")
|
| #set($dynamicsource = "$source$select")
|
| ## $dynamicsource is now the string '$source1'
|
| #evaluate($dynamicsource)
|
| </pre></div> |
| </div> |
| <a name="define"></a> |
| <h1>Define</h1> |
| |
| <div class="subsection"> |
| <p>
|
| The <em>#define</em> directive lets one assign a block of VTL to a reference.
|
| </p> |
| <p>The example below will display <code>Hello World!</code>.
|
| </p> |
| <div class="source">
|
| #define( $block )Hello $who#end
|
| #set( $who = 'World!' )
|
| $block
|
| </pre></div> |
| </div> |
| <a name="velocimacros"></a> |
| <h1>Velocimacros</h1> |
| |
| <div class="subsection"> |
| <p>
|
| The <em>#macro</em> script element allows template designers to
|
| define a repeated segment of a VTL template. Velocimacros are very
|
| useful in a wide range of scenarios both simple and complex. This
|
| Velocimacro, created for the sole purpose of saving keystrokes and
|
| minimizing typographic errors, provides an introduction to the
|
| concept of Velocimacros.
|
| </p> |
| <div class="source">
|
| #macro( d )
|
| <tr><td></td></tr>
|
| #end
|
| </pre></div> |
| <p>
|
| The Velocimacro being defined in this example is <em>d</em>, and it
|
| can be called in a manner analogous to any other VTL directive:
|
| </p> |
| <div class="source">
|
| #d()
|
| </pre></div> |
| <p>
|
| When this template is called, Velocity would replace <em>#d()</em>
|
| with a row containing a single, empty data cell.
|
| </p> |
| <p>
|
| A Velocimacro could take any number of arguments -- even zero
|
| arguments, as demonstrated in the first example, is an option -- but
|
| when the Velocimacro is invoked, it must be called with the same
|
| number of arguments with which it was defined. Many Velocimacros are
|
| more involved than the one defined above. Here is a Velocimacro that
|
| takes two arguments, a color and an array.
|
| </p> |
| <div class="source">
|
| #macro( tablerows $color $somelist )
|
| #foreach( $something in $somelist )
|
| <tr><td bgcolor=$color>$something</td></tr>
|
| #end
|
| #end
|
| </pre></div> |
| <p>
|
| The Velocimacro being defined in this example, <em>tablerows</em>,
|
| takes two arguments. The first argument takes the place of
|
| <em>$color</em>, and the second argument takes the place of
|
| <em>$somelist</em>.
|
| </p> |
| <p>
|
| Anything that can be put into a VTL template can go into the body of
|
| a Velocimacro. The <em>tablerows</em> Velocimacro is a
|
| <em>foreach</em> statement. There are two <em>#end</em> statements
|
| in the definition of the <em>#tablerows</em> Velocimacro; the first
|
| belongs to the <em>#foreach</em>, the second ends the Velocimacro
|
| definition.
|
| </p> |
| <div class="source">
|
| #set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
|
| #set( $color = "blue" )
|
| <table>
|
| #tablerows( $color $greatlakes )
|
| </table>
|
| </pre></div> |
| <p>
|
| Notice that <em>$greatlakes</em> takes the place of
|
| <em>$somelist</em>. When the <em>#tablerows</em> Velocimacro is
|
| called in this situation, the following output is generated:
|
| </p> |
| <div class="source">
|
| <table>
|
| <tr><td bgcolor="blue">Superior</td></tr>
|
| <tr><td bgcolor="blue">Michigan</td></tr>
|
| <tr><td bgcolor="blue">Huron</td></tr>
|
| <tr><td bgcolor="blue">Erie</td></tr>
|
| <tr><td bgcolor="blue">Ontario</td></tr>
|
| </table>
|
| </pre></div> |
| <p>
|
| Velocimacros can be defined <em>inline</em> in a Velocity template,
|
| meaning that it is unavailable to other Velocity templates on the
|
| same web site. Defining a Velocimacro such that it can be shared by
|
| all templates has obvious advantages: it reduces the need to
|
| redefine the Velocimacro on numerous templates, saving work and
|
| reducing the chance of error, and ensures that a single change to a
|
| macro available to more than one template.
|
| </p> |
| <p>
|
| Were the <em>#tablerows($color $list)</em> Velocimacro defined in a
|
| Velocimacros template library, this macro could be used on any of
|
| the regular templates. It could be used many times and for many
|
| different purposes. In the template <code>mushroom.vm</code> devoted
|
| to all things fungi, the <em>#tablerows</em> Velocimacro could be
|
| invoked to list the parts of a typical mushroom:
|
| </p> |
| <div class="source">
|
| #set( $parts = ["volva","stipe","annulus","gills","pileus"] )
|
| #set( $cellbgcol = "#CC00FF" )
|
| <table>
|
| #tablerows( $cellbgcol $parts )
|
| </table>
|
| </pre></div> |
| <p>
|
| When fulfilling a request for <code>mushroom.vm</code>, Velocity
|
| would find the <em>#tablerows</em> Velocimacro in the template
|
| library (defined in the <code>velocity.properties</code> file) and
|
| generate the following output:
|
| </p> |
| <div class="source">
|
| <table>
|
| <tr><td bgcolor="#CC00FF">volva</td></tr>
|
| <tr><td bgcolor="#CC00FF">stipe</td></tr>
|
| <tr><td bgcolor="#CC00FF">annulus</td></tr>
|
| <tr><td bgcolor="#CC00FF">gills</td></tr>
|
| <tr><td bgcolor="#CC00FF">pileus</td></tr>
|
| </table>
|
| </pre></div> |
| <strong>Velocimacro Arguments</strong> |
| <p>
|
| Velocimacros can take as arguments any of the following
|
| VTL elements :
|
| </p> |
| <ul> |
| <li> |
| |
| Reference : anything that starts with '$' |
| |
| </li> |
| <li> |
| |
| String literal : something like "$foo" or 'hello' |
| |
| </li> |
| <li> |
| |
| Number literal : 1, 2 etc |
| |
| </li> |
| <li> |
| |
| IntegerRange : [ 1..2] or [$foo .. $bar] |
| |
| </li> |
| <li> |
| |
| ObjectArray : [ "a", "b", "c"] |
| |
| </li> |
| <li> |
| |
| boolean value true |
| |
| </li> |
| <li> |
| |
| boolean value false |
| |
| </li> |
| </ul> |
| <p>
|
| When passing references as arguments to Velocimacros,
|
| please note that references are passed 'by name'.
|
| This means that their value is 'generated' at each
|
| use inside the Velocimacro. This feature allows you
|
| to pass references with method calls and have the
|
| method called at each use. For example, when calling
|
| the following Velocimacro as shown
|
| </p> |
| <div class="source">
|
| #macro( callme $a )
|
| $a $a $a
|
| #end
|
|
|
| #callme( $foo.bar() )
|
| </pre></div> |
| <p>
|
| results in the method bar() of the reference $foo
|
| being called 3 times.
|
| </p> |
| <p>
|
| At first glance, this feature appears surprising, but
|
| when you take into consideration the original motivation
|
| behind Velocimacros -- to eliminate cut'n'paste duplication
|
| of commonly used VTL -- it makes sense. It allows you to
|
| do things like pass stateful objects, such as an object
|
| that generates colors in a repeating sequence for
|
| coloring table rows, into the Velocimacro.
|
| </p> |
| <p>
|
| If you need to circumvent this feature, you can always
|
| just get the value from the method as a new reference
|
| and pass that :
|
| </p> |
| <div class="source">
|
| #set( $myval = $foo.bar() )
|
| #callme( $myval )
|
| </pre></div> |
| <strong>Velocimacro Properties</strong> |
| <p>
|
| Several lines in the <code>velocity.properties</code> file allow for
|
| flexible implementation of Velocimacros. Note that these are also
|
| documented in the <a href="developer-guide.html">Developer Guide</a>.
|
| </p> |
| <p>
|
| <code>velocimacro.library</code> - A comma-separated list of all
|
| Velocimacro template libraries. By default, Velocity looks for
|
| a single library: <em>VM_global_library.vm</em>. The configured template path
|
| is used to find the Velocimacro libraries.
|
| </p> |
| <p>
|
| <code>velocimacro.permissions.allow.inline</code> - This property,
|
| which has possible values of true or false, determines whether
|
| Velocimacros can be defined in regular templates. The default,
|
| true, allows template designers to define Velocimacros in the
|
| templates themselves.
|
| </p> |
| <p>
|
| <code>velocimacro.permissions.allow.inline.to.replace.global</code> -
|
| With possible values of true or false,
|
| this property allows the user to specify if a Velocimacro defined
|
| inline in a template can replace a globally defined template, one
|
| that was loaded on startup via the <code>velocimacro.library</code>
|
| property. The default, <code>false</code>, prevents
|
| Velocimacros defined inline in a template from replacing those
|
| defined in the template libraries loaded at startup.
|
| </p> |
| <p>
|
| <code>velocimacro.permissions.allow.inline.local.scope</code> - This
|
| property, with possible values of true or false, defaulting to false,
|
| controls if Velocimacros defined inline are 'visible' only to the
|
| defining template. In other words, with this property set to true,
|
| a template can define inline VMs that are usable only by the defining
|
| template. You can use this for fancy VM tricks - if a global VM calls
|
| another global VM, with inline scope, a template can define a
|
| private implementation of the second VM that will be called by the
|
| first VM when invoked by that template. All other templates
|
| are unaffected.
|
| </p> |
| <p>
|
| <code>velocimacro.context.localscope</code> - This property has the
|
| possible values true or false, and the default is false. When true,
|
| any modifications to the context via #set() within a Velocimacro
|
| are considered 'local' to the Velocimacro, and will not
|
| permanently affect the context.
|
| </p> |
| <p>
|
| <code>velocimacro.library.autoreload</code> - This property
|
| controls Velocimacro library autoloading. The default value
|
| is <code>false</code>. When set to <code>true</code>
|
| the source Velocimacro library for an invoked Velocimacro will be checked
|
| for changes, and reloaded if necessary. This allows you to change and
|
| test Velocimacro libraries without having to restart your application or
|
| servlet container, just like you can with regular templates.
|
| This mode only works when caching is <i>off</i>
|
| in the resource loaders (e.g. <code>file.resource.loader.cache = false</code> ).
|
| This feature is intended for development, not for production.
|
| </p> |
| </div> |
| <a name="getting_literal"></a> |
| <h1>Getting literal</h1> |
| |
| <div class="subsection"> |
| <p>
|
| VTL uses special characters, such as <em>$</em> and <em>#</em>, to
|
| do its work, so some added care should be taken where using these
|
| characters in your templates. This section deals with escaping these
|
| characters.
|
| </p> |
| <p>
|
| <a name="currency"><strong>Currency</strong></a>
|
| <br />
|
| There is no problem writing "I bought a 4 lb. sack of potatoes at
|
| the farmer's market for only $2.50!" As mentioned, a VTL identifier
|
| always begins with an upper- or lowercase letter, so $2.50 would not
|
| be mistaken for a reference.
|
| </p> |
| <p>
|
| <a name="escapingvalidvtlreferences"><strong>Escaping Valid VTL References</strong></a>
|
| <br />
|
| Cases may arise where you do not want to have a reference rendered by Velocity.
|
| <em>Escaping</em> special characters is the best way to output
|
| VTL's special characters in these situations, and this can be
|
| done using the backslash ( <em>\</em> ) character <i>when those special
|
| characters are part of a valid VTL reference</i>.
|
| <a href="#escapinginvalidvtlreferences" style="text-decoration: none"><sup>*</sup></a>
|
| </p> |
| <div class="source">
|
| #set( $email = "foo" )
|
| $email
|
| </pre></div> |
| <p>
|
| If Velocity encounters a reference in your VTL template to
|
| <em>$email</em>, it will search the Context for a corresponding
|
| value. Here the output will be <em>foo</em>, because <em>$email</em> is
|
| defined. If <em>$email</em> is not defined, the output will be
|
| <em>$email</em>.
|
| </p> |
| <p>
|
| Suppose that <em>$email</em> is defined (for example, if it has the
|
| value <em>foo</em>), and that you want to output <em>$email</em>. There are a few
|
| ways of doing this, but the simplest is to use the escape character.
|
| Here is a demonstration:
|
| </p> |
| <div class="source">## The following line defines $email in this template:
|
| #set( $email = "foo" )
|
| $email
|
| \$email
|
| </pre></div> |
| <p>
|
| renders as
|
| </p> |
| <div class="source">foo
|
| $email
|
| </pre></div> |
| <p>
|
| If, for some reason, you need a backslash before either line above,
|
| you can do the following:
|
| </p> |
| <div class="source">## The following line defines $email in this template:
|
| #set( $email = "foo" )
|
| \\$email
|
| \\\$email
|
| </pre></div> |
| <p>
|
| which renders as
|
| </p> |
| <div class="source">\foo
|
| \$email
|
| </pre></div> |
| <p>
|
| Note that the <em>\</em> character bind to the <em>$</em>
|
| from the left. The bind-from-left rule causes <em>\\\$email</em> to
|
| render as <em>\$email</em>. Compare these examples to those in
|
| which <em>$email</em> is not defined.
|
| </p> |
| <div class="source">
|
| $email
|
| \$email
|
| \\$email
|
| \\\$email
|
| </pre></div> |
| <p>
|
| renders as
|
| </p> |
| <div class="source">
|
| $email
|
| \$email
|
| \\$email
|
| \\\$email
|
| </pre></div> |
| <p>
|
| Notice Velocity handles references that are defined differently
|
| from those that have not been defined. Here is a set directive that
|
| gives <em>$foo</em> the value <em>gibbous</em>.
|
| </p> |
| <div class="source">
|
| #set( $foo = "gibbous" )
|
| $moon = $foo
|
| </pre></div> |
| <p>
|
| The output will be: <em>$moon = gibbous</em> -- where <em>$moon</em>
|
| is output as a literal because it is undefined and <em>gibbous</em>
|
| is output in place of <em>$foo</em>.
|
| </p> |
| <p>
|
| <a name="escapinginvalidvtlreferences"><strong>Escaping Invalid VTL References</strong></a>
|
| <br />
|
| Sometimes Velocity has trouble parsing your template when it encounters
|
| an "invalid reference" that you never intended to be a reference at all.
|
| <em>Escaping</em> special characters is, again, the best way to
|
| handle these situations, but in these situations, the backslash will
|
| likely fail you. Instead of simply trying to escape the problematic
|
| <code>$</code> or <code>#</code>, you should probably just replace this:
|
| </p> |
| <div class="source">
|
| ${my:invalid:non:reference}
|
| </pre></div> |
| <p>with something like this</p> |
| <div class="source">
|
| #set( $D = '$' )
|
| ${D}{my:invalid:non:reference}
|
| </pre></div> |
| <p>You can, of course, put your <code>$</code> or <code>#</code> string directly
|
| into the context from your java code (e.g. <code>context.put("D","$");</code>)
|
| to avoid the extra #set() directive in your template(s). Or, if you are using
|
| <a href="http://velocity.apache.org/tools/devel/">VelocityTools</a>, you can
|
| just use the EscapeTool like this:</p> |
| <div class="source">
|
| ${esc.d}{my:invalid:non:reference}
|
| </pre></div> |
| <p>
|
| Escaping of both valid and invalid VTL directives is
|
| handled in much the same manner; this is described in
|
| more detail in the Directives section.
|
| </p> |
| <p>
|
| <a name="escaping_vtl_directives"><strong>Escaping VTL Directives</strong></a>
|
| <br />
|
| VTL directives can be escaped with the backslash character ("\") in
|
| a manner similar to valid VTL references.
|
| </p> |
| <div class="source">
|
| ## #include( "a.txt" ) renders as <contents of a.txt>
|
| #include( "a.txt" )
|
|
|
| ## \#include( "a.txt" ) renders as #include( "a.txt" )
|
| \#include( "a.txt" )
|
|
|
| ## \\#include ( "a.txt" ) renders as \<contents of a.txt>
|
| \\#include ( "a.txt" )
|
| </pre></div> |
| <p>
|
| Extra care should be taken when escaping VTL directives that contain
|
| multiple script elements in a single directive (such as in an
|
| if-else-end statements). Here is a typical VTL if-statement:
|
| </p> |
| <div class="source">
|
| #if( $jazz )
|
| Vyacheslav Ganelin
|
| #end
|
| </pre></div> |
| <p>
|
| If <em>$jazz</em> is true, the output is
|
| </p> |
| <div class="source">
|
| Vyacheslav Ganelin
|
| </pre></div> |
| <p>
|
| If <em>$jazz</em> is false, there is no output. Escaping script elements
|
| alters the output. Consider the following case:
|
| </p> |
| <div class="source">
|
| \#if( $jazz )
|
| Vyacheslav Ganelin
|
| \#end
|
| </pre></div> |
| <p>
|
| This causes the directives to be escaped, but the rendering of <em>$jazz</em>
|
| proceeds as normal. So, if <em>$jazz</em> is true, the output is
|
| </p> |
| <div class="source">
|
| #if( true )
|
| Vyacheslav Ganelin
|
| #end
|
| </pre></div> |
| <p>
|
| Suppose backslashes precede script elements that are legitimately escaped:
|
| </p> |
| <div class="source">
|
| \\#if( $jazz )
|
| Vyacheslav Ganelin
|
| \\#end
|
| </pre></div> |
| <p>
|
| In this case, if <em>$jazz</em> is true, the output is
|
| </p> |
| <div class="source">
|
| \ Vyacheslav Ganelin
|
| \
|
| </pre></div> |
| <p>
|
| To understand this, note that the <code>#if( arg ) </code> when
|
| ended by a newline (return) will omit the newline from the output.
|
| Therefore, the body of the <code>#if()</code>
|
| block follows the first '\', rendered
|
| from the '\\' preceding the <code>#if()</code>.
|
| The last \ is on a different
|
| line than the text because there is a newline after 'Ganelin', so
|
| the final \\, preceding the <code>#end</code> is part of the
|
| body of the block.
|
| </p> |
| <p>
|
| If <em>$jazz</em> is false, the output is
|
| </p> |
| <div class="source">
|
| \
|
| </pre></div> |
| <p>
|
| Note that
|
| things start to break if script elements are not properly escaped.
|
| </p> |
| <div class="source">
|
| \\\#if( $jazz )
|
| Vyacheslave Ganelin
|
| \\#end
|
| </pre></div> |
| <p>
|
| Here the <em>#if</em> is escaped, but there is an <em>#end</em>
|
| remaining; having too many endings will cause a parsing error.
|
| </p> |
| </div> |
| <a name="vtl:_formatting_issues"></a> |
| <h1>VTL: Formatting Issues</h1> |
| |
| <div class="subsection"> |
| <p>
|
| Although VTL in this user guide is often displayed with newlines and
|
| whitespaces, the VTL shown below
|
| </p> |
| <div class="source">
|
| #set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
|
| #foreach( $shogun in $imperial )
|
| $shogun
|
| #end
|
| </pre></div> |
| <p>
|
| is equally valid as the following snippet that Geir Magnusson Jr.
|
| posted to the Velocity user mailing list to illustrate a completely
|
| unrelated point:
|
| </p> |
| <div class="source">
|
| Send me #set($foo=["$10 and ","a pie"])#foreach($a in $foo)$a#end please.
|
| </pre></div> |
| <p>
|
| Velocity's behaviour is to gobble up excess whitespace. The
|
| preceding directive can be written as:
|
| </p> |
| <div class="source">
|
| Send me
|
| #set( $foo = ["$10 and ","a pie"] )
|
| #foreach( $a in $foo )
|
| $a
|
| #end
|
| please.
|
| </pre></div> |
| <p>
|
| or as
|
| </p> |
| <div class="source">
|
| Send me
|
| #set($foo = ["$10 and ","a pie"])
|
| #foreach ($a in $foo )$a
|
| #end please.
|
| </pre></div> |
| <p>
|
| In each case the output will be the same.
|
| </p> |
| </div> |
| <a name="other_features_and_miscellany"></a> |
| <h1>Other Features and Miscellany</h1> |
| |
| <div class="subsection"> |
| <a name="math"></a> |
| <h2>Math</h2> |
| <div class="subsection"> |
| <p>
|
| Velocity has a handful of built-in mathematical functions that can
|
| be used in templates with the <em>set</em> directive. The following
|
| equations are examples of addition, subtraction, multiplication and
|
| division, respectively:
|
| </p> |
| <div class="source">
|
| #set( $foo = $bar + 3 )
|
| #set( $foo = $bar - 4 )
|
| #set( $foo = $bar * 6 )
|
| #set( $foo = $bar / 2 )
|
| </pre></div> |
| <p>
|
| When a division operation is performed between two integers, the result will be an
|
| integer, as the fractional portion is discarded. Any remainder can be obtained by
|
| using the modulus (<em>%</em>) operator.
|
| </p> |
| <div class="source">
|
| #set( $foo = $bar % 5 )
|
| </pre></div> |
| </div> |
| <a name="range_operator"></a> |
| <h2>Range Operator</h2> |
| <div class="subsection"> |
| <p>
|
| The range operator can be used in conjunction with <em>#set</em> and
|
| <em>#foreach</em> statements. Useful for its ability to produce an
|
| object array containing integers, the range operator has the
|
| following construction:
|
| </p> |
| <div class="source">
|
| [n..m]
|
| </pre></div> |
| <p>
|
| Both <em>n</em> and <em>m</em> must either be or produce integers.
|
| Whether <em>m</em> is greater than or less than <em>n</em> will not
|
| matter; in this case the range will simply count down. Examples
|
| showing the use of the range operator as provided below:
|
| </p> |
| <div class="source">
|
| First example:
|
| #foreach( $foo in [1..5] )
|
| $foo
|
| #end
|
|
|
| Second example:
|
| #foreach( $bar in [2..-2] )
|
| $bar
|
| #end
|
|
|
| Third example:
|
| #set( $arr = [0..1] )
|
| #foreach( $i in $arr )
|
| $i
|
| #end
|
|
|
| Fourth example:
|
| [1..3]
|
| </pre></div> |
| <p>
|
| Produces the following output:
|
| </p> |
| <div class="source">
|
| First example:
|
| 1 2 3 4 5
|
|
|
| Second example:
|
| 2 1 0 -1 -2
|
|
|
| Third example:
|
| 0 1
|
|
|
| Fourth example:
|
| [1..3]
|
| </pre></div> |
| <p>
|
| Note that the range operator only produces the array when used in
|
| conjunction with <em>#set</em> and <em>#foreach</em> directives, as
|
| demonstrated in the fourth example.
|
| </p> |
| <p>
|
| Web page designers concerned with making tables a standard size, but
|
| where some will not have enough data to fill the table, will find
|
| the range operator particularly useful.
|
| </p> |
| </div> |
| <a name="advanced_issues:_escaping_and_"></a> |
| <h2>Advanced Issues: Escaping and !</h2> |
| <div class="subsection"> |
| <p>
|
| When a reference is silenced with the <em>!</em> character and the
|
| <em>!</em> character preceded by an <em>\</em> escape character, the
|
| reference is handled in a special way. Note the differences between
|
| regular escaping, and the special case where <em>\</em> precedes
|
| <em>!</em> follows it:
|
| </p> |
| <div class="source">
|
| #set( $foo = "bar" )
|
| $\!foo
|
| $\!{foo}
|
| $\\!foo
|
| $\\\!foo
|
| </pre></div> |
| <p>
|
| This renders as:
|
| </p> |
| <div class="source">
|
| $!foo
|
| $!{foo}
|
| $\!foo
|
| $\\!foo
|
| </pre></div> |
| <p>
|
| Contrast this with regular escaping, where <em>\</em> precedes
|
| <em>$</em>:
|
| </p> |
| <div class="source">
|
| \$foo
|
| \$!foo
|
| \$!{foo}
|
| \\$!{foo}
|
| </pre></div> |
| <p>
|
| This renders as:
|
| </p> |
| <div class="source">
|
| $foo
|
| $!foo
|
| $!{foo}
|
| \bar
|
| </pre></div> |
| </div> |
| <a name="velocimacro_miscellany"></a> |
| <h2>Velocimacro Miscellany</h2> |
| <div class="subsection"> |
| <p>
|
| This section is a mini-FAQ on topics relating to Velocimacros. This
|
| section will change over time, so it's worth checking for new information
|
| from time to time.
|
| </p> |
| <p>
|
| Note : Throughout this section, 'Velocimacro' will commonly be abbreviated
|
| as 'VM'.
|
| </p> |
| <strong>Can I use a directive or another VM as an argument to a VM?</strong> |
| <p>
|
| Example : <code>#center( #bold("hello") )</code>
|
| </p> |
| <p>
|
| No. A directive isn't a valid argument to a directive, and for most practical
|
| purposes, a VM is a directive.
|
| </p> |
| <p>
|
| <i>However...</i>, there are things you can do. One easy solution is to take
|
| advantage of the fact that 'doublequote' (") renders its contents. So you
|
| could do something like
|
| </p> |
| <div class="source">
|
| #set($stuff = "#bold('hello')" )
|
| #center( $stuff )
|
| </pre></div> |
| <p>
|
| You can save a step...
|
| </p> |
| <div class="source">
|
| #center( "#bold( 'hello' )" )
|
| </pre></div> |
| <p>
|
| Please note that in the latter example the arg
|
| is evaluated <i>inside</i> the VM, not at the
|
| calling level. In other words, the argument to
|
| the VM is passed in in its entirety and evaluated within the VM
|
| it was passed into. This allows you to do things like :
|
| </p> |
| <div class="source">
|
|
|
| #macro( inner $foo )
|
| inner : $foo
|
| #end
|
|
|
| #macro( outer $foo )
|
| #set($bar = "outerlala")
|
| outer : $foo
|
| #end
|
|
|
| #set($bar = 'calltimelala')
|
| #outer( "#inner($bar)" )
|
|
|
| </pre></div> |
| <p>
|
| Where the output is
|
| </p> |
| <div class="source">
|
| Outer : inner : outerlala
|
| </pre></div> |
| <p>
|
| because the evaluation of the "#inner($bar)" happens inside #outer(), so the
|
| $bar value set inside #outer() is the one that's used.
|
| </p> |
| <p>
|
| This is an intentional and jealously guarded feature - args are passed 'by
|
| name' into VMs, so you can hand VMs things like stateful references such as
|
| </p> |
| <div class="source">
|
| #macro( foo $color )
|
| <tr bgcolor=$color><td>Hi</td></tr>
|
| <tr bgcolor=$color><td>There</td></tr>
|
| #end
|
|
|
| #foo( $bar.rowColor() )
|
| </pre></div> |
| <p>
|
| And have rowColor() called repeatedly, rather than just once. To avoid that,
|
| invoke the method outside of the VM, and pass the value into the VM.
|
| </p> |
| <div class="source">
|
| #set($color = $bar.rowColor())
|
| #foo( $color )
|
| </pre></div> |
| <strong>Can I register Velocimacros via #parse() ? </strong> |
| <p>
|
| <b>Yes! This became possible in Velocity 1.6.</b>
|
| </p> |
| <p>
|
| If you are using an earlier version, your Velocimacros
|
| must be defined before they are first
|
| used in a template. This means that your #macro() declarations
|
| should come before using the Velocimacros.
|
| </p> |
| <p>
|
| This is important to remember if you try to #parse()
|
| a template containing inline #macro() directives. Because
|
| the #parse() happens at runtime, and the parser decides if
|
| a VM-looking element in the template is a VM at parsetime,
|
| #parse()-ing a set of VM declarations won't work as expected.
|
| To get around this, simply use the <code>velocimacro.library</code>
|
| facility to have Velocity load your VMs at startup.
|
| </p> |
| <strong>What is Velocimacro Autoreloading?</strong> |
| <p>
|
| There is a property, meant to be used in <i>development</i>,
|
| not production :
|
| </p> |
| <p>
|
| <code>velocimacro.library.autoreload</code>
|
| </p> |
| <p>
|
| which defaults to false. When set to true <em>along with</em>
|
| </p> |
| <p>
|
| <code><type>.resource.loader.cache = false</code>
|
| </p> |
| <p>
|
| (where <type> is the name of the resource loader that you
|
| are using, such as 'file') then the Velocity engine will automatically
|
| reload changes to your Velocimacro library files when you make them,
|
| so you do not have to dump the servlet engine (or application) or do
|
| other tricks to have your Velocimacros reloaded.
|
| </p> |
| <p>
|
| Here is what a simple set of configuration properties would look like.
|
| </p> |
| <div class="source">
|
| file.resource.loader.path = templates
|
| file.resource.loader.cache = false
|
| velocimacro.library.autoreload = true
|
| </pre></div> |
| <p>
|
| Don't keep this on in production.
|
| </p> |
| </div> |
| <a name="string_concatenation"></a> |
| <h2>String Concatenation</h2> |
| <div class="subsection"> |
| <p>
|
| A common question that developers ask is
|
| <i>How do I do String concatenation? Is there any
|
| analogue to the '+' operator in Java?</i>.
|
| </p> |
| <p>
|
| To do concatenation of references in VTL, you
|
| just have to 'put them together'. The context of
|
| where you want to put them together does matter, so
|
| we will illustrate with some examples.
|
| </p> |
| <p>
|
| In the regular 'schmoo' of a template (when you are mixing
|
| it in with regular content) :
|
| </p> |
| <div class="source">
|
| #set( $size = "Big" )
|
| #set( $name = "Ben" )
|
|
|
| The clock is $size$name.
|
| </pre></div> |
| <p>
|
| and the output will render as 'The clock is BigBen'.
|
| For more interesting cases, such as when you want to concatenate
|
| strings to pass to a method, or to set a new reference, just
|
| do
|
| </p> |
| <div class="source">
|
| #set( $size = "Big" )
|
| #set( $name = "Ben" )
|
|
|
| #set($clock = "$size$name" )
|
|
|
| The clock is $clock.
|
| </pre></div> |
| <p>
|
| Which will result in the same output. As a final example, when
|
| you want to mix in 'static' strings with your references, you may
|
| need to use 'formal references' :
|
| </p> |
| <div class="source">
|
| #set( $size = "Big" )
|
| #set( $name = "Ben" )
|
|
|
| #set($clock = "${size}Tall$name" )
|
|
|
| The clock is $clock.
|
| </pre></div> |
| <p>
|
| Now the output is 'The clock is BigTallBen'. The
|
| formal notation is needed so the parser knows you
|
| mean to use the reference '$size' versus '$sizeTall'
|
| which it would if the '{}' weren't there.
|
| </p> |
| </div> |
| </div> |
| <a name="feedback"></a> |
| <h1>Feedback</h1> |
| |
| <div class="subsection"> |
| <p>
|
| If you encounter any mistakes in this manual or have
|
| other feedback related to the Velocity User Guide, please
|
| email the
|
| <a href="mailto:dev@velocity.apache.org">Velocity developers list</a>.
|
| Thanks!
|
| </p> |
| </div> |
| </div> |
| |
| <div id="footer"> |
| Copyright © 1999-2007, <a href="http://www.apache.org/">The Apache Software Foundation</a>. |
| </div> |
| |
| </div> |
| |
| </body> |
| </html> |
| <!-- end the processing --> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |