velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbris...@apache.org
Subject svn commit: r1873314 - in /velocity/site/cms/trunk/content/engine: 2.2/configuration.mdtext devel/configuration-property-changes-in-2.1.mdtext devel/configuration.mdtext devel/upgrading.mdtext
Date Wed, 29 Jan 2020 16:59:04 GMT
Author: cbrisson
Date: Wed Jan 29 16:59:04 2020
New Revision: 1873314

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

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

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=1873314&r1=1873313&r2=1873314&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:59:04 2020
@@ -80,7 +80,7 @@ The following tree gathers all non depre
     
     velocimacro. +-- arguments.strict = false
                  +-- body_reference = false
-                 +--enable_bc_mode = false
+                 +-- enable_bc_mode = false
                  +-- inline. +-- allow = true
                  |           +-- local_scope = false
                  |           +-- replace_global = false

Modified: velocity/site/cms/trunk/content/engine/devel/configuration-property-changes-in-2.1.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/configuration-property-changes-in-2.1.mdtext?rev=1873314&r1=1873313&r2=1873314&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/configuration-property-changes-in-2.1.mdtext
(original)
+++ velocity/site/cms/trunk/content/engine/devel/configuration-property-changes-in-2.1.mdtext
Wed Jan 29 16:59:04 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/devel/configuration.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/configuration.mdtext?rev=1873314&r1=1873313&r2=1873314&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/configuration.mdtext Wed Jan 29 16:59:04
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/devel/upgrading.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext?rev=1873314&r1=1873313&r2=1873314&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext Wed Jan 29 16:59:04 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
 



Mime
View raw message