Author: cbrisson
Date: Tue Aug 30 16:21:59 2016
New Revision: 1758418
URL: http://svn.apache.org/viewvc?rev=1758418&view=rev
Log:
[site] document space gobbling
Modified:
velocity/site/cms/trunk/content/css/site.css
velocity/site/cms/trunk/content/engine/devel/configuration.mdtext
velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext
Modified: velocity/site/cms/trunk/content/css/site.css
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/css/site.css?rev=1758418&r1=1758417&r2=1758418&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/css/site.css (original)
+++ velocity/site/cms/trunk/content/css/site.css Tue Aug 30 16:21:59 2016
@@ -227,7 +227,7 @@ a > img
{
clear: both;
font-size: 0.8em;
- text-align: center;
+ text-align: center;
}
.frame, pre
@@ -241,6 +241,15 @@ a > img
overflow-x: auto;
}
+/* fixed-size pre for side by side code comparison */
+pre.fixed
+{
+ overflow-x: hidden;
+ overflow-y: auto;
+ width: 25em;
+ height: 30em;
+}
+
.right
{
text-align: right;
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=1758418&r1=1758417&r2=1758418&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/configuration.mdtext Tue Aug
30 16:21:59 2016
@@ -113,7 +113,7 @@ The following resource management config
**`resource.loader = file`**
-> *Multi-valued key. Will accept CSV for value.* Public name of a resource
loader to be used. This public name will then be used in the specification of
the specific properties for that resource loader. Note that as a multi-valued
key, it's possible to pass a value like "file, class" (sans quotes), indicating
that following will be configuration values for two loaders.
+> *Multi-valued key. Will accept CSV for value.* Public name of a resource
loader to be used. This public name will then be used in the specification of
the specific properties for that resource loader. Note that as a multi-valued
key, it's possible to pass a value like "file, string" (sans quotes),
indicating that following will be configuration values for two loaders.
** *name*`.loader.description = Velocity File Resource Loader`**
@@ -265,6 +265,15 @@ Introspection is the process of mapping
**`runtime.string.interning = true`**
> This property specifies whether to use Java (String
> interning)[https://en.wikipedia.org/wiki/String_interning] on identifiers.
> This may save some memory when set to true, and run a little bit faster when
> set to false.
+## Space Gobbling
+
+**`space.gobbling = lines`**
+> Space gobbling policy. See the [Space Gobbling
section](developer-guide.html#space-gobbling) in the developer guide. Possible
values are:
+>- `none` : no space gobbling at all.
+>- `bc` : Velocity 1.x backward compatible space gobbling.
+>- `lines` : gobbles spaces and newline surrounding VTL directives alone in
their line.
+>- `structured` : like previous, plus fix inner text blocks indentation.
+
## Configuration Examples
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.
Modified: velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext?rev=1758418&r1=1758417&r2=1758418&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
(original)
+++ velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext Tue Aug
30 16:21:59 2016
@@ -513,6 +513,277 @@ By default, Velocity will use a logger t
+ By programmatically giving Velocity a living instance of an orf.slf4j.Logger
object, using the runtime.log.instance property key.
+ By configuring the name of the logger to be used by your velocity instance,
using the runtime.log.name property key. It can be done from the
velocity.properties file, if present.
+## Space Gobbling
+
+Since version 2.0, it's possible to control the whitespace and endline
gobbling performed by Velocity during the rendering, so as to control the
indentation of the generated code. Space gobbling only happens **around**
directive and control elements (all elements starting with `#`).
+
+The `space.gobbling` configuration key can take the following values: `none`,
`bc` (aka backward compatible), `lines` (the default) and `structured`, each
detailed below.
+
+### No space gobbling
+
+In some special circumstances, you may want to supress all space gobbling.
+
+<table>
+ <tbody>
+ <tr>
+ <td>
+ <div class="codehilite">
+ <pre class="fixed">
+#set($foo = 'foo')<span style="color:green">↲</span>
+<table><span style="color:green">↲</span>
+ <tbody><span style="color:green">↲</span>
+#foreach($row in [1..2])<span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ #foreach($col in [1..2])<span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ #set($text = "row $row, col $col")<span style="color:green">↲</span>
+ $text<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ #end<span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+#end<span style="color:green">↲</span>
+ </tbody><span style="color:green">↲</span>
+</table><span style="color:green">↲</span>
+ </pre>
+ </div>
+ </td>
+ <td valign="center" style="padding:1em;">
+ produces
+ </td>
+ <td>
+ <div class="codehilite">
+ <pre class="fixed">
+<span style="color:green">↲</span>
+<table><span style="color:green">↲</span>
+ <tbody><span style="color:green">↲</span>
+<span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ row 1, col 1<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ row 1, col 2<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+<span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ row 2, col 1<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ row 2, col 2<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+<span style="color:green">↲</span>
+ </tbody><span style="color:green">↲</span>
+</table><span style="color:green">↲</span>
+ </pre>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+### Backward compatible space gobbling
+
+This space gobbling mode mimics Velocity 1.x space gobbling. Basically, it
eats all extra endline characters **after** directives, plus extra whitespaces
**before** the `#set` directive whenever the previous line already contains a
directive.
+
+<table>
+ <tbody>
+ <tr>
+ <td>
+ <div class="codehilite">
+ <pre class="fixed">
+#set($foo = 'foo')<span style="color:green">↲</span>
+<table><span style="color:green">↲</span>
+ <tbody><span style="color:green">↲</span>
+#foreach($row in [1..2])<span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ #foreach($col in [1..2])<span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ #set($text = "row $row, col $col")<span style="color:green">↲</span>
+ $text<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ #end<span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+#end<span style="color:green">↲</span>
+ </tbody><span style="color:green">↲</span>
+</table><span style="color:green">↲</span>
+ </pre>
+ </div>
+ </td>
+ <td valign="center" style="padding:1em;">
+ produces
+ </td>
+ <td>
+ <div class="codehilite">
+ <pre class="fixed">
+<table><span style="color:green">↲</span>
+ <tbody><span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 1, col 1<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 1, col 2<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 2, col 1<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 2, col 2<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+ </tbody><span style="color:green">↲</span>
+</table><span style="color:green">↲</span>
+ </pre>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+As you can see, the output is a bit cleaner, but its indentation is not yet
perfect since spaces used to indent the VTL code are found back in it.
+
+### Lines space gobbling
+
+This is the default space gobbling mode. It gobbles all whitespace and endline
characters from lines containing only a single VTL directive.
+
+This is for instance the approriate mode if you use two distinct indentation
frameworks in your templates, one for the VTL, and the other for the generated
language (HTML in this example).
+
+<table>
+ <tbody>
+ <tr>
+ <td>
+ <div class="codehilite">
+ <pre class="fixed">
+#set($foo = 'foo')<span style="color:green">↲</span>
+<table><span style="color:green">↲</span>
+ <tbody><span style="color:green">↲</span>
+#foreach($row in [1..2])<span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ #foreach($col in [1..2])<span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ #set($text = "row $row, col $col")<span style="color:green">↲</span>
+ $text<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ #end<span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+#end<span style="color:green">↲</span>
+ </tbody><span style="color:green">↲</span>
+</table><span style="color:green">↲</span>
+ </pre>
+ </div>
+ </td>
+ <td valign="center" style="padding:1em;">
+ produces
+ </td>
+ <td>
+ <div class="codehilite">
+ <pre class="fixed">
+<table>
+ <tbody><span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 1, col 1<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 1, col 2<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 2, col 1<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 2, col 2<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+ </tbody><span style="color:green">↲</span>
+</table><span style="color:green">↲</span>
+ </pre>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+### Structured space gobbling
+
+The lines gobbling mode is not enough if you want to use a single indentation
framework for both VTL and the output language. Since you will want to further
indent text portions contained inside a directive, this extra indentation has
to be removed at runtime.
+
+Note: this is the only space gobbling mode that produces a bit of overhead at
parsing time. Computationnaly speaking, the current implementation is in
O(`depth`<sup>2</sup>) where `depth` is the VTL directive recursion depth.
+
+<table>
+ <tbody>
+ <tr>
+ <td>
+ <div class="codehilite">
+ <pre class="fixed">
+#set($foo = 'foo')<span style="color:green">↲</span>
+<table><span style="color:green">↲</span>
+ <tbody><span style="color:green">↲</span>
+ #foreach($row in [1..2])<span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ #foreach($col in [1..2])<span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ #set($text = "row $row, col $col")<span
style="color:green">↲</span>
+ $text<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ #end<span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+ #end<span style="color:green">↲</span>
+ </tbody><span style="color:green">↲</span>
+</table><span style="color:green">↲</span>
+ </pre>
+ </div>
+ </td>
+ <td valign="center" style="padding:1em;">
+ produces
+ </td>
+ <td>
+ <div class="codehilite">
+ <pre class="fixed">
+<table>
+ <tbody><span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 1, col 1<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 1, col 2<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+ <tr><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 2, col 1<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ <td><span style="color:green">↲</span>
+ row 2, col 2<span style="color:green">↲</span>
+ </td><span style="color:green">↲</span>
+ </tr><span style="color:green">↲</span>
+ </tbody><span style="color:green">↲</span>
+</table><span style="color:green">↲</span>
+ </pre>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+
## Resource Loaders
One of the fundamental and important parts about Velocity is the resource
management system and the resource loaders. They are referred to as
'resources' here rather than 'templates' because the resource management system
will also handle non-template reasources, specifically things that are loaded
via the #include() directive.
@@ -758,6 +1029,7 @@ Since Velocity 2.0, besides the default
- string to boolean: "true" is converted to `true`, every other string
(including the null string) are converted to `false`
- string to number: if the string does not represent a number or doesn't fit
into the expected number type, an exception is thrown
- narrowing number conversion: if the number doesn't fit into the expected
number type, an exception is thrown
+- string to enum constant: will throw if the string doesn't represent a
constant of the expected enum
You can provide a custom conversion handler class by use of the
`runtime.conversion.handler` property. The class must implement the
[`org.apache.Velocity.util.introspection.ConversionHandler`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html)
interface. Set it to `none` to only accept default Java conversions, as for
Velocity 1.x.
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=1758418&r1=1758417&r2=1758418&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext Tue Aug 30
16:21:59 2016
@@ -2,12 +2,19 @@ Title: Apache Velocity Engine - Upgradin
## Upgrading from earlier versions
-This page details
-
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.
## Upgrading from Velocity 1.7.x to Velocity 2.0.x
+For busy people: To maximize backward compatibility with Velocity 1.x, be sure
to include the following lines in your Velocity configuration:
+
+ runtime.conversion.handler = none
+ space.gobbling = bc
+
+and check the [Dependencies change](#dependencies-changes) below.
+
+Read below for futher details.
+
### Behavior / API changes:
+ velocity is now using the SLF4J logging facade. Hence, all methods accepting
or returning a logger now use the org.slf4j.Logger object.
@@ -30,6 +37,7 @@ Release with the same major number (1.x,
+ the hypen ( `-` ) cannot be used in variable names anymore
+ 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`.
### Dependencies changes:
