jcastura 00/12/05 21:17:40
Modified: xdocs user-guide.xml
Log:
added more on escaping references, directives
Revision Changes Path
1.20 +144 -19 jakarta-velocity/xdocs/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/user-guide.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- user-guide.xml 2000/12/03 01:07:02 1.19
+++ user-guide.xml 2000/12/06 05:17:40 1.20
@@ -25,11 +25,12 @@
</p>
<p>
- This user guide is a work in progress. Although every effort has been made
- to keep up-to-date with the development of Velocity,
+ This is an early draft of the user guide. Although every effort has
+ been made to keep up-to-date with the development of Velocity,
there remain some inconsistencies between the documented and the actual
- behaviour of Velocity. If you would like to report a mistake or offer a
suggestion,
- please send email to <link
href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link>.
+ behaviour of Velocity. To report a mistake or offer a suggestion,
+ please send email to
+ <link href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link>.
</p>
<p>
@@ -176,7 +177,7 @@
<p>
This VTL statement, like all VTL statements, begins with the
<directive>#</directive>
- character and contains a directive (<directive>set</directive>. When an online
visitor requests
+ character and contains a directive (<vtldirective>set</vtldirective>. When an
online visitor requests
your web page, the Velocity Templating Engine will search through your web page
to
find all <variable>#</variable> characters, then determine which mark the
beginning of VTL
statements, and which of the # characters that have nothing to do with VTL.
@@ -581,8 +582,8 @@
<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.
+ added care should be taken where using these characters in your templates. This
section deals
+ with escaping the $ character.
</p>
<p>
@@ -595,31 +596,99 @@
</p>
<p>
- <strong>Escaping special characters</strong>
+ <strong>Escaping Valid VTL References</strong>
<br/>
- Other cases may arise, however, where there is the potential for Velocity
+ Cases may arise where there is the potential for Velocity
to get confused. <em>Escaping</em> special characters is the best way
to handle VTL's special characters in your templates, and this can be
done using the backslash ("\") character.
</p>
-
+
<p>
- If Velocity encounters in your VTL template a reference to
- <variable>$email</variable>, it will search for a corresponding value, but
- when the escape character is used, <variable>$email</variable> is treated
- as ordinary text
+ <source><![CDATA[
+ #set $email = "foo"
+ $email
+ ]]></source>
</p>
-
+
+ <p>
+ If Velocity encounters a reference in your VTL template to
+ <variable>$email</variable>, it will search the Context for a corresponding
+ value. Here the output will be "foo", because <variable>$email</variable> is
defined.
+ If <variable>$email</variable> is not defined, the output will be "$email".
+ </p>
+
+ <p>
+ Suppose that <variable>$email</variable> is defined (for example, if it has the
value
+ "foo"), and that you want to output "$email". There are a few ways of doing
this,
+ but the simplest is to use the escape character.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ ## The following line defines $email in this template
+ #set $email = "foo"
+
+ ## The output of the following line will be $email's value: foo
+ $email
+
+ ## The output of the following line will be a literal: $email
+ \$email
+
+ ## The escape character binds from the left. The output of the following line
will
+ ## reflect this in its output: \$email
+ \\$email
+
+ ## The bind-from-left rule causes \\\$email to render as \\$email
+ \\\$email
+ ]]></source>
+ </p>
+
+ <p>
+ Compare these examples to those in which <variable>$email</variable> is not
defined.
+ </p>
+
<p>
<source><![CDATA[
+ ## $email is undefined
+
+ ## $email renders as $email
+ $email
+
+ ## \$email renders as \$email
\$email
+
+ ## \\$email renders as \\$email
+ \\$email
+
+ ## \\\$email renders as \\\$email
+ \\\$email
]]></source>
</p>
+
+ <p>
+ Notice Velocity handles references that are defined differently from those
+ that have not been defined.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ ## Here is a set directive that gives $foo the value "gibbous"
+ #set $foo = "gibbous"
+
+ ## The escape character is at work in the following line
+ $moon = $foo
+ #*
+ The output will be: $moon = gibbous
+ $moon is output as a literal because it is undefined.
+ The value of $foo is output because it is defined.
+ *#
+ ]]></source>
+ </p>
<p>
- Velocity treats <variable>$</variable> as a literal rather than a special
- character, <variable>$email</variable> as text rather than a reference,
- and doesn't even attempt to find a corresponding value.
+ It is also possible to escape VTL directives; this is described in more detail
in
+ the Directives section.
</p>
</s1>
@@ -943,7 +1012,7 @@
<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.
+ 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>
@@ -1131,6 +1200,62 @@
</table>
]]></source>
</p>
+
+ <p>
+ <strong>Escaping VTL Directives</strong>
+ <br/>
+ VTL directives can be escaped with the backslash character ("\") in a manner
similar
+ to valid VTL references.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ ## #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")
+ ]]></source>
+ </p>
+
+ <p>
+ 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).
+ </p>
+
+ <p>
+ <source><![CDATA[
+ ## Here is a typical VTL if-statement:
+ #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)
+ Vyacheslav Ganelin
+ \#end
+ ## This renders as: #if ($x) Vyacheslav Ganelin #end
+
+ ## A backslash can precede script elements that are legitimately escaped:
+ \\#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)
+ Vyacheslave Ganelin
+ \\#end
+ ## Here the #if is escaped, but there is an #end remaining.
+ ## Having too many endings will cause a parsing error.
+ ]]></source>
+ </p>
</s1>
