Author: cbrisson
Date: Mon Oct 15 16:20:50 2018
New Revision: 1843924
URL: http://svn.apache.org/viewvc?rev=1843924&view=rev
Log:
[site] Document last changes; and nicifies/fixes things here and there
Modified:
velocity/site/cms/trunk/content/engine/devel/configuration.mdtext
velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext
velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext
velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext
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=1843924&r1=1843923&r2=1843924&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/configuration.mdtext Mon Oct
15 16:20:50 2018
@@ -165,7 +165,6 @@ The following resource management config
**`velocimacro.library = VM_global_library.vm `**
-
> *Multi-valued key. Will accept CSV for value.* Filename(s) of Velocimacro
> library to be loaded when the Velocity Runtime engine starts. These
> Velocimacros are accessable to all templates. The file is assumed to be
> relative to the root of the file loader resource path.
**`velocimacro.permissions.allow.inline = true`**
@@ -196,6 +195,16 @@ The following resource management config
> Defines name of the reference that can be used to get the body content (an
> AST block) given for a block macro call (e.g. #@myMacro() has a body #end).
> The default reference name is "bodyContent" (e.g. $bodyContent). This block
> macro feature was introduced in Velocity 1.7.
+**`velocimacro.preserve.argument.literals = false`**
+
+> 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 )
+>
+> 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`.
+
**`macro.provide.scope.control = false`**
> Used to turn on the automatic provision of the $macro scope control during
> #macro calls. The default is false. Set it to true if you need a local
> namespace in macros or more advanced #break controls.
@@ -238,7 +247,7 @@ The following resource management config
**`parser.allows.dash.in.identifiers = false`**
-> This is a backward compatibility option, false by default, which allows the
'**`-`**' character inside variable identifiers. If enabled, be warned that you
will have to surround the mathematical minus sign with spaces for it to be
correctly interpreted.
+> This is a backward compatibility option, false by default, which allows the
'**`-`**' character inside variable identifiers (available since 2.1). If
enabled, be warned that you will have to surround the mathematical minus sign
with spaces for it to be correctly interpreted.
## Event Handlers
@@ -296,6 +305,8 @@ Introspection is the process of mapping
## Configuration Examples
+### Resource loading
+
Configuring the resource loaders for Velocity is straightforward. The
properties that control the are listed in the <a
href="#Configuring_Resource_Loaders">resource configuration</a> section, for
further reference.
The first step in configuring one or more resource loaders is do 'declare'
them by name to Velocity. Use the property `resource.loader` and list one or
more loader names. You can use anything you want - these names are used to
associate configuration properties with a given loader.
@@ -377,3 +388,24 @@ Those are the basics. What follows are
Node that the three names 'file', 'class', and 'jar' are merely for your
convenience and sanity. They can be anything you want - they are just used to
associate a set of properties together. However, it is recommended that you
use names that give some hint of the function.
Note that while all three require very little configuration information for
proper operation, the ClasspathResourceLoader is the simplest.
+
+### Backward compatibility
+
+The following configuration maximizes the backward compatibility with Velocity
1.7.
+
+ :::properties
+ # No automatic conversion of methods arguments
+ runtime.conversion.handler = none
+
+ # Use backward compatible space gobbling
+ space.gobbling = bc
+
+ # Have #if($foo) only returns false if $foo is false or null
+ directive.if.emptycheck = false
+
+ # Allow '-' in identifiers
+ parser.allows.dash.identifiers = true
+
+ # When displaying null arguments literals, use provided arguments literals
+ velocimacro.preserve.arguments.literals = 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=1843924&r1=1843923&r2=1843924&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext Mon Oct 15
16:20:50 2018
@@ -1,5 +1,9 @@
Title: Apache Velocity Engine - Upgrading
+## Upgrading - Contents
+
+[TOC]
+
## Upgrading from earlier versions
Release with the same major number (1.x, 2.x) are intended to be drop-in
replacements. However, in most cases the versions of dependency jars must be
adjusted because newer versions of Velocity might require updates.
@@ -16,10 +20,21 @@ Please note that the maven repository pa
For busy people: To maximize backward compatibility with Velocity 1.x, be sure
to include the following lines in your Velocity configuration:
+ :::properties
+ # No automatic conversion of methods arguments
runtime.conversion.handler = none
+
+ # Use backward compatible space gobbling
space.gobbling = bc
+
+ # Have #if($foo) only returns false if $foo is false or null
directive.if.emptycheck = false
+
+ # Allow '-' in identifiers
parser.allows.dash.identifiers = true
+
+ # When displaying null arguments literals, use provided arguments literals
+ velocimacro.preserve.arguments.literals = true
and check the [Dependency changes](#dependencies-changes) below.
@@ -41,14 +56,17 @@ Read below for futher details.
+ the macros are now using a 'call by sharing' convention (which means that
all arguments are evaluated once at start, and that the macro receives a copy
of the reference to each argument).
+ the `UberspectLoggable` interface has been removed.
+ the `directive.if.tostring.nullcheck` configuration property has been
superseded by the `directive.if.emptycheck` property, which defaults to true.
It means that all empty objects (strings and collections) as long as zero
numbers, do evaluate to false (see the complete [boolean context
evaluation](configuration.html#if-directive) rules.). You may want to set
`directive.if.emptycheck` to false to maximize backward compatibility with 1.x.
++ inside a macro, the rendering of null arguments uses the local reference
literal - to revert to the 1.7 behavior, you can set the boolean property
`velocimacro.preserve.arguments.literals` to true (since 2.1). The macros will
then use the provided argument literals in such cases.
### VTL Changes:
-+ the hypen ( `-` ) cannot be used in variable names anymore, but this
behavior can be restored for backward compatibility by setting the new
`parser.allows.dash.in.identifiers` boolean property to true
++ the hypen ( `-` ) cannot be used in variable names anymore, but this
behavior can be restored for backward compatibility (since 2.1) by setting the
new `parser.allows.dash.in.identifiers` boolean property to true
+ method arguments can be arithmetic expressions
+ method arguments are now converted as needed between all main basic Java
standard types (booleans, numbers and strings). If you want to revert to the
1.x behavior, set the property `runtime.conversion.handler = none`.
+ 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()`.
++ the #foreach predefined references `$velocityCount` and `$velocityHasNext`
have been removed. Use `$foreach.count` (1-based), `$foreach.index` (0-based)
and `foreach.hasNext()`.
++ since 2.1, it's now possible to provide default values for references, using
the syntax `${name|'John Doe'}`. The right part can be any valid VTL expression.
++ since 2.1, the `#foreach()` directive accepts an `#else` block which is
evaluated when the loop is empty: `#foreach(...) ... #else ... #end`.
### Dependency changes:
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=1843924&r1=1843923&r2=1843924&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext Mon Oct 15
16:20:50 2018
@@ -626,11 +626,14 @@ Velocity provides an easy way to get the
#end
</table>
-Velocity also now provides an easy way to tell if you are on the last
iteration of a loop:
+Velocity also provides an easy way to tell if you are on the first or last
iteration of a loop, and also lets you define what happens whenever the loop is
empty:
:::velocity
#foreach( $customer in $customerList )
- $customer.Name#if( $foreach.hasNext ),#end
+ #if( $foreach.first ) There are customer: #end
+ $customer.Name #if( $foreach.hasNext ),#end
+ #else
+ Nobody around
#end
If you want a zero-based index of the #foreach loop, you can just use
$foreach.index instead of $foreach.count. Likewise, $foreach.first and
$foreach.last are provided to compliment $foreach.hasNext. If you want to
access these properties for an outer #foreach loop, you can reference them
directly through the $foreach.parent or $foreach.topmost properties (e.g.
$foreach.parent.index or $foreach.topmost.hasNext).
Modified: velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext?rev=1843924&r1=1843923&r2=1843924&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext Mon Oct
15 16:20:50 2018
@@ -1,14 +1,20 @@
title: Apache Velocity Engine VTL Reference
+## VTL Reference - Contents
+
+[TOC]
+
## About this Guide
This guide is the reference for the Velocity Template Language (VTL). For more
information, please also refer to the [Velocity User Guide](user-guide.html).
+Notations are given in a very approximative EBNF-like syntax, the goal is to
remain readable.
+
## References
In the following syntax references, *identifier* refers to:
-( **a..z**, **A..Z**, **_** ) [ ( **a..z**, **A..Z**, **0..9**, **_** ) , (
**a..z**, **A..Z**, **0..9**, **_** ), ... ]
+<span class="blue">(</span> **a..z** <span class="bigger blue">|</span>
**A..Z** <span class="bigger blue">|</span> **_** <span class="blue">)</span>
<span class="blue">[</span> <span class="blue">(</span> **a..z** <span
class="bigger blue">|</span> **A..Z** <span class="bigger blue">|</span>
**0..9** <span class="bigger blue">|</span> **_** <span class="blue">)</span>
<span class="blue">,</span> <span class="blue">(</span> **a..z** <span
class="bigger blue">|</span> **A..Z** <span class="bigger blue">|</span>
**0..9** <span class="bigger blue">|</span> **_** <span class="blue">),
...</span> <span class="blue">]</span>
that is, a letter or an underscore followed by any number of letters, numbers
and underscores.
@@ -18,7 +24,7 @@ If the `parser.allows.dash.identifiers`
Notation:
-**$** [ **!** ] [ **{** ] *identifier* [ [ **|** *alternate value* ] **}** ]
+**$** <span class="blue">[</span> **!** <span class="blue">]</span> <span
class="blue">[</span> **{** <span class="blue">]</span> *identifier* <span
class="blue">[</span> <span class="blue">[</span> **|** *alternate value* <span
class="blue">]</span> **}** <span class="blue">]</span>
Usage:
@@ -38,7 +44,7 @@ Examples:
Notation:
-**$** [ **{** ] *identifier* **.** *identifier* [ [ **|** *alternate value* ]
**}** ]
+**$** <span class="blue">[</span> **{** <span class="blue">]</span>
*identifier* **.** *identifier* <span class="blue">[</span> <span
class="blue">[</span> **|** *alternate value* <span class="blue">]</span> **}**
<span class="blue">]</span>
Usage:
@@ -54,7 +60,7 @@ Examples:
Notation:
-**$** [ **{** ] *identifier* **.** *identifier* **(** [ *parameter list...* ]
**)** [ [ **|** *alternate value* ] **}** ]
+**$** <span class="blue">[</span> **{** <span class="blue">]</span>
*identifier* **.** *identifier* **(** <span class="blue">[</span> *parameter
list...* <span class="blue">]</span> **)** <span class="blue">[</span> <span
class="blue">[</span> **|** *alternate value* <span class="blue">]</span> **}**
<span class="blue">]</span>
Usage:
@@ -78,12 +84,12 @@ Each method argument can be any valid VT
Format:
-**#** [ **{** ] **set** [ **}** ] **(** *$ref* **=** [ **"**, **'** ] *arg* [
**"**, **'** ] )
+**#** <span class="blue">[</span> **{** <span class="blue">]</span> **set**
<span class="blue">[</span> **}** <span class="blue">]</span> **(** *$ref*
**=** <span class="blue">[</span> **"**, **'** <span class="blue">]</span>
*arg* <span class="blue">[</span> **"**, **'** <span class="blue">]</span> )
Usage:
+ *$ref* - The LHS of the assignment must be a variable reference or a
property reference.
-+ *arg* - The RHS of the assignment, *arg* is parsed if enclosed in double
quotes, and not parsed if enclosed in single quotes. If the RHS evaluates to
*null*, it is **not** assigned to the LHS.
++ *arg* - The RHS of the assignment, *arg* is parsed (i.e. interpolated) if
enclosed in double quotes, and not parsed if enclosed in single quotes. If the
RHS evaluates to *null*, it is **not** assigned to the LHS.
Examples:
@@ -108,11 +114,11 @@ The RHS can also be a simple arithmetic
Format:
-**#** [ **{** ] **if** [ **}** ] **(** *condition* **)** *output* [**#** [
**{** ] **elseif** [ **}** ] **(** *condition* **)** *output* ] [ **#** [ **{**
] **else** [ **}** ] *output* ] **#** [ **{** ] **end** [ **}** ]
+**#** <span class="blue">[</span> **{** <span class="blue">]</span> **if**
<span class="blue">[</span> **}** <span class="blue">]</span> **(** *condition*
**)** *output* [**#** <span class="blue">[</span> **{** <span
class="blue">]</span> **elseif** <span class="blue">[</span> **}** <span
class="blue">]</span> **(** *condition* **)** *output* <span
class="blue">]</span> <span class="blue">[</span> **#** <span
class="blue">[</span> **{** <span class="blue">]</span> **else** <span
class="blue">[</span> **}** <span class="blue">]</span> *output* <span
class="blue">]</span> **#** <span class="blue">[</span> **{** <span
class="blue">]</span> **end** <span class="blue">[</span> **}** <span
class="blue">]</span>
Usage:
-+ *condition* - Expression to evaluate. When tis result is null, evaluate to
false. Otherwise, check for conversion towards Boolean and non-emptiness as
follow:
++ *condition* - Expression to evaluate. When its result is null, evaluate to
false. Otherwise, check for conversion towards Boolean and non-emptiness as
follow:
- return its value for a Boolean object, or the result of the
getAsBoolean() method if it exists.
- if `directive.if.emptycheck` = `false` (`true` by default), stop here
and consider it true.
- return whether an array is empty.
@@ -152,30 +158,31 @@ Notes:
Format:
-**#** [ **{** ] **foreach** [ **}** ] **(** *$ref* **in** *arg* **)**
*statement* **#** [ **{** ] **end** [ **}** ]
+**#** <span class="blue">[</span> **{** <span class="blue">]</span>
**foreach** <span class="blue">[</span> **}** <span class="blue">]</span> **(**
*$ref* **in** *arg* **)** *statements* <span class="blue">[</span> **#** <span
class="blue">[</span> **{** <span class="blue">]</span> **else** <span
class="blue">[</span> **}** <span class="blue">]</span> *alternate statements*
<span class="blue">]</span> **#** <span class="blue">[</span> **{** <span
class="blue">]</span> **end** <span class="blue">[</span> **}** <span
class="blue">]</span>
Usage:
+ *$ref* - The first variable reference is the item.
+ *arg* - May be one of the following: a reference to a list (i.e. object
array, collection, or map), an array list, or the range operator.
-+ *statement* - What is output each time Velocity finds a valid item in the
list denoted above as *arg*. This output is any valid VTL and is rendered each
iteration of the loop.
++ *statements* - What is output each time Velocity finds a valid item in the
list denoted above as *arg*. This output is any valid VTL and is rendered each
iteration of the loop.
++ *alternate statements* - What is to display whenever Velocity did not enter
the loop (when *arg* is null, empty, or doesn't have any valid iterator).
-Examples of the #foreach(), omitting the statement block :
+Examples of the #foreach loop:
-+ Reference: `#foreach ( $item in $items )`
-+ Array list: `#foreach ( $item in ["Not", $my, "fault"] )`
-+ Range operator: `#foreach ( $item in [1..3] )`
++ Reference: `#foreach ( $item in $items ) $item #else no item #end`
++ Array list: `#foreach ( $item in ["Not", $my, "fault"] ) $item #end`
++ Range operator: `#foreach ( $item in [1..3] ) $item #end`
-Velocity provides an easy way to get the loop counter so that you can do
something like the following:
+Inside the #foreach loop, the following can be used:
- :::html+velocity
- <table>
- #foreach( $customer in $customerList )
- <tr><td>$foreach.count</td><td>$customer.Name</td></tr>
- #end
- </table>
++ `$foreach.count` : 1-based loop index
++ `$foreach.index` : 0-based loop index
++ `$foreach.first` : true on the first iteration
++ `$foreach.last` : true on the last iteration
++ `$foreach.hasNext` : false on the last iteration
++ `$foreach.stop()` : exists the loop, synonym for `#break`
-Additionally, the maximum allowed number of loop iterations can be controlled
engine-wide with `velocity.properties`. By default, there is no limit:
+The maximum allowed number of loop iterations can be controlled engine-wide
with `velocity.properties`. By default, there is no limit:
:::properties
# The maximum allowed number of loops.
@@ -185,7 +192,7 @@ Additionally, the maximum allowed number
Format:
-**#** [ **{** ] **include** [ **}** ] **(** *arg* [ *arg2* ... *argn* ] **)**
+**#** <span class="blue">[</span> **{** <span class="blue">]</span>
**include** <span class="blue">[</span> **}** <span class="blue">]</span> **(**
*arg* <span class="blue">[</span> *arg2* ... *argn* <span
class="blue">]</span> **)**
Usage:
@@ -200,7 +207,7 @@ Examples:
Format:
-**#** [ **{** ] **parse** [ **}** ] **(** *arg* **)**</p>
+**#** <span class="blue">[</span> **{** <span class="blue">]</span> **parse**
<span class="blue">[</span> **}** <span class="blue">]</span> **(** *arg*
**)**</p>
Usage:
@@ -217,7 +224,7 @@ Recursion permitted. See *parse_directiv
Format:
-**#** [ **{** ] **stop** [ **}** ]
+**#** <span class="blue">[</span> **{** <span class="blue">]</span> **stop**
<span class="blue">[</span> **}** <span class="blue">]</span>
Usage:
@@ -227,7 +234,7 @@ This will stop execution of the current
Format:
-**#** [ **{** ] **break** [ **}** ]
+**#** <span class="blue">[</span> **{** <span class="blue">]</span> **break**
<span class="blue">[</span> **}** <span class="blue">]</span>
Usage:
@@ -237,7 +244,7 @@ This will break execution of the current
Format:
-**#** [ **{** ] **evaluate** [ **}** ] **(** *arg* **)**
+**#** <span class="blue">[</span> **{** <span class="blue">]</span>
**evaluate** <span class="blue">[</span> **}** <span class="blue">]</span>
**(** *arg* **)**
Usage:
@@ -252,7 +259,7 @@ Examples:
Format:
-**#** [ **{** ] **define** [ **}** ] **(* *$ref* **)** *statement* **#** [
**{** ] **end** [ **}** ]
+**#** <span class="blue">[</span> **{** <span class="blue">]</span> **define**
<span class="blue">[</span> **}** <span class="blue">]</span> **(** *$ref*
**)** *statement* **#** <span class="blue">[</span> **{** <span
class="blue">]</span> **end** <span class="blue">[</span> **}** <span
class="blue">]</span>
Usage:
@@ -267,12 +274,12 @@ Example:
Format:
-**#** [ **{** ] **macro** [ **}** ] **(** *vmname* *$arg1* [ **=** *def1* ] [
*$arg2* [ **=** *def2* ] *$arg3* [ **=** def3 ] ... *$argn* [ **=** *defn* ] ]
**)** [ *VTL code* ] **#** [ **{** ] **end** [ **}** ]
+**#** <span class="blue">[</span> **{** <span class="blue">]</span> **macro**
<span class="blue">[</span> **}** <span class="blue">]</span> **(** *vmname*
*$arg1* <span class="blue">[</span> **=** *def1* <span class="blue">]</span>
<span class="blue">[</span> *$arg2* <span class="blue">[</span> **=** *def2*
<span class="blue">]</span> *$arg3* <span class="blue">[</span> **=** def3
<span class="blue">]</span> ... *$argn* <span class="blue">[</span> **=**
*defn* <span class="blue">]</span> ] **)** <span class="blue">[</span> *VTL
code* <span class="blue">]</span> **#** <span class="blue">[</span> **{** <span
class="blue">]</span> **end** <span class="blue">[</span> **}** <span
class="blue">]</span>
Usage:
+ *vmname* - Name used to call the VM (*#vmname*)
-+ *$arg1 $arg2 [ ... ]* - Arguments to the VM. There can be any number of
arguments, but the number used at invocation must match the number specified in
the definition, unless there is a default value provided for missing parameters.
++ *$arg1 $arg2* ... - Arguments to the VM. There can be any number of
arguments, but the number used at invocation must match the number specified in
the definition, unless there is a default value provided for missing parameters.
+ *def1, def2, ...* - Optional default values provided for macro arguments. If
a default value is provided for an argument, a default value must also be
provided to all subsequent arguments.
+ *VTL code* - Any valid VTL code, anything you can put into a template, can
be put into a VM.
@@ -291,6 +298,14 @@ VMs can be defined in one of two places:
1. *Template library:* can be either VMs pre-packaged with Velocity or
custom-made, user-defined, site-specific VMs; available from any template
2. *Inline:* found in regular templates, only usable when
*velocimacro.permissions.allowInline=true* in `velocity.properties`.
+Since 2.0, when a macro argument is null or invalid, its rendering will
display its local name. The following block of code:
+
+ :::velocity
+ #macro( vmname $foo ) $foo #end
+ #vmname( $null )
+
+will display `$foo`. If you wish to revert to the 1.x behavior (which is to
display `$null`), you can set the `velocimacro.preserve.arguments.literals`
configuration property to true (since 2.1).
+
## Comments
Comments are not rendered at runtime.
