You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by he...@apache.org on 2006/07/08 18:06:27 UTC
svn commit: r420158 -
/jakarta/velocity/docbook/trunk/src/docbook/userguide/VelocityUsersGuide.xml
Author: henning
Date: Sat Jul 8 09:06:26 2006
New Revision: 420158
URL: http://svn.apache.org/viewvc?rev=420158&view=rev
Log:
Continue working on the docs and examples.
Modified:
jakarta/velocity/docbook/trunk/src/docbook/userguide/VelocityUsersGuide.xml
Modified: jakarta/velocity/docbook/trunk/src/docbook/userguide/VelocityUsersGuide.xml
URL: http://svn.apache.org/viewvc/jakarta/velocity/docbook/trunk/src/docbook/userguide/VelocityUsersGuide.xml?rev=420158&r1=420157&r2=420158&view=diff
==============================================================================
--- jakarta/velocity/docbook/trunk/src/docbook/userguide/VelocityUsersGuide.xml (original)
+++ jakarta/velocity/docbook/trunk/src/docbook/userguide/VelocityUsersGuide.xml Sat Jul 8 09:06:26 2006
@@ -1,7 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-
<!--
Copyright 2006 The Apache Software Foundation.
@@ -17,9 +16,8 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-
<book lang="en">
- <title>Velocity User Guide</title>
+ <title>Velocity Users Guide</title>
<bookinfo>
<copyright>
@@ -38,12 +36,12 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/logo.png"/>
+ <imagedata fileref="images/logo.png" />
</imageobject>
</mediaobject>
</bookinfo>
- <toc/>
+ <toc></toc>
<chapter id="chapter-preface">
<title>Preface</title>
@@ -51,14 +49,15 @@
<section id="section-about-this-guide">
<title>About this Guide</title>
- <para>The Velocity User Guide is intended to help page designers and
+ <para>The Velocity Users Guide is intended to help page designers and
content providers get acquainted with Velocity and the syntax of its
simple yet powerful scripting language, the Velocity Template Language
(VTL). Many of the examples in this guide deal with using Velocity to
embed dynamic content in web sites, but all VTL examples are equally
applicable to other pages and templates.</para>
- <para>Thanks for choosing Velocity!</para>
+ <para><emphasis role="bold">Thanks for choosing
+ Velocity!</emphasis></para>
</section>
<section id="section-acknowledgements">
@@ -66,16 +65,45 @@
<para>This guide has been compiled from the xdoc Version which was
included with Velocity up to version 1.4. We explicitly acknowledge the
- efforts of Jason Van Zyl and John Castura in preparing this first
- version.</para>
+ efforts of all the contributors, especially Jason Van Zyl and John
+ Castura in preparing this first version.</para>
</section>
<section id="section-feedback">
<title>Feedback</title>
<para>If you encounter any mistakes in this manual or have other
- feedback related to the Velocity User Guide, please email the Velocity
- user list. Thanks!</para>
+ feedback related to the Velocity Users Guide, please send email to one
+ of the Velocity mailing lists:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><email>velocity-user@jakarta.apache.org</email></term>
+
+ <listitem>
+ <para>This mailing list is intended for discussion about using
+ Velocity, e.g. writing templates or integrating Velocity into your
+ application. If you need clarification about the content of this
+ guide or have questions about the examples, please send them to
+ this list.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><email>velocity-dev@jakarta.apache.org</email></term>
+
+ <listitem>
+ <para>This mailing list is intended for discussion about
+ developing Velocity itself. If you found a mistake in this guide,
+ want to improve its contents or the formatting framework, please
+ use this mailing list.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Please check also the Velocity Homepage located at
+ <uri>http://jakarta.apache.org/velocity/</uri> for up-to-date
+ information, new releases and general Velocity information.</para>
</section>
</chapter>
@@ -83,25 +111,25 @@
<title>What is Velocity?</title>
<para>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 Java Server Pages (JSPs) or PHP.</para>
-
- <para>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 Turbine web application framework. Velocity+Turbine will provide a
- template service that will allow web applications to be developed
+ designers to reference methods defined in Java code. Template developers
+ can work in parallel with Java programmers to develop web sites according
+ to the Model-View-Controller (MVC) model, meaning that they can focus
+ solely on creating templates, and programmers can focus solely on writing
+ Java code. Velocity separates Java code from the template pages, making a
+ project more maintainable over the long run.</para>
+
+ <para>In a web context, Velocit provides a viable alternative to Java
+ Server Pages (JSPs) or PHP.</para>
+
+ <para>Velocity can be used to generate web pages, Java source code, 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.</para>
+
+ <para>Velocity provides template services for a number of web frameworks,
+ e.g. the Turbine web application framework. In this contect, Velocity
+ offers a template service that will allow web applications to be developed
according to a true MVC model.</para>
- </chapter>
-
- <chapter id="chapter-what-can-velocity-do-for-me">
- <title>What can Velocity do for me?</title>
<section id="section-the-fruit-store-example">
<title>The Fruit Store Example</title>
@@ -115,9 +143,9 @@
customers regularly buy mangos, which are also on sale, though not as
popular and usually relegated to the margin of your web page.
Information about each customer is tracked in your database, so one day
- the question arises, Why not use Velocity to target special deals on
- fruit to the customers who are most interested in those types of
- fruits?</para>
+ the question arises: <emphasis>Why not use Velocity to target special
+ deals on fruit to the customers who are most interested in those types
+ of fruits?</emphasis></para>
<para>Velocity makes it easy to customize web pages to your online
visitors. As a web site designer at <emphasis>The Online Fruit
@@ -155,143 +183,299 @@
</body></html></programlisting>
<para>The exact details of the <literal>#foreach</literal> and
- <literal>#if</literal> statement will be described in greater depth
- shortly; what's important is the impact this short script may have on
- your web site. When a customer with a penchant for mangos logs in, and
- mangos are on sale, that is what this customer will see, prominently
- displayed. If another customer with a long history of apple purchases
- logs in, the notice of an apple sale will be front and center. The
- flexibility of Velocity is enormous and limited only by your
- creativity.</para>
-
- <para>Documented in the VTL Reference Manual are the many other Velocity
- elements, which collectively give you the power and flexibility you need
- to make your web site a web <emphasis>presence</emphasis>. As you get
- more familiar with these elements, you will begin to unleash the power
- of Velocity.</para>
+ <literal>#if</literal> statement will be described in greater depth in
+ the <link linkend="chapter-directives">Directives chapter</link>; what's
+ important is the impact this short script may have on your web site.
+ When a customer with a penchant for mangos logs in, and mangos are on
+ sale, that is what this customer will see, prominently displayed. If
+ another customer with a long history of apple purchases logs in, the
+ notice of an apple sale will be front and center. The flexibility of
+ Velocity is enormous and limited only by your creativity.</para>
+
+ <para>This manual should help you get started with Velocity and the
+ Velocity Template Language. It has a companion manual, <firstterm>The
+ Velocity Developers Guide</firstterm>, which describes how to integrate
+ Velocity into your own web applications (this is what the software
+ engineers at your company want to read).</para>
+ </section>
+
+ <section id="section-velocity-template-language-introduction">
+ <title>Velocity Template Language (VTL): An Introduction</title>
+
+ <para>The <firstterm>Velocity Template Language</firstterm>
+ (<firstterm>VTL</firstterm>) is meant to provide an easy, simple and
+ clean 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.</para>
+
+ <para>VTL uses <firstterm>references</firstterm> to embed dynamic
+ content in a web site, and a variable is one type of reference. They can
+ refer to something defined in the Java code, or it can get its value
+ from a VTL <firstterm>statement</firstterm> in the web page
+ itself.</para>
+
+ <example id="example-simple-vtl-statement">
+ <title>A simple VTL statement</title>
+
+ <programlisting>#set( $a = "Velocity" )</programlisting>
+ </example>
+
+ <para>This VTL statement, like all VTL statements, begins with the
+ <literal>#</literal> character and contains a directive:
+ <literal>set</literal>. When an online visitor requests your web page,
+ the Velocity Templating Engine will search through your web page to find
+ all <literal>#</literal> characters, then determine which mark the
+ beginning of VTL statements, and which of the <literal>#</literal>
+ characters that have nothing to do with VTL.</para>
+
+ <para>The <literal>#</literal> character is followed by a directive,
+ <literal>set</literal>. The <literal>set</literal> directive uses an
+ expression (enclosed in brackets) -- an equation that assigns a value to
+ a <firstterm>variable</firstterm>. The variable is listed on the left
+ hand side and its value on the right hand side; the two are separated by
+ an <literal>=</literal> character.</para>
+
+ <para>In the example above, the variable is <literal>$a</literal> and
+ the value is <literal>Velocity</literal>. This variable, like all
+ references, begins with the <literal>$</literal> character. String
+ values are always enclosed in quotes, either single or double quotes.
+ Single quotes will ensure that the quoted value will be assigned to the
+ reference as is. Double quotes allow you to use velocity references and
+ directives to interpolate, such as <literal>"Hello $name"</literal>,
+ where the <literal>$name</literal> will be replaced by the current value
+ before that string literal is assigned to the left hand side of the
+ <literal>=</literal>.</para>
+
+ <para>The following rule of thumb may be useful to better understand how
+ Velocity works: References begin with <literal>$</literal> and are used
+ to get something. Directives begin with <literal>#</literal> and are
+ used to do something.</para>
+
+ <para>In the example above, <literal>#set</literal> is used to assign a
+ value to a variable. The variable, <literal>$a</literal>, can then be
+ used in the template to output <literal>Velocity</literal>.</para>
+ </section>
+
+ <section id="section-hello-velocity-world">
+ <title>Hello Velocity World!</title>
+
+ <para>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 <literal>$foo</literal> and later
+ referenced.</para>
+
+ <programlisting><html><body>
+#set( $name = "Velocity" )
+Hello $name World!
+</body></html></programlisting>
+
+ <para>The result is a web page that reads</para>
+
+ <programlisting>Hello Velocity World!</programlisting>
+
+ <para>To make statements containing VTL directives more readable, we
+ encourage you to start each VTL statement on a new line, although you
+ are not required to do so.</para>
</section>
</chapter>
- <chapter id="chapter-velocity-template-language-introduction">
- <title>Velocity Template Language (VTL): An Introduction</title>
+ <chapter id="chapter-language-elements">
+ <title>Language elements</title>
- <para>The <firstterm>Velocity Template Language</firstterm>
- (<firstterm>VTL</firstterm>) is meant to provide an easy, simple and clean
- 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.</para>
-
- <para>VTL uses <firstterm>references</firstterm> to embed dynamic content
- in a web site, and a variable is one type of reference. Variables are one
- type of reference that can refer to something defined in the Java code, or
- it can get its value from a VTL <firstterm>statement</firstterm> in the
- web page itself. Here is an example of a VTL statement that could be
- embedded in an HTML document:</para>
-
- <programlisting>#set( $a = "Velocity" )</programlisting>
-
- <para>This VTL statement, like all VTL statements, begins with the
- <literal>#</literal> character and contains a directive:
- <literal>set</literal>. When an online visitor requests your web page, the
- Velocity Templating Engine will search through your web page to find all
- <literal>#</literal> characters, then determine which mark the beginning
- of VTL statements, and which of the <literal>#</literal> characters that
- have nothing to do with VTL.</para>
-
- <para>The <literal>#</literal> character is followed by a directive,
- <literal>set</literal>. The <literal>set</literal> directive uses an
- expression (enclosed in brackets) -- an equation that assigns a
- <firstterm>value</firstterm> to a <firstterm>variable</firstterm>. The
- variable is listed on the left hand side and its value on the right hand
- side; the two are separated by an <literal>=</literal> character.</para>
-
- <para>In the example above, the variable is <literal>$a</literal> and the
- value is <literal>Velocity</literal>. This variable, like all references,
- begins with the <literal>$</literal> character. String values are always
- enclosed in quotes, either single or double quotes. Single quotes will
- ensure that the quoted value will be assigned to the reference as is.
- Double quotes allow you to use velocity references and directives to
- interpolate, such as <literal>"Hello $name"</literal>, where the
- <literal>$name</literal> will be replaced by the current value before that
- string literal is assigned to the left hand side of the
- <literal>=</literal>.</para>
-
- <para>The following rule of thumb may be useful to better understand how
- Velocity works: References begin with <literal>$</literal> and are used to
- get something. Directives begin with <literal>#</literal> and are used to
- do something.</para>
-
- <para>In the example above, <literal>#set</literal> is used to assign a
- value to a variable. The variable, <literal>$a</literal>, can then be used
- in the template to output <literal>Velocity</literal>.</para>
- </chapter>
+ <para>Like other formal languages, Velocity consists of a number of
+ elements:</para>
- <chapter id="chapter-hello-velocity-world">
- <title>Hello Velocity World!</title>
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="section-directives">Statements and
+ Directives</link></para>
+ </listitem>
- <para>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 <literal>$foo</literal> and later referenced.</para>
-
- <programlisting><html><body>
-#set( $foo = "Velocity" )
-Hello $foo World!
-</body></html></programlisting>
+ <listitem>
+ <para><link linkend="section-reference">References</link></para>
+ </listitem>
- <para>The result is a web page that reads</para>
+ <listitem>
+ <para><link linkend="section-comments">Comments</link></para>
+ </listitem>
+ </itemizedlist>
- <programlisting>Hello Velocity World!</programlisting>
+ <para>Each of these elements will be introduced in this chapter.</para>
- <para>To make statements containing VTL directives more readable, we
- encourage you to start each VTL statement on a new line, although you are
- not required to do so. The <literal>set</literal> directive will be
- revisited in greater detail later on.</para>
- </chapter>
+ <section id="section-directives">
+ <title>Statements and Directives</title>
- <chapter id="chapter-comments">
- <title>Comments</title>
+ <para>Velocity directives are language elements than allow the template
+ designer to manipulate the rendering of the template. A directive is
+ part of a Velocity statement:</para>
+
+ <programlisting>#set($a = 10) ## Velocity single-line statement
+^\_/\_______/
+| | |
+| | +---------- expression in brackets
+| |
+| +---------------- Velocity directive
+|
++------------------ begin of Velocity statement
+
+
+
++------------------ begin of Velocity statement
+|
+| +-------------- Velocity directive
+| |
+| | +--- expression in brackets
+| __|__ ______|______
+v/ \/ \
+#foreach($i in [0..10]) ## Velocity multi-line statement
+ Counter is $i ## statement body
+#end ## end of Velocity multi-line statement</programlisting>
+
+ <para>Velocity knows about single-line and multi-line statements. A
+ single-line statement starts with a single <literal>#</literal>
+ character, followed by directive itself. Some directives also take
+ parameters in brackets. A single-line statement then ends
+ immediately.</para>
+
+ <example id="example-velocity-single-line-statements">
+ <title>Velocity single-line statements</title>
+
+ <programlisting>#set($name = "apple")
+
+#include("header.html")
+
+#parse("header.vm")
+
+#stop</programlisting>
+ </example>
+
+ <para>A multi-line statement starts like a single-line statement, but
+ also has a statement body. This body ends with
+ <literal>#end</literal>.</para>
+
+ <example id="example-velocity-multi-line-statements">
+ <title>Velocity multi-line statements</title>
+
+ <programlisting>#foreach($i in [1..10])
+ The count is $i
+#end
+
+#literal
+ This is a literal block of text
+#end
+
+#if ($fruit == "apple")
+ This is an apple.
+#else
+ This is not an apple.
+#end</programlisting>
+ </example>
+
+ <note>
+ <para>The
+ <literal>#if</literal>/<literal>#else</literal>/<literal>#end</literal>
+ combo is a special case because it might contain multiple statement
+ bodies between its elements.</para>
+ </note>
+
+ <para>If you need to explicitly separate a Velocity directive from
+ surrounding text, it is possible to wrap it in curly braces
+ (<literal>{</literal> and <literal>}</literal>):</para>
+
+ <programlisting>#{set}($name = "apple")
+
+#{foreach}($i in [1..10])
+ The count is $i
+#{end}</programlisting>
+
+ <para>All available Velocity directives are listed in the <link
+ linkend="chapter-directives">Directives chapter</link>.</para>
+ </section>
- <para>Comments allows descriptive text to be included that is not placed
- into the output of the template engine. Comments are a useful way of
- reminding yourself and explaining to others what your VTL statements are
- doing, or any other purpose you find useful. Below is an example of a
- comment in VTL.</para>
-
- <programlisting>## This is a single line comment.</programlisting>
-
- <para>A single line comment begins with <literal>##</literal> and finishes
- at the end of the line. If you're going to write a few lines of
- commentary, there's no need to have numerous single line comments.
- Multi-line comments, which begin with <literal>#*</literal> and end with
- <literal>*#</literal>, are available to handle this scenario.</para>
+ <section id="section-reference">
+ <title>References</title>
- <programlisting>This is text that is outside the multi-line comment.
+ <para>Velocity references are the glue which connect templates to the
+ application. Template designers and application developers must agree on
+ a common set of references used by the Java application and the Velocity
+ templates. Every Velocity reference represents a Java object.</para>
+
+ <para>A Velocity reference starts with a <literal>$</literal> character
+ followed by an <firstterm>identifier</firstterm> name.</para>
+
+ <example id="example-velocity-references">
+ <title>Velocity References</title>
+
+ <programlisting>## Simple reference
+The total amout is $total.
+
+## Property reference
+You currently have $cart.items Items in your Shopping cart.
+
+## Method reference
+We offer you a discount of $cart.calculateDiscount() for your purchase.
+
+## Creating a new reference from Velocity
+#set($linesPerPage = 20)</programlisting>
+ </example>
+
+ <para>If you need to separate a reference identifier name from the
+ surrounding template, you can wrap the reference identifier in curly
+ braces (<literal>{</literal> and <literal>}</literal>):</para>
+
+ <programlisting>The total amout is ${total}.
+
+You currently have ${cart.items} Items in your Shopping cart.</programlisting>
+
+ <para>Velocity references are discussed in depth in the <link
+ linkend="chapter-references">References chapter</link>.</para>
+ </section>
+
+ <section id="section-comments">
+ <title>Comments</title>
+
+ <para>Comments allows descriptive text to be included in a template that
+ is not placed into the output of the template engine. Comments are a
+ useful way of reminding yourself and explaining to others what your VTL
+ statements are doing, or any other purpose you find useful.</para>
+
+ <para>Like the Java programming language, Velocity has single-line and
+ block comments.</para>
+
+ <para>A single line comment begins with <literal>##</literal> and
+ finishes at the end of the line. This is an example of a single line
+ comment in VTL:</para>
+
+ <programlisting>## This is a single line comment.
+
+This is visible in the output ## This is a comment.</programlisting>
+
+ <para>If you are going to write a few lines of commentary, there is no
+ need to have numerous single line comments. Multi-line comments, which
+ begin with <literal>#*</literal> and end with <literal>*#</literal>, are
+ available to handle this scenario:</para>
+
+ <programlisting>This is text that is outside the multi-line comment.
Online visitors can see it.
#*
- Thus begins a multi-line comment. Online visitors won't
+ Thus begins a multi-line comment. Online visitors will not
see this text because the Velocity Templating Engine will
ignore it.
*#
Here is text outside the multi-line comment; it is visible.</programlisting>
- <para>Here are a few examples to clarify how single line and multi-line
- comments work:</para>
+ <para>Multiline comments can start and end in arbitrary columns of the
+ template.</para>
- <programlisting>This text is visible. ## This text is not.
-This text is visible.
-This text is visible. #* This text, as part of a multi-line
-comment, is not visible. This text is not visible; it is also
-part of the multi-line comment. This text still not
-visible. *# This text is outside the comment, so it is visible.
-## This text is not visible.</programlisting>
-
- <para>There is a third type of comment, the VTL comment block, which may
- be used to store such information as the document author and versioning
- information:</para>
+ <para>There is a third type of comment, the <firstterm>VTL comment
+ block</firstterm>, which may be used to store such information as the
+ document author and versioning information. It is similar to the Javadoc
+ comment block in the Java programming language:</para>
- <programlisting>#**
+ <programlisting>#**
This is a VTL comment block and
may be used to store such information
as the document author and versioning
@@ -299,6 +483,112 @@
@author
@version 5
*#</programlisting>
+ </section>
+
+ <section id="escaping-velocity">
+ <title>Escaping VTL elements</title>
+
+ <para>Most of the time, there is no problem, rendering a Velocity
+ template because the rendering engine is quite smart about finding
+ Velocity Statements and References and distinguishing them from regular
+ text.</para>
+
+ <programlisting>## Renders as normal text, because the dollar sign
+## is not followed by a letter.
+I bought a 4 lb. sack of potatoes for only $2.50!
+
+## Renders as variable
+I bought a 4 lb. sack of potatoes for only $money.</programlisting>
+
+ <para>Velocity allows for explicit escaping of References and Directives
+ using the <literal><literal>\</literal></literal> (backslash) character.
+ If the character following the <literal>\</literal> would start a new
+ directive or reference, then this character is output verbatim. This can
+ lead to some unexpected behaviour, especially with directives.</para>
+
+ <example id="example-vtl-escaping-examples">
+ <title>VTL escaping examples</title>
+
+ <programlisting>\ ## Renders as a single backslash (no # or $ follows)
+
+\\ \# \$ ## Renders as \\ \# \$ (no directive or reference follows)
+
+\#end ## Renders as #end, backslash escapes an existing directive</programlisting>
+ </example>
+
+ <para>Unfortunately, the escaping of VTL elements contains a number of
+ quirks that make them actually hard to use<footnote>
+ <para>It is really mind-boggling how we came up with this. It is
+ tied more to the internal workings of the Velocity engine than any
+ user-friendlyness. This is definitely subject to change in future
+ Velocity versions. Until then, please be kind to our
+ mistakes.</para>
+ </footnote>. As you have seen, the behaviour of the
+ <literal>\</literal> differs whether a directive or just text
+ follows:</para>
+
+ <example id="example-escaping-vtl-references">
+ <title>Escaping VTL references</title>
+
+ <programlisting>$a ## $a is a reference but an unbound on (it has no value)
+ ## This renders as $a in the output
+
+\$a ## Escaping an unbound reference renders it as \$a
+
+#set($a = 10) ## When a value is assigned to the reference...
+
+$a ## Now renders as 10
+
+\$a ## Now renders as $a</programlisting>
+ </example>
+
+ <para>Escaping VTL statements works in the same way.</para>
+
+ <example id="example-escaping-vtl-statements">
+ <title>Escaping VTL statements</title>
+
+ <programlisting>\#end ## Renders as #end
+\# end ## Renders as \# end (note the space)
+
+\#set ($a = 10) ## Renders as #set ($a = 10)
+
+## If $a has been assigned a value:
+
+#set ($a = 10)
+\#set ($a = 20) ## Renders as #set (10 = 20)
+
+## The backslash does not escape a whole multiline statement
+## This is a syntax error: (#end without a starting statement)
+\#if ($a == 10)
+#end</programlisting>
+ </example>
+
+ <para>Using <link linkend="chapter-velocity-macros">Velocity
+ Macros</link>, the behaviour of escaping <literal>#</literal> changes a
+ bit:<note>
+ <para>And you probably thought, the worst part was over...</para>
+ </note></para>
+
+ <example id="example-escaping-macros">
+ <title>Escaping Macros</title>
+
+ <programlisting>#apple ## Renders as #apple, because it is not a VTL
+ ## statement
+\#apple ## Renders as \#apple
+
+#macro(apple)
+ Apple
+#end
+
+#apple ## This is now an syntax error (#apple needs now
+ ## brackets because it's a macro)
+
+#apple() ## Renders as Apple (VTL Macro)
+
+\#apple ## renders as #apple, because it is now a VTL
+ ## statement after macro definition.</programlisting>
+ </example>
+ </section>
</chapter>
<chapter id="chapter-references">
@@ -306,214 +596,315 @@
<para>There are three types of references in the VTL:
<firstterm>variables</firstterm>, <firstterm>properties</firstterm> and
- <firstterm>methods</firstterm>. 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 in your templates.</para>
-
- <para>Everything coming to and from a reference is treated as a String
- object. If there is an object that represents <literal>$foo</literal>
- (such as an Integer object), then Velocity will call its
- <literal>.toString()</literal> method to resolve the object into a
- String.</para>
-
- <section id="section-variables">
- <title>Variables</title>
-
- <para>The shorthand notation of a variable consists of a leading "$"
- character followed by a VTL <firstterm>Identifier</firstterm>. A VTL
- Identifier must start with an alphabetic character (a .. z or A .. Z).
- The rest of the characters are limited to the following types of
- characters:</para>
+ <firstterm>methods</firstterm>. They are the glue that connects the
+ business logic of your application, which probably is written in Java to
+ your templates. The Java code and the templates must use the same set of
+ references, so you, as a template designer and your engineer must agree on
+ the references available for use on the templates.</para>
+
+ <para>Every reference that is output when a template is rendered, is
+ converted to a Java string by calling the <literal>toString()</literal>
+ method on the Java object which represents the reference. If you want a
+ reference rendered in a special way, you can ask your Java developers to
+ implement or override this method.</para>
+
+ <section id="section-identifiers">
+ <title>Identifiers</title>
+
+ <para>All references consist of a leading <literal>$</literal> character
+ followed by a VTL <firstterm>Identifier</firstterm>. A VTL Identifier
+ must start with an alphabetic character (a..z or A..Z). The rest of the
+ characters are limited to the following types of characters:</para>
<para><itemizedlist spacing="compact">
<listitem>
- <para>alphabetic (a .. z, A .. Z)</para>
+ <para>alphabetic (<literal>a..z</literal>,
+ <literal>A..Z</literal>)</para>
</listitem>
<listitem>
- <para>numeric (0 .. 9)</para>
+ <para>numeric (<literal>0..9</literal>)</para>
</listitem>
<listitem>
- <para>hyphen ("-")</para>
- </listitem>
-
- <listitem>
- <para>underscore ("_")</para>
+ <para>hyphen and underscore: <literal>-</literal> and
+ <literal>_</literal></para>
</listitem>
</itemizedlist></para>
- <para>Here are some examples of valid variable references in the
- VTL:</para>
+ <para>Velocity identifiers are, just as Java variable names,
+ case-sensitive.</para>
+ </section>
+
+ <section id="section-variables">
+ <title>Variables</title>
+
+ <para>Variables are the simplest type of references, because each
+ reference is also a variable. Each variable represents a Java
+ object.</para>
+
+ <example>
+ <title>Valid variable names</title>
- <programlisting>$foo
+ <programlisting>$foo
$bar
$foo-bar
$foo_bar
$fooBar1</programlisting>
+ </example>
- <para>When VTL references a variable, such as <literal>$foo</literal>,
- the variable can get its value from either a <literal>set</literal>
- directive in the template, or from Java code. For example, if the Java
- variable <literal>$foo</literal> has the value <literal>bar</literal> at
- the time the template is requested, <literal>bar</literal> replaces all
- instances of <literal>$foo</literal> on the web page. Alternatively, if
- I include the statement</para>
+ <para>Velocity keeps an internal map from Identifiers to Variables
+ called the <firstterm>Context</firstterm>. This map is where Java code
+ can place objects to be reference from the template.</para>
+
+ <para>A variable must be assigned a value before it can be referenced
+ from the template. Assigning a value to a Velocity variable is the same
+ as placing an object in the Context from the Java code of your
+ application.</para>
- <programlisting>#set( $foo = "bar" )</programlisting>
+ <programlisting>## Puts a String object representing "bar" in the Context
+#set( $foo = "bar" )</programlisting>
- <para>The output will be the same for all instances of
- <literal>$foo</literal> that follow this directive.</para>
+ <note>
+ <para>Assigning a new value using the #set statement to a variable
+ does change the object present in the Context.</para>
+ </note>
</section>
<section id="section-properties">
<title>Properties</title>
- <para>The second flavor of VTL references are properties, and properties
- have a distinctive format. The shorthand notation consists of a leading
- <literal>$</literal> character followed a VTL Identifier, followed by a
- dot character (".") and another VTL Identifier. These are examples of
- valid property references in the VTL:</para>
+ <para>Velocity allows you to access properties through a short-hand
+ notation. The objects to look up the properties must be available
+ through a Velocity variable and the notation consists of a leading
+ variable followed by the dot ("<literal>.</literal>") character and
+ another VTL Identifier.</para>
+
+ <example>
+ <title>Valid property names</title>
+
+ <programlisting>$customer.address
+$purchase.total
+$cart.customerDiscount</programlisting>
+ </example>
- <programlisting>$customer.address
-$purchase.total</programlisting>
+ <para>A property name can represent the following elements depending on
+ the object used for look-up:</para>
- <para>Take the first example, <literal>$customer.address</literal>. It
- can have two meanings. It can mean, "look in the hashtable identified as
- <literal>customer</literal> and return the value associated with the key
- <literal>address</literal>". But <literal>$customer.address</literal>
- can also be referring to a method (references that refer to methods will
- be discussed in the next chapter); <literal>$customer.address</literal>
- could be an abbreviated way of writing
- <literal>$customer.getAddress()</literal>. When your page is requested,
- Velocity will determine which of these two possibilities makes sense,
- and then return the appropriate value.<footnote id="properties1">
- <para>This might look confusing. It gets even more confusing due to
- the fact that you can write <literal>Address</literal> instead of
- <literal>address</literal> and while this will request a different
- key from the hashtable, it will still invoke
- <literal>getAddress()</literal>. If you use
- <literal>$customer.address</literal> to invoke a method getter, we
- strongly recommend that you use the first-letter lowercase
- notation.</para>
- </footnote></para>
- </section>
-
- <section id="section-methods">
- <title>Methods</title>
+ <itemizedlist>
+ <listitem>
+ <para>If the object has a method
+ <literal>get<property></literal> where the property name is
+ not modified, this method is invoked</para>
+ </listitem>
- <para>A method is defined in the Java code and is capable of doing
- something useful, like running a calculation or arriving at a decision.
- Methods are references that consist of a leading <literal>$</literal>
- character followed a VTL Identifier, followed by a VTL <firstterm>Method
- Body</firstterm>. A VTL Method Body consists of a VTL Identifier
- followed by an left parenthesis character ("("), followed by an optional
- parameter list, followed by right parenthesis character (")"). These are
- examples of valid method references in the VTL:</para>
+ <listitem>
+ <para>else if the object is a Java bean (has methods conforming to
+ the Sun Java Bean specification for accessing bean properties), the
+ bean getter is executed to access the value</para>
+ </listitem>
- <programlisting>$customer.getAddress()
-$purchase.getTotal()
-$page.setTitle( "My Home Page" )
-$person.setAttributes( ["Strange", "Weird", "Excited"] )</programlisting>
+ <listitem>
+ <para>finally if the object used to look up the property has a
+ get(String) method, invoke this method.</para>
+ </listitem>
+ </itemizedlist>
- <para>The first two examples --
- <literal>$customer.getAddress()</literal> and
- <literal>$purchase.getTotal()</literal> -- may look similar to those
- used in the Properties chapter above,
- <literal>$customer.address</literal> and
- <literal>$purchase.total</literal>. If you guessed that these examples
- must be related some in some fashion, you are correct!</para>
-
- <para>VTL Properties can be used as a shorthand notation for VTL
- Methods. The Property <literal>$customer.address</literal> has the exact
- same effect as using the Method
- <literal>$customer.getAddress()</literal>. 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.</para>
+ <para>Take the first example, <literal>$customer.address</literal>. It
+ can have multiple meanings:<footnote>
+ <para>The sequence of these lookups is determined by the
+ <firstterm>Velocity Uberspector</firstterm>. This is merely the
+ default lookup. A Java developer can customize this behaviour by
+ using a custom Uberspector.</para>
+ </footnote></para>
- <para>The shorthand notation can be used for the following
- Methods</para>
+ <itemizedlist>
+ <listitem>
+ <para>when the object has a method <literal>getaddress()</literal>,
+ invoke this method</para>
+ </listitem>
- <programlisting>$shop.getFruits()
-$sun.getPlanets()
-$album.getPhoto()</programlisting>
+ <listitem>
+ <para>when the object is a Java bean with a property
+ <literal>address</literal>, invoke its getter,
+ <literal>getAddress()</literal></para>
+ </listitem>
- <para>We might expect these methods to return the fruits belonging to a
- shop, the names of planets belonging to a sun, or get a photograph from
- an album. Only the long notation works for the following Methods.</para>
+ <listitem>
+ <para>when the object has a method <literal>get(String)</literal>,
+ invoke this method, passing <literal>address</literal> as
+ parameter.</para>
+ </listitem>
- <programlisting>$sun.getPlanet(3)
-## Can't pass a parameter with $sun.planet
+ <listitem>
+ <para>when the object has a method <literal>isAddress()</literal>,
+ invoke this method.</para>
+ </listitem>
+ </itemizedlist>
-$shop.orderFruits()
-## Velocity only allows shorthand notation for get<property name>
+ <note>
+ <para>When a property name refers to a getter method,
+ <literal>$obj.property</literal> and <literal>$obj.Property</literal>
+ will both invoke the same method (either
+ <literal>getproperty()</literal> or <literal>getProperty()</literal>).
+ However, if the object represented by <literal>$obj</literal> has a
+ <literal>get(String)</literal> method,
+ <literal>$obj.property</literal> and <literal>$obj.Property</literal>
+ will pass different values to this <literal>get(String)</literal>
+ method. This can lead to hard-to-find problems. It's a good practice
+ to standardize the capitalization of property names in your
+ application.</para>
+ </note>
-$book.setTitle( "Homage to Catalonia" )
-## Can't pass a parameter list</programlisting>
+ <para>If you wonder about setting property values, please look up the
+ #set() directive chapter. The setting of properties is discussed
+ there.</para>
+
+ <section id="section-property-lookup-rules">
+ <title>Default property lookup rules</title>
+
+ <para>Velocity is quite clever when figuring out which method
+ corresponds to a requested property.<footnote>
+ <para>Some people would say that it is entirely too clever.</para>
+ </footnote>It tries out different alternatives based on several
+ established naming conventions. The exact lookup sequence depends on
+ whether or not the property name starts with an upper-case letter. For
+ lower-case names, such as <literal>$customer.address</literal>, the
+ sequence is <itemizedlist spacing="compact">
+ <listitem>
+ <para><literal>getaddress()</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>getAddress()</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>get("address")</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>isAddress()</literal></para>
+ </listitem>
+ </itemizedlist> For upper-case property names like
+ <literal>$customer.Address</literal>, it is slightly different:
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para><literal>getAddress()</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>getaddress()</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>get("Address")</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>isAddress()</literal></para>
+ </listitem>
+ </itemizedlist>As regular bean properties tend to be written in
+ lowercase notation, you should talk to your programmers that they
+ don't add both lower-case and upper-case methods to their objects. It
+ would be a bad idea anyway.</para>
+
+ <caution>
+ <para>There are some exotic naming cases, such as a property
+ starting with multiple upper-case letters which are treated
+ specially according to the Java Bean specification. Velocity does
+ not conform to this specification, so if you have a method called
+ <literal>getURL()</literal>, you cannot use
+ <literal>$obj.url</literal> to invoke the method, you must use
+ <literal>$obj.URL</literal> or <literal>$obj.uRL</literal>. This
+ might change in future versions of Velocity.</para>
+ </caution>
+ </section>
</section>
- <section id="section-property-lookup-rules">
- <title>Property lookup rules</title>
+ <section id="section-methods">
+ <title>Methods</title>
- <para>As was mentioned earlier, properties often refer to methods of the
- parent object. Velocity is quite clever when figuring out which method
- corresponds to a requested property<footnote>
- <para>Some people would say, that it is entirely too clever. For
- this lookup, it uses a construct called the
- <emphasis>Uberspector</emphasis>. There is more information on this
- in the Developers Guide.</para>
- </footnote>. It tries out different alternatives based on several
- established naming conventions. The exact lookup sequence depends on
- whether or not the property name starts with an upper-case letter. For
- lower-case names, such as <literal>$customer.address</literal>, the
- sequence is <itemizedlist spacing="compact">
- <listitem>
- <para><literal>getaddress()</literal></para>
- </listitem>
+ <para>A method is part of a context object, written in Java code, and is
+ capable of doing something useful, like running a calculation or
+ arriving at a decision. Method invocation is indicated by round
+ parentheses following the method name. These parentheses can optionally
+ contain a parameter list.</para>
+
+ <example>
+ <title>Valid method references</title>
+
+ <programlisting>$cart.calculateTotal()
+$customer.updatePurchases($cart)
+$shop.checkInventory()
+$cart.addTaxes(8, 16)
- <listitem>
- <para><literal>getAddress()</literal></para>
- </listitem>
+# Property access
+$page.setTitle( "My Home Page" )
+$customer.getAddress()
+$purchase.getTotal()</programlisting>
+ </example>
+
+ <para>The last few examples are similar to the examples seen earlier
+ when discussing properties. As stated there, the properties notation is
+ a short-hand notation for the invocation of bean getters and
+ setters.<footnote>
+ <para>By explicitly stating the method name and parameters, the
+ Uberspector is not used. This is useful if you object has both,
+ <literal>get(String)</literal> and explicit property getter
+ methods.</para>
+ </footnote></para>
- <listitem>
- <para><literal>get("address")</literal></para>
- </listitem>
+ <para>The main difference between Properties and Methods is that you can
+ specify a parameter list to a Method.</para>
- <listitem>
- <para><literal>isAddress()</literal></para>
- </listitem>
- </itemizedlist> For upper-case property names like
- <literal>$customer.Address</literal>, it is slightly different:
- <itemizedlist spacing="compact">
- <listitem>
- <para><literal>getAddress()</literal></para>
- </listitem>
+ <example>
+ <title>Methods that can be used with shorthand notation</title>
- <listitem>
- <para><literal>getaddress()</literal></para>
- </listitem>
+ <programlisting>$shop.getFruits()
+$sun.getPlanets()
+$album.get("logo")
- <listitem>
- <para><literal>get("Address")</literal></para>
- </listitem>
+$shop.setCustomer($customer)
+$sun.setPlanetCount(9)
+$album.put("logo", "newlogo")
+
+## equal property getters and setters
+
+$shop.fruits
+$sun.Planets
+$album.logo
+
+#set ($shop.customer = $customer)
+#set ($sun.planetCount = 9)
+#set ($album.logo = "New Logo")</programlisting>
+ </example>
+
+ <warning>
+ <para>The last #set() example will not work in Velocity versions
+ before 1.5 unless the <literal>$album</literal> object implements
+ <literal>java.util.Map</literal>. This is a bug in older Velocity
+ versions.</para>
+ </warning>
+
+ <para>Not every method invocation can be replaced by short hand
+ notation. Even if a method is called
+ <literal>set<property>()</literal> or
+ <literal>get<property>()</literal>, it must still adhere to bean
+ getter and setter method signatures. </para>
- <listitem>
- <para><literal>isAddress()</literal></para>
- </listitem>
- </itemizedlist>As regular bean properties tend to be written in
- lowercase notation, you should talk to your programmers that they don't
- add both lower-case and upper-case methods to their objects. It would be
- a bad idea anyway.</para>
+ <example>
+ <title>Methods that can not be used with shorthand notation</title>
- <caution>
- <para>There are some exotic naming cases, such as a property starting
- with multiple upper-case letters which are treated specially according
- to the Java Bean specification. Velocity does not conform to this
- specification, so if you have a method called
- <literal>getURL()</literal>, you cannot use
- <literal>$obj.url</literal> to invoke themethod. This might change in
- future versions of Velocity.</para>
- </caution>
+ <programlisting>## Can't pass a parameter with $sun.planet
+$sun.getPlanet(3)
+
+## Velocity only allows shorthand notation for getter and setter
+$shop.orderFruits()
+
+## Can't pass a parameter list
+$book.setAuthorandTitle("George Orwell", "Homage to Catalonia")</programlisting>
+ </example>
</section>
<section id="section-formal-reference-notation">
@@ -598,85 +989,6 @@
<literal>#</literal>, to do its work, so some added care should be taken
where using these characters in your templates. This chapter deals with
escaping the <literal>$</literal> character.</para>
-
- <section id="section-currency">
- <title>Currency</title>
-
- <para>There is no problem writing "I bought a 4 lb. sack of potatoes at
- the farmer's market for only $2.50!" As mentioned, a VTL identifier
- always begins with an upper- or lowercase letter, so $2.50 would not be
- mistaken for a reference.</para>
- </section>
-
- <section id="section-escaping-valid-vtl-references">
- <title>Escaping Valid VTL References</title>
-
- <para>Cases may arise where there is the potential for Velocity to get
- confused. <emphasis>Escaping</emphasis> special characters is the best
- way to handle VTL's special characters in your templates, and this can
- be done using the backslash (<literal>\</literal>) character.</para>
-
- <para>Consider the following VTL template:</para>
-
- <programlisting>#set( $fruit = "apple" )
-$fruit</programlisting>
-
- <para>If Velocity encounters a reference in your VTL template to
- <literal>$fruit</literal>, it will search the Context for a
- corresponding value. Here the output will be <literal>apple</literal>,
- because <literal>$fruit</literal> is defined. If
- <literal>$fruit</literal> is not defined, the output will be
- <literal>$fruit</literal>.</para>
-
- <para>Suppose that <literal>$fruit</literal> is defined (for example, if
- it has the value <literal>apple</literal>), and that you want to output
- <literal>$fruit</literal>. There are a few ways of doing this, but the
- simplest is to use the escape character.</para>
-
- <programlisting>## The following line defines $fruit in this template:
-#set( $fruit = "apple" )
-$fruit
-\$fruit
-\\$fruit
-\\\$fruit</programlisting>
-
- <para>renders as</para>
-
- <programlisting>apple $fruit \apple
- \$fruit</programlisting>
-
- <para>Note that the <literal>\</literal> character bind to the
- <literal>$</literal> from the left. The bind-from-left rule causes
- <literal>\\\$fruit</literal> to render as <literal>\\$fruit</literal>.
- Compare these examples to those in which <literal>$fruit</literal> is
- not defined.</para>
-
- <programlisting>$fruit
-\$fruit
-\\$fruit
-\\\$fruit</programlisting>
-
- <para>renders as</para>
-
- <programlisting>$fruit \$fruit \\$fruit
- \\\$fruit</programlisting>
-
- <para>Notice Velocity handles references that are defined differently
- from those that have not been defined. Here is a set directive that
- gives <literal>$fruit</literal> the value
- <literal>orange</literal>.</para>
-
- <programlisting>#set( $fruit = "orange" )
-$moon = $orange</programlisting>
-
- <para>The output will be: <literal>$moon = orange</literal> -- where
- <literal>$moon</literal> is output as a literal because it is undefined
- and <literal>gibbous</literal> is output in place of
- <literal>$foo</literal>.</para>
-
- <para>It is also possible to escape VTL directives; this is described in
- more detail in the Directives chapter.</para>
- </section>
</chapter>
<chapter id="chapter-case-substitution">
@@ -1178,7 +1490,7 @@
false.</para>
</section>
- <section id="the-or-operator">
+ <section id="the-or-operator">
<title>The OR Operator</title>
<para>Logical OR operators work the same way as AND operators, except
@@ -1203,7 +1515,7 @@
and the output is This OR That</para>
</section>
- <section id="the-not-operator">
+ <section id="the-not-operator">
<title>The NOT Operator</title>
<para>With logical NOT operators, there is only one argument:</para>
@@ -1223,7 +1535,7 @@
</section>
</section>
- <section id="loops">
+ <section id="loops">
<title>Loops - #foreach</title>
<para>The <literal>#foreach</literal> element allows for looping:</para>
@@ -1676,83 +1988,6 @@
</section>
</chapter>
- <chapter id="chapter-escaping-vtl-directives">
- <title>Escaping VTL Directives</title>
-
- <para>VTL directives can be escaped with the backslash character ("\")
- similar to valid VTL references.</para>
-
- <programlisting>## #include( "a.txt" ) renders as <contents of a.txt>
-#include( "a.txt" )
-
-## \#include( "a.txt" ) renders as #include( "a.txt" )
-\#include( "a.txt" )
-
-## \\#include ( "a.txt" ) renders as \<contents of a.txt>
-\\#include ( "a.txt" )</programlisting>
-
- <para>Extra care should be taken when escaping VTL directives that contain
- multiple script elements in a single directive (such as in an if-else-end
- statements). Here is a typical VTL if-statement:</para>
-
- <programlisting>#if( $jazz )
- Vyacheslav Ganelin
-#end</programlisting>
-
- <para>If <literal>$jazz</literal> is true, the output is</para>
-
- <programlisting>Vyacheslav Ganelin</programlisting>
-
- <para>If <literal>$jazz</literal> is false, there is no output. Escaping
- script elements alters the output. Consider the following case:</para>
-
- <programlisting>\#if( $jazz )
- Vyacheslav Ganelin
-\#end</programlisting>
-
- <para>Whether <literal>$jazz</literal> is true or false, the output will
- be</para>
-
- <programlisting>#if($ jazz ) Vyacheslav Ganelin
- #end</programlisting>
-
- <para>In fact, because all script elements are escaped,
- <literal>$jazz</literal> is never evaluated for its boolean value. Suppose
- backslashes precede script elements that are legitimately escaped:</para>
-
- <programlisting>\\#if( $jazz )
- Vyacheslav Ganelin
-\\#end</programlisting>
-
- <para>In this case, if <literal>$jazz</literal> is true, the output
- is</para>
-
- <para><programlisting>\ Vyacheslav Ganelin \</programlisting></para>
-
- <para>To understand this, note that the <literal>#if( arg ) </literal>
- when ended by a newline (return) will omit the newline from the output.
- Therefore, the body of the <literal>#if()</literal> block follows the
- first '\', rendered from the '\\' preceding the <literal>#if()</literal>.
- The last \ is on a different line than the text because there is a newline
- after 'Ganelin', so the final \\, preceding the <literal>#end</literal> is
- part of the body of the block.</para>
-
- <para>If <literal>$jazz</literal> is false, the output is</para>
-
- <para><programlisting>\</programlisting></para>
-
- <para>Note that things start to break if script elements are not properly
- escaped.</para>
-
- <programlisting>\\\#if( $jazz )
- Vyacheslave Ganelin
-\\#end</programlisting>
-
- <para>Here the <literal>#if</literal> is escaped, but there is an
- <literal>#end</literal> remaining; having too many endings will cause a
- parsing error.</para>
- </chapter>
-
<chapter id="chapter-formatting-issues">
<title>Formatting Issues</title>
@@ -2067,4 +2302,4 @@
versus '$sizeTall' which it would if the '{}' weren't there.</para>
</section>
</chapter>
-</book>
+</book>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org