jvanzyl 00/10/15 17:43:03
Modified: docs contributors.html index.html install.html todo.html
user-guide.html velocity.pdf
Log:
- john edited some of the docs, and added some example to the users
guide.
Revision Changes Path
1.7 +6 -5 jakarta-velocity/docs/contributors.html
Index: contributors.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/contributors.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- contributors.html 2000/10/13 18:49:12 1.6
+++ contributors.html 2000/10/16 00:43:01 1.7
@@ -137,11 +137,12 @@
</P>
<P align="justify">
- We would also like to make special mention, and give credit for the
- original idea Velocity is based on, as Velocity is
- a new implementation of the model/view/controller architecture,
- concept, and syntax of the WebMacro Servlet Framework (www.webmacro.org)
- originally envisioned and implemented by Justin Wells at Semiotek Inc.
+ Velocity is a new implementation of the Model-View-Controller
+ architecture,
+ concept, and syntax of the WebMacro Servlet Framework
+ (<A href="http://www.webmacro.org">www.webmacro.org</A>),
+ which was originally envisioned and implemented by Justin Wells at
+ Semiotek, Inc.
</P>
</FONT></TD></TR></TABLE></DIV><BR>
1.7 +1 -1 jakarta-velocity/docs/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/index.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- index.html 2000/10/13 18:49:13 1.6
+++ index.html 2000/10/16 00:43:01 1.7
@@ -22,7 +22,7 @@
<P align="justify">
Velocity is a Java-based template engine. It permits web page designers
- to use simple yet powerful script elements that reference methods
+ to use simple yet powerful template language to reference objects
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
1.6 +5 -2 jakarta-velocity/docs/install.html
Index: install.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/install.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- install.html 2000/10/13 18:49:13 1.5
+++ install.html 2000/10/16 00:43:01 1.6
@@ -21,7 +21,9 @@
<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>Installation</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">
- Everything required to build Velocity comes with the distribution.
+ Everything required to build Velocity comes with the distribution, which
+ be obtained via <A
href="http://jakarta.apache.org/getinvolved/cvsindex.html">CVS</A>
+ or <A
href="http://jakarta.apache.org/builds/jakarta-velocity/nightly/">downloaded</A>.
</P>
</FONT></TD></TR></TABLE></DIV><BR>
@@ -29,7 +31,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>Compiling</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">
- On Unix/Linux, execute the following script in the velocity/build directory:
+ On Unix/Linux, sh to the velocity/build directory and execute the following
+ script:
</P>
<P align="justify">
1.4 +21 -21 jakarta-velocity/docs/todo.html
Index: todo.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/todo.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- todo.html 2000/10/13 18:49:15 1.3
+++ todo.html 2000/10/16 00:43:01 1.4
@@ -22,12 +22,11 @@
<P align="justify">
This is an informal document describing what needs to
-be done in the Velocity code base, and the
-Velocity documentation. If you need more detailed help, please
-send mail to the mailing list
-(<A
href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A>)
-and ask your specific questions there. The list below is vaguely in order of
-importance.
+be done in the Velocity code base and the
+Velocity documentation. If you need more detailed help, or have specific
+questions, please send mail to the mailing list
+(<A
href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A>).
+The Todo list that follows is roughly in order of importance.
</P>
</FONT></TD></TR></TABLE></DIV><BR>
@@ -37,7 +36,7 @@
<B>Runtime API</B>
<BR>
The Velocity Runtime is the single access point for all
- of Velocity's functionality. A standard API for the
+ Velocity's functionality. A standard API for the
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.
@@ -77,7 +76,7 @@
<B>Sample Applications</B>
<BR>
Any type of sample application would be useful to
- help kickstart new developers get acquainted with
+ help new developers get acquainted with
Velocity. Any suggestions are welcome.
<P align="justify"></P>
@@ -95,7 +94,7 @@
<B>Developer Guide</B>
<BR>
This would be a guide for developers who would use
- Velocity as a stand-alone servlet tool, or in conjuction
+ Velocity as a standalone servlet tool, or in conjuction
with a servlet controller framework like Turbine.
<A href="mailto:[EMAIL PROTECTED]">Jason van Zyl</A> is
currently working on this guide, but any and all suggestions
@@ -117,13 +116,14 @@
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
- by place expiry times on objects placed in the context,
- or a third party like a content manager. For example,
+ caching: the designer, by specifying something in the template;
+ 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
placed in the context. This top 10 list might be valid
for a 24 hour period: how should that be specified? Say
- a content manager decides that this list is now valid
+ a content manager later decides this list will be valid
for a week. Do they tell the designer, who in turn changes
the template, or could we provide a mechanism that would
allow a content manager to change the default expiry time
@@ -147,7 +147,7 @@
<B>UML Overview</B>
<BR>
It would great to include a set of comprehensive
- UML diagrams that describe Velocity in order to
+ UML diagrams that describe Velocity. This would
allow new developers to get up to speed quickly.
<P align="justify"></P>
@@ -183,7 +183,7 @@
<B>Context Tools</B>
<BR>
- What kind of tools might be good to add to Velocity. There
+ 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>
@@ -191,7 +191,7 @@
<B>Syntax Dumper</B>
<BR>
Right now there is a primitive syntax dumper in the Velocity
- code base, but it could be improved. This tool is very helpful
+ code base, and it could be improved. This tool is very helpful
in debugging, and it is also good for creating directives.
It basically has a simple dump method that is used for all
the AST node types. It would be good to tailor dump methods
@@ -201,7 +201,7 @@
<B>Syntax Checker</B>
<BR>
- It would be good to have a standard syntax checker. Something
+ 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.
@@ -219,8 +219,8 @@
<B>Compiler</B>
<BR>
It would be great to have a template compiler. There is a great
- utility call JavaClass that provides a very clean and simple way
- to create class files; there is also some byte code generating
+ 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>
@@ -234,10 +234,10 @@
<BR>
This is something that has been discussed on the Turbine
list. Allowing Context building classes to be written
- in JPython, Rhino or another scripting language. This would
+ in JPython, Rhino or other scripting languages would
dramatically improve development time and might allow technically
proficient web designers who are familiar JavaScript to create
- an entire servlet solution with Velocity. And as most of these
+ 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>
1.2 +301 -29 jakarta-velocity/docs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/user-guide.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- user-guide.html 2000/10/13 18:52:23 1.1
+++ user-guide.html 2000/10/16 00:43:01 1.2
@@ -1,4 +1,4 @@
-<HTML><HEAD><TITLE>Velocity User's 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>
+<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></P>
<FONT face="arial,helvetica,sanserif" size="-1"><LI><A
href="index.html">Overview</A></LI></FONT>
@@ -18,34 +18,224 @@
-<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>User's
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">
+ <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 provide an easy way for designers
- to get aquainted with Velocity. Velocity may be used as a
- stand-alone servlet framework, or may be used in conjuction
- with another servlet framework like
- <A href="http://java.apache.org/turbine/">Turbine</A>,
- but in both cases a designer will be using the Velocity
- Template Language (VTL) to incorporate dynamic content
- into a site design.
-</P>
-
-<P align="justify">
- The VTL is meant to provide the easiest, simplest, and
- cleanest way to render dynamic content in a page design.
-</P>
+ <P align="justify">
+ The Velocity User Guide is intended to help page designers and content
+ providers get aquainted 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>
-</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>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>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">
+ <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>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">
+ <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
+ 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 buy 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 it occurs to you one day, 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 the variable $customer will hold all the
+ information about the customer currently logged in,
+ that $mudsOnSpecial will be all the types mud on sale at
+ present, and that the
+ $flogger() variable contains methods for promoting
+ particular types of mud.
+ 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
+ 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 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
+ 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>
+
+ </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.
+ </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>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>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:
+ </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 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
+ 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
+ = 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.
+ 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">
+ 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 $foo 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 your VTL directive statements 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>
+
+ <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.
+ </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
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">
+
<P align="justify">
- Velocity references its variables in a fashion similar to Perl (i.e. they
- use a $), but takes advantage of some Java principles that template
- designers will find easy to use. For example:
+ 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>
<P align="justify">
@@ -53,15 +243,16 @@
$foo
$foo.getBar() or $foo.Bar
$data.getUser("jon") or $data.User("jon")
- $data.getRequest().getServerName() or $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>
+ $data.getRequest().getServerName() or $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 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 variables almost
- anywhere in your template. These variables can be evaluated.
+ as well as the objects methods. It is possible to embed and evaluate
+ variables almost anywhere in your template.
</P>
<P align="justify">
@@ -70,7 +261,87 @@
then Velocity will call its .toString() method to resolve the
object into a String.
</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">
+ VTL variables can reference three types of objects: variables,
+ properties, and methods.
+ </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">
+ A VTL variable, such as $foo, 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 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 $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">
+ <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>
+ $whomever.Address
+ </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, $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").
+ 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>
+
+ <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">
+
+ <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:
+ </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>
+ $purchase.getTotalPrice()
+ </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, 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.
+ </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>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">
@@ -233,11 +504,12 @@
<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 VelociDoc comment block and
- may be used to store author and versioning
+ This is a VTL comment block and
+ may be used to store such information
+ as the document author and versioning
information:
- @author Designer Dude
+ @author
@version 5
*#
1.3 +173 -155 jakarta-velocity/docs/velocity.pdf
<<Binary file>>
