Author: cbrisson
Date: Thu Jun 21 00:29:32 2018
New Revision: 1833964
URL: http://svn.apache.org/viewvc?rev=1833964&view=rev
Log:
[site] Push documentation changes to production
Removed:
velocity/site/production/tools/devel/struts-user-guide.html
velocity/site/production/tools/devel/struts.html
Modified:
velocity/site/production/tools/devel/changes.html
velocity/site/production/tools/devel/creating-tools.html
velocity/site/production/tools/devel/frameworks.html
velocity/site/production/tools/devel/standalone.html
velocity/site/production/tools/devel/upgrading.html
velocity/site/production/tools/devel/view-layoutservlet.html
velocity/site/production/tools/devel/view-servlet.html
Modified: velocity/site/production/tools/devel/changes.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/tools/devel/changes.html?rev=1833964&r1=1833963&r2=1833964&view=diff
==============================================================================
--- velocity/site/production/tools/devel/changes.html (original)
+++ velocity/site/production/tools/devel/changes.html Thu Jun 21 00:29:32 2018
@@ -279,9 +279,51 @@ h2:hover > .headerlink, h3:hover > .head
<tbody>
<tr>
<td>
+ <img src="images/fix.png"/>
+ </td>
+ <td> Drop undocumented autoloaded tools feature, and have
org.apache.velocity.tools.loadDefaults default to false . </td>
+ <td>cbrisson</td>
+ </tr>
+ <tr>
+ <td>
+ <img src="images/fix.png"/>
+ </td>
+ <td> Make tools-view initialization much pickier about file accesses,
to ease the use of a Java SecurityManager . </td>
+ <td>cbrisson</td>
+ </tr>
+ <tr>
+ <td>
+ <img src="images/fix.png"/>
+ </td>
+ <td> Fixed BrowserTool Accept-Language header parsing . </td>
+ <td>cbrisson</td>
+ </tr>
+ <tr>
+ <td>
+ <img src="images/add.png"/>
+ </td>
+ <td> Added new <code> $conv.toList(obj) </code> method . </td>
+ <td>cbrisson</td>
+ </tr>
+ <tr>
+ <td>
+ <img src="images/add.png"/>
+ </td>
+ <td> Added <code> $browser.IPAddress </code> . </td>
+ <td>cbrisson</td>
+ </tr>
+ <tr>
+ <td>
+ <img src="images/fix.png"/>
+ </td>
+ <td> Removed deprecated components velocity-tools-uberjar and
velocity-tools-assembly . </td>
+ <td>cbrisson</td>
+ </tr>
+ <tr>
+ <td>
<img src="images/add.png"/>
</td>
- <td> ImportTool reenginering: <ul> <li> the ImportSupport utility
class has been splitted between o.a.v.generic.ImportSupport and
o.a.v.view.ViewImportSupport </li> <li> the ImportTool now has a generic
version (for remote URLs import) and a view version (for local URLs import)
which cannot use remote URLs in safe mode </li> </ul> . </td>
+ <td> ImportTool reenginering: <ul> <li> the ImportSupport utility
class has been splitted between o.a.v.generic.ImportSupport and
o.a.v.view.ViewImportSupport </li> <li> the ImportTool now has a generic
version (for remote URLs import) and a view version (for local URLs import)
which cannot use remote URLs in safe mode </li> <li> the local URLs import
respects the 3.1 servlets specification: query parameters of the included URL
do overwrite original ones </li> </ul> . </td>
<td>cbrisson</td>
</tr>
<tr>
Modified: velocity/site/production/tools/devel/creating-tools.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/tools/devel/creating-tools.html?rev=1833964&r1=1833963&r2=1833964&view=diff
==============================================================================
--- velocity/site/production/tools/devel/creating-tools.html (original)
+++ velocity/site/production/tools/devel/creating-tools.html Thu Jun 21
00:29:32 2018
@@ -317,7 +317,7 @@ public class PagerTool
</ul>
<h3 id="be-robust">Be Robust<a class="headerlink" href="#be-robust"
title="Permanent link">¶</a></h3>
<p>Always return null on errors! No Exceptions! Ok, maybe there are some
exceptions if you are sure that's what you want your tool to do. Just be aware
that this will likely surprise the user because uncaught exceptions halt
template processing at the point the exception is thrown. If the output of the
template is not buffered, this will result in an awkward, partial rendering.
So, if you are going to let an exception through, make sure it is worth halting
everything for. Often it is sufficient to return null, thus allowing the
failed reference to appear in the output like this:</p>
-<div class="codehilite"><pre><span class="p">$</span><span
class="nv">mytool</span><span class="p">.</span><span
class="nv">somemethod</span><span class="p">(</span><span class="s1">'bad
input'</span><span class="p">)</span><span class="x"></span>
+<div class="codehilite"><pre>$mytool.somemethod('bad input')
</pre></div>
Modified: velocity/site/production/tools/devel/frameworks.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/tools/devel/frameworks.html?rev=1833964&r1=1833963&r2=1833964&view=diff
==============================================================================
--- velocity/site/production/tools/devel/frameworks.html (original)
+++ velocity/site/production/tools/devel/frameworks.html Thu Jun 21 00:29:32
2018
@@ -229,13 +229,13 @@ h2:hover > .headerlink, h3:hover > .head
<p>VelocityTools is not meant to be a framework in itself, but rather should
ideally be integrated with other frameworks for applications of much size. The
simplest means of integration is to have your framework handle requests,
placing contextual data into the request, session or servlet context attributes
where templates and/or tools can find them, then forward those requests to a
VelocityViewServlet or VelocityLayoutServlet, letting those servlets manage
your VelocityView support for you and render your templates into the response.
If, however, your framework is one like Spring MVC and you either cannot or do
not wish to forward requests to one of the provided servlets, then the
instructions, tips and code below should make it easy for you to integrate
VelocityTools support into your framework of choice.</p>
<h2 id="integration-via-velocityview">Integration Via VelocityView<a
class="headerlink" href="#integration-via-velocityview" title="Permanent
link">¶</a></h2>
<h3 id="configuring">Configuring<a class="headerlink" href="#configuring"
title="Permanent link">¶</a></h3>
-<p><a
href="apidocs/org/apache/velocity/tools/view/VelocityView.html">VelocityView</a>
supports the following configuration parameters as <init-param>s in
web.xml:</p>
+<p><a
href="apidocs/org/apache/velocity/tools/view/VelocityView.html">VelocityView</a>
supports the following configuration parameters as application
<context-param>s or as specific servlet <init-param>s in web.xml:</p>
<dl>
-<dt>org.apache.velocity.toolbox</dt>
+<dt><strong>org.apache.velocity.toolbox</strong></dt>
<dd>Path and name of the toolbox configuration file. The path must be relative
to the web application root directory. If this parameter is not found, the
servlet will check for a toolbox file at <code>/WEB-INF/tools.xml</code>.</dd>
-<dt>org.apache.velocity.properties</dt>
+<dt><strong>org.apache.velocity.properties</strong></dt>
<dd>Path and name of the Velocity configuration file. The path must be
relative to the web application root directory. If this parameter is not
present, Velocity will check for a properties file at
<code>/WEB-INF/velocity.properties</code>. If no file is found there, then
Velocity is initialized with the settings in the classpath at
<code>org.apache.velocity.tools.view.velocity.properties</code>.</dd>
-<dt>org.apache.velocity.tools.deprecationSupportMode</dt>
+<dt><strong>org.apache.velocity.tools.deprecationSupportMode</strong></dt>
<dd>Tells VelocityView whether or not it should</dd>
<dd>
<ul>
@@ -255,11 +255,11 @@ h2:hover > .headerlink, h3:hover > .head
<dd>
<p>By default, this is true, so turn it to false if you want to fully upgrade
to the new systems. Also, specific tools may look for and respect the
deprecationSupportMode setting (e.g. ValueParser, ResourceTool) to provide old
behavior where it has otherwise changed.</p>
</dd>
-<dt>org.apache.velocity.tools.loadDefaults</dt>
-<dd>Tells VelocityView whether or not it should include the default tools.xml
configurations provided in the VelocityTools jar(s). This is true by
default.</dd>
-<dt>org.apache.velocity.tools.cleanConfiguration</dt>
+<dt><strong>org.apache.velocity.tools.loadDefaults</strong></dt>
+<dd>Tells VelocityView whether or not it should include the default tools.xml
configurations provided in the VelocityTools jar(s). This was true by default
in 2.0, it's now false by default.</dd>
+<dt><strong>org.apache.velocity.tools.cleanConfiguration</strong></dt>
<dd>Tells VelocityView to test all the tool configurations and remove any
invalid ones, rather than allow them to throw errors. This is false by
default.</dd>
-<dt>org.apache.velocity.tools.userCanOverwriteTools</dt>
+<dt><strong>org.apache.velocity.tools.userCanOverwriteTools</strong></dt>
<dd>Tells VelocityView to construct the context in such a way that any
user-set variables with the same keys as any of the configured tools are given
primacy when resolving references. This is true by default, unlike in Tools
1.x.</dd>
</dl>
<p>The VelocityView instance is typically the heart of any VelocityTools-using
application. It encapsulates all necessary VelocityEngine and ToolboxFactory
configuration and provides a simple API for processing templates or other VTL
(e.g. VelocityViewTag body content).</p>
Modified: velocity/site/production/tools/devel/standalone.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/tools/devel/standalone.html?rev=1833964&r1=1833963&r2=1833964&view=diff
==============================================================================
--- velocity/site/production/tools/devel/standalone.html (original)
+++ velocity/site/production/tools/devel/standalone.html Thu Jun 21 00:29:32
2018
@@ -211,10 +211,10 @@ h2:hover > .headerlink, h3:hover > .head
<p>There's nothing particularly special about the tools in VelocityTools 2.
No special interfaces, most don't ''need'' any configuration or API access, and
those that do are now relatively easy to handle (compared to VelocityTools
1.x). So, if you need a tool, just create an instance, do any configuration
you want or need and go. Nothing else to it.</p>
<h2 id="toolmanager">ToolManager<a class="headerlink" href="#toolmanager"
title="Permanent link">¶</a></h2>
<p>However, if you want to externalize your configuration or have your tools
created and configured for you on demand and you are not working in a servlet
environment, then we have created a simple ToolManager that you can use. It's
relatively simple. Just create a ToolManager (can be created with or without
default tools available), configure it (if you want to), ask it to create a
context for you, and use the context as you would any other. Of course,
there's more to it, but this should get you started:</p>
-<div class="codehilite"><pre><span class="x">ToolManager manager = new
ToolManager();</span>
-<span
class="x">manager.configure("/path/to/my/configuration.xml");</span>
-<span class="x">Context context = manager.createContext();</span>
-<span class="x">myVelocityEngine.evaluate(context, myOutputWriter, "This
is a </span><span class="p">$</span><span class="nv">text</span><span
class="p">.</span><span class="nv">test</span><span class="x">",
"Test template");</span>
+<div class="codehilite"><pre>ToolManager manager = new ToolManager();
+manager.configure("/path/to/my/configuration.xml");
+Context context = manager.createContext();
+myVelocityEngine.evaluate(context, myOutputWriter, "This is a
$text.test", "Test template");
</pre></div>
Modified: velocity/site/production/tools/devel/upgrading.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/tools/devel/upgrading.html?rev=1833964&r1=1833963&r2=1833964&view=diff
==============================================================================
--- velocity/site/production/tools/devel/upgrading.html (original)
+++ velocity/site/production/tools/devel/upgrading.html Thu Jun 21 00:29:32 2018
@@ -228,6 +228,22 @@ h2:hover > .headerlink, h3:hover > .head
<p>All objects, methods and configuration formats deprecated in 2.0 have been
suppressed.</p>
<p>Support for the Struts 1.x tools has been discontinued.</p>
<p>For custom objects refering directly to the Velocity Engine API, please
refer to the <a
href="http://velocity.apache.org/engine/2.0/upgrading.html";>Velocity Engine 2.0
Upgrading section</a>.</p>
+<p>Default tools aren't loaded anymore in velocity-tools-view. To load them,
you must enable default loading from your <code>WEB-INF/web.xml</code> file:</p>
+<div class="codehilite"><pre><span class="nt"><context-param></span>
+ <span
class="nt"><param-name></span>org.apache.velocity.tools.loadDefaults<span
class="nt"></param-name></span>
+ <span class="nt"><param-value></span>true<span
class="nt"></param-value></span>
+<span class="nt"></context-param></span>
+</pre></div>
+
+
+<p>or do the same for a specific servlet inside its
<code><servlet></code> tag:</p>
+<div class="codehilite"><pre><span class="nt"><init-param></span>
+ <span
class="nt"><param-name></span>org.apache.velocity.tools.loadDefaults<span
class="nt"></param-name></span>
+ <span class="nt"><param-value></span>true<span
class="nt"></param-value></span>
+<span class="nt"></init-param></span>
+</pre></div>
+
+
<h2 id="upgrading-to-20">Upgrading to 2.0<a class="headerlink"
href="#upgrading-to-20" title="Permanent link">¶</a></h2>
<p>VelocityTools 2.0 marks the most significant set of upgrades and changes
ever done for the VelocityTools library. In order to provide flexible
configurations, lazy-loading for tools, and a host of other improvements,
almost all of the tool management and configuration code from Tools 1.x has
been deprecated and replaced by completely different APIs. Thankfully, we were
able to continue supporting old toolbox.xml configuration files and old tool
design patterns, though these too have been deprecated and are unable to take
full advantage of many of the new features.</p>
<p>Still, as such things have only been deprecated and not removed,
<strong>the first step in upgrading to 2.0 is simply replacing your old
VelocityTools jar with the 2.0 jar</strong>. If this causes any errors for you,
please report them to [email protected], so that we can fix it and help
you work around it in the meantime.</p>
Modified: velocity/site/production/tools/devel/view-layoutservlet.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/tools/devel/view-layoutservlet.html?rev=1833964&r1=1833963&r2=1833964&view=diff
==============================================================================
--- velocity/site/production/tools/devel/view-layoutservlet.html (original)
+++ velocity/site/production/tools/devel/view-layoutservlet.html Thu Jun 21
00:29:32 2018
@@ -231,7 +231,7 @@ tools.view.servlet.layout.default.templa
<h2 id="layouts">Layouts<a class="headerlink" href="#layouts" title="Permanent
link">¶</a></h2>
<p>Now, in your layout templates, the only thing you really need is the screen
content reference. So an acceptable layout template could be:</p>
-<div class="codehilite"><pre><span class="p">$</span><span
class="nv">screen_content</span><span class="x"></span>
+<div class="codehilite"><pre>$screen_content
</pre></div>
@@ -260,9 +260,9 @@ tools.view.servlet.layout.default.templa
</li>
</ol>
<p>In the requested screen, put a line like this:</p>
-<div class="codehilite"><pre><span class="x"> </span><span
class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span
class="p">$</span><span class="nv">layout</span> <span class="o">=</span> <span
class="s2">"MyOtherLayout.vm"</span> <span class="p">)</span><span
class="x"></span>
+<div class="codehilite"><pre> #set( $layout = "MyOtherLayout.vm" )
-<span class="x">This will direct the VLS to use "MyOtherLayout.vm"
instead of "Default.vm". *Setting the layout in this fashion will
override any layout set by the request parameters.*</span>
+This will direct the VLS to use "MyOtherLayout.vm" instead of
"Default.vm". *Setting the layout in this fashion will override any
layout set by the request parameters.*
</pre></div>
@@ -330,13 +330,13 @@ $screen_content
</tbody>
</table>
<p>In the event that a MethodInvocationException is behind the calling of
error(), the root cause is extracted from it and dealt with as described above.
But, since template reference behavior is partly at fault here, the VLS will
also add the MethodInvocationException itself to the context as
$invocation_exception. This allows you to discover the reference and method
call that triggered the root cause. To get those, do something like this in
your error template:</p>
-<div class="codehilite"><pre><span class="cp">#</span><span
class="nf">if</span><span class="p">(</span> <span class="p">$</span><span
class="nv">invocation_exception</span> <span class="p">)</span><span
class="x"></span>
-<span class="x"> oh joy! it's a MethodInvocationException!</span>
+<div class="codehilite"><pre>#if( $invocation_exception )
+ oh joy! it's a MethodInvocationException!
-<span class="x"> Message: </span><span class="p">$</span><span
class="nv">invocation_exception</span><span class="p">.</span><span
class="nv">message</span><span class="x"></span>
-<span class="x"> Reference name: </span><span class="p">$</span><span
class="nv">invocation_exception</span><span class="p">.</span><span
class="nv">referenceName</span><span class="x"></span>
-<span class="x"> Method name: </span><span class="p">$</span><span
class="nv">invocation_exception</span><span class="p">.</span><span
class="nv">methodName</span><span class="x"></span>
-<span class="cp">#</span><span class="nf">end</span><span class="x"></span>
+ Message: $invocation_exception.message
+ Reference name: $invocation_exception.referenceName
+ Method name: $invocation_exception.methodName
+#end
</pre></div></div></div>
<hr/>
<div id="copyright">
Modified: velocity/site/production/tools/devel/view-servlet.html
URL:
http://svn.apache.org/viewvc/velocity/site/production/tools/devel/view-servlet.html?rev=1833964&r1=1833963&r2=1833964&view=diff
==============================================================================
--- velocity/site/production/tools/devel/view-servlet.html (original)
+++ velocity/site/production/tools/devel/view-servlet.html Thu Jun 21 00:29:32
2018
@@ -251,6 +251,19 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
+<p>Please note that the <code>org.apache.velocity.toolbox</code> and
<code>org.apache.velocity.properties</code> parameters can also be set as
<code><context-params></code> at the application level as follow:</p>
+<div class="codehilite"><pre><span class="nt"><context-param></span>
+ <span class="nt"><param-name></span>org.apache.velocity.toolbox<span
class="nt"></param-name></span>
+ <span class="nt"><param-value></span>/WEB-INF/tools.xml<span
class="nt"></param-value></span>
+<span class="nt"></context-param></span>
+
+<span class="nt"><context-param></span>
+ <span
class="nt"><param-name></span>org.apache.velocity.properties<span
class="nt"></param-name></span>
+ <span class="nt"><param-value></span>/WEB-INF/velocity.properties<span
class="nt"></param-value></span>
+<span class="nt"></context-param></span>
+</pre></div>
+
+
<h3 id="velocity-configuration">Velocity Configuration<a class="headerlink"
href="#velocity-configuration" title="Permanent link">¶</a></h3>
<p>Velocity configuration is <strong>optional</strong>, and for most
applications the defaults will work fine. The
<strong>velocity.properties</strong> file contains settings that affect
logging, encoding, and macro settings.</p>
<p>The default configuration specifies the location of a 'global' Velocimacro
template. This file can contain macros which will be made available to all
templates.</p>
