jvanzyl 00/10/19 09:38:46
Added: docs vtl-reference-guide.html
Log:
- adding VTL guide.
Revision Changes Path
1.1 jakarta-velocity/docs/vtl-reference-guide.html
Index: vtl-reference-guide.html
===================================================================
<HTML><HEAD><TITLE>VTL Reference 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></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></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>
</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">
This guide is meant to be the definitive reference for
the Velocity Template Language (VTL).
</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</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 must come to an agreement
with your engineers as to what the specific names of references are so
you can use them correctly in your templates.
</P>
<P align="justify">
<B>Variables</B>
<BR>
Variables are references that consist of a leading "$" character
followed by a VTL <I>Identifier</I>. A VTL <I>Identifier</I> must start with
an alphabetic character (a .. z or A .. Z), the rest of the
characters must be of the following types: an alphabetic character,
a numeric character (0 .. 9), a hyphen character ("-"),
or an underscore character ("_"). These are 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>
$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">
<B>Properties</B>
<BR>
Properties are references that consist of a leading "$"
character followed a VTL <I>Identifier</I>, followed by
of dot character (".") then another VTL <I>Identifier</I>.
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">
<B>Methods</B>
<BR>
Methods are references that consist of a leading "$"
character followed a VTL <I>Identifier</I>, followed
by a VTL <I>Method Body</I>. A VTL <I>Method Body</I>
consists of a VTL <I>Identifier</I> 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">
Now you may have noticed that the first two examples
$customer.getAddress() and $purchase.getTotal() look very
similiar to the first two example Properties $customer.Address
and $purchase.Total. If you guessed that these examples must
be related some in some fashion you are correct! VTL Properties
are simply a shorthand for notation for VTL Methods. Using the
Property $customer.Address would have the exact same effect as
using the Method $customer.getAddress(). 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">
<B>Formal Reference Notation</B>
<BR>
In the examples listed above the shorthand notation for
references was used, but there is a formal notation that
looks 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>
${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 there are some cases where the formal
notation is required for correct processing. Say you were
constructing a sentence on the fly where $vice was to be
used as the base word in the noun of a sentence. Say you
wanted 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.". You might have the following in
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>
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">
But as you might have guessed this will confuse Velocity
because Velocity can't tell that $vice is the Identifer
that you mean to use. It will assume that $vicemaniac
is the Identifier and try to use that to find an appropriate
value. You can get around this problem by using the formal
notation for a reference:
</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 you want to use $vice as your
Identifier and not $vicemaniac. The formal notation usually
comes in handy when you have references directly ajacent
to text in your templates.
</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">
</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 The Apache Software Foundation.
All Rights Reserved.
</I></FONT></TD></TR></TABLE></BODY></HTML>
