| <HTML><HEAD><TITLE>Velocity User Guide</TITLE></HEAD><BODY alink="#023264" bgcolor="#ffffff" leftmargin="4" link="#023264" marginheight="4" marginwidth="4" text="#000000" topmargin="4" vlink="#023264"><TABLE border="0" cellpadding="0" cellspacing="0" width="100%"><TR><TD align="left" valign="top"><A href="http://jakarta.apache.org/index.html"><IMG border="0" hspace="0" src="resources/jakarta-logo.gif" vspace="0"></A></TD><TD align="left" bgcolor="#ffffff" valign="top" width="100%"><IMG align="right" alt="" border="0" hspace="0" src="resources/header.gif" vspace="0"></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"></TD></TR><TR><TD background="resources/line.gif" colspan="2" height="2" width="100%"><IMG alt="" border="0" height="2" hspace="0" src="resources/line.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="100%"><TR><TD valign="top" width="1%"></TD><TD nowrap="1" valign="top" width="14%"><BR> |
| |
| <P>About</P> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="index.html">Overview</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="getting-started.html">Getting Started</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="install.html">Install</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="design.html">Design</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="contributors.html">Contributors</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="code-standards.html">Coding Standards</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="license.html">License</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="todo.html">TODO</A></LI></FONT> |
| <P>Guides</P> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="user-guide.html">User's Guide</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="developer-guide.html">Developer's Guide</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="vtl-reference-guide.html">VTL Reference Guide</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="differences.html">VM/WM Differences</A></LI></FONT> |
| <P>Tools</P> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="anakia.html">Anakia</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="texen.html">Texen</A></LI></FONT> |
| <FONT face="arial,helvetica,sanserif" size="-1"><LI><A href="migration.html">Migration To Velocity</A></LI></FONT> |
| </TD><TD align="left" valign="top" width="*"><TABLE border="0" cellpadding="3" cellspacing="0"><TR><TD><BR> |
| |
| |
| |
| |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>About this Guide</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| 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 align="justify"> |
| This is an early draft of the user guide. Although every effort has |
| been made to keep up-to-date with the development of Velocity, |
| there remain some inconsistencies between the documented and the actual |
| behaviour of Velocity. To report a mistake or offer a suggestion, |
| please send email to |
| <A href="mailto:jcastura@apache.org">jcastura@apache.org</A>. |
| </P> |
| |
| <P align="justify"> |
| Thanks for choosing Velocity! |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>What is Velocity?</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| 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 align="justify"> |
| 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> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>What can Velocity do for me?</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>The Mud Store Example</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| 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 align="justify"> |
| 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 align="justify"> |
| You meet with software engineers at your company, and everyone |
| has agreed that <VARIABLE><FONT face="courier, monospaced">$customer</FONT></VARIABLE> will hold information |
| pertaining to the customer currently logged in, |
| that <VARIABLE><FONT face="courier, monospaced">$mudsOnSpecial</FONT></VARIABLE> will be all the types mud on sale at present. |
| The <VARIABLE><FONT face="courier, monospaced">$flogger</FONT></VARIABLE> 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 align="justify"> |
| You could embed the following VTL statement in the web page: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The exact details of the <VTLDIRECTIVE><FONT face="courier, monospaced">foreach</FONT></VTLDIRECTIVE> 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 align="justify"> |
| 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 |
| <I>presence</I>. As you get more familiar with these elements, you will begin to |
| unleash the power of Velocity. |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Velocity Template Language (VTL): An Introduction</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| 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 align="justify"> |
| VTL uses <I>references</I> 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 |
| <I>statement</I> in the web page itself. Here is an example of a VTL statement |
| that could be embedded in an HTML document: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $a = "Velocity" ) |
| |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| This VTL statement, like all VTL statements, begins with the <VTLDIRECTIVE><FONT face="courier, monospaced">#</FONT></VTLDIRECTIVE> |
| character and contains a directive: <VTLDIRECTIVE><FONT face="courier, monospaced">set</FONT></VTLDIRECTIVE>. When an online visitor requests |
| your web page, the Velocity Templating Engine will search through your web page to |
| find all <VTL><FONT face="courier, monospaced">#</FONT></VTL> characters, then determine which mark the beginning of VTL |
| statements, and which of the <VTL><FONT face="courier, monospaced">#</FONT></VTL> characters that have nothing to do with VTL. |
| </P> |
| |
| <P align="justify"> |
| The <VTL><FONT face="courier, monospaced">#</FONT></VTL> character is followed by a directive, |
| <VTLDIRECTIVE><FONT face="courier, monospaced">set</FONT></VTLDIRECTIVE>. The <VTLDIRECTIVE><FONT face="courier, monospaced">set</FONT></VTLDIRECTIVE> directive uses an expression |
| (enclosed in brackets) -- an equation that assigns a <I>value</I> to a <I>variable</I>. |
| The variable is listed on the left hand side and its value on the right hand side; |
| the two are separated by an <VTL><FONT face="courier, monospaced">=</FONT></VTL> character. |
| </P> |
| |
| <P align="justify"> |
| In the example above, the variable is <VARIABLE><FONT face="courier, monospaced">$a</FONT></VARIABLE> and the value is |
| <VARIABLE><FONT face="courier, monospaced">Velocity</FONT></VARIABLE>. This variable, like all references, begins with the |
| <VARIABLE><FONT face="courier, monospaced">$</FONT></VARIABLE> character. Values are always enclosed in quotes; with Velocity |
| there is no confusion about data types, as only strings (text-based information) may |
| be passed to variables. |
| </P> |
| |
| <P align="justify"> |
| The following rule of thumb may be useful to better understand how Velocity works: |
| <B>References begin with <VTL><FONT face="courier, monospaced">$</FONT></VTL> and are used to get something. Directives begin |
| with <VTL><FONT face="courier, monospaced">#</FONT></VTL> and are used to do something.</B> |
| </P> |
| |
| <P align="justify"> |
| In the example above, <VTLDIRECTIVE><FONT face="courier, monospaced">#set</FONT></VTLDIRECTIVE> is used to assign a value to |
| a variable. The variable, <VARIABLE><FONT face="courier, monospaced">$a</FONT></VARIABLE>, can then be used in the template |
| to output "Velocity". |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Hello Velocity World!</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| 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 <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> and later referenced. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| <HTML> |
| <BODY> |
| #set( $foo = "Velocity" ) |
| Hello $foo World! |
| </BODY> |
| <HTML> |
| |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The result is a web page that prints "Hello Velocity World!". |
| </P> |
| |
| <P align="justify"> |
| 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 <VTLDIRECTIVE><FONT face="courier, monospaced">set</FONT></VTLDIRECTIVE> directive will be revisited in greater detail |
| later on. |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Comments</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| ## This is a single line comment. |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| A single line comment begins with <VTL><FONT face="courier, monospaced">##</FONT></VTL> 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 <VTL><FONT face="courier, monospaced">#*</FONT></VTL> |
| and end with <VTL><FONT face="courier, monospaced">*#</FONT></VTL>, are available to handle this scenario. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Here's a few examples to clarify how single line and multi-line comments |
| work: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>References, revisited</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| 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 align="justify"> |
| Everything coming to and from a reference is treated as a String object. |
| If there is an object that represents <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> (such as an Integer object), |
| then Velocity will call its <CODE><FONT face="courier, monospaced">.toString()</FONT></CODE> method to resolve the |
| object into a String. |
| </P> |
| |
| <P align="justify"> |
| <B>Variables</B> |
| <BR> |
| The shorthand notation of a variable consists of a leading "$" character |
| followed by a VTL <I>Identifier</I>. 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: alphabetic, |
| numeric (0 .. 9), hyphen ("-"), and underscore ("_"). |
| Here are some examples of valid variable references in the VTL: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| $foo |
| $mudSlinger |
| $mud-slinger |
| $mud_slinger |
| $mudSlinger1 |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| When VTL references a variable, such as <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE>, the variable can |
| get its value from either a <VTLDIRECTIVE><FONT face="courier, monospaced">set</FONT></VTLDIRECTIVE> directive in the template, or from the |
| Java code. For example, if the Java variable <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> |
| has the value <VARIABLE><FONT face="courier, monospaced">bar</FONT></VARIABLE> at the time the template is requested, |
| <VARIABLE><FONT face="courier, monospaced">bar</FONT></VARIABLE> replaces all instances of <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> on the web |
| page. Alternatively, if I include the statement |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $foo = "bar" ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| the output will be the same for all instances of <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> |
| that follow this directive. |
| </P> |
| |
| <P align="justify"> |
| <B>Properties</B> |
| <BR> |
| The second flavor of VTL references are properties, and properties have |
| a distinctive format. The shorthand notation consists of a leading <VTL><FONT face="courier, monospaced">$</FONT></VTL> |
| 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| $customer.Address |
| $purchase.Total |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Take the first example, <VARIABLE><FONT face="courier, monospaced">$customer.Address</FONT></VARIABLE>. It can |
| have two meanings. It can mean, |
| Look in the hashtable identified as <VARIABLE><FONT face="courier, monospaced">customer</FONT></VARIABLE> and return the |
| value associated with the key <VARIABLE><FONT face="courier, monospaced">Address</FONT></VARIABLE>. But |
| <VARIABLE><FONT face="courier, monospaced">$customer.Address</FONT></VARIABLE> can also be referring to a method (references |
| that refer to methods will be discussed |
| in the next section); <VARIABLE><FONT face="courier, monospaced">$customer.Address</FONT></VARIABLE> could be an |
| abbreviated way of writing <VARIABLE><FONT face="courier, monospaced">$customer.getAddress()</FONT></VARIABLE>. |
| When your page is requested, Velocity will determine which of these |
| two possibilities makes sense, and then return the appropriate value. |
| </P> |
| |
| <P align="justify"> |
| <B>Methods</B> |
| <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 <I>Method Body</I>. 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| $customer.getAddress() |
| $purchase.getTotal() |
| $page.setTitle( "My Home Page" ) |
| $person.setAttributes( ["Strange", "Weird", "Excited"] ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The first two examples -- |
| <VARIABLE><FONT face="courier, monospaced">$customer.getAddress()</FONT></VARIABLE> and <VARIABLE><FONT face="courier, monospaced">$purchase.getTotal()</FONT></VARIABLE> |
| -- may look similiar to those used in the Properties section above, |
| <VARIABLE><FONT face="courier, monospaced">$customer.Address</FONT></VARIABLE> |
| and <VARIABLE><FONT face="courier, monospaced">$purchase.Total</FONT></VARIABLE>. If you guessed that these examples must |
| be related some in some fashion, you are correct! |
| </P> |
| |
| <P align="justify"> |
| VTL Properties can be used as a shorthand notation for VTL Methods. The |
| Property <VARIABLE><FONT face="courier, monospaced">$customer.Address</FONT></VARIABLE> has the exact same effect as |
| using the Method <VARIABLE><FONT face="courier, monospaced">$customer.getAddress()</FONT></VARIABLE>. 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 align="justify"> |
| The shorthand notation can be used for the following Methods |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| $sun.getPlanets() |
| $annelid.getDirt() |
| $album.getPhoto() |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| <B>Formal Reference Notation</B> |
| <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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| ${mudSlinger} |
| ${customer.Address} |
| ${purchase.getTotal()} |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| 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 align="justify"> |
| Suppose you were |
| constructing a sentence on the fly where <VARIABLE><FONT face="courier, monospaced">$vice</FONT></VARIABLE> 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| Jack is a $vicemaniac. |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| There is ambiguity here, and Velocity assumes that <VARIABLE><FONT face="courier, monospaced">$vicemaniac</FONT></VARIABLE>, |
| not <VARIABLE><FONT face="courier, monospaced">$vice</FONT></VARIABLE>, is the Identifier that you mean to use. Finding no |
| value for <VARIABLE><FONT face="courier, monospaced">$vicemaniac</FONT></VARIABLE>, it will return <VARIABLE><FONT face="courier, monospaced">$vicemaniac</FONT></VARIABLE>. |
| Using formal notation can resolve this problem. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| Jack is a ${vice}maniac. |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Now Velocity knows that <VARIABLE><FONT face="courier, monospaced">$vice</FONT></VARIABLE>, not <VARIABLE><FONT face="courier, monospaced">$vicemaniac</FONT></VARIABLE>, is |
| the reference. Formal notation is often useful when references are directly adjacent to text |
| in a template. |
| </P> |
| |
| |
| <P align="justify"> |
| <B>Quiet Reference Notation</B> |
| <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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| <input type="text" name="email" value="$email"/> |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| When the form initially loads, the variable |
| reference <VARIABLE><FONT face="courier, monospaced">$email</FONT></VARIABLE> 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 <VARIABLE><FONT face="courier, monospaced">$email</FONT></VARIABLE> in the |
| VTL you would use <VARIABLE><FONT face="courier, monospaced">$!email</FONT></VARIABLE>. So the above example |
| would look like the following: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| <input type="text" name="email" value="$!email"/> |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Now when the form is initially loaded and |
| <VARIABLE><FONT face="courier, monospaced">$email</FONT></VARIABLE> still has no value, an empty string will |
| be output instead of "$email". |
| </P> |
| |
| <P align="justify"> |
| Formal and quiet reference notation can be used together, |
| as demonstrated below. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| <input type="text" name="email" value="$!{email}"/> |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Getting literal</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| VTL uses special characters, such as <VTL><FONT face="courier, monospaced">$</FONT></VTL> and <VTL><FONT face="courier, monospaced">#</FONT></VTL>, to do its work, so some |
| added care should be taken where using these characters in your templates. This section deals |
| with escaping the <VTL><FONT face="courier, monospaced">$</FONT></VTL> character. |
| </P> |
| |
| <P align="justify"> |
| <B>Currency</B> |
| <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 align="justify"> |
| <B>Escaping Valid VTL References</B> |
| <BR> |
| Cases may arise where there is the potential for Velocity |
| to get confused. <I>Escaping</I> special characters is the best way |
| to handle VTL's special characters in your templates, and this can be |
| done using the backslash ("\") character. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $email = "foo" ) |
| $email |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| If Velocity encounters a reference in your VTL template to |
| <VARIABLE><FONT face="courier, monospaced">$email</FONT></VARIABLE>, it will search the Context for a corresponding |
| value. Here the output will be "foo", because <VARIABLE><FONT face="courier, monospaced">$email</FONT></VARIABLE> is defined. |
| If <VARIABLE><FONT face="courier, monospaced">$email</FONT></VARIABLE> is not defined, the output will be "$email". |
| </P> |
| |
| <P align="justify"> |
| Suppose that <VARIABLE><FONT face="courier, monospaced">$email</FONT></VARIABLE> is defined (for example, if it has the value |
| "foo"), and that you want to output "$email". There are a few ways of doing this, |
| but the simplest is to use the escape character. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| ## The following line defines $email in this template: |
| #set( $email = "foo" ) |
| |
| ## The output of the following line will be $email's value: foo |
| $email |
| |
| ## The output of the following line will be a literal: $email |
| \$email |
| |
| ## The escape character binds from the left. The output of the following line will |
| ## reflect this in its output: \$email |
| \\$email |
| |
| ## The bind-from-left rule causes \\\$email to render as \\$email |
| \\\$email |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Compare these examples to those in which <VARIABLE><FONT face="courier, monospaced">$email</FONT></VARIABLE> is not defined. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| ## $email is undefined |
| |
| ## $email renders as $email |
| $email |
| |
| ## \$email renders as \$email |
| \$email |
| |
| ## \\$email renders as \\$email |
| \\$email |
| |
| ## \\\$email renders as \\\$email |
| \\\$email |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Notice Velocity handles references that are defined differently from those |
| that have not been defined. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| ## Here is a set directive that gives $foo the value "gibbous" |
| #set( $foo = "gibbous" ) |
| |
| ## The escape character is at work in the following line |
| $moon = $foo |
| #* |
| The output will be: $moon = gibbous |
| $moon is output as a literal because it is undefined. |
| The value of $foo is output because it is defined. |
| *# |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| It is also possible to escape VTL directives; this is described in more detail in |
| the Directives section. |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Summary: References</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| $foo |
| |
| $foo.getBar() |
| ## is the same as |
| $foo.Bar |
| |
| $data.getUser("jon") |
| ## is the same as |
| $data.User("jon") |
| |
| |
| $data.getRequest().getServerName() |
| ## is the same as |
| $data.Request.ServerName |
| ## is the same as |
| ${data.Request.ServerName} |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| 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> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Directives</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| References allow template designers to generate dynamic content for |
| web sites, while <I>directives</I> -- 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 align="justify"> |
| <B>#set</B> |
| <BR> |
| The <VTLDIRECTIVE><FONT face="courier, monospaced">#set</FONT></VTLDIRECTIVE> 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $primate = "monkey" ) |
| #set( $customer.Behavior = $primate ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| 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 align="justify"> |
| <BLOCKQUOTE><UL> |
| <LI>Variable reference</LI> |
| <LI>String literal</LI> |
| <LI>Property reference</LI> |
| <LI>Method reference</LI> |
| <LI>Number literal</LI> |
| <LI>Object array</LI> |
| </UL></BLOCKQUOTE> |
| </P> |
| |
| <P align="justify"> |
| These examples demonstrate each of the aforementioned |
| types: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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"] ) ##object array |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The RHS can also be a simple arithmetic expression: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $value = $foo + 1 ) |
| #set( $value = $bar - 1 ) |
| #set( $value = $foo * $bar ) |
| #set( $value = $foo / $bar ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Unlike some of the other Velocity directives, the <VTLDIRECTIVE><FONT face="courier, monospaced">#set</FONT></VTLDIRECTIVE> directive |
| does not have an <VTLDIRECTIVE><FONT face="courier, monospaced">#end</FONT></VTLDIRECTIVE> statement. Instead, the left bracket marks |
| the beginning and the right bracket marks the end of an assignment. |
| </P> |
| |
| <P align="justify"> |
| <B>String Literals</B> |
| </P> |
| |
| <P align="justify"> |
| When using the <VTLDIRECTIVE><FONT face="courier, monospaced">#set</FONT></VTLDIRECTIVE> directive, string literals that are enclosed |
| in double quote characters will be parsed and rendered, as shown: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $directoryRoot = "www" ) |
| #set( $templateName = "index.vm" ) |
| #set( $template = "$directoryRoot/$templateName" ) |
| $template |
| |
| #* |
| The output will be: www/index.vm |
| *# |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| However, when the string literal is enclosed in single quote characters, it will not be parsed: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $foo = "bar" ) |
| $foo |
| #set( $blargh = '$foo' ) |
| $blargh |
| |
| #* |
| This renders as: |
| bar |
| $foo |
| *# |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| By default, this feature of using single quotes to render unparsed text is available in Velocity. |
| This default can be changed by editing <FILENAME><I>velocity.properties</I></FILENAME> such that |
| <CODE><FONT face="courier, monospaced">stringliterals.interpolate=false</FONT></CODE>. |
| </P> |
| |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Conditionals</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <B>If / ElseIf / Else</B> |
| <P align="justify"> |
| The <VTLDIRECTIVE><FONT face="courier, monospaced">#if</FONT></VTLDIRECTIVE> 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #if( $foo ) |
| <strong>Velocity!</strong> |
| #end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The variable <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> is evaluated to determine whether it is true, which will happen |
| under one of two circumstances: (i) <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> is a boolean (true/false) which |
| has a true value, or (ii) the value is not null. The content between the |
| <VTLDIRECTIVE><FONT face="courier, monospaced">#if</FONT></VTLDIRECTIVE> and the <VTLDIRECTIVE><FONT face="courier, monospaced">#end</FONT></VTLDIRECTIVE> statements become the output if |
| the evaluation is true. In this case, if <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> is true, the |
| output will be: "Velocity!". Conversely, if <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> has a null |
| value, or if it is a boolean false, the statement evaluates as false, and |
| there is no output. |
| </P> |
| |
| <P align="justify"> |
| An <VTLDIRECTIVE><FONT face="courier, monospaced">#elseif</FONT></VTLDIRECTIVE> or <VTLDIRECTIVE><FONT face="courier, monospaced">#else</FONT></VTLDIRECTIVE> element can be used with an <VTLDIRECTIVE><FONT face="courier, monospaced">#if</FONT></VTLDIRECTIVE> 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 <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> has a |
| value of 15 and <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> has a value of 6. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| In this example, <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> is greater than or equal to 10, so the Velocity |
| Templating Engine makes the output of the if |
| statement <B>Go East</B>. If <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> had a value of 10 and <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> |
| had a value of 6.1, then <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> is neither greater than 10 nor equal to |
| 10, and <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> is not equal to 6. All if and elseif statements are false, |
| so the output is <B>Go West</B>. |
| </P> |
| |
| <P align="justify"> |
| <B>Relational and Logical Operators</B> |
| </P> |
| |
| |
| <P align="justify"> |
| 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Two kinds of logical operators, logical AND and logical OR, are expected to be added to Velocity soon. |
| Below is an example of an if statement using logical AND. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #if( $foo && $bar ) |
| <strong>Velocity Rocks!</strong> |
| #end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The if statement will only evaluate to true if both <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> and |
| <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> are true. If <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> is false, the expression will evaluate |
| to false; <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> will not be evaluated. If <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> is true, the |
| Velocity Templating Engine will then check the value of <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE>; |
| if <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> is true, then the entire expression is |
| true and <B>Velocity Rocks!</B> becomes the output. |
| If <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> is false, then there will be no output; the entire |
| expression is false. |
| </P> |
| |
| <P align="justify"> |
| 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #if( $foo || $bar ) |
| <strong>Velocity Rocks Again!</strong> |
| #end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| If <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> is true, the Velocity Templating Engine has no |
| need to look at <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE>; whether <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> is true or false, the |
| expression will be true, and <B>Velocity Rocks |
| Again!</B> will be output. If <VARIABLE><FONT face="courier, monospaced">$foo</FONT></VARIABLE> is false, however, |
| <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> must be checked. In this case, if <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> is also false, |
| the expression evaluates to false and there is no output. |
| On the other hand, if <VARIABLE><FONT face="courier, monospaced">$bar</FONT></VARIABLE> is true, then the entire |
| expression is true, and the output is <B>Velocity Rocks |
| Again!</B> |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Loops</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| <B>Foreach Loop</B> |
| <P align="justify"> |
| The <VTLDIRECTIVE><FONT face="courier, monospaced">#foreach</FONT></VTLDIRECTIVE> element allows for looping. For example: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| <ul> |
| #foreach( $product in $allProducts ) |
| <li>$product</li> |
| #end |
| </ul> |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| This <VTLDIRECTIVE><FONT face="courier, monospaced">#foreach</FONT></VTLDIRECTIVE> loop causes the <VARIABLE><FONT face="courier, monospaced">$allProducts</FONT></VARIABLE> list (the object) to be |
| looped over for all of the products (targets) in the list. Each time |
| through the loop, the value from <VARIABLE><FONT face="courier, monospaced">$allProducts</FONT></VARIABLE> is placed into the |
| <VARIABLE><FONT face="courier, monospaced">$product</FONT></VARIABLE> variable. |
| </P> |
| |
| <P align="justify"> |
| The contents of the <VARIABLE><FONT face="courier, monospaced">$allProducts</FONT></VARIABLE> variable is a Vector, a Hashtable |
| or an Array. The value assigned to the <VARIABLE><FONT face="courier, monospaced">$product</FONT></VARIABLE> variable is a Java |
| Object and can be referenced from a variable as such. For example, if |
| <VARIABLE><FONT face="courier, monospaced">$product</FONT></VARIABLE> was really a Product class in Java, its name could be retrieved |
| by referencing the <VARIABLE><FONT face="courier, monospaced">$product.Name</FONT></VARIABLE> method (ie: <VARIABLE><FONT face="courier, monospaced">$Product.getName()</FONT></VARIABLE>). |
| </P> |
| |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Include</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| <P align="justify"> |
| The <VTLDIRECTIVE><FONT face="courier, monospaced">#include</FONT></VTLDIRECTIVE> script element allows the template designer to import a |
| local file, which is then inserted into the location where the <VTLDIRECTIVE><FONT face="courier, monospaced">#include</FONT></VTLDIRECTIVE> |
| 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #include( "one.txt" ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The file to which the <VTLDIRECTIVE><FONT face="courier, monospaced">#include</FONT></VTLDIRECTIVE> directive refers is enclosed in quotes. If more than one file will be included, they should be separated by commas. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #include( "one.gif","two.txt","three.htm" ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| 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 targetting output according to criteria determined when the page request is submitted. Here is an example showing both a filename and a variable. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #include( "greetings.txt", $seasonalstock ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Parse</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| <P align="justify"> |
| The <VTLDIRECTIVE><FONT face="courier, monospaced">#parse</FONT></VTLDIRECTIVE> 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #parse( "me.vm" ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Like the <VTLDIRECTIVE><FONT face="courier, monospaced">#include</FONT></VTLDIRECTIVE> directive, <VTLDIRECTIVE><FONT face="courier, monospaced">#parse</FONT></VTLDIRECTIVE> |
| can take a variable rather than a template. Any templates to which <VTLDIRECTIVE><FONT face="courier, monospaced">#parse</FONT></VTLDIRECTIVE> |
| refers must be included under TEMPLATE_ROOT. Unlike the <VTLDIRECTIVE><FONT face="courier, monospaced">#include</FONT></VTLDIRECTIVE> directive, |
| <VTLDIRECTIVE><FONT face="courier, monospaced">#parse</FONT></VTLDIRECTIVE> will only take a single argument. |
| </P> |
| |
| <P align="justify"> |
| VTL templates can have <VTLDIRECTIVE><FONT face="courier, monospaced">#parse</FONT></VTLDIRECTIVE> statements referring to templates that in turn |
| have <VTLDIRECTIVE><FONT face="courier, monospaced">#parse</FONT></VTLDIRECTIVE> statements. By default set to 10, the <VTL><FONT face="courier, monospaced">parse_directive.maxdepth</FONT></VTL> |
| line of the <FILENAME><I>velocity.properties</I></FILENAME> allows users to customize maximum number of |
| <VTLDIRECTIVE><FONT face="courier, monospaced">#parse</FONT></VTLDIRECTIVE> referrals that can occur from a single |
| template. (Note: If the <VTL><FONT face="courier, monospaced">parse_directive.maxdepth</FONT></VTL> property is absent from the |
| <FILENAME><I>velocity.properties</I></FILENAME> file, Velocity will set this default to 10.) |
| Recursion is permitted, for example, if the template <FILENAME><I>dofoo.vm</I></FILENAME> contains the following lines: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| Count down. |
| #set( $count = 8 ) |
| #parse( "parsefoo.vm" ) |
| All done with dofoo.vm! |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| It would reference the template <FILENAME><I>parsefoo.vm</I></FILENAME>, which might contain the following VTL: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| $count |
| #set( $count = $count - 1 ) |
| #if( $count > 0 ) |
| #parse( "parsefoo.vm" ) |
| #else |
| All done with parsefoo.vm! |
| #end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| After "Count down." is displayed, Velocity passes through <FILENAME><I>parsefoo.vm</I></FILENAME>, 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 |
| <FILENAME><I>dofoo.vm</I></FILENAME> and output the "All done with dofoo.vm!" message. |
| </P> |
| |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Stop</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| <P align="justify"> |
| The <VTLDIRECTIVE><FONT face="courier, monospaced">#stop</FONT></VTLDIRECTIVE> script element allows the template designer to stop the execution |
| of the template engine and return. This is useful for debugging purposes. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #stop |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Velocimacros</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| <P align="justify"> |
| The <VTLDIRECTIVE><FONT face="courier, monospaced">#macro</FONT></VTLDIRECTIVE> 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #macro( d ) |
| <tr><td></td></tr> |
| #end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The Velocimacro being defined in this example is <VTL><FONT face="courier, monospaced">d</FONT></VTL>, and it can be called in a manner |
| analogous to any other VTL directive: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #d |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| When this template is called, Velocity would replace <VTL><FONT face="courier, monospaced">#d</FONT></VTL> with a row containing a single, |
| empty data cell. |
| </P> |
| |
| <P align="justify"> |
| A Velocimacro could take any number 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #macro( tablerows $color $somelist ) |
| #foreach( $something in $somelist ) |
| <tr><td bgcolor=$color>$something</td></tr> |
| #end |
| #end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The Velocimacro being defined in this example, <VTL><FONT face="courier, monospaced">tablerows</FONT></VTL>, takes two arguments. |
| The first argument takes the place of <VARIABLE><FONT face="courier, monospaced">$color</FONT></VARIABLE>, and the second |
| argument takes the place of <VARIABLE><FONT face="courier, monospaced">$somelist</FONT></VARIABLE>. |
| </P> |
| |
| <P align="justify"> |
| Anything that can be put into a VTL template can go into the body of a Velocimacro. The <VTL><FONT face="courier, monospaced">tablerows</FONT></VTL> |
| Velocimacro is a <VTL><FONT face="courier, monospaced">foreach</FONT></VTL> statement. There are two <VTL><FONT face="courier, monospaced">#end</FONT></VTL> statements in the definition of |
| the <VTL><FONT face="courier, monospaced">#tablerows</FONT></VTL> Velocimacro; the first belongs to the |
| <VTLDIRECTIVE><FONT face="courier, monospaced">#foreach</FONT></VTLDIRECTIVE>, the second ends the Velocimacro definition. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] ) |
| #set( $color = "blue" ) |
| <table> |
| #tablerows( $color $greatlakes ) |
| </table> |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Notice that <VARIABLE><FONT face="courier, monospaced">$greatlakes</FONT></VARIABLE> takes the place of <VARIABLE><FONT face="courier, monospaced">$somelist</FONT></VARIABLE>. |
| When the <VTL><FONT face="courier, monospaced">#tablerows</FONT></VTL> Velocimacro is called in this situation, the following output is generated: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Velocimacros can be defined <I>inline</I> 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 align="justify"> |
| Several lines in the <FILENAME><I>velocity.properties</I></FILENAME> file allow for flexible |
| implementation of Velocimacros: |
| </P> |
| |
| <P align="justify"> |
| <CODE><FONT face="courier, monospaced">velocimacro.library.global</FONT></CODE> - This is the name of the global Velocimacros |
| template library. By default, <CODE><FONT face="courier, monospaced">velocimacro.library.global=VM_global_template.vm</FONT></CODE>. |
| This file, which must be found in the template path, contains useful macros that are |
| shipped with the Velocity distribution. |
| </P> |
| |
| <P align="justify"> |
| <CODE><FONT face="courier, monospaced">velocimacro.library.local</FONT></CODE> - Adding this line to the <FILENAME><I>velocity.properties</I></FILENAME> |
| file allows the template designer to define a local Velocimacros |
| template library. Velocity users can use the local template library to define their |
| own Velocimacros and keep these in a file other than the global defaults. |
| </P> |
| |
| <P align="justify"> |
| <CODE><FONT face="courier, monospaced">velocimacro.permissions.allowInline</FONT></CODE> - This property, which has |
| possible values of true or false, determines whether Velocimacros |
| can be defined in regular templates. The default, false, limits template designers |
| to defining Velocimacros in the global/local templates. |
| </P> |
| |
| <P align="justify"> |
| <CODE><FONT face="courier, monospaced">velocimacro.permissions.allowInlineToOverride</FONT></CODE> - When Velocimacros can be |
| defined in both global/local template library and in regular templates, it becomes |
| possible for a Velocimacro to be defined more than once. With possible values of |
| true or false, this property allows the user to specify which Velocimacro will |
| take precedence over the other. The default, <CODE><FONT face="courier, monospaced">false</FONT></CODE>, allows Velocimacros |
| defined in the global/local template libraries to take precedence over those defined |
| in regular templates. |
| </P> |
| |
| <P align="justify"> |
| Were the <VTL><FONT face="courier, monospaced">#tablerows</FONT></VTL> Velocimacro defined in the local 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 <FILENAME><I>mushroom.vm</I></FILENAME> |
| devoted to all things fungi, the <VTL><FONT face="courier, monospaced">#tablerows</FONT></VTL> Velocimacro could be invoked |
| to list the parts of a typical mushroom: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $parts = ["volva","stipe","annulus","gills","pileus"] ) |
| #set( $cellbgcol = "#CC00FF" ) |
| <table> |
| #tablerows( $cellbgcol $parts ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| When fulfilling a request for <FILENAME><I>mushroom.vm</I></FILENAME>, Velocity would find the |
| <VTL><FONT face="courier, monospaced">#tablerows</FONT></VTL> Velocimacro in the local template library (defined in the |
| <FILENAME><I>velocity.properties</I></FILENAME> file) and generate the following output: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Escaping VTL Directives</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| VTL directives can be escaped with the backslash character ("\") in a manner similar |
| to valid VTL references. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| 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> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #if( $jazz ) |
| Vyacheslav Ganelin |
| #end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| If <VARIABLE><FONT face="courier, monospaced">$jazz</FONT></VARIABLE> is true, the output is "Vyacheslav |
| Ganelin"; if <VARIABLE><FONT face="courier, monospaced">$jazz</FONT></VARIABLE> is false, there is no |
| output. Escaping script elements alters the output. Consider the |
| following case: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| \#if( $jazz ) |
| Vyacheslav Ganelin |
| \#end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Whether <VARIABLE><FONT face="courier, monospaced">$jazz</FONT></VARIABLE> is true or false, the output will be |
| "#if( $jazz ) Vyacheslav Ganelin #end"; in fact, because |
| all script elements are escaped the truth of |
| <VARIABLE><FONT face="courier, monospaced">$jazz</FONT></VARIABLE> is never checked. Suppose backslashes precede |
| script elements that are legitimately escaped: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| \\#if( $jazz ) |
| Vyacheslav Ganelin |
| \\#end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| In this case, if <VARIABLE><FONT face="courier, monospaced">$jazz</FONT></VARIABLE> is true, the output is |
| "\ Vyacheslav Ganelin \". If <VARIABLE><FONT face="courier, monospaced">$jazz</FONT></VARIABLE> is false, |
| there is no output. Note that things start to break if script elements |
| are not properly escaped. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| \\\#if( $jazz ) |
| Vyacheslave Ganelin |
| \\#end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Here the <VTL><FONT face="courier, monospaced">#if</FONT></VTL> is escaped, but there is an <VTL><FONT face="courier, monospaced">#end</FONT></VTL> |
| remaining; having too many endings will cause a parsing error. |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>VTL: Formatting Issues</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| Although VTL in this user guide is often displayed with |
| newlines and whitespaces, the VTL shown below |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] ) |
| #foreach( $shogun in $imperial ) |
| $shogun |
| #end |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| is equally valid as the following snippet that Geir Magnusson Jr. |
| posted to the Velocity user listserve to illustrate a completely |
| unrelated point: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please. |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Velocity's behaviour is to gobble up excess whitespace. The preceding |
| directive can be written as |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| Send me |
| #set( $foo = ["$10 and ","a cake"] ) |
| #foreach( $a in $foo ) |
| $a |
| #end |
| please. |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| or as |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| Send me |
| #set($foo = ["$10 and ","a cake"]) |
| #foreach ($a in $foo )$a |
| #end please. |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| In each case the output will be the same. |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Other Features</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Math</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| Velocity has a handful of built-in mathematical functions that can be used |
| in templates with the <VTLDIRECTIVE><FONT face="courier, monospaced">set</FONT></VTLDIRECTIVE> directive. The following |
| equations are examples of addition, subtraction, multiplication and division, |
| respectively: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $foo = $bar + 3 ) |
| #set( $foo = $bar - 4 ) |
| #set( $foo = $bar * 6 ) |
| #set( $foo = $bar / 2 ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| When a division operation is performed, the result will be an integer. Any remainder |
| can be obtained by using the remainder (<VTL><FONT face="courier, monospaced">%</FONT></VTL>) operand. |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $foo = $bar % 5 ) |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Only integers (...-2, -1, 0, 1, 2...) are permissible when performing |
| mathematical equations in Velocity; when a non-integer is used, it is |
| logged and a null will be returned as the output. |
| </P> |
| |
| <P align="justify"> |
| Velocity has a built-in way of dealing with division by zero. In the following example |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $foo = 5 ) |
| #set( $bar = $foo - 5 ) |
| #set( $uhoh = $foo / $bar ) |
| $uhoh |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| The reference <VARIABLE><FONT face="courier, monospaced">$uhoh</FONT></VARIABLE> is assigned the value of five divided by zero. |
| When Velocity renders this template, the output will be: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| $uhoh |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Range Operator</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| The range operator can be used in conjunction with <VTLDIRECTIVE><FONT face="courier, monospaced">#set</FONT></VTLDIRECTIVE> |
| and <VTLDIRECTIVE><FONT face="courier, monospaced">#foreach</FONT></VTLDIRECTIVE> statements. Useful for its ability to |
| produce an object array containing integers, the range operator has the following |
| construction: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| [n..m] |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Both <VTL><FONT face="courier, monospaced">n</FONT></VTL> and <VTL><FONT face="courier, monospaced">m</FONT></VTL> must either be or produce integers. Whether |
| <VTL><FONT face="courier, monospaced">m</FONT></VTL> is greater than or less than <VTL><FONT face="courier, monospaced">n</FONT></VTL> will not matter; in this |
| case the range will simply count down. Examples showing the use of the range |
| operator as provided below: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><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></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Produces the following output: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| First example: |
| 1 2 3 4 5 |
| |
| Second example: |
| 2 1 0 -1 -2 |
| |
| Third example: |
| 0 1 |
| |
| Fourth example: |
| [1..3] |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| <P align="justify"> |
| Note that the range operator only produces the array when used in |
| conjunction with <VTLDIRECTIVE><FONT face="courier, monospaced">#set</FONT></VTLDIRECTIVE> |
| and <VTLDIRECTIVE><FONT face="courier, monospaced">#foreach</FONT></VTLDIRECTIVE> directives, as demonstrated |
| in the fourth example. |
| </P> |
| |
| <P align="justify"> |
| 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> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| <DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="5"><B>Advanced Isseus: Escaping and !</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000" face="arial,helvetica,sanserif"> |
| |
| <P align="justify"> |
| When a reference is silenced with the <VTL><FONT face="courier, monospaced">!</FONT></VTL> character and |
| the <VTL><FONT face="courier, monospaced">!</FONT></VTL> character preceded by an escape characters ("\"), |
| the reference is handled in a special way. Note the differences |
| between regular escaping (where the escape character precedes the |
| <VTL><FONT face="courier, monospaced">$</FONT></VTL> character, and this case, where is follows it: |
| </P> |
| |
| <P align="justify"> |
| <DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE> |
| #set( $foo = "bar" ) |
| |
| # The special case, where "\" precedes "!": |
| $\!foo # This renders as: $!foo |
| $\!{foo} # This renders as: $!{foo} |
| $\\!foo # This renders as: $\!foo |
| $\\\!foo # This renders as: $\\!foo |
| |
| # Contrast this with regular escaping, where "\" precedes "$": |
| \$foo # This renders as: \#$foo |
| \$!foo # This renders as: \$!foo |
| \$!{foo} # This renders as: \$!{foo} |
| \\$!{foo} # This renders as: \bar |
| </PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV> |
| </P> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| </FONT></TD></TR></TABLE></DIV><BR> |
| |
| |
| </TD></TR></TABLE></TD></TR></TABLE><BR><TABLE border="0" cellpadding="0" cellspacing="0" width="100%"><TR><TD bgcolor="#023264"><IMG height="1" src="resources/resources.gif" width="1"></TD></TR><TR><TD align="center"><FONT color="#023264" face="arial,helvetica,sanserif" size="-1"><I> |
| Copyright © 2000-2001 The Apache Software Foundation. |
| All Rights Reserved. |
| </I></FONT></TD></TR></TABLE></BODY></HTML> |
