Author: henning
Date: Mon Sep 4 15:04:39 2006
New Revision: 440195
URL: http://svn.apache.org/viewvc?view=rev&rev=440195
Log:
Chapter 6 mostly done now.
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?view=diff&rev=440195&r1=440194&r2=440195
==============================================================================
--- jakarta/velocity/docbook/trunk/src/docbook/userguide/VelocityUsersGuide.xml
(original)
+++ jakarta/velocity/docbook/trunk/src/docbook/userguide/VelocityUsersGuide.xml
Mon Sep 4 15:04:39 2006
@@ -36,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>
@@ -353,7 +353,7 @@
<para>A multi-line statement starts like a single-line statement, but
also has a statement body. This body ends with
<literal>#end</literal>.<footnote>
- <para>Technically spoken, the opening statement and
+ <para>Technically speaking, the opening statement and
<literal>#end</literal> can be on the same line. We will still call
it a multi-line statement.</para>
</footnote></para>
@@ -1012,6 +1012,49 @@
directive, we will still speak about the <literal>#if</literal> or
<literal>#set</literal> directive.</para>
+ <para>Velocity knows about the following directives:<footnote>
+ <para>If is possible to add custom directives through the Velocity
+ configuration. These are merely the directives shipped with the
+ default Velocity configuration. It is even possible to turn some of
+ these off.</para>
+ </footnote></para>
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para><literal>#set()</literal> (single line statement)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>#literal()</literal> (multi line statement)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>#if() / #elseif() / #else</literal> (multi line
+ statement)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>#foreach()</literal> (multiline statement)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>#include()</literal> (single line statement)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>#parse()</literal> (single line statement)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>#stop()</literal> (single line statement)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>#macro()</literal> (multi line statement, see Chapter
+ 7)</para>
+ </listitem>
+ </itemizedlist>
+
<section id="section-the-set-directive">
<title>The <literal>#set</literal> directive</title>
@@ -1518,7 +1561,10 @@
and #parse directive, which both load external resources into the
rendering process of a template.</para>
- <para>Velocity does not allow you to </para>
+ <para>Velocity does not allow you to include arbitrary files into your
+ templates for security reasons. All included files will be loaded from
+ ResourceLoaders configured in the Velocity configuration. Please consult
+ the Developers Guide for information on how to do this.</para>
<section id="section-file-inclusion">
<title>File inclusion - #include</title>
@@ -1526,72 +1572,91 @@
<para>The <literal>#include</literal> directive allows the template
designer to import a local file. Its contents replace the
<literal>#include</literal> directive in the template. These contents
- are inserted as-is, they are not rendered through the template engine.
- For security reasons, the file to be included may only be under
- TEMPLATE_ROOT.</para>
+ are inserted as-is, they are not rendered through the template
+ engine.</para>
- <programlisting>#include( "one.txt" )</programlisting>
+ <para>Multiple files can be loaded through a single #include
+ directive, their names must be separated by commas.</para>
- <para>The file to which the <literal>#include</literal> directive
- refers is enclosed in quotes. If more than one file will be included,
- they should be separated by commas:</para>
+ <example>
+ <title>Including files into a Velocity Template</title>
+
+ <programlisting>## Load the file one.txt into this template
+#include( "one.txt" )
- <programlisting>#include( "one.gif","two.txt","three.htm"
)</programlisting>
+## Load multiple files into this template
+#include( "one.txt","two.txt","three.txt" )</programlisting>
+ </example>
<para>The file being included need not be referenced by name; in fact,
it is often preferable to use a variable instead of a filename. This
could be useful for targeting output according to criteria determined
- when the page request is submitted. Here is an example showing both a
- filename and a variable.</para>
+ when the page request is submitted.</para>
- <programlisting>#set ($seasonalgreetings = "christmas.txt")
+ <example>
+ <title>Including a file named by a variable reference</title>
+
+ <programlisting>#set ($seasonalgreetings = "christmas.txt")
#include( "greetings.txt", $seasonalgreetings )</programlisting>
+ </example>
</section>
<section id="section-template-inclusion">
<title>Template inclusion - #parse</title>
- <para>The <literal>#parse</literal> script element allows the template
- designer to import a local file that contains VTL. Velocity will parse
- the VTL and render the template specified. The output will replace the
+ <para>The <literal>#parse</literal> directive works similar to
+ <literal>#include</literal>, but the contents of the file will be part
+ of the template rendering process and all VTL elements in the file
+ will be evaluted. The output will replace the
<literal>#parse</literal> directive in the importing template.</para>
- <programlisting>#parse( "me.vm" )</programlisting>
+ <example>
+ <title>Including an external template</title>
+
+ <programlisting>#parse( "one.vm" )</programlisting>
+ </example>
<para>Like the <literal>#include</literal> directive,
<literal>#parse</literal> can take a variable rather than a template.
- Any templates to which <literal>#parse</literal> refers must be
- located under TEMPLATE_ROOT. Unlike the <literal>#include</literal>
- directive, <literal>#parse</literal> will only take a single
- argument.</para>
-
- <para>VTL templates can have <literal>#parse</literal> statements
- referring to templates that in turn have <literal>#parse</literal>
- statements:</para>
+ Unlike the <literal>#include</literal> directive,
+ <literal>#parse</literal> will only take a single argument, you cannot
+ load multiple templates with a single <literal>#parse</literal>
+ directive.</para>
+
+ <para>Recursion is permitted; VTL templates can have
+ <literal>#parse</literal> statements referring to templates that in
+ turn have <literal>#parse</literal> statements.</para>
- <para>Recursion is permitted:</para>
+ <example>
+ <title>Parsing a recursive template</title>
- <programlisting>## Template "countdown.vm"
+ <programlisting>## ########################################
+## Template "countdown.vm"
+## ########################################
Count down.
#set( $count = 8 )
#parse( "counter.vm" )
All done with countdown.vm!
+## ########################################
+## ########################################
## Template "counter.vm
+## ########################################
$count
#set( $count = $count - 1 )
#if( $count > 0 )
#parse("counter.vm" )
#else
All done with counter.vm!
-#end</programlisting>
+#end
+## ########################################
+
- <para>Rendering the <filename>countdown.vm</filename> template results
- in the following output:</para>
+The resulting output:
- <programlisting>Count down.
+Count down.
8
7
6
@@ -1604,9 +1669,16 @@
All done with counter.vm!
All done with countdown.vm!</programlisting>
+ </example>
<para>To avoid infinitive recursion, the number of levels is limited
- through a configuration property:</para>
+ through a configuration property. It is not possible to configure an
+ infinite recursion depth. The default maximum number of recursions is
+ 20.<footnote>
+ <para>As we said, we wanted to make it hard to write templates
+ that contain endless loops. Allowing recustion would have been too
+ easy.</para>
+ </footnote></para>
<programlisting># Maximum number of #parse levels
directive.parse.max.depth = 10</programlisting>
@@ -1616,23 +1688,65 @@
<section id="section-stop-template-rendering">
<title>Stop template rendering - #stop</title>
- <para>The <literal>#stop</literal> directive stops the execution of the
- template engine and return. The remaining part of the template after
- this directive is discarded. The most common usage of this directive is
- debugging templates.</para>
+ <para>The <literal>#stop</literal> directive stops the rendering of a
+ template. The remaining part of the template after this directive is
+ discarded. The most common usage of this directive is debugging
+ templates.</para>
- <programlisting>#stop</programlisting>
+ <example>
+ <title>Using <literal>#stop</literal> to end template
+ rendering</title>
- <para>Unlike most other directives, <literal>#stop</literal> has no
- matching <literal>#end</literal> directive.</para>
+ <programlisting>This part gets rendered in the output.
+#stop
+This part does not get rendered.</programlisting>
+ </example>
+
+ <para>The <literal>#stop</literal> directive can also be written as
+ <literal>#stop()</literal>.</para>
+
+ <caution>
+ <para>While <literal>#stop</literal> ends the rendering process, it
+ <emphasis>does not</emphasis> affect the template parsing. If you have
+ a syntax error in the VTL code after the <literal>#stop</literal>
+ directive, this error will still be reported.<footnote>
+ <para>It is possible to do strange things by using the
+ <literal>#stop</literal> directive inside <literal>#if ... #else
+ ... #end</literal> blocks. As <literal>#stop</literal> only ends
+ the rendering if it is actually rendered, it is possible to skip
+ over the directive.</para>
+ </footnote></para>
+ </caution>
+
+ <para/>
</section>
</chapter>
<chapter id="section-relational-and-logical-operators">
- <title>Relational and Logical Operators</title>
+ <title>Operators</title>
+
+ <para>Velocity knows a number of relational and logical operators. They
+ can be used everywhere an expression is evaluated, most prominently in
+ <literal>#if</literal> and <literal>#set</literal> directives.</para>
+
+ <para>Each operator is available in two notations, a short version which
+ is roughly equal to the Java notation and a text representation which can
+ be used to avoid problems e.g. with XML templates and the
+ <literal><</literal>, <literal>></literal> and
+ <literal>&&</literal> operators.<example>
+ <title>Using operators</title>
+
+ <para><programlisting>#set ($a = true)
+#set ($b = false)
+
+#if ($a || $b)
+ short version 'or' was true
+#end
- <para>Velocity uses operators to determine the relationships between
- variables.</para>
+#if ($a and $b)
+ text version 'and' was true
+#end</programlisting></para>
+ </example></para>
<table id="table-velocity-relational-and-logical-operators">
<title>Velocity Relational and logical operators</title>
@@ -1733,8 +1847,17 @@
</tgroup>
</table>
- <para>Here is a simple example to illustrate how the equivalent operator
- is used.</para>
+ <para><caution>
+ <para>Unlike other languages, Velocity does not consider the number 0
+ (zero) or the empty String ('') to be equivalent to false. Only the
+ boolean value false (primitive oder <literal>Boolean.FALSE</literal>)
+ and null are evaluated to false. Everything else evaluates to
+ true.<footnote>
+ <para>This was a conscious decision by the Velocity designers and
+ is not likely to change.</para>
+ </footnote></para>
+ </caution>Here is a simple example to illustrate how the equivalent
+ operator is used.</para>
<programlisting>#set ($foo = "deoxyribonucleic acid")
#set ($bar = "ribonucleic acid")
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
