jvanzyl 00/10/25 15:33:59
Modified: xdocs contributors.xml todo.xml user-guide.xml
vtl-reference-guide.xml
Log:
- xdoc fixes. Thanks again to Fedor.
Revision Changes Path
1.11 +120 -120 jakarta-velocity/xdocs/contributors.xml
Index: contributors.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/contributors.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- contributors.xml 2000/10/24 17:35:10 1.10
+++ contributors.xml 2000/10/25 22:33:55 1.11
@@ -1,120 +1,120 @@
-<?xml version="1.0"?>
-
-<document>
-
- <header>
- <title>Velocity Contributors</title>
- <subtitle>Velocity Contributors</subtitle>
- <authors>
- <person name="Velocity Documentation Team" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
-
-<body>
-
-<s1 title="Contributors">
-
-<p>
- The people listed below have made significant contributions to Velocity by
- working long and hard to make quality software for the rest of the world to
- use.
-</p>
-
-<p>
- If you would like to contribute to Velocity, please see the
- <link href="todo.html">to do</link> list to find areas where you can
contribute.
- If there is nothing in there that suits your interest, but you still have
- ideas, please feel free to suggest them on the mailing list.
-</p>
-
-<p>
- Velocity follows a certification scheme similar to the one that is outlined
- on
- <link
href="http://www.advogato.org/certs.html">http://www.advogato.org/certs.html</link>.
- Names on this list are ordered from first contributor at the top to the most
recent contributor
- at the bottom.
-</p>
-
-<p>
-<table>
-
-<tr>
- <td>Jason van Zyl</td>
- <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
- <td>Periapt</td>
- <td>Master</td>
-</tr>
-
-<tr>
- <td>Jon S. Stevens</td>
- <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
- <td>CollabNet</td>
- <td>Master</td>
-</tr>
-
-<tr>
- <td>Daniel L. Rall</td>
- <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
- <td>CollabNet</td>
- <td>Master</td>
-</tr>
-
-<tr>
- <td>Dave Bryson</td>
- <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
- <td>Miceda-Data</td>
- <td>Master</td>
-</tr>
-
-<tr>
- <td>Josh Lucas</td>
- <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
- <td>CollabNet</td>
- <td>Master</td>
-</tr>
-
-<tr>
- <td>Bob McWhirter</td>
- <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
- <td>Werken & Sons Company</td>
- <td>Master</td>
-</tr>
-
-<tr>
- <td>Terence Parr</td>
- <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
- <td>JGuru</td>
- <td>Master</td>
-</tr>
-
-<tr>
- <td>Geir Magnusson Jr.</td>
- <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
- <td>Independent</td>
- <td>Master</td>
-</tr>
-
-<tr>
- <td>John Castura</td>
- <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
- <td> </td>
- <td>Apprentice</td>
-</tr>
-
-</table>
-
-</p>
-
-<p>
- Velocity is a new implementation of the Model-View-Controller
- architecture,
- concept, and syntax of the WebMacro Servlet Framework
- (<link href="http://www.webmacro.org">www.webmacro.org</link>),
- which was originally envisioned and implemented by Justin Wells at
- Semiotek, Inc.
-</p>
-
-</s1>
-
-</body>
-</document>
+<?xml version="1.0"?>
+
+<document>
+
+ <header>
+ <title>Velocity Contributors</title>
+ <subtitle>Velocity Contributors</subtitle>
+ <authors>
+ <person name="Velocity Documentation Team" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+
+<body>
+
+<s1 title="Contributors">
+
+<p>
+ The people listed below have made significant contributions to Velocity by
+ working long and hard to make quality software for the rest of the world to
+ use.
+</p>
+
+<p>
+ If you would like to contribute to Velocity, please see the
+ <link href="todo.html">to do</link> list to find areas where you can
contribute.
+ If there is nothing in there that suits your interest, but you still have
+ ideas, please feel free to suggest them on the mailing list.
+</p>
+
+<p>
+ Velocity follows a certification scheme similar to the one that is outlined
+ on
+ <link
href="http://www.advogato.org/certs.html">http://www.advogato.org/certs.html</link>.
+ Names on this list are ordered from first contributor at the top to the most
recent contributor
+ at the bottom.
+</p>
+
+<p>
+<table>
+
+<tr>
+ <td>Jason van Zyl</td>
+ <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
+ <td>Periapt</td>
+ <td>Master</td>
+</tr>
+
+<tr>
+ <td>Jon S. Stevens</td>
+ <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
+ <td>CollabNet</td>
+ <td>Master</td>
+</tr>
+
+<tr>
+ <td>Daniel L. Rall</td>
+ <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
+ <td>CollabNet</td>
+ <td>Master</td>
+</tr>
+
+<tr>
+ <td>Dave Bryson</td>
+ <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
+ <td>Miceda-Data</td>
+ <td>Master</td>
+</tr>
+
+<tr>
+ <td>Josh Lucas</td>
+ <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
+ <td>CollabNet</td>
+ <td>Master</td>
+</tr>
+
+<tr>
+ <td>Bob McWhirter</td>
+ <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
+ <td>Werken & Sons Company</td>
+ <td>Master</td>
+</tr>
+
+<tr>
+ <td>Terence Parr</td>
+ <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
+ <td>JGuru</td>
+ <td>Master</td>
+</tr>
+
+<tr>
+ <td>Geir Magnusson Jr.</td>
+ <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
+ <td>Independent</td>
+ <td>Master</td>
+</tr>
+
+<tr>
+ <td>John Castura</td>
+ <td><link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link></td>
+ <td>-</td>
+ <td>Apprentice</td>
+</tr>
+
+</table>
+
+</p>
+
+<p>
+ Velocity is a new implementation of the Model-View-Controller
+ architecture,
+ concept, and syntax of the WebMacro Servlet Framework
+ (<link href="http://www.webmacro.org">www.webmacro.org</link>),
+ which was originally envisioned and implemented by Justin Wells at
+ Semiotek, Inc.
+</p>
+
+</s1>
+
+</body>
+</document>
1.7 +265 -244 jakarta-velocity/xdocs/todo.xml
Index: todo.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/todo.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- todo.xml 2000/10/14 19:20:43 1.6
+++ todo.xml 2000/10/25 22:33:56 1.7
@@ -1,244 +1,265 @@
-<?xml version="1.0"?>
-
-<document>
-
- <header>
- <title>Velocity Todo</title>
- <subtitle>Velocity Todo</subtitle>
- <authors>
- <person name="Velocity Documentation Team" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
-
-<body>
-
-<s1 title="Todo">
-
-<p>
-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, or have specific
-questions, please send mail to the mailing list
-(<link
href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link>).
-The Todo list that follows is roughly in order of importance.
-</p>
-
-</s1>
-
-<s1 title="The List">
-
- <strong>Runtime API</strong>
- <br/>
- The Velocity Runtime is the single access point for all
- 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.
- <p/>
-
- <strong>JUnit Test Suite</strong>
- <br/>
- A JUnit test suite would allow Velocity developers to
- aggressively add, refactor, and optimize code. We need
- a comprehensive test suite so that we can
- be assured changes in the code base have no adverse
- effects for users. <link href="mailto:[EMAIL PROTECTED]">Daniel L. Rall</link>
- 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/>
-
- <strong>Directive Interface</strong>
- <br/>
- Right now there is a very thin interface for directives, but
- some knowledge of JavaCC is required. The directive
- 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/>
-
- <strong>Context</strong>
- <br/>
- The Velocity Context class is still fairly primitive. It
- loosely adheres to a Map, but it definitely needs some
- thinking. It works fine now, but it might be good to
- think about: how to load standard tools and how to
- 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/>
-
- <strong>Sample Applications</strong>
- <br/>
- Any type of sample application would be useful to
- help new developers get acquainted with
- Velocity. Any suggestions are welcome.
- <p/>
-
- <strong>User's Guide</strong>
- <br/>
- This would be a guide for designers who would
- be using the Velocity Template Language (VTL) to
- create templates. The users guide would give
- example usage and a definitive description
- of the VTL syntax. <link href="mailto:[EMAIL PROTECTED]">Jason van
Zyl</link>
- has started work on this with John Castura, but any and all
- suggestions are welcome.
- <p/>
-
- <strong>Developer Guide</strong>
- <br/>
- This would be a guide for developers who would use
- Velocity as a standalone servlet tool, or in conjuction
- with a servlet controller framework like Turbine.
- <link href="mailto:[EMAIL PROTECTED]">Jason van Zyl</link> is
- currently working on this guide, but any and all suggestions
- are welcome.
- <p/>
-
- <strong>Template Loader System</strong>
- <br/>
- The template loader system is functional but could probably use an
- overhaul. There is currently a double template instantiation
- problem. It is not causing any serious problems, but it
- should be corrected. We could utilize some
- object caching/pooling code from Turbine, or JServ, or the
- Avalon Server Framework.
- <p/>
-
- <strong>Caching</strong>
- <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,
- 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 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
- for that particular context object with the aid of a webapp
- 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/>
-
- <strong>Parser Pool</strong>
- <br/>
- It would be good to create a pool of parsers that could
- be utilized by the Runtime. Right now there is only a single
- parser and the parsing is synchronized. The parsing doesn't
- happen all that often in production, but a small pool of
- parsers might alleviate any potential bottlenecks. Again,
- object caching/pooling code could be borrowed from Turbine,
- JServ, or the Avalon Server Framework.
- <p/>
-
- <strong>UML Overview</strong>
- <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/>
-
- <strong>Velocity Profiling</strong>
- <br/>
- If someone is handy with one of the standard profilers,
- it would be great to start hunting for bottlenecks. No
- serious optimization has been started. But in conjuction
- with the presence of a JUnit test suite, optimization
- changes could be made with confidence. It would be nice
- 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/>
-
- <strong>Encoding Caching</strong>
- <br/>
- What would this entail? And how could we implement an
- efficient encoding caching mechanism.
- <p/>
-
- <strong>Plugins</strong>
- <br/>
- It would be good to allow plugins in the form of JAR files
- to be picked up the Velocity Runtime during startup. This
- would be a good way for Velocity developers to share tools
- that could be used in a context. For example there are some
- utilities in Turbine that allow email to be sent from within
- 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/>
-
- <strong>Context Tools</strong>
- <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/>
-
- <strong>Syntax Dumper</strong>
- <br/>
- Right now there is a primitive syntax dumper in the Velocity
- 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
- for particular AST node types so that the structure produced
- is a little clearer.
- <p/>
-
- <strong>Syntax Checker</strong>
- <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/>
-
- <strong>Extended Properties</strong>
- <br/>
- There are classes that are present in JServ, Turbine and Cocoon
- that allow a more flexible properties mechanism. It allows properties
- 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/>
-
- <strong>Compiler</strong>
- <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/>
-
- <strong>IDE Integration</strong>
- <br/>
- How could Velocity be integrated into standard IDEs like
- JBuilder and VisualAge?
- <p/>
-
- <strong>Scripting Language Integration</strong>
- <br/>
- This is something that has been discussed on the Turbine
- list. Allowing Context building classes to be written
- 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. As most of these
- scripting solutions provide a compiler, performance would still
- remain at an acceptable level.
- <p/>
-
-
-
-</s1>
-
-</body>
-</document>
+<?xml version="1.0"?>
+
+<document>
+
+ <header>
+ <title>Velocity Todo</title>
+ <subtitle>Velocity Todo</subtitle>
+ <authors>
+ <person name="Velocity Documentation Team" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+
+<body>
+
+<s1 title="Todo">
+
+<p>
+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, or have specific
+questions, please send mail to the mailing list
+(<link
href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link>).
+The Todo list that follows is roughly in order of importance.
+</p>
+
+</s1>
+
+<s1 title="The List">
+
+ <p>
+ <strong>Runtime API</strong>
+ <br/>
+ The Velocity Runtime is the single access point for all
+ 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.
+ </p>
+
+ <p>
+ <strong>JUnit Test Suite</strong>
+ <br/>
+ A JUnit test suite would allow Velocity developers to
+ aggressively add, refactor, and optimize code. We need
+ a comprehensive test suite so that we can
+ be assured changes in the code base have no adverse
+ effects for users. <link href="mailto:[EMAIL PROTECTED]">Daniel L. Rall</link>
+ 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>
+
+ <p>
+ <strong>Directive Interface</strong>
+ <br/>
+ Right now there is a very thin interface for directives, but
+ some knowledge of JavaCC is required. The directive
+ 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>
+
+ <p>
+ <strong>Context</strong>
+ <br/>
+ The Velocity Context class is still fairly primitive. It
+ loosely adheres to a Map, but it definitely needs some
+ thinking. It works fine now, but it might be good to
+ think about: how to load standard tools and how to
+ 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>
+
+ <p>
+ <strong>Sample Applications</strong>
+ <br/>
+ Any type of sample application would be useful to
+ help new developers get acquainted with
+ Velocity. Any suggestions are welcome.
+ </p>
+
+ <p>
+ <strong>User's Guide</strong>
+ <br/>
+ This would be a guide for designers who would
+ be using the Velocity Template Language (VTL) to
+ create templates. The users guide would give
+ example usage and a definitive description
+ of the VTL syntax. <link href="mailto:[EMAIL PROTECTED]">Jason van
Zyl</link>
+ has started work on this with John Castura, but any and all
+ suggestions are welcome.
+ </p>
+
+ <p>
+ <strong>Developer Guide</strong>
+ <br/>
+ This would be a guide for developers who would use
+ Velocity as a standalone servlet tool, or in conjuction
+ with a servlet controller framework like Turbine.
+ <link href="mailto:[EMAIL PROTECTED]">Jason van Zyl</link> is
+ currently working on this guide, but any and all suggestions
+ are welcome.
+ </p>
+
+ <p>
+ <strong>Template Loader System</strong>
+ <br/>
+ The template loader system is functional but could probably use an
+ overhaul. There is currently a double template instantiation
+ problem. It is not causing any serious problems, but it
+ should be corrected. We could utilize some
+ object caching/pooling code from Turbine, or JServ, or the
+ Avalon Server Framework.
+ </p>
+
+ <p>
+ <strong>Caching</strong>
+ <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,
+ 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 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
+ for that particular context object with the aid of a webapp
+ 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>
+
+ <p>
+ <strong>Parser Pool</strong>
+ <br/>
+ It would be good to create a pool of parsers that could
+ be utilized by the Runtime. Right now there is only a single
+ parser and the parsing is synchronized. The parsing doesn't
+ happen all that often in production, but a small pool of
+ parsers might alleviate any potential bottlenecks. Again,
+ object caching/pooling code could be borrowed from Turbine,
+ JServ, or the Avalon Server Framework.
+ </p>
+
+ <p>
+ <strong>UML Overview</strong>
+ <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>
+
+ <p>
+ <strong>Velocity Profiling</strong>
+ <br/>
+ If someone is handy with one of the standard profilers,
+ it would be great to start hunting for bottlenecks. No
+ serious optimization has been started. But in conjuction
+ with the presence of a JUnit test suite, optimization
+ changes could be made with confidence. It would be nice
+ 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>
+
+ <p>
+ <strong>Encoding Caching</strong>
+ <br/>
+ What would this entail? And how could we implement an
+ efficient encoding caching mechanism.
+ </p>
+
+ <p>
+ <strong>Plugins</strong>
+ <br/>
+ It would be good to allow plugins in the form of JAR files
+ to be picked up the Velocity Runtime during startup. This
+ would be a good way for Velocity developers to share tools
+ that could be used in a context. For example there are some
+ utilities in Turbine that allow email to be sent from within
+ 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>
+
+ <p>
+ <strong>Context Tools</strong>
+ <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>
+
+ <p>
+ <strong>Syntax Dumper</strong>
+ <br/>
+ Right now there is a primitive syntax dumper in the Velocity
+ 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
+ for particular AST node types so that the structure produced
+ is a little clearer.
+ </p>
+
+ <p>
+ <strong>Syntax Checker</strong>
+ <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>
+
+ <p>
+ <strong>Extended Properties</strong>
+ <br/>
+ There are classes that are present in JServ, Turbine and Cocoon
+ that allow a more flexible properties mechanism. It allows properties
+ 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>
+
+ <p>
+ <strong>Compiler</strong>
+ <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>
+
+ <p>
+ <strong>IDE Integration</strong>
+ <br/>
+ How could Velocity be integrated into standard IDEs like
+ JBuilder and VisualAge?
+ </p>
+
+ <p>
+ <strong>Scripting Language Integration</strong>
+ <br/>
+ This is something that has been discussed on the Turbine
+ list. Allowing Context building classes to be written
+ 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. As most of these
+ scripting solutions provide a compiler, performance would still
+ remain at an acceptable level.
+ </p>
+
+
+
+</s1>
+
+</body>
+</document>
1.9 +563 -563 jakarta-velocity/xdocs/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/user-guide.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- user-guide.xml 2000/10/24 17:35:11 1.8
+++ user-guide.xml 2000/10/25 22:33:56 1.9
@@ -1,563 +1,563 @@
-<?xml version="1.0"?>
-
-<document>
-
- <header>
- <title>Velocity User Guide</title>
- <subtitle>Velocity User Guide</subtitle>
- <authors>
- <person name="Velocity Documentation Team" email="[EMAIL PROTECTED]"/>
- <person name="John Castura" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
-
-<body>
-
- <s1 title="About this Guide">
-
- <p>
- 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>
-
- </s1>
-
- <s1 title="What is Velocity?">
-
- <p>
- Velocity is a Java-based template engine. It permits web page designers
- to reference methods defined in Java code. Web designers can work in parallel
- with Java programmers to develop web sites according to the
Model-View-Controller
- (MVC) model, meaning that web page designers can focus solely on creating
- a well-designed site, and programmers can focus solely on writing
- top-notch code. Velocity separates Java code from the web pages,
- making the web site more maintainable over the long run and providing
- a viable alternative to
- <link href="http://java.sun.com/products/jsp/">Java Server Pages</link>
- (JSPs) or <link href="http://www.php.net/">PHP</link>.
- </p>
-
- <p>
- Velocity can be used to generate web pages, SQL, PostScript and other
- output from templates.
- It can be used either as a standalone utility for generating
- source code and reports, or as an integrated component of other systems.
- When complete, Velocity will provide template services for the
- <link href="http://java.apache.org/turbine/">Turbine</link>
- 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>
-
- </s1>
-
- <s1 title="What can Velocity do for me?">
-
- <s1 title="The Mud Store Example">
-
- <p>
- 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>
- Velocity makes it easy to customize web pages to your online visitors. As a web
site
- designer at The Mud Room, you want to make the web page that the customer will
- see after logging into your site.
- </p>
-
- <p>
- You meet with software engineers at your company, and everyone
- has agreed that the variable <pre>$customer</pre> will hold information
- pertaining to the customer currently logged in,
- that <pre>$mudsOnSpecial</pre> will be all the types mud on sale at present.
- The <pre>$flogger</pre> 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
- engineers extract the necessary information from the database, you just need
- to know that it works. This lets you get on with your job, and lets the
- software engineers get on with theirs.
- </p>
-
- <p>
- You could embed the following VTL statement in the web page:
- </p>
-
- <p>
- <source><![CDATA[
- <HTML>
- <BODY>
- Hello $customer.Name!
- <table>
- #foreach ($mud in $mudsOnSpecial)
- #if ($customer.hasPurchased($mud))
- <tr>
- <td>
- $flogger.getPromo($mud)
- </td>
- </tr>
- #end
- #end
- </table>
- ]]></source>
- </p>
-
- <p>
- The extact details of the <pre>foreach</pre> 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>
-
- </s1>
-
- <p>
- 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
- <em>presence</em>. As you get more familiar with these elements, you will begin
to unleash the power
- of Velocity.
- </p>
-
- </s1>
-
- <s1 title="Velocity Template Language (VTL): An Introduction">
-
- <p>
- The Velocity Template
- Language (VTL) is meant to provide the easiest, simplest, and cleanest way
- to incorporate dynamic content in a web page. Even a web page developer with
little
- or no programming experience should soon be capable of using VTL to incorporate
- dynamic content in a web site.
- </p>
-
- <p>
- VTL uses <em>statements</em> to embed dynamic content in a web site. Statements
- are made up of <em>elements</em>. Here is an example of a VTL statement
- embedded in an HTML document:
- </p>
-
- <p>
- <source><![CDATA[
- #set $a = "Velocity"
- ]]>
- </source>
- </p>
-
- <p>
- This VTL statement, like all VTL statements that contain directives, begins
- with the <pre>#</pre> character. When an online visitor requests
- your web page, the
- Velocity Templating Engine will search through your web page to find all
- <pre>#</pre> characters, then determine which mark the beginning of VTL
- statements, and which of the # characters that have nothing to do with VTL.
- </p>
-
- <p>
- The <pre>#</pre> character is followed by a directive,
- <pre>set</pre>. The <pre>set</pre> directive works in conjunction with other
- script elements to assign a <em>value</em> to a <em>variable</em>. The variable
- is listed on the left and its value on the right; the two are separated by an
- <pre>=</pre> character.
- </p>
-
- <p>
- In the example above, the variable is <pre>$a</pre> and the value is
- <pre>Velocity</pre>. Variables <em>always</em> begin with <pre>$</pre>
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>
- 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 <pre>$foo</pre> and later referenced.
- </p>
-
- <p>
- <source><![CDATA[
- <HTML>
- <BODY>
- #set $foo = "Velocity"
- Hello $foo World!
- </BODY>
- <HTML>
- ]]>
- </source>
- </p>
-
- <p>
- The result is a web page that prints "Hello Velocity World!".
- </p>
-
- <p>
- 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 <pre>set</pre> directive will be revisited in greater detail
- later on.
- </p>
-
- <p>
- The <pre>set</pre> example is useful for demonstrating the syntax of a simple
VTL
- statement, but not very exciting for revealing the capabilities of Velocity.
- </p>
-
-
- </s1>
-
- <s1 title="VTL Reference">
-
- <p>
- Velocity references take advantage of some Java principles that
- template designers will find easy to use. For example:
- </p>
-
- <p>
- <source><![CDATA[
- $foo
- $foo.getBar() or $foo.Bar
- $data.getUser("jon") or $data.User("jon")
- $data.getRequest().getServerName() or $data.Request.ServerName
- ]]></source>
- </p>
-
- <p>
- These examples illustrate alternative uses for the same references.
- Velocity takes advantage of Java's introspection and
- bean features to resolve the reference names to both objects in the Context
- as well as the objects methods. It is possible to embed and evaluate
- references almost anywhere in your template.
- </p>
-
- <p>
- 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>
- There are three types of references in the VTL: variables,
- properties, and methods.
-
- <s1 title="Variables">
-
- <p>
- When VTL references a variable, such as <pre>$foo</pre>, the variable can
- get its value from either a <pre>set</pre> directive in the template, or from
the
- Java code. For example, if the Java variable <pre>$foo</pre>
- has the value <pre>bar</pre> at the time the template is requested,
- <pre>bar</pre> replaces all instances of <pre>$foo</pre> on the web
- page. Alternatively, if I include the statement
- </p>
-
- <p>
- <source><![CDATA[
- #set $foo = "bar"
- ]]></source>
- </p>
-
- <p>
- the output will be the same for all instances of <pre>$foo</pre>
- that follow this directive.
- </p>
-
- </s1>
-
- <s1 title="Properties">
-
- <p>
- The second flavour of VTL references are properties, and properties have
- a distinctive format:
- </p>
-
- <p>
- <source><![CDATA[
- $whomever.Address
- ]]></source>
- </p>
-
- <p>
- Here, <pre>$whomever.Address</pre> can have two meanings. It can mean,
- Look in the hashtable identified as <pre>whomever</pre> and return the
- value associated with the key <pre>Address</pre>. This syntax can also
- be referring to a method (variables that refer to methods will be discussed
- in the next section); <pre>$whomever.Address</pre> could be an
- abbreviated way of writing <pre>getAddress("whomever")</pre>.
- When your page is requested, Velocity will determine which of these
- two possibilities makes sense, and then return the appropriate value.
- </p>
-
- </s1>
-
- <s1 title="Methods">
-
- <p>
- 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>
- <source><![CDATA[
- $purchase.getTotalPrice()
- ]]></source>
- </p>
-
- <p>
- 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,
- <pre>$purchase.TotalPrice</pre>.
- </p>
-
- </s1>
- </p>
- </s1>
-
- <s1 title="Conditionals">
-
- <s1 title="If / ElseIf / Else Conditionals">
- <p>
- The #if statement in Velocity allows for text in the brackets to be
- included in the text, on the conditional that the if statement
- is true. For example:
- </p>
-
- <p>
- <source><![CDATA[
- #if ($foo)
- <strong>Velocity Rocks!</strong>
- #end
- ]]></source>
- </p>
-
- <p>
- The variable $foo is evaluated to see if it is a boolean or not null; the
- content within the brackets becomes the output if the evaluation is true.
- Unlike in JSP, Velocity does not force web developers to wrap HTML code
- within an out.println(), or to delve into ugly workarounds to out.println().
- </p>
-
- <p>
- An #elseif or #else element can be used with an #if element.
- </p>
-
- <p>
- <source><![CDATA[
- #if ($foo)
- <strong>Velocity Rocks!</strong>
- #elseif($bar)
- <strong>Velocity Rocks Again!</strong>
- #else
- <strong>Velocity Still Rocks!</strong>
- #end
- ]]></source>
- </p>
-
- <p>
- In this example, if $foo is false, then the output will be
- <strong>Velocity Still Rocks!</strong>
- </p>
-
- <p>
- Note that logical operators are not yet available in Velocity.
- This functionality is expected to be added soon. An example of
- a logical operator is shown below.
- </p>
-
- <p>
- <source><![CDATA[
- #if ($foo && $bar)
- <strong>Velocity Rocks!</strong>
- #end
- ]]></source>
- </p>
- </s1>
-</s1>
-
-<s1 title="Loops">
- <s1 title="Foreach Loop">
- <p>
- The #foreach element allows for looping. For example:
- </p>
-
- <p>
- <source><![CDATA[
- <ul>
- #foreach ($product in $allProducts)
- <li>$product</li>
- #end
- </ul>
- ]]></source>
- </p>
-
- <p>
- This #foreach loop causes the $allProducts list (the object) to be
- looped over for all of the products (targets) in the list. Each time
- through the loop, the value from $allProducts is placed into the
- $product variable.
- </p>
-
- <p>
- The contents of the $allProducts variable is either a Vector, a Hashtable
- or an Array. The value assigned to the $product variable is a Java
- Object and can be referenced from a variable as such. For example, if
- $product was really a Product class in Java, its name could be retrieved
- by referencing the $product.Name method (ie: Product.getName()).
- </p>
- </s1>
-</s1>
-
-<s1 title="Include">
- <p>
- The #include script element allows the template designer to import a
- local file, which is then inserted into the location where the #include
- directive is defined. The contents of the file are not rendered through
- the template engine.
- </p>
-
- <p>
- <source><![CDATA[
- #include /path/to/file.vm
- ]]></source>
- </p>
-</s1>
-
-<s1 title="Set">
- <p>
- The #set script element allows the template designer to set variables
- within the Context.
- </p>
-
- <p>
- <source><![CDATA[
- #set $name = "Fred"
- ]]></source>
- </p>
-
- <p>
- When using the #set directive, the variable on the left side must be
- prefixed with a $. This provides a
- consistent syntax for referencing variables in Velocity.
- </p>
-
- <p>
- The following script elements have not been implemented.
- </p>
-</s1>
-
-<s1 title="Comments">
- <p>
- There are three comment types that allow the template designer to
- place descriptive text in templates that is not placed into the
- output of the template engine.
- </p>
-
- <p>
- <source><![CDATA[
- ## this is a line comment
- ]]></source>
- </p>
-
- <p>
- <source><![CDATA[
- #*
-
- This is a multiline
- block comment used for
- longer descriptions.
-
- *#
- ]]></source>
- </p>
-
- <p>
- <source><![CDATA[
- #**
-
- This is a VTL comment block and
- may be used to store such information
- as the document author and versioning
- information:
-
- @author
- @version 5
-
- *#
- ]]></source>
- </p>
-
-</s1>
-
-<s1 title="Stop">
- <p>
- The #stop script element allows the template designer to stop the execution
- of the template engine and return. This is useful for debugging purposes.
- </p>
-
- <p>
- <source><![CDATA[
- #stop
- ]]></source>
- </p>
-</s1>
-
-<s1 title="Macro">
- <p>
- With the #macro script element, the template designer can define a
- time-saving macro.
- </p>
-
- <p>
- <source><![CDATA[
- #macro (row $content) <tr><td>$content</td></tr> #end
- ]]></source>
- </p>
-
- <p>
- This establishes a macro called "row", which uses HTML tags to
- put content into its own table data cell in an HTML table. Having
- defined the #row macro, the template designer can now call the #row
- macro by name.
- </p>
-
- <p>
- <source><![CDATA[
- <table>
- #foreach ($element in $list)
- #row ($element)
- #end
- </table>
- ]]></source>
- </p>
-
- <p>
- Here a newly created #row macro is nested inside a #foreach
- statement. As the #foreach statement loops through each $element
- target in the $list object, the #row macro will take the value of
- $element and put it into its table data cell.
- </p>
-
-</s1>
-
-</s1>
-
-</body>
-</document>
+<?xml version="1.0"?>
+
+<document>
+
+ <header>
+ <title>Velocity User Guide</title>
+ <subtitle>Velocity User Guide</subtitle>
+ <authors>
+ <person name="Velocity Documentation Team" email="[EMAIL PROTECTED]"/>
+ <person name="John Castura" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+
+<body>
+
+ <s1 title="About this Guide">
+
+ <p>
+ 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>
+
+ </s1>
+
+ <s1 title="What is Velocity?">
+
+ <p>
+ Velocity is a Java-based template engine. It permits web page designers
+ to reference methods defined in Java code. Web designers can work in parallel
+ with Java programmers to develop web sites according to the
Model-View-Controller
+ (MVC) model, meaning that web page designers can focus solely on creating
+ a well-designed site, and programmers can focus solely on writing
+ top-notch code. Velocity separates Java code from the web pages,
+ making the web site more maintainable over the long run and providing
+ a viable alternative to
+ <link href="http://java.sun.com/products/jsp/">Java Server Pages</link>
+ (JSPs) or <link href="http://www.php.net/">PHP</link>.
+ </p>
+
+ <p>
+ Velocity can be used to generate web pages, SQL, PostScript and other
+ output from templates.
+ It can be used either as a standalone utility for generating
+ source code and reports, or as an integrated component of other systems.
+ When complete, Velocity will provide template services for the
+ <link href="http://java.apache.org/turbine/">Turbine</link>
+ 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>
+
+ </s1>
+
+ <s1 title="What can Velocity do for me?">
+
+ <s1 title="The Mud Store Example">
+
+ <p>
+ 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>
+ Velocity makes it easy to customize web pages to your online visitors. As a web
site
+ designer at The Mud Room, you want to make the web page that the customer will
+ see after logging into your site.
+ </p>
+
+ <p>
+ You meet with software engineers at your company, and everyone
+ has agreed that the variable <pre>$customer</pre> will hold information
+ pertaining to the customer currently logged in,
+ that <pre>$mudsOnSpecial</pre> will be all the types mud on sale at present.
+ The <pre>$flogger</pre> 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
+ engineers extract the necessary information from the database, you just need
+ to know that it works. This lets you get on with your job, and lets the
+ software engineers get on with theirs.
+ </p>
+
+ <p>
+ You could embed the following VTL statement in the web page:
+ </p>
+
+ <p>
+ <source><![CDATA[
+ <HTML>
+ <BODY>
+ Hello $customer.Name!
+ <table>
+ #foreach ($mud in $mudsOnSpecial)
+ #if ($customer.hasPurchased($mud))
+ <tr>
+ <td>
+ $flogger.getPromo($mud)
+ </td>
+ </tr>
+ #end
+ #end
+ </table>
+ ]]></source>
+ </p>
+
+ <p>
+ The extact details of the <pre>foreach</pre> 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>
+
+ </s1>
+
+ <p>
+ 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
+ <em>presence</em>. As you get more familiar with these elements, you will begin
to unleash the power
+ of Velocity.
+ </p>
+
+ </s1>
+
+ <s1 title="Velocity Template Language (VTL): An Introduction">
+
+ <p>
+ The Velocity Template
+ Language (VTL) is meant to provide the easiest, simplest, and cleanest way
+ to incorporate dynamic content in a web page. Even a web page developer with
little
+ or no programming experience should soon be capable of using VTL to incorporate
+ dynamic content in a web site.
+ </p>
+
+ <p>
+ VTL uses <em>statements</em> to embed dynamic content in a web site. Statements
+ are made up of <em>elements</em>. Here is an example of a VTL statement
+ embedded in an HTML document:
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #set $a = "Velocity"
+ ]]>
+ </source>
+ </p>
+
+ <p>
+ This VTL statement, like all VTL statements that contain directives, begins
+ with the <pre>#</pre> character. When an online visitor requests
+ your web page, the
+ Velocity Templating Engine will search through your web page to find all
+ <pre>#</pre> characters, then determine which mark the beginning of VTL
+ statements, and which of the # characters that have nothing to do with VTL.
+ </p>
+
+ <p>
+ The <pre>#</pre> character is followed by a directive,
+ <pre>set</pre>. The <pre>set</pre> directive works in conjunction with other
+ script elements to assign a <em>value</em> to a <em>variable</em>. The variable
+ is listed on the left and its value on the right; the two are separated by an
+ <pre>=</pre> character.
+ </p>
+
+ <p>
+ In the example above, the variable is <pre>$a</pre> and the value is
+ <pre>Velocity</pre>. Variables <em>always</em> begin with <pre>$</pre>
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>
+ 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 <pre>$foo</pre> and later referenced.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ <HTML>
+ <BODY>
+ #set $foo = "Velocity"
+ Hello $foo World!
+ </BODY>
+ <HTML>
+ ]]>
+ </source>
+ </p>
+
+ <p>
+ The result is a web page that prints "Hello Velocity World!".
+ </p>
+
+ <p>
+ 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 <pre>set</pre> directive will be revisited in greater detail
+ later on.
+ </p>
+
+ <p>
+ The <pre>set</pre> example is useful for demonstrating the syntax of a simple
VTL
+ statement, but not very exciting for revealing the capabilities of Velocity.
+ </p>
+
+
+ </s1>
+
+ <s1 title="VTL Reference">
+
+ <p>
+ Velocity references take advantage of some Java principles that
+ template designers will find easy to use. For example:
+ </p>
+
+ <p>
+ <source><![CDATA[
+ $foo
+ $foo.getBar() or $foo.Bar
+ $data.getUser("jon") or $data.User("jon")
+ $data.getRequest().getServerName() or $data.Request.ServerName
+ ]]></source>
+ </p>
+
+ <p>
+ These examples illustrate alternative uses for the same references.
+ Velocity takes advantage of Java's introspection and
+ bean features to resolve the reference names to both objects in the Context
+ as well as the objects methods. It is possible to embed and evaluate
+ references almost anywhere in your template.
+ </p>
+
+ <p>
+ 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>
+ There are three types of references in the VTL: variables,
+ properties, and methods.
+
+ <s1 title="Variables">
+
+ <p>
+ When VTL references a variable, such as <pre>$foo</pre>, the variable can
+ get its value from either a <pre>set</pre> directive in the template, or from
the
+ Java code. For example, if the Java variable <pre>$foo</pre>
+ has the value <pre>bar</pre> at the time the template is requested,
+ <pre>bar</pre> replaces all instances of <pre>$foo</pre> on the web
+ page. Alternatively, if I include the statement
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #set $foo = "bar"
+ ]]></source>
+ </p>
+
+ <p>
+ the output will be the same for all instances of <pre>$foo</pre>
+ that follow this directive.
+ </p>
+
+ </s1>
+
+ <s1 title="Properties">
+
+ <p>
+ The second flavour of VTL references are properties, and properties have
+ a distinctive format:
+ </p>
+
+ <p>
+ <source><![CDATA[
+ $whomever.Address
+ ]]></source>
+ </p>
+
+ <p>
+ Here, <pre>$whomever.Address</pre> can have two meanings. It can mean,
+ Look in the hashtable identified as <pre>whomever</pre> and return the
+ value associated with the key <pre>Address</pre>. This syntax can also
+ be referring to a method (variables that refer to methods will be discussed
+ in the next section); <pre>$whomever.Address</pre> could be an
+ abbreviated way of writing <pre>getAddress("whomever")</pre>.
+ When your page is requested, Velocity will determine which of these
+ two possibilities makes sense, and then return the appropriate value.
+ </p>
+
+ </s1>
+
+ <s1 title="Methods">
+
+ <p>
+ 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>
+ <source><![CDATA[
+ $purchase.getTotalPrice()
+ ]]></source>
+ </p>
+
+ <p>
+ 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,
+ <pre>$purchase.TotalPrice</pre>.
+ </p>
+
+ </s1>
+ </p>
+ </s1>
+
+ <s1 title="Conditionals">
+
+ <s1 title="If / ElseIf / Else Conditionals">
+ <p>
+ The #if statement in Velocity allows for text in the brackets to be
+ included in the text, on the conditional that the if statement
+ is true. For example:
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #if ($foo)
+ <strong>Velocity Rocks!</strong>
+ #end
+ ]]></source>
+ </p>
+
+ <p>
+ The variable $foo is evaluated to see if it is a boolean or not null; the
+ content within the brackets becomes the output if the evaluation is true.
+ Unlike in JSP, Velocity does not force web developers to wrap HTML code
+ within an out.println(), or to delve into ugly workarounds to out.println().
+ </p>
+
+ <p>
+ An #elseif or #else element can be used with an #if element.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #if ($foo)
+ <strong>Velocity Rocks!</strong>
+ #elseif($bar)
+ <strong>Velocity Rocks Again!</strong>
+ #else
+ <strong>Velocity Still Rocks!</strong>
+ #end
+ ]]></source>
+ </p>
+
+ <p>
+ In this example, if $foo is false, then the output will be
+ <strong>Velocity Still Rocks!</strong>
+ </p>
+
+ <p>
+ Note that logical operators are not yet available in Velocity.
+ This functionality is expected to be added soon. An example of
+ a logical operator is shown below.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #if ($foo && $bar)
+ <strong>Velocity Rocks!</strong>
+ #end
+ ]]></source>
+ </p>
+ </s1>
+</s1>
+
+<s1 title="Loops">
+ <s1 title="Foreach Loop">
+ <p>
+ The #foreach element allows for looping. For example:
+ </p>
+
+ <p>
+ <source><![CDATA[
+ <ul>
+ #foreach ($product in $allProducts)
+ <li>$product</li>
+ #end
+ </ul>
+ ]]></source>
+ </p>
+
+ <p>
+ This #foreach loop causes the $allProducts list (the object) to be
+ looped over for all of the products (targets) in the list. Each time
+ through the loop, the value from $allProducts is placed into the
+ $product variable.
+ </p>
+
+ <p>
+ The contents of the $allProducts variable is either a Vector, a Hashtable
+ or an Array. The value assigned to the $product variable is a Java
+ Object and can be referenced from a variable as such. For example, if
+ $product was really a Product class in Java, its name could be retrieved
+ by referencing the $product.Name method (ie: Product.getName()).
+ </p>
+ </s1>
+</s1>
+
+<s1 title="Include">
+ <p>
+ The #include script element allows the template designer to import a
+ local file, which is then inserted into the location where the #include
+ directive is defined. The contents of the file are not rendered through
+ the template engine.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #include /path/to/file.vm
+ ]]></source>
+ </p>
+</s1>
+
+<s1 title="Set">
+ <p>
+ The #set script element allows the template designer to set variables
+ within the Context.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #set $name = "Fred"
+ ]]></source>
+ </p>
+
+ <p>
+ When using the #set directive, the variable on the left side must be
+ prefixed with a $. This provides a
+ consistent syntax for referencing variables in Velocity.
+ </p>
+
+ <p>
+ The following script elements have not been implemented.
+ </p>
+</s1>
+
+<s1 title="Comments">
+ <p>
+ There are three comment types that allow the template designer to
+ place descriptive text in templates that is not placed into the
+ output of the template engine.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ ## this is a line comment
+ ]]></source>
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #*
+
+ This is a multiline
+ block comment used for
+ longer descriptions.
+
+ *#
+ ]]></source>
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #**
+
+ This is a VTL comment block and
+ may be used to store such information
+ as the document author and versioning
+ information:
+
+ @author
+ @version 5
+
+ *#
+ ]]></source>
+ </p>
+
+</s1>
+
+<s1 title="Stop">
+ <p>
+ The #stop script element allows the template designer to stop the execution
+ of the template engine and return. This is useful for debugging purposes.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #stop
+ ]]></source>
+ </p>
+</s1>
+
+<s1 title="Macro">
+ <p>
+ With the #macro script element, the template designer can define a
+ time-saving macro.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #macro (row $content) <tr><td>$content</td></tr> #end
+ ]]></source>
+ </p>
+
+ <p>
+ This establishes a macro called "row", which uses HTML tags to
+ put content into its own table data cell in an HTML table. Having
+ defined the #row macro, the template designer can now call the #row
+ macro by name.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ <table>
+ #foreach ($element in $list)
+ #row ($element)
+ #end
+ </table>
+ ]]></source>
+ </p>
+
+ <p>
+ Here a newly created #row macro is nested inside a #foreach
+ statement. As the #foreach statement loops through each $element
+ target in the $list object, the #row macro will take the value of
+ $element and put it into its table data cell.
+ </p>
+
+</s1>
+<!--
+</s1>
+-->
+</body>
+</document>
1.10 +335 -335 jakarta-velocity/xdocs/vtl-reference-guide.xml
Index: vtl-reference-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/vtl-reference-guide.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- vtl-reference-guide.xml 2000/10/24 17:35:11 1.9
+++ vtl-reference-guide.xml 2000/10/25 22:33:56 1.10
@@ -1,335 +1,335 @@
-<?xml version="1.0"?>
-
-<document>
-
- <header>
- <title>VTL Reference Guide</title>
- <subtitle>VTL Refernce Guide</subtitle>
- <authors>
- <person name="Jason van Zyl" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
-
-<body>
-
-<!--
-
-Some of the user's guide info should be moved into
-this reference guide and links should be made from
-the user's guide to this document
-
--->
-
-<s1 title="About this Guide">
-
-<p>
- This guide is meant to be the definitive reference for
- the Velocity Template Language (VTL).
-</p>
-
-</s1>
-
-<s1 title="References">
-
-<p>
- There are three types of references in the VTL: variables, properties
- and methods. As a designer using the VTL, you and your engineers must
- come to an agreement on the specific names of references so
- you can use them correctly in your templates.
-</p>
-
-<p>
- <strong>Variables</strong>
- <br/>
- Variables are references that consist of a leading "$" character
- followed by a VTL <em>Identifier</em>. A VTL <em>Identifier</em> 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 ("_"). Here are some examples of valid
- variable references in the VTL:
-</p>
-
-<p>
- <source><![CDATA[
- $mudSlinger
- $mud-slinger
- $mud_slinger
- $mudSlinger1
- ]]></source>
-</p>
-
-<p>
- <strong>Properties</strong>
- <br/>
- Properties are references that consist of a leading "$"
- character followed a VTL <em>Identifier</em>, followed by
- of dot character (".") then another VTL <em>Identifier</em>.
- These are examples of valid property references in the VTL:
-</p>
-
-<p>
- <source><![CDATA[
- $customer.Address
- $purchase.Total
- ]]></source>
-</p>
-
-<p>
- <strong>Methods</strong>
- <br/>
- Methods are references that consist of a leading "$"
- character followed a VTL <em>Identifier</em>, followed
- by a VTL <em>Method Body</em>. A VTL <em>Method Body</em>
- consists of a VTL <em>Identifier</em> 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>
- <source><![CDATA[
- $customer.getAddress()
- $purchase.getTotal()
- $page.setTitle("My Home Page")
- $person.setAttributes("Strange", "Weird", "Excited")
- ]]></source>
-</p>
-
-<p>
- Now you may have noticed that the first two examples
- $customer.getAddress() and $purchase.getTotal() look very
- similiar to the first two example Properties $customer.Address
- and $purchase.Total. If you guessed that these examples must
- be related some in some fashion, you are correct! VTL Properties
- are simply a shorthand for notation for VTL Methods. 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>
- <strong>Formal Reference Notation</strong>
- <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>
- <source><![CDATA[
- ${mudSlinger}
- ${customer.Address}
- ${purchase.getTotal()}
- ]]></source>
-</p>
-
-<p>
- In almost all cases you will use the shorthand notation
- for references, but in some cases the formal
- notation is required for correct processing. 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>
- <source><![CDATA[
- Jack is a $vicemaniac.
- ]]></source>
-</p>
-
-<p>
- 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>
- <source><![CDATA[
- Jack is a ${vice}maniac.
- ]]></source>
-</p>
-
-<p>
- 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>
- <strong>Quiet Reference Notation</strong>
- <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>
- <source><![CDATA[
- <input type="text" name="email" value="$email"/>
- ]]></source>
-</p>
-
-<p>
- 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>
- <source><![CDATA[
- <input type="text" name="email" value="$!email"/>
- ]]></source>
-</p>
-
-<p>
- Now when the form is initially loaded and
- $email still has no value, an empty string will
- be output instead of "$email".
-</p>
-
-</s1>
-
-<s1 title="Directives">
-<p>
- <strong>#set</strong>
- <br/>
- The #set directive is used for setting the value of
- a reference. A value can be assigned to either a variable
- reference or a property reference:
-</p>
-
-<p>
- <source><![CDATA[
- #set $primate = "monkey"
- #set $customer.Behavior = $primate
- ]]></source>
-</p>
-
-<p>
- The left hand side (LHS) of the assigment must be
- a variable reference or a property reference. The
- right hand side (RHS) can be one of the following:
-</p>
-
-<p>
- <ul>
- <li>Variable reference</li>
- <li>String literal</li>
- <li>Property reference</li>
- <li>Method reference</li>
- <li>Number literal</li>
- <li>Object array</li>
- </ul>
-</p>
-
-<p>
- Here are examples demonstrating the
- aforementioned types:
-</p>
-
-<p>
- <source><![CDATA[
- #set $monkey = $bill
- #set $monkey.Friend = "monica"
- #set $monkey.Blame = $whitehouse.Leak
- #set $monkey.Plan = $spindoctor.weave($web)
- #set $monkey.Number = 123
- #set $monkey.Say = ["Not", $my, "fault"]
- ]]></source>
-</p>
-
-<p>
- The RHS can also be a simple arithmetic expression:
-</p>
-
-<p>
- <source><![CDATA[
- #set $value = $foo + 1
- #set $value = $bar - 1
- #set $value = $foo * $bar
- #set $value = $foo / $bar
- ]]></source>
-</p>
-
-<p>
- <strong>#foreach</strong>
- <br/>
- The #foreach directive provides a simple way of looping
- through a list of objects:
-</p>
-
-<p>
- <source><![CDATA[
- <table>
- #foreach ($customer in $customerList)
- <tr>
- <td>
- $customer.Name
- </td>
- </tr>
- #end
- ]]></source>
-</p>
-
-<p>
- Velocity provides an easy way to get the loop
- counter so that you can do something like the
- following:
-</p>
-
-<p>
- <source><![CDATA[
- <table>
- #foreach ($customer in $customerList)
- <tr>
- <td>
- $velocityCounter
- </td>
- <td>
- $customer.Name
- </td>
- </tr>
- #end
- ]]></source>
-</p>
-
-<p>
- The default name for the loop counter variable
- reference, which is specified in the velocity.properties
- file, is $velocityCount. By default the counter starts
- at 1, but this can be set to either 0 or 1 in the
- velocity.properties file. Here's what the loop counter
- properties section of the velocity.properties file appears:
-</p>
-
-<p>
- <source><![CDATA[
- # Default name of the loop counter
- # variable refernce.
- counter.name = velocityCount
-
- # Default starting value of the loop
- # counter variable reference.
- counter.initial.value = 1
- ]]></source>
-</p>
-
-
-
-</body>
-</document>
+<?xml version="1.0"?>
+
+<document>
+
+ <header>
+ <title>VTL Reference Guide</title>
+ <subtitle>VTL Refernce Guide</subtitle>
+ <authors>
+ <person name="Jason van Zyl" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+
+<body>
+
+<!--
+
+Some of the user's guide info should be moved into
+this reference guide and links should be made from
+the user's guide to this document
+
+-->
+
+<s1 title="About this Guide">
+
+<p>
+ This guide is meant to be the definitive reference for
+ the Velocity Template Language (VTL).
+</p>
+
+</s1>
+
+<s1 title="References">
+
+<p>
+ There are three types of references in the VTL: variables, properties
+ and methods. As a designer using the VTL, you and your engineers must
+ come to an agreement on the specific names of references so
+ you can use them correctly in your templates.
+</p>
+
+<p>
+ <strong>Variables</strong>
+ <br/>
+ Variables are references that consist of a leading "$" character
+ followed by a VTL <em>Identifier</em>. A VTL <em>Identifier</em> 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 ("_"). Here are some examples of valid
+ variable references in the VTL:
+</p>
+
+<p>
+ <source><![CDATA[
+ $mudSlinger
+ $mud-slinger
+ $mud_slinger
+ $mudSlinger1
+ ]]></source>
+</p>
+
+<p>
+ <strong>Properties</strong>
+ <br/>
+ Properties are references that consist of a leading "$"
+ character followed a VTL <em>Identifier</em>, followed by
+ of dot character (".") then another VTL <em>Identifier</em>.
+ These are examples of valid property references in the VTL:
+</p>
+
+<p>
+ <source><![CDATA[
+ $customer.Address
+ $purchase.Total
+ ]]></source>
+</p>
+
+<p>
+ <strong>Methods</strong>
+ <br/>
+ Methods are references that consist of a leading "$"
+ character followed a VTL <em>Identifier</em>, followed
+ by a VTL <em>Method Body</em>. A VTL <em>Method Body</em>
+ consists of a VTL <em>Identifier</em> 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>
+ <source><![CDATA[
+ $customer.getAddress()
+ $purchase.getTotal()
+ $page.setTitle("My Home Page")
+ $person.setAttributes("Strange", "Weird", "Excited")
+ ]]></source>
+</p>
+
+<p>
+ Now you may have noticed that the first two examples
+ $customer.getAddress() and $purchase.getTotal() look very
+ similiar to the first two example Properties $customer.Address
+ and $purchase.Total. If you guessed that these examples must
+ be related some in some fashion, you are correct! VTL Properties
+ are simply a shorthand for notation for VTL Methods. 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>
+ <strong>Formal Reference Notation</strong>
+ <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>
+ <source><![CDATA[
+ ${mudSlinger}
+ ${customer.Address}
+ ${purchase.getTotal()}
+ ]]></source>
+</p>
+
+<p>
+ In almost all cases you will use the shorthand notation
+ for references, but in some cases the formal
+ notation is required for correct processing. 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>
+ <source><![CDATA[
+ Jack is a $vicemaniac.
+ ]]></source>
+</p>
+
+<p>
+ 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>
+ <source><![CDATA[
+ Jack is a ${vice}maniac.
+ ]]></source>
+</p>
+
+<p>
+ 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>
+ <strong>Quiet Reference Notation</strong>
+ <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>
+ <source><![CDATA[
+ <input type="text" name="email" value="$email"/>
+ ]]></source>
+</p>
+
+<p>
+ 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>
+ <source><![CDATA[
+ <input type="text" name="email" value="$!email"/>
+ ]]></source>
+</p>
+
+<p>
+ Now when the form is initially loaded and
+ $email still has no value, an empty string will
+ be output instead of "$email".
+</p>
+
+</s1>
+
+<s1 title="Directives">
+<p>
+ <strong>#set</strong>
+ <br/>
+ The #set directive is used for setting the value of
+ a reference. A value can be assigned to either a variable
+ reference or a property reference:
+</p>
+
+<p>
+ <source><![CDATA[
+ #set $primate = "monkey"
+ #set $customer.Behavior = $primate
+ ]]></source>
+</p>
+
+<p>
+ The left hand side (LHS) of the assigment must be
+ a variable reference or a property reference. The
+ right hand side (RHS) can be one of the following:
+</p>
+
+<p>
+ <ul>
+ <li>Variable reference</li>
+ <li>String literal</li>
+ <li>Property reference</li>
+ <li>Method reference</li>
+ <li>Number literal</li>
+ <li>Object array</li>
+ </ul>
+</p>
+
+<p>
+ Here are examples demonstrating the
+ aforementioned types:
+</p>
+
+<p>
+ <source><![CDATA[
+ #set $monkey = $bill
+ #set $monkey.Friend = "monica"
+ #set $monkey.Blame = $whitehouse.Leak
+ #set $monkey.Plan = $spindoctor.weave($web)
+ #set $monkey.Number = 123
+ #set $monkey.Say = ["Not", $my, "fault"]
+ ]]></source>
+</p>
+
+<p>
+ The RHS can also be a simple arithmetic expression:
+</p>
+
+<p>
+ <source><![CDATA[
+ #set $value = $foo + 1
+ #set $value = $bar - 1
+ #set $value = $foo * $bar
+ #set $value = $foo / $bar
+ ]]></source>
+</p>
+
+<p>
+ <strong>#foreach</strong>
+ <br/>
+ The #foreach directive provides a simple way of looping
+ through a list of objects:
+</p>
+
+<p>
+ <source><![CDATA[
+ <table>
+ #foreach ($customer in $customerList)
+ <tr>
+ <td>
+ $customer.Name
+ </td>
+ </tr>
+ #end
+ ]]></source>
+</p>
+
+<p>
+ Velocity provides an easy way to get the loop
+ counter so that you can do something like the
+ following:
+</p>
+
+<p>
+ <source><![CDATA[
+ <table>
+ #foreach ($customer in $customerList)
+ <tr>
+ <td>
+ $velocityCounter
+ </td>
+ <td>
+ $customer.Name
+ </td>
+ </tr>
+ #end
+ ]]></source>
+</p>
+
+<p>
+ The default name for the loop counter variable
+ reference, which is specified in the velocity.properties
+ file, is $velocityCount. By default the counter starts
+ at 1, but this can be set to either 0 or 1 in the
+ velocity.properties file. Here's what the loop counter
+ properties section of the velocity.properties file appears:
+</p>
+
+<p>
+ <source><![CDATA[
+ # Default name of the loop counter
+ # variable refernce.
+ counter.name = velocityCount
+
+ # Default starting value of the loop
+ # counter variable reference.
+ counter.initial.value = 1
+ ]]></source>
+</p>
+
+</s1>
+
+</body>
+</document>
