| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <html> |
| <head> |
| <title>Apache Velocity - |
| Velocity User Guide</title> |
| <style type="text/css" media="all"> |
| @import url("../css/maven-base.css"); |
| @import url("../css/maven-theme.css"); |
| @import url("../css/site.css"); |
| </style> |
| <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> |
| <link rel="alternate" href="http://feeds.feedburner.com/ApacheVelocitySiteNews" type="application/rss+xml" title="Apache Velocity - |
| Velocity User Guide News" /> |
| <meta name="author" content=" |
| Velocity Documentation Team" /> |
| <meta name="author" content=" |
| John Castura" /> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="../../../" id="bannerLeft"> |
| |
| <img src="../images/velocity_project_wide.png" alt="" /> |
| |
| </a> |
| <span id="bannerRight"> |
| |
| <img src="../images/velocity-logo.png" alt="" /> |
| |
| </span> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="xleft"> |
| |
| <a href="http://www.apache.org/">Apache</a> |
| > |
| |
| <a href="../../../../">Velocity</a> |
| > |
| |
| <a href="../">Velocity Engine</a> |
| </div> |
| <div class="xright"> <a href="../../../devel/index.html">Engine</a> |
| | |
| <a href="../../../../tools/devel/index.html">Tools</a> |
| | |
| <a href="../../../../dvsl/devel/index.html">DVSL</a> |
| |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5>Velocity</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="../index.html">General</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../overview.html">Overview</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../getting-started.html">Getting Started</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../webapps.html">Web Applications</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../../../download.cgi">Download</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/VelocityFAQ">FAQ (Wiki)</a> |
| </li> |
| </ul> |
| <h5>Docs</h5> |
| <ul> |
| |
| <li class="none"> |
| <strong>User Guide</strong> |
| </li> |
| |
| <li class="none"> |
| <a href="../docs/developer-guide.html">Developer Guide</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../docs/vtl-reference-guide.html">VTL Reference</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../docs/anakia.html">Anakia: XML->doc tool</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../docs/texen.html">Texen: text generation</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../docs/veltag.html">Veltag: JSP taglib</a> |
| </li> |
| </ul> |
| <h5>Developers</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="../license.html">License</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../apidocs/index.html">Javadoc</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../changes-report.html">Changes in 1.5</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../jira-report.html">Resolved Issues in 1.5</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../jar-dependencies.html">Dependencies</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../../../download.cgi">Source Code Repository</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../build.html">Building from Source</a> |
| </li> |
| </ul> |
| <h5>Community</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/">Wiki</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../../../news.html">Recent News</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/PoweredByVelocity">Powered By Velocity</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/VelocityEditors">IDE/Editor Plugins</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/PublishedArticlesAndBooks">Articles and Books</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/GetInvolved">Get Involved</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../../../contact.html">Mailing Lists</a> |
| </li> |
| </ul> |
| <h5>Velocity Development</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/RoadMap">Road Map</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/CodeStandards">Coding Standards</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/DocumentationGuidelines">Documentation Guidelines</a> |
| </li> |
| |
| <li class="none"> |
| <a href="https://issues.apache.org/jira/browse/VELOCITY">Issues</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../../../who-we-are.html">Who we are</a> |
| </li> |
| </ul> |
| <h5>Translations</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="http://www.jajakarta.org/velocity/">Site (Japanese)</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../translations/user-guide_fi.html">User's Guide (Finnish)</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../translations/user-guide_fr.html">User's Guide (French)</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../translations/user-guide_es.html">User's Guide (Spanish)</a> |
| </li> |
| </ul> |
| <h5>Project Documentation</h5> |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="collapsed"> |
| <a href="../project-info.html">Project Information</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="collapsed"> |
| <a href="../project-reports.html">Project Reports</a> |
| </li> |
| </ul> |
| |
| |
| |
| <a class="poweredBy" href="../../../../" title="Apache Velocity" ><img class="poweredBy" alt="Apache Velocity" src="../images/pbv90x30.png" /></a> |
| |
| |
| |
| <a class="poweredBy" href="../../../../rss/news.rss" title="Velocity News Feed" ><img class="poweredBy" alt="Velocity News Feed" src="../images/feed-icon-24x24.jpg" /></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| |
| |
| |
| |
| |
| |
| <a name="user_guide_-_contents"></a><div class="section"><h2>User Guide - Contents</h2> |
| |
| <ol type="1"> |
| <li><a href="#AboutthisGuide">About this Guide</a></li> |
| <li><a href="#WhatisVelocity?">What is Velocity?</a></li> |
| <li><a href="#WhatcanVelocitydoforme?">What can Velocity do for me?</a> |
| <ol type="1"> |
| <li><a href="#TheMudStoreExample">The Mud Store example</a></li> |
| </ol> |
| </li> |
| <li><a href="#VelocityTemplateLanguage(VTL):AnIntroduction">Velocity Template Language (VTL): An Introduction</a></li> |
| <li><a href="#HelloVelocityWorld!">Hello Velocity World!</a></li> |
| <li><a href="#Comments">Comments</a></li> |
| <li><a href="#References">References</a> |
| <ol type="1"> |
| <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> |
| </ol> |
| </li> |
| <li><a href="#FormalReferenceNotation">Formal Reference Notation</a></li> |
| <li><a href="#QuietReferenceNotation">Quiet Reference Notation</a></li> |
| <li><a href="#Gettingliteral">Getting literal</a> |
| <ol type="1"> |
| <li><a href="#Currency">Currency</a></li> |
| <li><a href="#EscapingValidVTLReferences">Escaping Valid VTL References</a></li> |
| </ol> |
| </li> |
| <li><a href="#CaseSubstitution">Case Substitution</a></li> |
| <li><a href="#Directives">Directives</a> |
| <ol type="1"> |
| <li><a href="#Set">Set</a></li> |
| <li><a href="#StringLiterals">Literals</a></li> |
| <li><a href="#Conditionals">If-Else Statements</a> |
| <ol type="1"> |
| <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="#Velocimacros">Velocimacros</a></li> |
| </ol> |
| </li> |
| <li><a href="#EscapingVTLDirectives">Escaping VTL Directives</a></li> |
| <li><a href="#VTL:FormattingIssues">VTL: Formatting Issues</a></li> |
| <li><a href="#OtherFeaturesandMiscellany">Other Features and Miscellany</a> |
| <ol type="1"> |
| <li><a href="#Math">Math</a></li> |
| <li><a href="#RangeOperator">Range Operator</a></li> |
| <li><a href="#AdvancedIssues:Escapingand!">Advanced Issues: Escaping and |
| !</a></li> |
| <li><a href="#VelocimacroMiscellany">Velocimacro Miscellany</a></li> |
| <li><a href="#StringConcatenation">String Concatenation</a></li> |
| </ol> |
| </li> |
| <li><a href="#Feedback">Feedback</a></li> |
| </ol> |
| |
| </div> |
| |
| <a name="about_this_guide"></a><div class="section"><h2>About this Guide</h2> |
| |
| <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><div class="section"><h2>What is Velocity?</h2> |
| |
| <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/" class="externalLink">Java Server Pages</a> |
| (JSPs) or <a href="http://www.php.net/" class="externalLink">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/" class="externalLink">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><div class="section"><h2>What can Velocity do for me?</h2> |
| <a name="the_mud_store_example"></a><div class="section"><h3>The Mud Store Example</h3> |
| <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"><pre> |
| <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><div class="section"><h2>Velocity Template Language (VTL): An Introduction</h2> |
| |
| <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"><pre> |
| #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><div class="section"><h2>Hello Velocity World!</h2> |
| |
| <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"><pre> |
| <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><div class="section"><h2>Comments</h2> |
| |
| <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"><pre> |
| ## 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"><pre> |
| 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"><pre> |
| 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 such information as the document author and |
| versioning information: |
| </p> |
| |
| <div class="source"><pre> |
| #** |
| 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><div class="section"><h2>References</h2> |
| |
| <p> |
| There are three types of references in the VTL: variables, |
| properties and methods. As a designer using the VTL, you and your |
| engineers must come to an agreement on the specific names of |
| references so you can use them correctly in your templates. |
| </p> |
| |
| <p> |
| Everything coming to and from a reference is treated as a String |
| object. If there is an object that represents <em>$foo</em> (such as |
| an Integer object), then Velocity will call its |
| <code>.toString()</code> method to resolve the object into a String. |
| </p> |
| |
| <p> |
| <a name="variables"><strong>Variables</strong></a> |
| <br></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"><pre> |
| $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"><pre> |
| #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></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"><pre> |
| $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></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"><pre> |
| $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"><pre> |
| $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"><pre> |
| $sun.getPlanet( ["Earth", "Mars", "Neptune"] ) |
| ## Can't pass a parameter list with $sun.Planets |
| |
| $sisyphus.pushRock() |
| ## Velocity assumes I mean $sisyphus.getRock() |
| |
| $book.setTitle( "Homage to Catalonia" ) |
| ## Can't pass a parameter list |
| </pre></div> |
| |
| <p> |
| <a name="propertylookuprules"><strong>Property Lookup Rules</strong></a> |
| <br></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 type="1"> |
| <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 type="1"> |
| <li>getAddress()</li> |
| <li>getaddress()</li> |
| <li>get("Address")</li> |
| <li>isAddress()</li> |
| </ol> |
| </p> |
| |
| <p> |
| <a name="formalreferencenotation"><strong>Formal Reference Notation</strong></a> |
| <br></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"><pre> |
| ${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"><pre> |
| 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"><pre> |
| 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></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"><pre> |
| <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"><pre> |
| <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"><pre> |
| <input type="text" name="email" value="$!{email}"/> |
| </pre></div> |
| |
| </div> |
| |
| <a name="getting_literal"></a><div class="section"><h2>Getting literal</h2> |
| |
| <p> |
| VTL uses special characters, such as <em>$</em> and <em>#</em>, to |
| do its work, so some added care should be taken where using these |
| characters in your templates. This section deals with escaping the |
| <em>$</em> character. |
| </p> |
| |
| <p> |
| <a name="currency"><strong>Currency</strong></a> |
| <br></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></br> |
| Cases may arise where there is the potential for Velocity to get |
| confused. <em>Escaping</em> special characters is the best way to |
| handle VTL's special characters in your templates, and this can be |
| done using the backslash ( <em>\</em> ) character. |
| </p> |
| |
| <div class="source"><pre> |
| #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. |
| </p> |
| |
| <div class="source"><pre> |
| ## The following line defines $email in this template: |
| #set( $email = "foo" ) |
| $email |
| \$email |
| \\$email |
| \\\$email |
| </pre></div> |
| |
| <p> |
| renders as |
| </p> |
| |
| <div class="source"><pre> |
| foo |
| $email |
| \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"><pre> |
| $email |
| \$email |
| \\$email |
| \\\$email |
| </pre></div> |
| |
| <p> |
| renders as |
| </p> |
| |
| <div class="source"><pre> |
| $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"><pre> |
| #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> |
| It is also possible to escape VTL directives; this is described in |
| more detail in the Directives section. |
| </p> |
| |
| </div> |
| |
| <a name="case_substitution"></a><div class="section"><h2>Case Substitution</h2> |
| |
| <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"><pre> |
| $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><div class="section"><h2>Directives</h2> |
| |
| <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"><pre> |
| #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"><pre> |
| #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"><pre> |
| #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"><pre> |
| #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("bannana") 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"><pre> |
| #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"><pre> |
| #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"><pre> |
| 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"><pre> |
| |
| #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"><pre> |
| |
| #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"><pre> |
| #set( $directoryRoot = "www" ) |
| #set( $templateName = "index.vm" ) |
| #set( $template = "$directoryRoot/$templateName" ) |
| $template |
| </pre></div> |
| |
| <p> |
| The output will be |
| </p> |
| |
| <div class="source"><pre> |
| 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"><pre> |
| #set( $foo = "bar" ) |
| $foo |
| #set( $blargh = '$foo' ) |
| $blargh |
| </pre></div> |
| |
| This renders as: |
| |
| <div class="source"><pre> |
| 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"><pre> |
| #literal() |
| #foreach ($woogie in $boogie) |
| nothing will happen to $woogie |
| #end |
| #end |
| </pre></div> |
| |
| <p> |
| Renders as: |
| </p> |
| |
| <div class="source"><pre> |
| #foreach ($woogie in $boogie) |
| nothing will happen to $woogie |
| #end |
| </pre></div> |
| </div> |
| |
| |
| <a name="conditionals"></a><div class="section"><h2>Conditionals</h2> |
| |
| <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"><pre> |
| #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"><pre> |
| #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"><pre> |
| #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. |
| For further information, please see the |
| <a href="vtl-reference-guide.html">VTL Reference Guide</a> |
| Below are examples demonstrating the use of the |
| logical AND, OR and NOT operators. |
| </p> |
| |
| <div class="source"><pre> |
| ## 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"><pre> |
| ## 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"><pre> |
| |
| ##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"><pre> |
| #if( $foo == $bar)it's true!#{else}it's not!#end</li> |
| </pre></div> |
| |
| </div> |
| |
| <a name="loops"></a><div class="section"><h2>Loops</h2> |
| |
| <strong>Foreach Loop</strong> |
| |
| <p> |
| The <em>#foreach</em> element allows for looping. For example: |
| </p> |
| |
| <div class="source"><pre> |
| <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"><pre> |
| <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"><pre> |
| <table> |
| #foreach( $customer in $customerList ) |
| <tr><td>$velocityCount</td><td>$customer.Name</td></tr> |
| #end |
| </table> |
| </pre></div> |
| |
| <p> |
| The default name for the loop counter variable reference, which is |
| specified in the velocity.properties file, is $velocityCount. By |
| default the counter starts at 1, but this can be set to either 0 or |
| 1 in the <code>velocity.properties</code> file. Here's what the loop |
| counter properties section of the <code>velocity.properties</code> |
| file appears: |
| </p> |
| |
| <div class="source"><pre> |
| # Default name of the loop counter |
| # variable reference. |
| directive.foreach.counter.name = velocityCount |
| |
| # Default starting value of the loop |
| # counter variable reference. |
| directive.foreach.counter.initial.value = 1 |
| </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"><pre> |
| # The maximum allowed number of loops. |
| directive.foreach.maxloops = -1 |
| </pre></div> |
| |
| </div> |
| |
| <a name="include"></a><div class="section"><h2>Include</h2> |
| |
| <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"><pre> |
| #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"><pre> |
| #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"><pre> |
| #include( "greetings.txt", $seasonalstock ) |
| </pre></div> |
| |
| </div> |
| |
| <a name="parse"></a><div class="section"><h2>Parse</h2> |
| |
| <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"><pre> |
| #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"><pre> |
| 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"><pre> |
| $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><div class="section"><h2>Stop</h2> |
| |
| <p> |
| The <em>#stop</em> script element allows the template designer to |
| stop the execution of the template engine and return. This is useful |
| for debugging purposes. |
| </p> |
| |
| <div class="source"><pre> |
| #stop |
| </pre></div> |
| </div> |
| |
| <a name="velocimacros"></a><div class="section"><h2>Velocimacros</h2> |
| |
| <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"><pre> |
| #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"><pre> |
| #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"><pre> |
| #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"><pre> |
| #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"><pre> |
| <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"><pre> |
| #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"><pre> |
| <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"><pre> |
| #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"><pre> |
| #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> |
| |
| <strong>Velocimacro Trivia</strong> |
| |
| <p> |
| Currently, Velocimacros must be defined before they are first |
| used in a template. This means that your #macro() declarations |
| should come before using the Velocimacros. |
| </p> |
| |
| <p> |
| This is important to remember if you try to #parse() |
| a template containing inline #macro() directives. Because |
| the #parse() happens at runtime, and the parser decides if |
| a VM-looking element in the template is a VM at parsetime, |
| #parse()-ing a set of VM declarations won't work as expected. |
| To get around this, simply use the <code>velocimacro.library</code> |
| facility to have Velocity load your VMs at startup. |
| </p> |
| </div> |
| |
| <a name="escaping_vtl_directives"></a><div class="section"><h2>Escaping VTL Directives</h2> |
| <p> |
| VTL directives can be escaped with the backslash character ("\") in |
| a manner similar to valid VTL references. |
| </p> |
| |
| <div class="source"><pre> |
| ## #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"><pre> |
| #if( $jazz ) |
| Vyacheslav Ganelin |
| #end |
| </pre></div> |
| |
| <p> |
| If <em>$jazz</em> is true, the output is |
| </p> |
| <div class="source"><pre> |
| 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"><pre> |
| \#if( $jazz ) |
| Vyacheslav Ganelin |
| \#end |
| </pre></div> |
| |
| <p> |
| Whether <em>$jazz</em> is true or false, the output will be |
| </p> |
| |
| <div class="source"><pre> |
| #if($ jazz ) |
| Vyacheslav Ganelin |
| #end |
| </pre></div> |
| |
| <p> |
| In fact, because all script elements |
| are escaped, <em>$jazz</em> is never evaluated for its boolean value. |
| Suppose |
| backslashes precede script elements that are legitimately escaped: |
| </p> |
| |
| <div class="source"><pre> |
| \\#if( $jazz ) |
| Vyacheslav Ganelin |
| \\#end |
| </pre></div> |
| |
| <p> |
| In this case, if <em>$jazz</em> is true, the output is |
| </p> |
| |
| <div class="source"><pre> |
| \ 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> |
| \ |
| </pre></div> |
| |
| <p> |
| Note that |
| things start to break if script elements are not properly escaped. |
| </p> |
| |
| <div class="source"><pre> |
| \\\#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><div class="section"><h2>VTL: Formatting Issues</h2> |
| |
| <p> |
| Although VTL in this user guide is often displayed with newlines and |
| whitespaces, the VTL shown below |
| </p> |
| |
| <div class="source"><pre> |
| #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"><pre> |
| Send #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"><pre> |
| Send me |
| #set( $foo = ["$10 and ","a pie"] ) |
| #foreach( $a in $foo ) |
| $a |
| #end |
| please. |
| </pre></div> |
| |
| <p> |
| or as |
| </p> |
| |
| <div class="source"><pre> |
| 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><div class="section"><h2>Other Features and Miscellany</h2> |
| |
| <a name="math"></a><div class="section"><h3>Math</h3> |
| |
| <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"><pre> |
| #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. Any remainder can be obtained by using the modulus |
| (<em>%</em>) operator. |
| </p> |
| |
| <div class="source"><pre> |
| #set( $foo = $bar % 5 ) |
| </pre></div> |
| |
| </div> |
| |
| <a name="range_operator"></a><div class="section"><h3>Range Operator</h3> |
| |
| <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"><pre> |
| [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"><pre> |
| 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"><pre> |
| 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><div class="section"><h3>Advanced Issues: Escaping and !</h3> |
| |
| <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"><pre> |
| #set( $foo = "bar" ) |
| $\!foo |
| $\!{foo} |
| $\\!foo |
| $\\\!foo |
| </pre></div> |
| |
| <p> |
| This renders as: |
| </p> |
| |
| <div class="source"><pre> |
| $!foo |
| $!{foo} |
| $\!foo |
| $\\!foo |
| </pre></div> |
| |
| <p> |
| Contrast this with regular escaping, where <em>\</em> precedes |
| <em>$</em>: |
| </p> |
| |
| <div class="source"><pre> |
| \$foo |
| \$!foo |
| \$!{foo} |
| \\$!{foo} |
| </pre></div> |
| |
| <p> |
| This renders as: |
| </p> |
| |
| <div class="source"><pre> |
| $foo |
| $!foo |
| $!{foo} |
| \bar |
| </pre></div> |
| |
| </div> |
| |
| <a name="velocimacro_miscellany"></a><div class="section"><h3>Velocimacro Miscellany</h3> |
| |
| <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"><pre> |
| #set($stuff = "#bold('hello')" ) |
| #center( $stuff ) |
| </pre></div> |
| |
| <p> |
| You can save a step... |
| </p> |
| |
| <div class="source"><pre> |
| #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"><pre> |
| |
| #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"><pre> |
| 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"><pre> |
| #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"><pre> |
| #set($color = $bar.rowColor()) |
| #foo( $color ) |
| </pre></div> |
| |
| |
| <strong>Can I register Velocimacros via #parse() ? </strong> |
| |
| <p> |
| Currently, Velocimacros must be defined before they are first |
| used in a template. This means that your #macro() declarations |
| should come before using the Velocimacros. |
| </p> |
| |
| <p> |
| This is important to remember if you try to #parse() |
| a template containing inline #macro() directives. Because |
| the #parse() happens at runtime, and the parser decides if |
| a VM-looking element in the template is a VM at parsetime, |
| #parse()-ing a set of VM declarations won't work as expected. |
| To get around this, simply use the <code>velocimacro.library</code> |
| facility to have Velocity load your VMs at startup. |
| </p> |
| |
| |
| <strong>What is Velocimacro Autoreloading?</strong> |
| |
| <p> |
| There is a property, meant to be used in <i>development</i>, |
| not production : |
| </p> |
| |
| <p> |
| <code>velocimacro.library.autoreload</code> |
| </p> |
| |
| <p> |
| which defaults to false. When set to true <em>along with</em> |
| </p> |
| |
| <p> |
| <code><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"><pre> |
| 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><div class="section"><h3>String Concatenation</h3> |
| |
| <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"><pre> |
| #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"><pre> |
| #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"><pre> |
| #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><div class="section"><h2>Feedback</h2> |
| |
| <p> |
| If you encounter any mistakes in this manual or have |
| other feedback related to the Velocity User Guide, please |
| email the |
| <a href="mailto:velocity-user@jakarta.apache.org">Velocity user list</a>. |
| Thanks! |
| </p> |
| |
| </div> |
| |
| |
| |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright">© |
| 2000-2007 |
| |
| The Apache Software Foundation |
| |
| |
| |
| |
| |
| |
| |
| |
| Last Published: 2007-01-28 17:40:21 |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| </body> |
| </html> |