Author: cbrisson
Date: Tue Oct 2 15:02:47 2018
New Revision: 1842632
URL: http://svn.apache.org/viewvc?rev=1842632&view=rev
Log:
[VELOCITY-902] docfix - plus add how to test for special values => into prod
Modified:
velocity/site/production/engine/2.0/user-guide.html
velocity/site/production/engine/devel/user-guide.html
Modified: velocity/site/production/engine/2.0/user-guide.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/engine/2.0/user-guide.html?rev=1842632&r1=1842631&r2=1842632&view=diff
==============================================================================
--- velocity/site/production/engine/2.0/user-guide.html (original)
+++ velocity/site/production/engine/2.0/user-guide.html Tue Oct 2 15:02:47 2018
@@ -666,54 +666,7 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>If the RHS is a property or method reference that evaluates to
<em>null</em>, it will <b>not</b> be assigned to the LHS. Depending on how
Velocity is configured, it is usually not possible to remove an existing
reference from the context via this mechanism. (Note that this can be permitted
by changing one of the Velocity configuration properties). This can be
confusing for newcomers to Velocity. For example:</p>
-<div class="codehilite"><pre><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span
class="nv">query</span><span class="p">.</span><span
class="nv">criteria</span><span class="p">(</span><span
class="s2">"name"</span><span class="p">)</span> <span
class="p">)</span><span class="x"></span>
-<span class="x">The result of the first query is </span><span
class="p">$</span><span class="nv">result</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">set</span><span class="p">(</span>
<span class="p">$</span><span class="nv">result</span> <span class="o">=</span>
<span class="p">$</span><span class="nv">query</span><span
class="p">.</span><span class="nv">criteria</span><span class="p">(</span><span
class="s2">"address"</span><span class="p">)</span> <span
class="p">)</span><span class="x"></span>
-<span class="x">The result of the second query is </span><span
class="p">$</span><span class="nv">result</span><span class="x"></span>
-</pre></div>
-
-
-<p>If <em>$query.criteria("name")</em> returns the string "bill", and
<em>$query.criteria("address")</em> returns <em>null</em>, the above VTL will
render as the following:</p>
-<div class="codehilite"><pre>The result of the first query is bill
-
-The result of the second query is bill
-</pre></div>
-
-
-<p>This tends to confuse newcomers who construct <em>#foreach</em> loops that
attempt to <em>#set</em> a reference via a property or method reference, then
immediately test that reference with an <em>#if</em> directive. For
example:</p>
-<div class="codehilite"><pre><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">criteria</span> <span class="o">=</span> <span
class="o">[</span><span class="s2">"name"</span><span
class="p">,</span> <span class="s2">"address"</span><span
class="p">]</span> <span class="p">)</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">foreach</span><span
class="p">(</span> <span class="p">$</span><span class="nv">criterion</span>
<span class="o">in</span> <span class="p">$</span><span
class="nv">criteria</span> <span class="p">)</span><span class="x"></span>
-
-<span class="x"> </span><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span
class="nv">query</span><span class="p">.</span><span
class="nv">criteria</span><span class="p">($</span><span
class="nv">criterion</span><span class="p">)</span> <span
class="p">)</span><span class="x"></span>
-
-<span class="x"> </span><span class="cp">#</span><span
class="nf">if</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="p">)</span><span class="x"></span>
-<span class="x"> Query was successful</span>
-<span class="x"> </span><span class="cp">#</span><span
class="nf">end</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">end</span><span class="x"></span>
-</pre></div>
-
-
-<p>In the above example, it would not be wise to rely on the evaluation of
<em>$result</em> to determine if a query was successful. After
<em>$result</em> has been <em>#set</em> (added to the context), it cannot be
set back to <em>null</em> (removed from the context). The details of the
<em>#if</em> and <em>#foreach</em> directives are covered later in this
document.</p>
-<p>One solution to this would be to pre-set <em>$result</em> to
<em>false</em>. Then if the <em>$query.criteria()</em> call fails, you can
check.</p>
-<div class="codehilite"><pre><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">criteria</span> <span class="o">=</span> <span
class="o">[</span><span class="s2">"name"</span><span
class="p">,</span> <span class="s2">"address"</span><span
class="p">]</span> <span class="p">)</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">foreach</span><span
class="p">(</span> <span class="p">$</span><span class="nv">criterion</span>
<span class="o">in</span> <span class="p">$</span><span
class="nv">criteria</span> <span class="p">)</span><span class="x"></span>
-
-<span class="x"> </span><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="o">=</span> <span class="nf">false</span>
<span class="p">)</span><span class="x"></span>
-<span class="x"> </span><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span
class="nv">query</span><span class="p">.</span><span
class="nv">criteria</span><span class="p">($</span><span
class="nv">criterion</span><span class="p">)</span> <span
class="p">)</span><span class="x"></span>
-
-<span class="x"> </span><span class="cp">#</span><span
class="nf">if</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="p">)</span><span class="x"></span>
-<span class="x"> Query was successful</span>
-<span class="x"> </span><span class="cp">#</span><span
class="nf">end</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">end</span><span class="x"></span>
-</pre></div>
-
-
+<p>If the RHS is a property or method reference that evaluates to
<em>null</em>, then the LHS will be set to null.</p>
<p>Unlike some of the other Velocity directives, the <em>#set</em> directive
does not have an <em>#end</em> statement.</p>
<h4 id="literals">Literals<a class="headerlink" href="#literals"
title="Permanent link">¶</a></h4>
<p>When using the <em>#set</em> directive, string literals that are enclosed
in double quote characters will be parsed and rendered, as shown:</p>
@@ -777,6 +730,14 @@ $foo
<li><em>$foo</em> is an object (other than a string, a number or a collection)
which is not null</li>
</ul>
<p>(please note that this is the default behavior, but Velocity can be
configured to <a href="configuration.html#if-directive">skip all checks beyond
boolean and nullity ones</a>).</p>
+<p>To test if a reference has a special values, you can use:</p>
+<ul>
+<li><code>#if ($ref == $null)</code> to specifically test for the null value
(provided you didn't put anything in <code>$null</code>)</li>
+<li><code>#if ($ref == false)</code> to specifically test for the false
value</li>
+<li><code>#if ($ref == '')</code> to specifically test for the empty
string</li>
+<li><code>#if ($ref == 0)</code> to specifically test for zero</li>
+<li><code>#if ($ref.size() == 0)</code> to specifically test for an empty
collection</li>
+</ul>
<p>Remember that the Velocity context only contains Objects, so when we say
'boolean', it will be represented as a Boolean (the class). This is true even
for methods that return <code>boolean</code> - the introspection infrastructure
will return a <code>Boolean</code> of the same logical value.</p>
<p>The content between the <em>#if</em> and the <em>#end</em> statements
become the output if the evaluation is true. In this case, if <em>$foo</em> is
true, the output will be: "Velocity!". Conversely, if <em>$foo</em> has a null
value, or if it is a boolean false, the statement evaluates as false, and there
is no output.</p>
<p>An <em>#elseif</em> or <em>#else</em> element can be used with an
<em>#if</em> element. Note that the Velocity Templating Engine will stop at the
first expression that is found to be true. In the following example, suppose
that <em>$foo</em> has a value of 15 and <em>$bar</em> has a value of 6.</p>
Modified: velocity/site/production/engine/devel/user-guide.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/engine/devel/user-guide.html?rev=1842632&r1=1842631&r2=1842632&view=diff
==============================================================================
--- velocity/site/production/engine/devel/user-guide.html (original)
+++ velocity/site/production/engine/devel/user-guide.html Tue Oct 2 15:02:47
2018
@@ -666,54 +666,7 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>If the RHS is a property or method reference that evaluates to
<em>null</em>, it will <b>not</b> be assigned to the LHS. Depending on how
Velocity is configured, it is usually not possible to remove an existing
reference from the context via this mechanism. (Note that this can be permitted
by changing one of the Velocity configuration properties). This can be
confusing for newcomers to Velocity. For example:</p>
-<div class="codehilite"><pre><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span
class="nv">query</span><span class="p">.</span><span
class="nv">criteria</span><span class="p">(</span><span
class="s2">"name"</span><span class="p">)</span> <span
class="p">)</span><span class="x"></span>
-<span class="x">The result of the first query is </span><span
class="p">$</span><span class="nv">result</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">set</span><span class="p">(</span>
<span class="p">$</span><span class="nv">result</span> <span class="o">=</span>
<span class="p">$</span><span class="nv">query</span><span
class="p">.</span><span class="nv">criteria</span><span class="p">(</span><span
class="s2">"address"</span><span class="p">)</span> <span
class="p">)</span><span class="x"></span>
-<span class="x">The result of the second query is </span><span
class="p">$</span><span class="nv">result</span><span class="x"></span>
-</pre></div>
-
-
-<p>If <em>$query.criteria("name")</em> returns the string "bill", and
<em>$query.criteria("address")</em> returns <em>null</em>, the above VTL will
render as the following:</p>
-<div class="codehilite"><pre>The result of the first query is bill
-
-The result of the second query is bill
-</pre></div>
-
-
-<p>This tends to confuse newcomers who construct <em>#foreach</em> loops that
attempt to <em>#set</em> a reference via a property or method reference, then
immediately test that reference with an <em>#if</em> directive. For
example:</p>
-<div class="codehilite"><pre><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">criteria</span> <span class="o">=</span> <span
class="o">[</span><span class="s2">"name"</span><span
class="p">,</span> <span class="s2">"address"</span><span
class="p">]</span> <span class="p">)</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">foreach</span><span
class="p">(</span> <span class="p">$</span><span class="nv">criterion</span>
<span class="o">in</span> <span class="p">$</span><span
class="nv">criteria</span> <span class="p">)</span><span class="x"></span>
-
-<span class="x"> </span><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span
class="nv">query</span><span class="p">.</span><span
class="nv">criteria</span><span class="p">($</span><span
class="nv">criterion</span><span class="p">)</span> <span
class="p">)</span><span class="x"></span>
-
-<span class="x"> </span><span class="cp">#</span><span
class="nf">if</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="p">)</span><span class="x"></span>
-<span class="x"> Query was successful</span>
-<span class="x"> </span><span class="cp">#</span><span
class="nf">end</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">end</span><span class="x"></span>
-</pre></div>
-
-
-<p>In the above example, it would not be wise to rely on the evaluation of
<em>$result</em> to determine if a query was successful. After
<em>$result</em> has been <em>#set</em> (added to the context), it cannot be
set back to <em>null</em> (removed from the context). The details of the
<em>#if</em> and <em>#foreach</em> directives are covered later in this
document.</p>
-<p>One solution to this would be to pre-set <em>$result</em> to
<em>false</em>. Then if the <em>$query.criteria()</em> call fails, you can
check.</p>
-<div class="codehilite"><pre><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">criteria</span> <span class="o">=</span> <span
class="o">[</span><span class="s2">"name"</span><span
class="p">,</span> <span class="s2">"address"</span><span
class="p">]</span> <span class="p">)</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">foreach</span><span
class="p">(</span> <span class="p">$</span><span class="nv">criterion</span>
<span class="o">in</span> <span class="p">$</span><span
class="nv">criteria</span> <span class="p">)</span><span class="x"></span>
-
-<span class="x"> </span><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="o">=</span> <span class="nf">false</span>
<span class="p">)</span><span class="x"></span>
-<span class="x"> </span><span class="cp">#</span><span
class="nf">set</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span
class="nv">query</span><span class="p">.</span><span
class="nv">criteria</span><span class="p">($</span><span
class="nv">criterion</span><span class="p">)</span> <span
class="p">)</span><span class="x"></span>
-
-<span class="x"> </span><span class="cp">#</span><span
class="nf">if</span><span class="p">(</span> <span class="p">$</span><span
class="nv">result</span> <span class="p">)</span><span class="x"></span>
-<span class="x"> Query was successful</span>
-<span class="x"> </span><span class="cp">#</span><span
class="nf">end</span><span class="x"></span>
-
-<span class="cp">#</span><span class="nf">end</span><span class="x"></span>
-</pre></div>
-
-
+<p>If the RHS is a property or method reference that evaluates to
<em>null</em>, then the LHS will be set to null.</p>
<p>Unlike some of the other Velocity directives, the <em>#set</em> directive
does not have an <em>#end</em> statement.</p>
<h4 id="literals">Literals<a class="headerlink" href="#literals"
title="Permanent link">¶</a></h4>
<p>When using the <em>#set</em> directive, string literals that are enclosed
in double quote characters will be parsed and rendered, as shown:</p>
@@ -777,6 +730,14 @@ $foo
<li><em>$foo</em> is an object (other than a string, a number or a collection)
which is not null</li>
</ul>
<p>(please note that this is the default behavior, but Velocity can be
configured to <a href="configuration.html#if-directive">skip all checks beyond
boolean and nullity ones</a>).</p>
+<p>To test if a reference has a special values, you can use:</p>
+<ul>
+<li><code>#if ($ref == $null)</code> to specifically test for the null value
(provided you didn't put anything in <code>$null</code>)</li>
+<li><code>#if ($ref == false)</code> to specifically test for the false
value</li>
+<li><code>#if ($ref == '')</code> to specifically test for the empty
string</li>
+<li><code>#if ($ref == 0)</code> to specifically test for zero</li>
+<li><code>#if ($ref.size() == 0)</code> to specifically test for an empty
collection</li>
+</ul>
<p>Remember that the Velocity context only contains Objects, so when we say
'boolean', it will be represented as a Boolean (the class). This is true even
for methods that return <code>boolean</code> - the introspection infrastructure
will return a <code>Boolean</code> of the same logical value.</p>
<p>The content between the <em>#if</em> and the <em>#end</em> statements
become the output if the evaluation is true. In this case, if <em>$foo</em> is
true, the output will be: "Velocity!". Conversely, if <em>$foo</em> has a null
value, or if it is a boolean false, the statement evaluates as false, and there
is no output.</p>
<p>An <em>#elseif</em> or <em>#else</em> element can be used with an
<em>#if</em> element. Note that the Velocity Templating Engine will stop at the
first expression that is found to be true. In the following example, suppose
that <em>$foo</em> has a value of 15 and <em>$bar</em> has a value of 6.</p>
