You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by cb...@apache.org on 2018/10/15 16:20:50 UTC
svn commit: r1843924 - in /velocity/site/cms/trunk/content/engine/devel:
configuration.mdtext upgrading.mdtext user-guide.mdtext vtl-reference.mdtext
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.