jvanzyl 00/10/26 19:26:57
Modified: docs contributors.html todo.html user-guide.html
vtl-reference-guide.html
Log:
- john's updates.
Revision Changes Path
1.11 +2 -2 jakarta-velocity/docs/contributors.html
Index: contributors.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/contributors.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- contributors.html 2000/10/22 02:07:05 1.10
+++ contributors.html 2000/10/27 02:26:55 1.11
@@ -138,9 +138,9 @@
<TR>
<TD align="left" bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"><FONT
color="#000000" face="arial,helvetica,sanserif" size="-1">John Castura
</FONT></TD>
- <TD align="left" bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"><FONT
color="#000000" face="arial,helvetica,sanserif" size="-1"><A
href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A>
+ <TD align="left" bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"><FONT
color="#000000" face="arial,helvetica,sanserif" size="-1"><A
href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A>
</FONT></TD>
- <TD align="left" bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"><FONT
color="#000000" face="arial,helvetica,sanserif" size="-1">Compusense
+ <TD align="left" bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"><FONT
color="#000000" face="arial,helvetica,sanserif" size="-1">-
</FONT></TD>
<TD align="left" bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"><FONT
color="#000000" face="arial,helvetica,sanserif" size="-1">Apprentice
</FONT></TD>
1.7 +43 -22 jakarta-velocity/docs/todo.html
Index: todo.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/todo.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- todo.html 2000/10/22 02:07:05 1.6
+++ todo.html 2000/10/27 02:26:55 1.7
@@ -36,6 +36,7 @@
<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
List</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">
<B>Runtime API</B>
<BR>
The Velocity Runtime is the single access point for all
@@ -43,8 +44,9 @@
Runtime should be defined so that in the span between
the 0.5 Milestone release and a 1.0 release, the Runtime
API changes as little as possible.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>JUnit Test Suite</B>
<BR>
A JUnit test suite would allow Velocity developers to
@@ -54,8 +56,9 @@
effects for users. <A href="mailto:[EMAIL PROTECTED]">Daniel L. Rall</A>
has started us off with some code so you may want to contact
him if you are interested in working on a JUnit test suite.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Directive Interface</B>
<BR>
Right now there is a very thin interface for directives, but
@@ -63,8 +66,9 @@
interface is not intended to be used outside core Velocity
developers (it is not intended to be a public API), but it
probably makes sense to shield directive creators from JavaCC.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Context</B>
<BR>
The Velocity Context class is still fairly primitive. It
@@ -74,15 +78,17 @@
make that process efficient; how to stamp items in
the context with expiry durations so that items can
be cached and how this might work.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Sample Applications</B>
<BR>
Any type of sample application would be useful to
help new developers get acquainted with
Velocity. Any suggestions are welcome.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>User's Guide</B>
<BR>
This would be a guide for designers who would
@@ -92,8 +98,9 @@
of the VTL syntax. <A href="mailto:[EMAIL PROTECTED]">Jason van Zyl</A>
has started work on this with John Castura, but any and all
suggestions are welcome.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Developer Guide</B>
<BR>
This would be a guide for developers who would use
@@ -102,8 +109,9 @@
<A href="mailto:[EMAIL PROTECTED]">Jason van Zyl</A> is
currently working on this guide, but any and all suggestions
are welcome.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Template Loader System</B>
<BR>
The template loader system is functional but could probably use an
@@ -112,15 +120,16 @@
should be corrected. We could utilize some
object caching/pooling code from Turbine, or JServ, or the
Avalon Server Framework.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Caching</B>
<BR>
It would be good to have a discussion about how objects
in the context should be cached, how the caching
should be specified, and who should control the
caching: the designer, by specifying something in the template;
- the developer,
+ the developer,
by placing expiry times on objects placed in the context;
or a third party, such as a content manager. For example,
say an array consisting of a top 10 list of books is
@@ -134,8 +143,9 @@
of some sort? The groundwork has be laid for a flexible
caching system in Velocity, but this discussion would be
one of usage and policy.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Parser Pool</B>
<BR>
It would be good to create a pool of parsers that could
@@ -145,15 +155,17 @@
parsers might alleviate any potential bottlenecks. Again,
object caching/pooling code could be borrowed from Turbine,
JServ, or the Avalon Server Framework.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>UML Overview</B>
<BR>
It would great to include a set of comprehensive
UML diagrams that describe Velocity. This would
allow new developers to get up to speed quickly.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Velocity Profiling</B>
<BR>
If someone is handy with one of the standard profilers,
@@ -164,14 +176,16 @@
to have a configuration of a setup for a common profiler
so that anyone who wanted to do some profiling could do
so in a consistent manner.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Encoding Caching</B>
<BR>
What would this entail? And how could we implement an
efficient encoding caching mechanism.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Plugins</B>
<BR>
It would be good to allow plugins in the form of JAR files
@@ -182,15 +196,17 @@
a template. It might be good to package this sort of utility
in a JAR file so that there are no dependencies in the
Velocity build for a specific utility.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Context Tools</B>
<BR>
What kind of tools might be good to add to Velocity? There
are several utilties that have been created in Turbine that
might be good to move over to the Velocity code base.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Syntax Dumper</B>
<BR>
Right now there is a primitive syntax dumper in the Velocity
@@ -200,16 +216,18 @@
the AST node types. It would be good to tailor dump methods
for particular AST node types so that the structure produced
is a little clearer.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Syntax Checker</B>
<BR>
It would be good to have a standard syntax checker, something
that would find all syntax errors and report them to the
designer in some intelligible format. This tool could be
hooked into various designer tools like DreamWeaver.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Extended Properties</B>
<BR>
There are classes that are present in JServ, Turbine and Cocoon
@@ -217,22 +235,25 @@
files to be 'included', and allows the concatentation of the values
of multiply defined properties. These classes are very good and
should be integrated into Velocity.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Compiler</B>
<BR>
It would be great to have a template compiler. There is a great
utility called JavaClass that provides a very clean and simple way
to create class files, and there is also some byte code generating
code present in the DynamicJava package that could be utilized.
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>IDE Integration</B>
<BR>
How could Velocity be integrated into standard IDEs like
JBuilder and VisualAge?
- <P align="justify"></P>
+ </P>
+ <P align="justify">
<B>Scripting Language Integration</B>
<BR>
This is something that has been discussed on the Turbine
@@ -243,7 +264,7 @@
an entire servlet solution with Velocity. As most of these
scripting solutions provide a compiler, performance would still
remain at an acceptable level.
- <P align="justify"></P>
+ </P>
1.8 +331 -107 jakarta-velocity/docs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/user-guide.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- user-guide.html 2000/10/22 02:07:05 1.7
+++ user-guide.html 2000/10/27 02:26:56 1.8
@@ -68,8 +68,8 @@
<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 have an online store that specializes in selling mud. Let's call
- it "The Online Mud Store". Business is thriving. Your customers
+ 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
@@ -89,12 +89,12 @@
<P align="justify">
You meet with software engineers at your company, and everyone
- has agreed that the variable $customer will hold information
+ has agreed that $customer will hold information
pertaining to the customer currently logged in,
that $mudsOnSpecial will be all the types mud on sale at present.
The $flogger object contains methods that help with promotion.
For the task at hand, let's concern ourselves only with these three
- variables. Remember, you don't need to worry about how the software
+ 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.
@@ -126,7 +126,7 @@
<P align="justify">
The extact details of the foreach statement will be described
in greater depth shortly; what's important is the impact this short
- script will have on your web site. When a customer with a
+ 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,
@@ -137,10 +137,10 @@
</FONT></TD></TR></TABLE></DIV><BR>
<P align="justify">
- VTL has many other elements documented in the VTL Reference, 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.
+ 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>
@@ -156,9 +156,11 @@
</P>
<P align="justify">
- VTL uses <I>statements</I> to embed dynamic content in a web site. Statements
- are made up of <I>elements</I>. Here is an example of a VTL statement
- embedded in an HTML document:
+ 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">
@@ -169,29 +171,35 @@
</P>
<P align="justify">
- This VTL statement, like all VTL statements that contain directives, begins
- with the # character. When an online visitor requests
- your web page, the
- Velocity Templating Engine will search through your web page to find all
- # characters, then determine which mark the beginning of VTL
+ This VTL statement, like all VTL statements, begins with the #
+ character and contains a directive (set. When an online visitor requests
+ your web page, the Velocity Templating Engine will search through your web page
to
+ find all # characters, then determine which mark the beginning of VTL
statements, and which of the # characters that have nothing to do with VTL.
</P>
<P align="justify">
- The # character is followed by a directive,
- set. The set directive works in conjunction with other
- script elements to assign a <I>value</I> to a <I>variable</I>. The variable
- is listed on the left and its value on the right; the two are separated by an
+ The # character is followed by a directive, set. The
+ set directive uses an equation to assign 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
= character.
</P>
<P align="justify">
In the example above, the variable is $a and the value is
- Velocity. Variables <I>always</I> begin with $ characters.
+ Velocity. References <I>always</I> begin with $
+ characters; all variables are references, ergo all variables begin
+ with $ characters.
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>
+ </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,
@@ -215,135 +223,351 @@
</P>
<P align="justify">
- To make your VTL directive statements more readable, we encourage you to
+ 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 set 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">
- The set example is useful for demonstrating the syntax of a simple VTL
- statement, but not very exciting for revealing the capabilities of Velocity.
+ Adding comments to your VTL 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="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ ## This is a single line comment.
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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 ## 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. Multiline comments, which begin with #*
+ and end with *#, are available to handle this scenario.
+ </P>
+
+ <P align="justify">
+ <DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
- </FONT></TD></TR></TABLE></DIV><BR>
+ This is text that is outside the comment block. Online visitors can see it.
- <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
Reference</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">
+ #*
+ Thus begins a multi-line comment. Online visitors won't see this text because
+ the Velocity Templating Engine will ignore it.
+ *#
- <P align="justify">
- Velocity references its variables in a fashion similar to
- <A href="http://www.perl.com">Perl</A> (i.e. they
- use a $), but takes advantage of some Java principles that
- template designers will find easy to use. For example:
- </P>
+ Here is text outside the comment block; it is visible.
+
+ </PRE></TD></TR></TABLE></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" colspan="3" height="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV>
+ </P>
- <P align="justify">
- <DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
- $foo
- $foo.getBar() or $foo.Bar
- $data.getUser("jon") or $data.User("jon")
- $data.getRequest().getServerName() or $data.Request.ServerName
- </PRE></TD></TR></TABLE></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" colspan="3" height="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">
- These examples illustrate alternative uses for the same variables.
- Velocity takes advantage of Java's introspection and
- bean features to resolve the variable names to both objects in the Context
- as well as the objects methods. It is possible to embed and evaluate
- variables almost anywhere in your template.
- </P>
-
- <P align="justify">
- Everything coming to and from a variable is treated as a String object.
+ <P align="justify">
+ <DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ This text is visible. ## This text is not.
+ This text is visible.
+ This text is visible. #* This text, as part of a comment block, is not.
+ This text is not visible; it is also part of the comment block.
+ This text still not visible. *# This text is outside the comment block, so
+ it is visible.
+ ## This text is not visible.
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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 $foo (such as an Integer object),
then Velocity will call its .toString() method to resolve the
object into a String.
- </P>
+ </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>
- <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>Variables</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">
+ <DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ $foo
+ $mudSlinger
+ $mud-slinger
+ $mud_slinger
+ $mudSlinger1
+ </PRE></TD></TR></TABLE></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" colspan="3" height="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV>
+ </P>
- <P align="justify">
- VTL variables can reference three types of objects: variables,
- properties, and methods.
-
- <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>Variables</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">
- A VTL variable, such as $foo, can get its value from
- either a set directive in the template, or from the
+ <P align="justify">
+ When VTL references a variable, such as $foo, the variable can
+ get its value from either a set directive in the template, or from the
Java code. For example, if the Java variable $foo
has the value bar at the time the template is requested,
bar replaces all instances of $foo on the web
page. Alternatively, if I include the statement
- </P>
+ </P>
- <P align="justify">
+ <P align="justify">
<DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
#set $foo = "bar"
</PRE></TD></TR></TABLE></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" colspan="3" height="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></DIV>
- </P>
+ </P>
- <P align="justify">
+ <P align="justify">
the output will be the same for all instances of $foo
that follow this directive.
- </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>Properties</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 second flavour of VTL variable references properties, and it has
- a distinctive format:
- </P>
-
- <P align="justify">
+ </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 "$"
+ 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="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
- $whomever.Address
+ $customer.Address
+ $purchase.Total
</PRE></TD></TR></TABLE></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" colspan="3" height="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, $whomever.Address can have two meanings. It can mean,
- Look in the hashtable identified as whomever and return the
- value associated with the key Address. This syntax can also
- be referring to a method (variables that refer to methods will be discussed
- in the next section); $whomever.Address could be an
- abbreviated way of writing getAddress("whomever").
+ </P>
+
+ <P align="justify">
+ Take the first example, $customer.Address. It can
+ have two meanings. It can mean,
+ Look in the hashtable identified as customer and return the
+ value associated with the key Address. But
+ $customer.Address can also be referring to a method (references
+ that refer to methods will be discussed
+ in the next section); $customer.Address could be an
+ abbreviated way of writing $customer.getAddress().
When your page is requested, Velocity will determine which of these
two possibilities makes sense, and then return the appropriate value.
- </P>
-
- </FONT></TD></TR></TABLE></DIV><BR>
+ </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="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ $customer.getAddress()
+ $purchase.getTotal()
+ $page.setTitle("My Home Page")
+ $person.setAttributes("Strange", "Weird",
"Excited")
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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 --
+ $customer.getAddress() and $purchase.getTotal()
+ -- may look similiar to those used in the Properties section above,
+ $customer.Address
+ and $purchase.Total. 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 $customer.Address has 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">
+ The shorthand notation can be used for the following Methods
+ </P>
+
+ <P align="justify">
+ <DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ $sun.getPlanets()
+ $annelid.getDirt()
+ $album.getPhoto()
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ $sun.getPlanets("Earth", "Mars", "Neptune")
+ ## Can't pass a parameter list with $sun.Planets
+
+ $annelid.digestDirt
+ ## $annelid.Segments assumes I mean $annelid.getSegements()
- <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>Methods</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">
+ $book.getChapter("1", "4", "11")
+ ## Can't pass a parameter list with $book.Chapter
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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>
+ 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="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ ${mudSlinger}
+ ${customer.Address}
+ ${purchase.getTotal()}
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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. Suppose 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 attempt to use the following in
+ a VTL template:
+</P>
+
+<P align="justify">
+ <DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ Jack is a $vicemaniac.
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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 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 this reference:
+</P>
+
+<P align="justify">
+ <DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ Jack is a ${vice}maniac.
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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 $vice, not $vicemaniac, is your
+ Identifier. The formal notation usually
+ comes in handy when you have references directly adjacent
+ to text in your templates.
+</P>
+
+
+<P align="justify">
+ <B>Quiet Reference Notation</B>
+ <BR>
+ When Velocity encounters a reference that is undefined,
+ its normal behavior is to output the image
+ of the reference. For example, if you have
+ the following VTL as part of an HTML page:
+</P>
+
+<P align="justify">
+ <DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ <input type="text" name="email"
value="$email"/>
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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 $email has no value, but you prefer the
+ a blank text field to one with a value of "$email".
+ Using the quiet reference notation can circumvent Velocity's
+ normal behavior; instead of using $email in the
+ VTL you would use $!email. So the above example
+ would look like the following:
+</P>
+
+<P align="justify">
+ <DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
+ <input type="text" name="email"
value="$!email"/>
+ </PRE></TD></TR></TABLE></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" colspan="3" height="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
+ $email still has no value, an empty string will
+ be output instead of "$email".
+</P>
+
+ <B>Summary: References</B>
<P align="justify">
- A method is defined in the Java code and is capable of doing something
- useful, like running a calculation or arriving at a decision. VTL
- variables that refer to Java methods have the following format:
+ Velocity references take advantage of some Java principles that
+ template designers will find easy to use. For example:
</P>
-
+
<P align="justify">
<DIV align="left"><TABLE border="0" cellpadding="0" cellspacing="0"><TR><TD
bgcolor="#023264" colspan="3" height="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"><TABLE><TR><TD align="left"><PRE>
- $purchase.getTotalPrice()
+ $foo
+ $foo.getBar() or $foo.Bar
+ $data.getUser("jon") or $data.User("jon")
+ $data.getRequest().getServerName() or $data.Request.ServerName
</PRE></TD></TR></TABLE></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" colspan="3" height="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, the getTotalPrice() method, defined in the Java code,
- will presumably return the total price of a purchase that is being tracked.
- Note that this could also have been written,
- $purchase.TotalPrice.
+ 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>
- </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>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">
- <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">
+<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">
<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>If / ElseIf / Else
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">
<P align="justify">
1.8 +46 -58 jakarta-velocity/docs/vtl-reference-guide.html
Index: vtl-reference-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/vtl-reference-guide.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- vtl-reference-guide.html 2000/10/22 02:07:05 1.7
+++ vtl-reference-guide.html 2000/10/27 02:26:56 1.8
@@ -36,21 +36,20 @@
<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
+ 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">
<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:
+ 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">
@@ -66,8 +65,8 @@
<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>.
+ 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>
@@ -82,9 +81,9 @@
<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
+ 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
@@ -105,9 +104,9 @@
$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
+ be related some in some fashion, you are correct! VTL Properties
+ are simply a shorthand for notation for VTL Methods. The
+ Property $customer.Address has 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.
@@ -131,13 +130,13 @@
<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
+ for references, but in some cases the formal
+ notation is required for correct processing. Suppose 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
+ "Jack is a kleptomaniac.". You might attempt to use the following in
a VTL template:
</P>
@@ -148,12 +147,11 @@
</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
+ 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:
+ notation for this reference:
</P>
<P align="justify">
@@ -163,20 +161,19 @@
</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
+ Now Velocity knows that $vice, not $vicemaniac, is your
+ Identifier. The formal notation usually
+ comes in handy when you have references directly adjacent
to text in your templates.
</P>
<P align="justify">
<B>Quiet Reference Notation</B>
<BR>
- Velocity's normal behavior upon encountering a
- reference that is undefined is to output the image
- of the reference. For example, say you have have
- the following VTL as part of an HTML for you
- want to produce:
+ When Velocity encounters a reference that is undefined,
+ its normal behavior is to output the image
+ of the reference. For example, if you have
+ the following VTL as part of an HTML page:
</P>
<P align="justify">
@@ -186,12 +183,11 @@
</P>
<P align="justify">
- Now when the form initially loads the variable
- reference $email has no value, but you don't
- want the text field to have a value of "$email"
- it should be blank. To circumvent Velocity's
- normal behavior you use the quiet reference
- notation: so instead of using $email in the
+ When the form initially loads the variable
+ reference $email has no value, but you prefer the
+ a blank text field to one with a value of "$email".
+ Using the quiet reference notation can circumvent Velocity's
+ normal behavior; instead of using $email in the
VTL you would use $!email. So the above example
would look like the following:
</P>
@@ -203,8 +199,8 @@
</P>
<P align="justify">
- Now when the form is initially loaded, while
- $email has no value yet, an empty string will
+ Now when the form is initially loaded and
+ $email still has no value, an empty string will
be output instead of "$email".
</P>
@@ -215,8 +211,8 @@
<B>#set</B>
<BR>
The #set directive is used for setting the value of
- a reference. The reference being assigned a value can
- either be a variable reference or a property reference:
+ a reference. A value can be assigned to either a variable
+ reference or a property reference:
</P>
<P align="justify">
@@ -244,8 +240,8 @@
</P>
<P align="justify">
- Here is an example of showing the use of the
- above mentioned types:
+ Here are examples demonstrating the
+ aforementioned types:
</P>
<P align="justify">
@@ -275,7 +271,7 @@
<P align="justify">
<B>#foreach</B>
<BR>
- The #foreach directive provide a simple way of looping
+ The #foreach directive provides a simple way of looping
through a list of objects:
</P>
@@ -316,11 +312,11 @@
<P align="justify">
The default name for the loop counter variable
- reference is $velocityCounter, but you can specify
- this in the velocity.properties file. You can also
- specify whether the counter should start at 0 or 1.
- Here's what the properties look like in the
- velocity.properties file:
+ reference, which is specified in the velocity.properties
+ file, is $velocityCount. By default the counter starts
+ at 1, but this can be set to either 0 or 1 in the
+ velocity.properties file. Here's what the loop counter
+ properties section of the velocity.properties file appears:
</P>
<P align="justify">
@@ -335,14 +331,6 @@
</PRE></TD></TR></TABLE></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" colspan="3" height="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>#if/#elseif/#else</B>
- <BR>
-</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>Macros</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>
