velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbris...@apache.org
Subject svn commit: r1833964 - in /velocity/site/production/tools/devel: changes.html creating-tools.html frameworks.html standalone.html struts-user-guide.html struts.html upgrading.html view-layoutservlet.html view-servlet.html
Date Thu, 21 Jun 2018 00:29:32 GMT
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">&para;</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">&#39;bad input&#39;</span><span class="p">)</span><span
class="x"></span>
+<div class="codehilite"><pre>$mytool.somemethod(&#39;bad input&#39;)
 </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">&para;</a></h2>
 <h3 id="configuring">Configuring<a class="headerlink" href="#configuring" title="Permanent
link">&para;</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">&para;</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(&quot;/path/to/my/configuration.xml&quot;);</span>
-<span class="x">Context context = manager.createContext();</span>
-<span class="x">myVelocityEngine.evaluate(context, myOutputWriter, &quot;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">&quot;,
&quot;Test template&quot;);</span>
+<div class="codehilite"><pre>ToolManager manager = new ToolManager();
+manager.configure(&quot;/path/to/my/configuration.xml&quot;);
+Context context = manager.createContext();
+myVelocityEngine.evaluate(context, myOutputWriter, &quot;This is a $text.test&quot;,
&quot;Test template&quot;);
 </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">&lt;context-param&gt;</span>
+  <span class="nt">&lt;param-name&gt;</span>org.apache.velocity.tools.loadDefaults<span
class="nt">&lt;/param-name&gt;</span>
+  <span class="nt">&lt;param-value&gt;</span>true<span class="nt">&lt;/param-value&gt;</span>
+<span class="nt">&lt;/context-param&gt;</span>
+</pre></div>
+
+
+<p>or do the same for a specific servlet inside its <code>&lt;servlet&gt;</code>
tag:</p>
+<div class="codehilite"><pre><span class="nt">&lt;init-param&gt;</span>
+  <span class="nt">&lt;param-name&gt;</span>org.apache.velocity.tools.loadDefaults<span
class="nt">&lt;/param-name&gt;</span>
+  <span class="nt">&lt;param-value&gt;</span>true<span class="nt">&lt;/param-value&gt;</span>
+<span class="nt">&lt;/init-param&gt;</span>
+</pre></div>
+
+
 <h2 id="upgrading-to-20">Upgrading to 2.0<a class="headerlink" href="#upgrading-to-20"
title="Permanent link">&para;</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 user@velocity.apache.org,
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">&para;</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">&quot;MyOtherLayout.vm&quot;</span> <span class="p">)</span><span
class="x"></span>
+<div class="codehilite"><pre>    #set( $layout = &quot;MyOtherLayout.vm&quot;
)
 
-<span class="x">This will direct the VLS to use &quot;MyOtherLayout.vm&quot;
instead of &quot;Default.vm&quot;. *Setting the layout in this fashion will override
any layout set by the request parameters.*</span>
+This will direct the VLS to use &quot;MyOtherLayout.vm&quot; instead of &quot;Default.vm&quot;.
*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&#39;s a MethodInvocationException!</span>
+<div class="codehilite"><pre>#if( $invocation_exception )
+    oh joy! it&#39;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>&lt;context-params&gt;</code> at the
application level as follow:</p>
+<div class="codehilite"><pre><span class="nt">&lt;context-param&gt;</span>
+  <span class="nt">&lt;param-name&gt;</span>org.apache.velocity.toolbox<span
class="nt">&lt;/param-name&gt;</span>
+  <span class="nt">&lt;param-value&gt;</span>/WEB-INF/tools.xml<span
class="nt">&lt;/param-value&gt;</span>
+<span class="nt">&lt;/context-param&gt;</span>
+
+<span class="nt">&lt;context-param&gt;</span>
+  <span class="nt">&lt;param-name&gt;</span>org.apache.velocity.properties<span
class="nt">&lt;/param-name&gt;</span>
+  <span class="nt">&lt;param-value&gt;</span>/WEB-INF/velocity.properties<span
class="nt">&lt;/param-value&gt;</span>
+<span class="nt">&lt;/context-param&gt;</span>
+</pre></div>
+
+
 <h3 id="velocity-configuration">Velocity Configuration<a class="headerlink" href="#velocity-configuration"
title="Permanent link">&para;</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>



Mime
View raw message