svn commit: r1873313 - in /velocity/site/cms/trunk/content/engine/2.2: configuration-property-changes-in-2.1.mdtext configuration.mdtext upgrading.mdtext

[cb...@apache.org]

Author: cbrisson
Date: Wed Jan 29 16:56:39 2020
New Revision: 1873313

URL: http://svn.apache.org/viewvc?rev=1873313&view=rev
Log:
[site/engine] Document new velocimacro.enable_bc_mode flag

Modified:
    velocity/site/cms/trunk/content/engine/2.2/configuration-property-changes-in-2.1.mdtext
    velocity/site/cms/trunk/content/engine/2.2/configuration.mdtext
    velocity/site/cms/trunk/content/engine/2.2/upgrading.mdtext

Modified: velocity/site/cms/trunk/content/engine/2.2/configuration-property-changes-in-2.1.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.2/configuration-property-changes-in-2.1.mdtext?rev=1873313&r1=1873312&r2=1873313&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/2.2/configuration-property-changes-in-2.1.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/2.2/configuration-property-changes-in-2.1.mdtext Wed Jan 29 16:56:39 2020
@@ -41,7 +41,7 @@ velocimacro.permissions.allow.inline.to.
 velocimacro.permissions.allow.inline.local.scope | velocimacro.inline.local_scope | whether inline macros have a local scope
 velocimacro.arguments.strict | *unchanged* | expect strict argments number
 velocimacro.messages.on (unused) | *deprecated* | obsolete property
-*n/a* | velocimacro.arguments.preserve_literals (since 2.1) | (1.7 BC flag) whether invalid references is literal provided argument or argument name
+*n/a* | velocimacro.arguments.preserve_literals (since 2.1) | (1.7 BC flag) whether invalid references is literal provided argument or argument name ; note: deprecated in 2.2 in favor of velocimacro.enable_bc_mode
 velocimacro.max.depth | velocimacro.max_depth | velocimacros max calling depth
 velocimacro.body.reference | velocimacro.body_reference | name of the reference holding the body passed to a block macro
 runtime.references.strict | runtime.strict_mode.enable | enables strict rendering mode
@@ -64,7 +64,7 @@ Also, the default velocimacro library te
 
 Velocity Engine 2.1 introduces the following new properties:
 
-- `velocimacro.arguments.preserve_literals`: 1.7.x backward compatibility flag: if true, when a macro has to dispay an invalid argument, it displays the literal name of the reference passed to the macro, not the literal name of the argument
+- `velocimacro.arguments.preserve_literals`: 1.7.x backward compatibility flag: if true, when a macro has to dispay an invalid argument, it displays the literal name of the reference passed to the macro, not the literal name of the argument ; note: deprecated in 2.2 in favor of velocimacro.enable_bc_mode.
 - `parser.allow_hyphen_in_identifiers`: 1.7.x backward compatibility flag: if true, allow Velocity identifiers to contain an hyphen '`-`' in identifiers (a minus sign in a mathematical expression will then sometimes need a space around it, as was needed in 1.7.x).
 - `runtime.log.log_invalid_method_calls`: whether to log invalid method calls
 - `introspector.conversion_handler.instance`: live instance of an `org.apache.velocity.util.introspection.TypeConversionHandler` (or of a deprecated org.apache.velocity.util.introspection.ConversionHandler)

Modified: velocity/site/cms/trunk/content/engine/2.2/configuration.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.2/configuration.mdtext?rev=1873313&r1=1873312&r2=1873313&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/2.2/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/2.2/configuration.mdtext Wed Jan 29 16:56:39 2020
@@ -78,9 +78,9 @@ The following tree gathers all non depre
              |                +-- escape = false
              +--string_interning = true
     
-    velocimacro. +-- arguments. +-- preserve_literals = false
-                 |              +-- strict = false
+    velocimacro. +-- arguments.strict = false
                  +-- body_reference = false
+                 +--enable_bc_mode = false
                  +-- inline. +-- allow = true
                  |           +-- local_scope = false
                  |           +-- replace_global = false
@@ -261,15 +261,26 @@ The following resource management config
 
 > When set to true, will throw a `ParseErrorException` when parsing a template containing a macro with an invalid number of arguments. Is set to false by default to maintain backwards compatibility with templates written before this feature became available.
 
