Author: cbrisson
Date: Tue Aug 30 16:23:01 2016
New Revision: 1758419
URL: http://svn.apache.org/viewvc?rev=1758419&view=rev
Log:
[site] push space gobbling documentation onto prod site
Modified:
velocity/site/production/css/site.css
velocity/site/production/engine/devel/configuration.html
velocity/site/production/engine/devel/developer-guide.html
velocity/site/production/engine/devel/upgrading.html
Modified: velocity/site/production/css/site.css
URL:
http://svn.apache.org/viewvc/velocity/site/production/css/site.css?rev=1758419&r1=1758418&r2=1758419&view=diff
==============================================================================
--- velocity/site/production/css/site.css (original)
+++ velocity/site/production/css/site.css Tue Aug 30 16:23:01 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/production/engine/devel/configuration.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/engine/devel/configuration.html?rev=1758419&r1=1758418&r2=1758419&view=diff
==============================================================================
--- velocity/site/production/engine/devel/configuration.html (original)
+++ velocity/site/production/engine/devel/configuration.html Tue Aug 30
16:23:01 2016
@@ -249,6 +249,7 @@ h2:hover > .headerlink, h3:hover > .head
<li><a href="#introspection">Introspection</a></li>
<li><a href="#context">Context</a></li>
<li><a href="#string-interning">String Interning</a></li>
+<li><a href="#space-gobbling">Space Gobbling</a></li>
<li><a href="#configuration-examples">Configuration Examples</a></li>
</ul>
</div>
@@ -344,7 +345,7 @@ h2:hover > .headerlink, h3:hover > .head
</blockquote>
<p><strong><code>resource.loader = file</code></strong></p>
<blockquote>
-<p><em>Multi-valued key. Will accept CSV for value.</em> 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.</p>
+<p><em>Multi-valued key. Will accept CSV for value.</em> 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.</p>
</blockquote>
<p><strong> <em>name</em><code>.loader.description = Velocity File Resource
Loader</code></strong></p>
<blockquote>
@@ -490,6 +491,15 @@ file.resource.loader.modificationCheckIn
<blockquote>
<p>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.</p>
</blockquote>
+<h2 id="space-gobbling">Space Gobbling<a class="headerlink"
href="#space-gobbling" title="Permanent link">¶</a></h2>
+<p><strong><code>space.gobbling = lines</code></strong></p>
+<blockquote>
+<p>Space gobbling policy. See the <a
href="developer-guide.html#space-gobbling">Space Gobbling section</a> in the
developer guide. Possible values are:
+- <code>none</code> : no space gobbling at all.
+- <code>bc</code> : Velocity 1.x backward compatible space gobbling.
+- <code>lines</code> : gobbles spaces and newline surrounding VTL directives
alone in their line.
+- <code>structured</code> : like previous, plus fix inner text blocks
indentation.</p>
+</blockquote>
<h2 id="configuration-examples">Configuration Examples<a class="headerlink"
href="#configuration-examples" title="Permanent link">¶</a></h2>
<p>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.</p>
<p>The first step in configuring one or more resource loaders is do 'declare'
them by name to Velocity. Use the property <code>resource.loader</code> 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.</p>
Modified: velocity/site/production/engine/devel/developer-guide.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/engine/devel/developer-guide.html?rev=1758419&r1=1758418&r2=1758419&view=diff
==============================================================================
--- velocity/site/production/engine/devel/developer-guide.html (original)
+++ velocity/site/production/engine/devel/developer-guide.html Tue Aug 30
16:23:01 2016
@@ -259,6 +259,13 @@ h2:hover > .headerlink, h3:hover > .head
</ul>
</li>
<li><a href="#logging">Logging</a></li>
+<li><a href="#space-gobbling">Space Gobbling</a><ul>
+<li><a href="#no-space-gobbling">No space gobbling</a></li>
+<li><a href="#backward-compatible-space-gobbling">Backward compatible space
gobbling</a></li>
+<li><a href="#lines-space-gobbling">Lines space gobbling</a></li>
+<li><a href="#structured-space-gobbling">Structured space gobbling</a></li>
+</ul>
+</li>
<li><a href="#resource-loaders">Resource Loaders</a></li>
<li><a href="#application-attributes">Application Attributes</a></li>
<li><a href="#event-handlers">Event Handlers</a><ul>
@@ -740,6 +747,262 @@ velocityEngine.init();
<li>By programmatically giving Velocity a living instance of an
orf.slf4j.Logger object, using the runtime.log.instance property key.</li>
<li>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.</li>
</ul>
+<h2 id="space-gobbling">Space Gobbling<a class="headerlink"
href="#space-gobbling" title="Permanent link">¶</a></h2>
+<p>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
<strong>around</strong> directive and control elements (all elements starting
with <code>#</code>).</p>
+<p>The <code>space.gobbling</code> configuration key can take the following
values: <code>none</code>, <code>bc</code> (aka backward compatible),
<code>lines</code> (the default) and <code>structured</code>, each detailed
below.</p>
+<h3 id="no-space-gobbling">No space gobbling<a class="headerlink"
href="#no-space-gobbling" title="Permanent link">¶</a></h3>
+<p>In some special circumstances, you may want to supress all space
gobbling.</p>
+<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>
+
+<h3 id="backward-compatible-space-gobbling">Backward compatible space
gobbling<a class="headerlink" href="#backward-compatible-space-gobbling"
title="Permanent link">¶</a></h3>
+<p>This space gobbling mode mimics Velocity 1.x space gobbling. Basically, it
eats all extra endline characters <strong>after</strong> directives, plus extra
whitespaces <strong>before</strong> the <code>#set</code> directive whenever
the previous line already contains a directive.</p>
+<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>
+
+<p>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.</p>
+<h3 id="lines-space-gobbling">Lines space gobbling<a class="headerlink"
href="#lines-space-gobbling" title="Permanent link">¶</a></h3>
+<p>This is the default space gobbling mode. It gobbles all whitespace and
endline characters from lines containing only a single VTL directive.</p>
+<p>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).</p>
+<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>
+
+<h3 id="structured-space-gobbling">Structured space gobbling<a
class="headerlink" href="#structured-space-gobbling" title="Permanent
link">¶</a></h3>
+<p>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.</p>
+<p>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(<code>depth</code><sup>2</sup>) where <code>depth</code> is the VTL directive
recursion depth.</p>
+<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>
+
<h2 id="resource-loaders">Resource Loaders<a class="headerlink"
href="#resource-loaders" title="Permanent link">¶</a></h2>
<p>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.</p>
<p>The resource loader system if very flexible, allowing one or more resource
loaders to be in operation at the same time. This allows tremendous
flexibility in configuration and resource managment, and futher allows you to
write your own resource loaders for your special needs.</p>
@@ -999,6 +1262,7 @@ eventhandler.escape.sql.match = /sql.*/
<li>string to boolean: "true" is converted to <code>true</code>, every other
string (including the null string) are converted to <code>false</code></li>
<li>string to number: if the string does not represent a number or doesn't fit
into the expected number type, an exception is thrown</li>
<li>narrowing number conversion: if the number doesn't fit into the expected
number type, an exception is thrown</li>
+<li>string to enum constant: will throw if the string doesn't represent a
constant of the expected enum</li>
</ul>
<p>You can provide a custom conversion handler class by use of the
<code>runtime.conversion.handler</code> property. The class must implement the
<a
href="apidocs/org/apache/velocity/util/introspection/ConversionHandler.html"><code>org.apache.Velocity.util.introspection.ConversionHandler</code></a>
interface. Set it to <code>none</code> to only accept default Java
conversions, as for Velocity 1.x.</p>
<p>You can also provide custom <a
href="apidocs/org/apache/velocity/util/introspection/Converter.html"><code>Converter<T></code></a>
objects that handle a conversion towards a specific type:</p>
Modified: velocity/site/production/engine/devel/upgrading.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/engine/devel/upgrading.html?rev=1758419&r1=1758418&r2=1758419&view=diff
==============================================================================
--- velocity/site/production/engine/devel/upgrading.html (original)
+++ velocity/site/production/engine/devel/upgrading.html Tue Aug 30 16:23:01
2016
@@ -224,9 +224,16 @@ h2:hover > .headerlink, h3:hover > .head
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
<h2 id="upgrading-from-earlier-versions">Upgrading from earlier versions<a
class="headerlink" href="#upgrading-from-earlier-versions" title="Permanent
link">¶</a></h2>
-<p>This page details </p>
<p>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.</p>
<h2 id="upgrading-from-velocity-17x-to-velocity-20x">Upgrading from Velocity
1.7.x to Velocity 2.0.x<a class="headerlink"
href="#upgrading-from-velocity-17x-to-velocity-20x" title="Permanent
link">¶</a></h2>
+<p>For busy people: To maximize backward compatibility with Velocity 1.x, be
sure to include the following lines in your Velocity configuration:</p>
+<div class="codehilite"><pre>runtime.conversion.handler = none
+space.gobbling = bc
+</pre></div>
+
+
+<p>and check the <a href="#dependencies-changes">Dependencies change</a>
below.</p>
+<p>Read below for futher details.</p>
<h3 id="behavior-api-changes">Behavior / API changes:<a class="headerlink"
href="#behavior-api-changes" title="Permanent link">¶</a></h3>
<ul>
<li>velocity is now using the SLF4J logging facade. Hence, all methods
accepting or returning a logger now use the org.slf4j.Logger object.</li>
@@ -252,6 +259,7 @@ h2:hover > .headerlink, h3:hover > .head
<li>the hypen ( <code>-</code> ) cannot be used in variable names anymore</li>
<li>method arguments can be arithmetic expressions</li>
<li>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 <code>runtime.conversion.handler =
none</code>.</li>
+<li>space gobbling (to control the indentation of generated code) is now
configurable via the <code>space.gobbing</code> configuration key, which can
take the following values: <code>none</code>, <code>bc</code> (aka. backward
compatible), <code>lines</code> and <code>structured</code>. See the related
documentation section for details. To maximize backward compatibility with 1.x,
set it to <code>bc</code>.</li>
</ul>
<h3 id="dependencies-changes">Dependencies changes:<a class="headerlink"
href="#dependencies-changes" title="Permanent link">¶</a></h3>
<ul>
