velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbris...@apache.org
Subject svn commit: r1842631 - in /velocity/site/cms/trunk/content/engine: 2.0/user-guide.mdtext devel/user-guide.mdtext
Date Tue, 02 Oct 2018 15:01:33 GMT
Author: cbrisson
Date: Tue Oct  2 15:01:33 2018
New Revision: 1842631

URL: http://svn.apache.org/viewvc?rev=1842631&view=rev
Log:
[VELOCITY-902] docfix - plus add how to test for special values

Modified:
    velocity/site/cms/trunk/content/engine/2.0/user-guide.mdtext
    velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext

Modified: velocity/site/cms/trunk/content/engine/2.0/user-guide.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.0/user-guide.mdtext?rev=1842631&r1=1842630&r2=1842631&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/2.0/user-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/2.0/user-guide.mdtext Tue Oct  2 15:01:33 2018
@@ -431,53 +431,7 @@ The RHS can also be a simple arithmetic
     #set( $value = $foo * $bar )
     #set( $value = $foo / $bar )
 
-If the RHS is a property or method reference that evaluates to *null*, 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:
-
-    :::velocity
-    #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
-
-If *$query.criteria("name")* returns the string "bill", and *$query.criteria("address")*
returns *null*, the above VTL will render as the following:
-
-    The result of the first query is bill
-
-    The result of the second query is bill
-
-This tends to confuse newcomers who construct *#foreach* loops that attempt to *#set* a reference
via a property or method reference, then immediately test that reference with an *#if* directive.
 For example:
-
-    :::velocity
-    #set( $criteria = ["name", "address"] )
-
-    #foreach( $criterion in $criteria )
-
-        #set( $result = $query.criteria($criterion) )
-
-        #if( $result )
-            Query was successful
-        #end
-
-    #end
-
-In the above example, it would not be wise to rely on the evaluation of *$result* to determine
if a query was successful.  After *$result* has been *#set* (added to the context), it cannot
be set back to *null* (removed from the context).  The details of the *#if* and *#foreach*
directives are covered later in this document.
-
-One solution to this would be to pre-set *$result* to *false*.  Then if the *$query.criteria()*
call fails, you can check.
-
-    :::velocity
-    #set( $criteria = ["name", "address"] )
-
-    #foreach( $criterion in $criteria )
-
-        #set( $result = false )
-        #set( $result = $query.criteria($criterion) )
-
-        #if( $result )
-           Query was successful
-        #end
-
-    #end
+If the RHS is a property or method reference that evaluates to *null*, then the LHS will
be set to null.
 
 Unlike some of the other Velocity directives, the *#set* directive does not have an *#end*
statement.
 
@@ -545,6 +499,14 @@ The variable *$foo* is evaluated to dete
 
 (please note that this is the default behavior, but Velocity can be configured to [skip all
checks beyond boolean and nullity ones](configuration.html#if-directive)).
 
+To test if a reference has a special values, you can use:
+
++ `#if ($ref == $null)` to specifically test for the null value (provided you didn't put
anything in `$null`)
++ `#if ($ref == false)` to specifically test for the false value
++ `#if ($ref == '')` to specifically test for the empty string
++ `#if ($ref == 0)` to specifically test for zero
++ `#if ($ref.size() == 0)` to specifically test for an empty collection
+
 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 `boolean`
- the introspection infrastructure will return a `Boolean` of the same logical value.
 
 The content between the *#if* and the *#end* statements become the output if the evaluation
is true. In this case, if *$foo* is true, the output will be: "Velocity!". Conversely, if
*$foo* has a null value, or if it is a boolean false, the statement evaluates as false, and
there is no output.

Modified: velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext?rev=1842631&r1=1842630&r2=1842631&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext Tue Oct  2 15:01:33 2018
@@ -431,53 +431,7 @@ The RHS can also be a simple arithmetic
     #set( $value = $foo * $bar )
     #set( $value = $foo / $bar )
 
-If the RHS is a property or method reference that evaluates to *null*, 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:
-
-    :::velocity
-    #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
-
-If *$query.criteria("name")* returns the string "bill", and *$query.criteria("address")*
returns *null*, the above VTL will render as the following:
-
-    The result of the first query is bill
-
-    The result of the second query is bill
-
-This tends to confuse newcomers who construct *#foreach* loops that attempt to *#set* a reference
via a property or method reference, then immediately test that reference with an *#if* directive.
 For example:
-
-    :::velocity
-    #set( $criteria = ["name", "address"] )
-
-    #foreach( $criterion in $criteria )
-
-        #set( $result = $query.criteria($criterion) )
-
-        #if( $result )
-            Query was successful
-        #end
-
-    #end
-
-In the above example, it would not be wise to rely on the evaluation of *$result* to determine
if a query was successful.  After *$result* has been *#set* (added to the context), it cannot
be set back to *null* (removed from the context).  The details of the *#if* and *#foreach*
directives are covered later in this document.
-
-One solution to this would be to pre-set *$result* to *false*.  Then if the *$query.criteria()*
call fails, you can check.
-
-    :::velocity
-    #set( $criteria = ["name", "address"] )
-
-    #foreach( $criterion in $criteria )
-
-        #set( $result = false )
-        #set( $result = $query.criteria($criterion) )
-
-        #if( $result )
-           Query was successful
-        #end
-
-    #end
+If the RHS is a property or method reference that evaluates to *null*, then the LHS will
be set to null.
 
 Unlike some of the other Velocity directives, the *#set* directive does not have an *#end*
statement.
 
@@ -545,6 +499,14 @@ The variable *$foo* is evaluated to dete
 
 (please note that this is the default behavior, but Velocity can be configured to [skip all
checks beyond boolean and nullity ones](configuration.html#if-directive)).
 
+To test if a reference has a special values, you can use:
+
++ `#if ($ref == $null)` to specifically test for the null value (provided you didn't put
anything in `$null`)
++ `#if ($ref == false)` to specifically test for the false value
++ `#if ($ref == '')` to specifically test for the empty string
++ `#if ($ref == 0)` to specifically test for zero
++ `#if ($ref.size() == 0)` to specifically test for an empty collection
+
 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 `boolean`
- the introspection infrastructure will return a `Boolean` of the same logical value.
 
 The content between the *#if* and the *#end* statements become the output if the evaluation
is true. In this case, if *$foo* is true, the output will be: "Velocity!". Conversely, if
*$foo* has a null value, or if it is a boolean false, the statement evaluates as false, and
there is no output.



Mime
View raw message