You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by cb...@apache.org on 2018/10/02 15:02:47 UTC
svn commit: r1842632 - in /velocity/site/production/engine:
2.0/user-guide.html devel/user-guide.html
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>