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