-**`velocimacro.arguments.preserve_literals = false`**
+**`velocimacro.enable_bc_mode = false`**
 
-> Since 2.0, inside a macro, the rendering of null arguments uses the local reference literal. For instance, the following VTL code
+> This flag enables Velocimacro backward compatible mode. It has two effects:
+> 
+> 1. Since 2.0, inside a macro, the rendering of null arguments uses the local reference literal. For instance, the following VTL code
 > 
 >     :::velocity
 >     #macro( display $foo ) $foo #end
->     #display( $null )
+>     #display( $bar ) ## where $bar is null
 > 
-> will display `$foo`. To revert to the 1.x behavior, since 2.1, you can set this property to true. The previous code will then display `$null`.
+> will display `$foo`. When B.C. mode is enabled, Velocity will mimic the 1.x behavior which is to render `$bar`.
+>
+> 2. Since 2.0, missing arguments which don't have an explicit default value are considered null inside the macro. The following code
+>
+>     :::velocity
+>     #macro( display $foo ) $foo #end
+>     #set( $foo = 'hello' )
+>     #display()
+>
+> will display `$foo`. When B.C. mode is enabled, Velocity will mimic the 1.x behavior which is to use the global context value, that is render `hello`.
 
 **`velocimacro.body_reference = false`**
 
@@ -507,6 +518,8 @@ The following configuration maximizes th
     # Allow '-' in identifiers
     parser.allow_hyphen_in_identifiers = true
     
-    # When displaying null arguments literals, use provided arguments literals
-    velocimacro.arguments.preserve_literals = true
+    # Enable velocimacros backward compatibility mode
+    velocimacro.enable_bc_mode = true
+
+
 

Modified: velocity/site/cms/trunk/content/engine/2.2/upgrading.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.2/upgrading.mdtext?rev=1873313&r1=1873312&r2=1873313&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/2.2/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/2.2/upgrading.mdtext Wed Jan 29 16:56:39 2020
@@ -25,8 +25,8 @@ For busy people: To maximize backward co
     # Allow '-' in identifiers (since 2.1)
     parser.allow_hyphen_in_identifiers = true
     
-    # When displaying null arguments literals, use provided arguments literals (since 2.1)
-    velocimacro.arguments.preserve_literals = true
+    # Enable backward compatibility mode for Velocimacros
+    velocimacro.enable_bc_mode = true
     
     # When using an invalid reference handler, also include quiet references (since 2.2)
     event_handler.invalid_references.quiet = true
@@ -72,7 +72,7 @@ For busy people: To maximize backward co
     # Allow '-' in identifiers (since 2.1)
     parser.allow_hyphen_in_identifiers = true
     
-    # When displaying null arguments literals, use provided arguments literals (since 2.1)
+    # When displaying null arguments literals, use provided arguments literals (since 2.1, but deprecated in 2.2)
     velocimacro.arguments.preserve_literals = true
 
 Also, please note that Velocity 2.1 now requires Java JDK 1.8+ for bulding and Java JRE 1.8+ at runtime.
@@ -147,7 +147,7 @@ Read below for futher details.
 + space gobbling (to control the indentation of generated code) is now configurable via the `space.gobbing` configuration key, which can take the following values: `none`, `bc` (aka. backward compatible), `lines` and `structured`. See the related documentation section for details. To maximize backward compatibility with 1.x, set it to `bc`.
 + the #foreach predefined references `$velocityCount` and `$velocityHasNext` have been removed. Use `$foreach.count` (1-based), `$foreach.index` (0-based) and `foreach.hasNext()`.
 + Velocimacro arguments are now evaluated only once (instead of each time they were referenced inside the macro body as was the case for v1.7) and passed by value (or more precisely as reference after evaluation).
-+ Velocimacros do not anymore have a *proxy context* of their own - if they do insert new values in the context, and then call an external code changing those values, they will now see the new values.
++ Velocimacros do not anymore have a *proxy context* of their own - if they do insert new values in the context, and then call an external code changing those values, they will now see the new values (see 2.2 for the velicomacro.enable_bc_mode backward compatibility flag).
 
 ### Dependency Changes