geirm 01/12/13 10:38:46
Modified: xdocs user-guide.xml
docs user-guide.html
Log:
Added patch from Pete Kazmier <[EMAIL PROTECTED]> re #set() and a little
note from me re #if(). Thanks, Pete!
Revision Changes Path
1.56 +91 -1 jakarta-velocity/xdocs/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/user-guide.xml,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -r1.55 -r1.56
--- user-guide.xml 2001/12/06 07:54:05 1.55
+++ user-guide.xml 2001/12/13 18:38:46 1.56
@@ -859,6 +859,88 @@
]]></source>
<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. It is
+ not possible to remove an existing reference from the context via
+ this mechanism. This can be confusing for
+ newcomers to Velocity. For example:
+ </p>
+
+<source><![CDATA[
+#set( $result = $query.criteria("name") )
+The result of the first query is $result
+
+#set( $result = $query.criteria("address") )
+The result of the second query is $result
+]]></source>
+
+ <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>
+
+<source><![CDATA[
+The result of the first query is bill
+
+The result of the second query is bill
+]]></source>
+
+ <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>
+
+<source><![CDATA[
+
+#set( $criteria = ["name", "address"] )
+
+#foreach( $criterion in $criteria )
+
+ #set( $result = $query.criteria($criterion) )
+
+ #if( $result )
+ Query was successful
+ #end
+
+#end
+]]></source>
+
+ <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 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>
+
+
+<source><![CDATA[
+
+#set( $criteria = ["name", "address"] )
+
+#foreach( $criterion in $criteria )
+
+ #set( $result = false )
+ #set( $result = $query.criteria($criterion) )
+
+ #if( $result )
+ Query was successful
+ #end
+
+#end
+]]></source>
+
+ <p>
Unlike some of the other Velocity directives, the <em>#set</em>
directive does not have an <em>#end</em> statement.
</p>
@@ -933,7 +1015,15 @@
The variable <em>$foo</em> is evaluated to determine whether it is
true, which will happen under one of two circumstances: (i)
<em>$foo</em> is a boolean (true/false) which has a true value, or
- (ii) the value is not null. The content between the <em>#if</em>
+ (ii) the value is not null. 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 intrspection 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
1.60 +152 -1 jakarta-velocity/docs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/user-guide.html,v
retrieving revision 1.59
retrieving revision 1.60
diff -u -r1.59 -r1.60
--- user-guide.html 2001/12/07 23:59:48 1.59
+++ user-guide.html 2001/12/13 18:38:46 1.60
@@ -1493,6 +1493,150 @@
</table>
</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. It is
+ not possible to remove an existing reference from the context via
+ this mechanism. This can be confusing for
+ newcomers to Velocity. For example:
+ </p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+#set( $result = $query.criteria("name") )
+The result of the first query is $result
+
+#set( $result = $query.criteria("address") )
+The result of the second query is $result
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </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 align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+The result of the first query is bill
+
+The result of the second query is bill
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </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 align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+#set( $criteria = ["name", "address"] )
+
+#foreach( $criterion in $criteria )
+
+ #set( $result = $query.criteria($criterion) )
+
+ #if( $result )
+ Query was successful
+ #end
+
+#end
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </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 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 align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+#set( $criteria = ["name", "address"] )
+
+#foreach( $criterion in $criteria )
+
+ #set( $result = false )
+ #set( $result = $query.criteria($criterion) )
+
+ #if( $result )
+ Query was successful
+ #end
+
+#end
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
Unlike some of the other Velocity directives, the <em>#set</em>
directive does not have an <em>#end</em> statement.
</p>
@@ -1652,7 +1796,14 @@
The variable <em>$foo</em> is evaluated to determine whether it is
true, which will happen under one of two circumstances: (i)
<em>$foo</em> is a boolean (true/false) which has a true value, or
- (ii) the value is not null. The content between the <em>#if</em>
+ (ii) the value is not null. 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 intrspection 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
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
