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.
