jcastura 00/12/12 17:46:24
Modified: xdocs user-guide.xml vtl-reference-guide.xml
Log:
Christoph's suggestions for formatting in docs
Revision Changes Path
1.22 +104 -62 jakarta-velocity/xdocs/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/user-guide.xml,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- user-guide.xml 2000/12/12 05:06:50 1.21
+++ user-guide.xml 2000/12/13 01:46:24 1.22
@@ -115,11 +115,11 @@
<BODY>
Hello $customer.Name!
<table>
- #foreach ($mud in $mudsOnSpecial)
- #if ($customer.hasPurchased($mud))
+ #foreach( $mud in $mudsOnSpecial )
+ #if ( $customer.hasPurchased($mud) )
<tr>
<td>
- $flogger.getPromo($mud)
+ $flogger.getPromo( $mud )
</td>
</tr>
#end
@@ -170,7 +170,7 @@
<p>
<source><![CDATA[
- #set ($a = "Velocity")
+ #set( $a = "Velocity" )
]]>
</source>
</p>
@@ -225,7 +225,7 @@
<source><![CDATA[
<HTML>
<BODY>
- #set $foo = "Velocity"
+ #set( $foo = "Velocity" )
Hello $foo World!
</BODY>
<HTML>
@@ -370,7 +370,7 @@
<p>
<source><![CDATA[
- #set $foo = "bar"
+ #set( $foo = "bar" )
]]></source>
</p>
@@ -428,8 +428,8 @@
<source><![CDATA[
$customer.getAddress()
$purchase.getTotal()
- $page.setTitle("My Home Page")
- $person.setAttributes(["Strange", "Weird", "Excited"])
+ $page.setTitle( "My Home Page" )
+ $person.setAttributes( ["Strange", "Weird", "Excited"] )
]]></source>
</p>
@@ -470,13 +470,13 @@
<p>
<source><![CDATA[
- $sun.getPlanet(["Earth", "Mars", "Neptune"])
+ $sun.getPlanet( ["Earth", "Mars", "Neptune"] )
## Can't pass a parameter list with $sun.Planets
$sisyphus.pushRock()
## Velocity assumes I mean $sisyphus.getRock()
- $book.setTitle("Homage to Catalonia")
+ $book.setTitle( "Homage to Catalonia" )
## Can't pass a parameter list
]]></source>
</p>
@@ -593,7 +593,7 @@
<p>
VTL uses special characters, such as <vtl>$</vtl> and <vtl>#</vtl>, to do its
work, so some
added care should be taken where using these characters in your templates. This
section deals
- with escaping the $ character.
+ with escaping the <vtl>$</vtl> character.
</p>
<p>
@@ -616,7 +616,7 @@
<p>
<source><![CDATA[
- #set $email = "foo"
+ #set( $email = "foo" )
$email
]]></source>
</p>
@@ -637,7 +637,7 @@
<p>
<source><![CDATA[
## The following line defines $email in this template
- #set $email = "foo"
+ #set( $email = "foo" )
## The output of the following line will be $email's value: foo
$email
@@ -684,7 +684,7 @@
<p>
<source><![CDATA[
## Here is a set directive that gives $foo the value "gibbous"
- #set $foo = "gibbous"
+ #set( $foo = "gibbous" )
## The escape character is at work in the following line
$moon = $foo
@@ -764,8 +764,8 @@
<p>
<source><![CDATA[
- #set ($primate = "monkey")
- #set ($customer.Behavior = $primate)
+ #set( $primate = "monkey" )
+ #set( $customer.Behavior = $primate )
]]></source>
</p>
@@ -794,12 +794,12 @@
<p>
<source><![CDATA[
- #set ($monkey = $bill) ##variable reference
- #set ($monkey.Friend = "monica") ##string literal
- #set ($monkey.Blame = $whitehouse.Leak) ##property reference
- #set ($monkey.Plan = $spindoctor.weave($web)) ##method reference
- #set ($monkey.Number = 123) ##number literal
- #set ($monkey.Say = ["Not", $my, "fault"]) ##object array
+ #set( $monkey = $bill ) ##variable reference
+ #set( $monkey.Friend = "monica" ) ##string literal
+ #set( $monkey.Blame = $whitehouse.Leak ) ##property reference
+ #set( $monkey.Plan = $spindoctor.weave($web) ) ##method reference
+ #set( $monkey.Number = 123 ) ##number literal
+ #set( $monkey.Say = ["Not", $my, "fault"] ) ##object array
]]></source>
</p>
@@ -809,10 +809,10 @@
<p>
<source><![CDATA[
- #set ($value = $foo + 1)
- #set ($value = $bar - 1)
- #set ($value = $foo * $bar)
- #set ($value = $foo / $bar)
+ #set( $value = $foo + 1 )
+ #set( $value = $bar - 1 )
+ #set( $value = $foo * $bar )
+ #set( $value = $foo / $bar )
]]></source>
</p>
@@ -842,7 +842,7 @@
<p>
<source><![CDATA[
- #if ($foo)
+ #if( $foo )
<strong>Velocity!</strong>
#end
]]></source>
@@ -868,11 +868,11 @@
<p>
<source><![CDATA[
- #if ($foo < 10)
+ #if( $foo < 10 )
<strong>Go North</strong>
- #elseif ($foo > 10)
+ #elseif( $foo > 10 )
<strong>Go East</strong>
- #elseif ($bar = 6)
+ #elseif( $bar = 6 )
<strong>Go South</strong>
#else
<strong>Go West</strong>
@@ -900,7 +900,7 @@
<p>
<source><![CDATA[
- #if ($foo && $bar)
+ #if( $foo && $bar )
<strong>Velocity Rocks!</strong>
#end
]]></source>
@@ -926,7 +926,7 @@
<p>
<source><![CDATA[
- #if ($foo || $bar)
+ #if( $foo || $bar )
<strong>Velocity Rocks Again!</strong>
#end
]]></source>
@@ -955,7 +955,7 @@
<p>
<source><![CDATA[
<ul>
- #foreach ($product in $allProducts)
+ #foreach( $product in $allProducts )
<li>$product</li>
#end
</ul>
@@ -991,7 +991,7 @@
<p>
<source><![CDATA[
- #include ("one.txt")
+ #include( "one.txt" )
]]></source>
</p>
@@ -1001,7 +1001,7 @@
<p>
<source><![CDATA[
- #include ("one.gif","two.txt","three.htm")
+ #include( "one.gif","two.txt","three.htm" )
]]></source>
</p>
@@ -1011,7 +1011,7 @@
<p>
<source><![CDATA[
- #include ("greetings.txt",$seasonalstock)
+ #include( "greetings.txt",$seasonalstock )
]]></source>
</p>
@@ -1025,14 +1025,23 @@
<p>
<source><![CDATA[
- #parse ("me.vm")
+ #parse( "me.vm" )
]]></source>
</p>
<p>
- Like the <vtldirective>#include</vtldirective> directive,
<vtldirective>#parse</vtldirective> can take a variable rather than a template. Any
templates to which <vtldirective>#parse</vtldirective> refers must be included under
TEMPLATE_ROOT. Unlike the <vtldirective>#include</vtldirective> directive,
<vtldirective>#parse</vtldirective> will only take a single argument.
- Recursion is strictly prohibited; for example, <filename>foo.vm</filename>
cannot include the directive <vtldirective>#parse (foo.vm)</vtldirective>, nor can it
reference any other template which contains the statement <vtldirective>#parse
(foo.vm)</vtldirective>.
- VTL templates can have <vtldirective>#parse</vtldirective> statements referring
to templates that in turn have <vtldirective>#parse</vtldirective> statements. By
default set to 10, the <vtl>parse_directive.maxdepth</vtl> line of the
<filename>.properties</filename> allows users to customize maximum number of
<vtldirective>#parse</vtldirective> referrals that can occur from a single template.
(Note: If the <vtl>parse_directive.maxdepth</vtl> property is absent from the
<filename>velocity.properties</filename> file, Velocity will set this default to 20.)
+ Like the <vtldirective>#include</vtldirective> directive,
<vtldirective>#parse</vtldirective>
+ can take a variable rather than a template. Any templates to which
<vtldirective>#parse</vtldirective>
+ refers must be included under TEMPLATE_ROOT. Unlike the
<vtldirective>#include</vtldirective> directive,
+ <vtldirective>#parse</vtldirective> will only take a single argument.
+ Recursion is strictly prohibited; for example, <filename>foo.vm</filename>
cannot include the directive
+ <vtldirective>#parse (foo.vm)</vtldirective>, nor can it reference any other
template which contains the
+ statement <vtldirective>#parse (foo.vm)</vtldirective>. VTL templates can have
<vtldirective>#parse</vtldirective>
+ statements referring to templates that in turn have
<vtldirective>#parse</vtldirective> statements. By default
+ set to 10, the <vtl>parse_directive.maxdepth</vtl> line of the
<filename>.properties</filename> allows users
+ to customize maximum number of <vtldirective>#parse</vtldirective> referrals
that can occur from a single
+ template. (Note: If the <vtl>parse_directive.maxdepth</vtl> property is absent
from the
+ <filename>velocity.properties</filename> file, Velocity will set this default
to 20.)
</p>
</s1>
@@ -1061,7 +1070,7 @@
<p>
<source><![CDATA[
- #macro (d)
+ #macro( d )
<tr><td></td></tr>
#end
]]></source>
@@ -1093,8 +1102,8 @@
<p>
<source><![CDATA[
- #macro (tablerows $color $somelist)
- #foreach ($something in $somelist)
+ #macro( tablerows $color $somelist )
+ #foreach( $something in $somelist )
<tr><td bgcolor=$color>$something</td></tr>
#end
#end
@@ -1116,10 +1125,10 @@
<p>
<source><![CDATA[
- #set ($greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"])
- #set ($color = "blue")
+ #set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
+ #set( $color = "blue" )
<table>
- #tablerows ($color $names)
+ #tablerows( $color $names )
</table>
]]></source>
</p>
@@ -1196,10 +1205,10 @@
<p>
<source><![CDATA[
- #set ($parts = ["volva","stipe","annulus","gills","pileus"])
- #set ($cellbgcol = "#CC00FF")
+ #set( $parts = ["volva","stipe","annulus","gills","pileus"] )
+ #set( $cellbgcol = "#CC00FF" )
<table>
- #tablerows ($cellbgcol $parts)
+ #tablerows( $cellbgcol $parts )
]]></source>
</p>
@@ -1231,14 +1240,14 @@
<p>
<source><![CDATA[
- ## #include ("a.txt") renders as <contents of a.txt>
- #include ("a.txt")
+ ## #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 \#include( "a.txt" )
+ \#include( "a.txt" )
- ## \\#include ("a.txt") renders as \<contents of a.txt>
- \\#include ("a.txt")
+ ## \\#include ( "a.txt" ) renders as \<contents of a.txt>
+ \\#include ( "a.txt" )
]]></source>
</p>
@@ -1250,27 +1259,27 @@
<p>
<source><![CDATA[
## Here is a typical VTL if-statement:
- #if ($jazz)
+ #if( $jazz )
Vyacheslav Ganelin
#end
## If $jazz is true / not null, this renders as: Vyacheslav Ganelin
## If $jazz is false / null, there is no output
## Script elements can be escaped, as shown:
- \#if ($jazz)
+ \#if( $jazz )
Vyacheslav Ganelin
\#end
- ## This renders as: #if ($x) Vyacheslav Ganelin #end
+ ## This renders as: #if( $jazz ) Vyacheslav Ganelin #end
## A backslash can precede script elements that are legitimately escaped:
- \\#if ($jazz)
+ \\#if( $jazz )
Vyacheslav Ganelin
\\#end
## If $jazz is true / not null, this renders as: / Vyacheslav Ganelin /
## If $jazz is false / null, there is no output.
## Things break if script elements are not properly escaped.
- \\\#if ($jazz)
+ \\\#if( $jazz )
Vyacheslave Ganelin
\\#end
## Here the #if is escaped, but there is an #end remaining.
@@ -1289,8 +1298,8 @@
<p>
<source><![CDATA[
- #set ($imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"])
- #foreach ($shogun in $imperial)
+ #set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
+ #foreach( $shogun in $imperial )
$shogun
#end
]]></source>
@@ -1306,6 +1315,39 @@
<source><![CDATA[
Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.
]]></source>
+ </p>
+
+ <p>
+ Velocity's behaviour is to gobble up excess whitespace. The preceding
+ directive can be written as
+ </p>
+
+ <p>
+ <source><![CDATA[
+ Send me
+ #set( $foo = [#10 and ","a cake"] )
+ #foreach( $a in $foo )
+ $a
+ #end
+ please.
+ ]]></source>
+ </p>
+
+ <p>
+ or as
+ </p>
+
+ <p>
+ <source><![CDATA[
+ Send me
+ #set($foo = [#10 and ","a cake"])
+ #foreach ($a in $foo )$a
+ #end please.
+ ]]></source>
+ </p>
+
+ <p>
+ In each case the output will be the same.
</p>
</s1>
1.14 +61 -103 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.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- vtl-reference-guide.xml 2000/12/12 05:08:06 1.13
+++ vtl-reference-guide.xml 2000/12/13 01:46:24 1.14
@@ -7,6 +7,7 @@
<subtitle>VTL Refernce Guide</subtitle>
<authors>
<person name="Jason van Zyl" email="[EMAIL PROTECTED]"/>
+ <person name="John Castura" email="[EMAIL PROTECTED]"/>
</authors>
</header>
@@ -18,17 +19,17 @@
this reference guide and links should be made from
the user's guide to this document
-I now envision the user guide to be a long, pedagogical
-book and the VTL guide to be a distillation of VTL for
+I now envision the user guide to be pedagogical
+in nature and the VTL guide to be a distillation of VTL for
expert users and fast learners. I'd like each directive to
-have an identical format.
+have an identical format. -JC
-->
<s1 title="About this Guide">
<p>
- This guide is meant to be the definitive reference for
+ This guide is the definitive reference for
the Velocity Template Language (VTL).
</p>
@@ -46,12 +47,12 @@
<p>
<strong>Variables</strong>
<br/>
- The shorthand notation of a variable consists of a leading "$" character
+ The shorthand notation of a variable consists of a leading <vtl>$</vtl>
character
followed by a VTL <em>Identifier</em>. A VTL Identifier must
start with an alphabetic character (a .. z or A .. Z); the rest of the
characters are limited to the following types of characters: alphabetic,
numeric (0 .. 9), hyphen ("-"), and underscore ("_").
- Here are some examples of valid variable references in the VTL:
+ Here are examples of valid variable references in the VTL:
</p>
<p>
@@ -66,7 +67,7 @@
<p>
<strong>Properties</strong>
<br/>
- Properties are references that consist of a leading "$"
+ Properties are references that consist of a leading <vtl>$</vtl>
character followed a VTL Identifier, followed by
a dot character (".") and another VTL Identifier.
These are examples of valid property references in the VTL:
@@ -82,39 +83,39 @@
<p>
<strong>Methods</strong>
<br/>
- Methods are references that consist of a leading "$"
+ Methods are references that consist of a leading <vtl>$</vtl>
character followed a VTL Identifier, followed
by a VTL <em>Method Body</em>. 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:
+ Examples of valid method references in the
+ VTL are shown below:
</p>
<p>
<source><![CDATA[
$customer.getAddress()
$purchase.getTotal()
- $page.setTitle("My Home Page")
- $person.setAttributes("Strange", "Weird", "Excited")
+ $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.
+ VTL Properties can be used as a shorthand notation
+ for VTL Methods that take <vtl>get</vtl> and <vtl>set</vtl>.
+ <vtl>$object.getMethod()</vtl> or <vtl>$object.setMethod()</vtl>
+ can be abbreviated as <vtl>$object.Method</vtl>.
</p>
<p>
+ 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
@@ -130,30 +131,13 @@
]]></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:
+ Shorthand notation is usually used for references, but formal
+ reference notation is required for correct processing when
+ the identifier would otherwise be adjacent to text. In the
+ following example, Velocity would determine the reference
+ to be <vtl>$vicemaniac</vtl> were shorthand reference notation
+ used.
</p>
<p>
@@ -162,48 +146,19 @@
]]></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".
+ When Velocity encounters an undefined reference,
+ it outputs the image of the reference. For example, if
+ <vtl>$reference</vtl> is undefined, the output will be
+ <vtl>$reference</vtl>. Quiet reference notation can be
+ used to suppress this output, and is denoted with a
+ <vtl>!</vtl> after the <vtl>$</vtl> character; for
+ example, the quiet notation for <vtl>$reference</vtl>
+ is <vtl>$!reference</vtl> if shorthand notation is used,
+ and <vtl>$!{reference}</vtl> if formal notation is used.
</p>
</s1>
@@ -212,13 +167,13 @@
<p>
<strong>#set</strong>
<br/>
- The <vtldirective>#set</vtldirective> directive is used to
- set the value of a reference.
+ The <vtl>#set</vtl> directive is used to set the value of
+ a reference.
</p>
<p>
<source><![CDATA[
- #set ($ref = arg)
+ #set( $ref = arg )
]]></source>
</p>
@@ -228,7 +183,7 @@
</p>
<p>
- <vtl>$arg</vtl> - The RHS is limited to the following
+ <vtl>arg</vtl> - The RHS is limited to the following
types:
<ul>
<li>Variable reference</li>
@@ -247,12 +202,12 @@
<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"])
+ #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>
@@ -262,10 +217,10 @@
<p>
<source><![CDATA[
- #set ($value = $foo + 1)
- #set ($value = $bar - 1)
- #set ($value = $foo * $bar)
- #set ($value = $foo / $bar)
+ #set( $value = $foo + 1 )
+ #set( $value = $bar - 1 )
+ #set( $value = $foo * $bar )
+ #set( $value = $foo / $bar )
]]></source>
</p>
@@ -273,14 +228,14 @@
<p>
<strong>#foreach</strong>
<br/>
- The <vtldirective>#foreach</vtldirective> directive
- provides a simple way of looping through a list of objects.
+ The <vtl>#foreach</vtl> directive provides a simple way
+ of looping through a list of objects.
</p>
<p>
<source><![CDATA[
<table>
- #foreach ($customer in $customerList)
+ #foreach( $customer in $customerList )
<tr>
<td>
$customer.Name
@@ -299,7 +254,7 @@
<p>
<source><![CDATA[
<table>
- #foreach ($customer in $customerList)
+ #foreach( $customer in $customerList )
<tr>
<td>
$velocityCounter
@@ -337,13 +292,13 @@
<strong>#macro</strong>
<p>
- A Velocimacro is defined with the <vtldirective>#macro</vtldirective>
+ A Velocimacro is defined with the <vtl>#macro</vtl>
directive.
</p>
<p>
<source><![CDATA[
- #macro (vmname arg1 arg2)
+ #macro( vmname arg1 arg2 )
<VM VTL code>
#end
]]></source>
@@ -389,4 +344,7 @@
</body>
</document>
+
+
+
