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:01:33 UTC
svn commit: r1842631 - in /velocity/site/cms/trunk/content/engine:
2.0/user-guide.mdtext devel/user-guide.mdtext
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.