velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nbu...@apache.org
Subject svn commit: r603140 [1/2] - /velocity/tools/trunk/xdocs/
Date Tue, 11 Dec 2007 03:56:56 GMT
Author: nbubna
Date: Mon Dec 10 19:56:55 2007
New Revision: 603140

URL: http://svn.apache.org/viewvc?rev=603140&view=rev
Log:
lots more doc updates

Added:
    velocity/tools/trunk/xdocs/view.servlet.xml   (with props)
    velocity/tools/trunk/xdocs/view.tag.xml   (with props)
Removed:
    velocity/tools/trunk/xdocs/generic.index.xml
    velocity/tools/trunk/xdocs/struts.index.xml
    velocity/tools/trunk/xdocs/view.index.xml
Modified:
    velocity/tools/trunk/xdocs/changes.xml
    velocity/tools/trunk/xdocs/config.java.xml
    velocity/tools/trunk/xdocs/config.properties.xml
    velocity/tools/trunk/xdocs/config.xml
    velocity/tools/trunk/xdocs/config.xml.xml
    velocity/tools/trunk/xdocs/creatingtools.xml
    velocity/tools/trunk/xdocs/dependencies.xml
    velocity/tools/trunk/xdocs/frameworks.xml
    velocity/tools/trunk/xdocs/generic.project.xml
    velocity/tools/trunk/xdocs/generic.xml
    velocity/tools/trunk/xdocs/index.xml
    velocity/tools/trunk/xdocs/site.dvsl
    velocity/tools/trunk/xdocs/standalone.xml
    velocity/tools/trunk/xdocs/struts.project.xml
    velocity/tools/trunk/xdocs/struts.userguide.xml
    velocity/tools/trunk/xdocs/struts.xml
    velocity/tools/trunk/xdocs/view.layoutservlet.xml
    velocity/tools/trunk/xdocs/view.project.xml
    velocity/tools/trunk/xdocs/view.xml

Modified: velocity/tools/trunk/xdocs/changes.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/changes.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/changes.xml (original)
+++ velocity/tools/trunk/xdocs/changes.xml Mon Dec 10 19:56:55 2007
@@ -37,6 +37,7 @@
         <li>Added VelocityViewTag for JSP integration</li>
         <li>Added DisplayTool, ConversionTool, ClassTool, LoopTool, FieldTool and more</li>
         <li>Refactored and enhanced a number of existing tools</li>
+        <li>Improved documentation</li>
         <li>Deprecated lots of outdated things</li>
         <li>... and lots more. :)</li>
         </ul>

Modified: velocity/tools/trunk/xdocs/config.java.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/config.java.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/config.java.xml (original)
+++ velocity/tools/trunk/xdocs/config.java.xml Mon Dec 10 19:56:55 2007
@@ -31,9 +31,12 @@
 
     <section name="Configuration using Java">
         <p>
-            Of course, it is possible to configure things purely via Java, 
-            though this too is much easier than it was in VelocityTools 1.x. 
-            Here again, is an example that is equivalent to those above:
+            As of VelocityTools 2, its no longer merely possible to configure 
+            things purely via Java, it is now much easier to do and can be done
+            in several different ways. 
+            Here again, is an example that is equivalent to those demonstrated
+            in the <a href="config.properties.html">properties</a> and
+            <a href="config.xml.html">xml</a> configurations:
         </p>
 
         <sourcecode>
@@ -57,11 +60,16 @@
         </sourcecode>
 
         <p>
-            This example uses the EasyFactoryConfiguration API for brevity, 
-            but you can also directly use the FactoryConfiguration/
-            ToolboxConfiguration/ToolConfiguration/Data API, as you would 
-            probably do if you were to construct your configuration via an 
-            dependency injection framework (such as Spring).
+            This example uses the 
+            <a href="javadoc/org/apache/velocity/tools/config/EasyFactoryConfiguration.html">EasyFactoryConfiguration</a>
+            API for brevity, 
+            but you can also directly use the 
+            <a href="javadoc/org/apache/velocity/tools/config/FactoryConfiguration.html">FactoryConfiguration</a>/
+            <a href="javadoc/org/apache/velocity/tools/config/ToolboxConfiguration.html">ToolboxConfiguration</a>/
+            <a href="javadoc/org/apache/velocity/tools/config/ToolConfiguration.html">ToolConfiguration</a>/
+            <a href="javadoc/org/apache/velocity/tools/config/Data.html">Data</a>
+            API, as you would probably do if you were to construct your
+            configuration via a dependency injection framework (such as Spring).
         </p>
     </section>
 

Modified: velocity/tools/trunk/xdocs/config.properties.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/config.properties.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/config.properties.xml (original)
+++ velocity/tools/trunk/xdocs/config.properties.xml Mon Dec 10 19:56:55 2007
@@ -31,9 +31,11 @@
 
     <section name="Configuration using Properties">
         <p>
-            You can also configure VelocityTools2 via a properties file.  
-            Here's the same configuration as the <a href="configxml.html">XML 
-            example</a> done using the properties format:
+            VelocityTools 2 can be configured using a properties file.  
+            Here's the same configuration as the 
+            <a href="config.xml.html">XML</a> and
+            <a href="config.java.html">Java</a> examples
+            in the properties format:
         </p>
 
         <sourcecode>

Modified: velocity/tools/trunk/xdocs/config.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/config.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/config.xml (original)
+++ velocity/tools/trunk/xdocs/config.xml Mon Dec 10 19:56:55 2007
@@ -32,7 +32,7 @@
 
     <section name="Configuration Overview">
         <p>
-            The VelocityTools2 support infrastructure exists to 
+            The VelocityTools support infrastructure exists to 
             provide all your templates a common set of tools 
             and data.  This is inspired by the 
             <a href="http://turbine.apache.org/turbine/turbine-2.2.0/pullmodel.html">
@@ -52,7 +52,7 @@
         </p>
 
         <p>
-            The default VelocityTools2 configuration does not 
+            The default VelocityTools 2 configuration does not 
             include any "gross MVC offenders", as such things 
             would be hard to generalize usefully.  The default 
             configuration primarily includes tools for 
@@ -63,7 +63,7 @@
 
         <p>
             However, it is likely that you will want to add your own data and 
-            tools to your VelocityTools2 configuration or at least want to 
+            tools to your VelocityTools 2 configuration or at least want to 
             change the default settings of the standard tools.  To that end, 
             configuration of your applications "toolbox(es)" can be done via 
             XML, Java or properties.  Different configurations can also be 
@@ -73,16 +73,32 @@
         <p>
             There a few basic concepts to the configuration that 
             it is useful to know.  First, what you are creating 
-            a configuration for is a ToolboxFactory.  This factory 
-            produces your toolbox(es) as needed by 
+            a configuration for is a 
+            <a href="javadoc/org/apache/velocity/tools/ToolboxFactory.html">ToolboxFactory</a>.
+            This factory produces your toolbox(es) as needed by 
             <a href="view.html">VelocityView</a> or your own 
             application. A factory can have any number of 
             toolboxes, all distinguished by their scope property. 
             There are three special scopes automatically recognized 
-            by VelocityTools2:  "request", "application", and 
+            by VelocityTools 2:  "request", "application", and 
             "session".  The "session" scope is only relevant within 
             a <a href="view.html">VelocityView</a> app, but the 
-            other two may be useful anywhere.
+            other two may be useful anywhere. Placing a
+            tool within "request" scope means that a new instance
+            will be created for every context.  Placing a tool
+            within "application" scope means that only one instance
+            of the tool will be created and shared throughout the
+            application, effectively acting as a singleton. This,
+            of course, means that thread-safety must be considered
+            when putting a tool in "application" scope.
+        </p>
+
+        <p>
+            Because of such concerns, Velocity Tools now provides
+            annotations to allow developers to restrict the scope(s)
+            in which a tool can be placed. For more on these and other available
+            annotations, see
+            <a href="creatingtools.html">Creating Your Own Tools</a>.
         </p>
 
         <p>
@@ -93,7 +109,9 @@
             application. You can configure any number of data for 
             your application and the configuration supports both 
             automatic and explicit type conversion (via 
-            Commons-BeanUtils converters) for these values (since 
+            Commons-BeanUtils 
+            <a href="http://commons.apache.org/beanutils/commons-beanutils-1.7.0/docs/api/org/apache/commons/beanutils/Converter.html">converters</a>
+            ) for these values (since 
             XML and properties formats only allow string inputs).                    
         </p>
         <p>

Modified: velocity/tools/trunk/xdocs/config.xml.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/config.xml.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/config.xml.xml (original)
+++ velocity/tools/trunk/xdocs/config.xml.xml Mon Dec 10 19:56:55 2007
@@ -34,9 +34,9 @@
             Providing an xml format configuration file is still the standard, 
             but unlike VelocityTools 1.x, it is no longer necessary at all, 
             thanks to the introduction of default configurations.  The default 
-            configurations for <a href="VelocityTools2/GenericTools">
-            GenericTools</a>, <a href="VelocityTools2/VelocityView">
-            VelocityView</a> and <a href="VelocityTools2/VelocityStruts">
+            configurations for <a href="generic.html">
+            GenericTools</a>, <a href="view.html">
+            VelocityView</a> and <a href="struts.html">
             VelocityStruts</a> are all defined via XML.
         </p>
 

Modified: velocity/tools/trunk/xdocs/creatingtools.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/creatingtools.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/creatingtools.xml (original)
+++ velocity/tools/trunk/xdocs/creatingtools.xml Mon Dec 10 19:56:55 2007
@@ -28,10 +28,90 @@
 
     <body>
 
-    <section name="Creating your own tools">
+    <section name="Overview">
         <p class="note">
-            This page is quite unfinished.
+            This page is still unfinished.
             <a href="index.html#Contribution">Help is welcome!</a>
+        </p>
+    </section>
+    <section name="Conventions">
+        <subsection name="Tool Keys/Names">
+            <p>
+            TODO: talk about [Key]Tool class name, precedence, etc
+            </p>
+        </subsection>
+        <subsection name="Tool Properties">
+            <p>
+            TODO: talk about camelCase config properties, precedence, etc
+            </p>
+        </subsection>
+    </section>
+    <section name="Annotations">
+        <p>
+        TODO: talk about
+        <a href="javadoc/org/apache/velocity/tools/config/DefaultKey.html">DefaultKey</a>,
+        <a href="javadoc/org/apache/velocity/tools/config/InvalidScope.html">InvalidScope</a> and
+        <a href="javadoc/org/apache/velocity/tools/config/ValidScope.html">ValidScope</a>
+        </p>
+    </section>
+    <section name="Support Classes">
+        <subsection name="Base Classes">
+            <p>
+            <a href="javadoc/org/apache/velocity/tools/generic/AbstractLockConfig.html">AbstractLockConfig</a>
+            - This serves as a base class for tools who need to have
+            their configuration be read-only for thread-safety or
+            other reasons.  By default, tools which extend this can
+            only be configured once.
+            </p>
+            <p>
+            <a href="javadoc/org/apache/velocity/tools/generic/LocaleConfig.html">LocaleConfig</a>
+            - Subclass of AbstractLockConfig that has standardized
+            support for configuring a Locale for the tool to use as
+            its default.
+            </p>
+            <p>
+            <a href="javadoc/org/apache/velocity/tools/generic/FormatConfig.html">FormatConfig</a>
+            - Subclass of FormatConfig that has standardized support
+            for providing a format string value for the tool to use
+            as its default.
+            </p>
+        </subsection>
+        <subsection name="Utility Classes">
+            <p>
+            <a href="javadoc/org/apache/velocity/tools/ClassUtils.html">ClassUtils</a>
+            - Provides utility methods for loading classes,
+            finding methods, accessing static field values,
+            and more.
+            </p>
+            <p>
+            <a href="javadoc/org/apache/velocity/tools/ConversionUtils.html">ConversionUtils</a>
+            - Provides utility methods for common type
+            conversions/value parsing.
+            </p>
+            <p>
+            <a href="javadoc/org/apache/velocity/tools/view/ServletUtils.html">ServletUtils</a>
+            - Utility methods for the servlet environment, mostly
+            centered on accessing the VelocityView or tool instances
+            handled thereby.
+            </p>
+            <p>
+            <a href="javadoc/org/apache/velocity/tools/generic/ValueParser.html">ValueParser</a>
+            - Used to retrieve and parse (aka convert) String
+            values pulled from a map; this is mostly commonly
+            used directly by other tools rather than within
+            templates.
+            </p>
+        </subsection>
+    </section>
+    <section name="Designing Template-friendly Interfaces">
+        <p>
+        Always return null on errors! No Exceptions!
+        </p>
+        <p>
+        TODO: talk about security
+        </p>
+        <p>
+        TODO: talk about using "subtools" for a fluent API
         </p>
     </section>
 

Modified: velocity/tools/trunk/xdocs/dependencies.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/dependencies.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/dependencies.xml (original)
+++ velocity/tools/trunk/xdocs/dependencies.xml Mon Dec 10 19:56:55 2007
@@ -30,7 +30,11 @@
               <td>1.7.0</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for infrastructure, MathTool and SortTool</td>
+              <td>Required for core infrastructure,
+                <a href="javadoc/org/apache/velocity/tools/generic/MathTool.html">MathTool</a>
+                and
+                <a href="javadoc/org/apache/velocity/tools/generic/SortTool.html">SortTool</a>
+              </td>
             </tr>
             <tr>
               <td>commons-collections</td>
@@ -44,14 +48,18 @@
               <td>1.8</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for xml config</td>
+              <td>Required for
+                <a href="config.xml.html">xml configuration</a>
+              </td>
             </tr>
             <tr>
               <td>commons-lang</td>
               <td>2.1</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for EscapeTool</td>
+              <td>Required for
+                <a href="javadoc/org/apache/velocity/tools/generic/EscapeTool.html">EscapeTool</a>
+              </td>
             </tr>
             <tr>
               <td>commons-logging</td>
@@ -65,7 +73,12 @@
               <td>1.5</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for ClassTool, IteratorTool and RenderTool</td>
+              <td>Required for
+                <a href="javadoc/org/apache/velocity/tools/generic/ClassTool.html">ClassTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/generic/LoopTool.html">LoopTool</a>
+                and
+                <a href="javadoc/org/apache/velocity/tools/generic/RenderTool.html">RenderTool</a>
+              </td>
             </tr>
           </table>
       </subsection>
@@ -84,7 +97,11 @@
               <td>1.7.0</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for infrastructure, MathTool and SortTool</td>
+              <td>Required for core infrastructure,
+                <a href="javadoc/org/apache/velocity/tools/generic/MathTool.html">MathTool</a>
+                and
+                <a href="javadoc/org/apache/velocity/tools/generic/SortTool.html">SortTool</a>
+              </td>
             </tr>
             <tr>
               <td>commons-collections</td>
@@ -98,14 +115,18 @@
               <td>1.8</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for xml config</td>
+              <td>Required for
+                <a href="config.xml.html">xml configuration</a>
+              </td>
             </tr>
             <tr>
               <td>commons-lang</td>
               <td>2.1</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for EscapeTool</td>
+              <td>Required for
+                <a href="javadoc/org/apache/velocity/tools/generic/EscapeTool.html">EscapeTool</a>
+              </td>
             </tr>
             <tr>
               <td>commons-logging</td>
@@ -119,16 +140,28 @@
               <td>2.3</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for all VelocityView tools except for ViewRenderTool</td>
+              <td>Required for all
+                <a href="javadoc/org/apache/velocity/tools/view/package-summary.html">VelocityView</a>
+                tools except for
+                <a href="javadoc/org/apache/velocity/tools/view/ViewRenderTool.html">ViewRenderTool</a>
+              </td>
             </tr>
             <tr>
               <td>velocity</td>
               <td>1.5</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for AbstractSearchTool, ClassTool, ContextTool,
-              ImportTool, IteratorTool, LinkTool, MultiViewsTool, and
-              ViewRenderTool</td>
+              <td>Required for 
+                <a href="javadoc/org/apache/velocity/tools/generic/ClassTool.html">ClassTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/AbstractSearchTool.html">AbstractSearchTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/ContextTool.html">ContextTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/ImportTool.html">ImportTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/LinkTool.html">LinkTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/LoopTool.html">LoopTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/MultiViewsTool.html">MultiViewsTool</a>
+                and
+                <a href="javadoc/org/apache/velocity/tools/view/ViewRenderTool.html">ViewRenderTool</a>
+              </td>
             </tr>
           </table>
       </subsection>
@@ -147,7 +180,11 @@
               <td>1.7.0</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for infrastructure, MathTool and SortTool</td>
+              <td>Required for core infrastructure,
+                <a href="javadoc/org/apache/velocity/tools/generic/MathTool.html">MathTool</a>
+                and
+                <a href="javadoc/org/apache/velocity/tools/generic/SortTool.html">SortTool</a>
+              </td>
             </tr>
             <tr>
               <td>commons-collections</td>
@@ -161,14 +198,18 @@
               <td>1.8</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for xml config</td>
+              <td>Required for
+                <a href="config.xml.html">xml configuration</a>
+              </td>
             </tr>
             <tr>
               <td>commons-lang</td>
               <td>2.1</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for EscapeTool</td>
+              <td>Required for
+                <a href="javadoc/org/apache/velocity/tools/generic/EscapeTool.html">EscapeTool</a>
+              </td>
             </tr>
             <tr>
               <td>commons-logging</td>
@@ -182,51 +223,83 @@
               <td>1.3.8</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for all VelocityStruts tools</td>
+              <td>Required for all
+                <a href="javadoc/org/apache/velocity/tools/struts/package-summary.html">VelocityStruts</a>
+                tools
+              </td>
             </tr>
             <tr>
               <td>struts-taglib</td>
               <td>1.3.8</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for FormTool, SecureLinkTool and StrutsLinkTool</td>
+              <td>Required for
+                <a href="javadoc/org/apache/velocity/tools/struts/FormTool.html">FormTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/struts/SecureLinkTool.html">SecureLinkTool</a>
+                and
+                <a href="javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html">StrutsLinkTool</a>
+              </td>
             </tr>
             <tr>
               <td>struts-tiles</td>
               <td>1.3.8</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for TilesTool</td>
+              <td>Required for
+                <a href="javadoc/org/apache/velocity/tools/struts/TilesTool.html">TilesTool</a>
+              </td>
             </tr>
             <tr>
               <td>ssl-ext</td>
               <td>1.2</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for SecureLinkTool</td>
+              <td>Required for
+                <a href="javadoc/org/apache/velocity/tools/struts/SecureLinkTool.html">SecureLinkTool</a>
+              </td>
             </tr>
             <tr>
               <td>commons-validator</td>
               <td>1.3.1</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for ValidatorTool</td>
+              <td>Required for 
+                <a href="javadoc/org/apache/velocity/tools/struts/ValidatorTool.java">ValidatorTool</a>
+              </td>
             </tr>
             <tr>
               <td>servletapi</td>
               <td>2.3</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for all VelocityStruts tools</td>
+              <td>Required for all
+                <a href="javadoc/org/apache/velocity/tools/struts/package-summary.html">VelocityStruts</a>
+                tools and all
+                <a href="javadoc/org/apache/velocity/tools/view/package-summary.html">VelocityView</a>
+                tools except for
+                <a href="javadoc/org/apache/velocity/tools/view/ViewRenderTool.html">ViewRenderTool</a>
+              </td>
             </tr>
             <tr>
               <td>velocity</td>
               <td>1.5</td>
               <td>Yes</td>
               <td>Yes</td>
-              <td>Required for AbstractSearchTool, ActionMessagesTool, ClassTool,
-              ContextTool, ErrorsTool, ImportTool, IteratorTool, SecureLinkTool,
-              StrutsLinkTool, MessageTool, MultiViewsTool, TilesTool, ViewRenderTool</td>
+              <td>Required for 
+                <a href="javadoc/org/apache/velocity/tools/generic/ClassTool.html">ClassTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/AbstractSearchTool.html">AbstractSearchTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/ContextTool.html">ContextTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/ImportTool.html">ImportTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/LinkTool.html">LinkTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/LoopTool.html">LoopTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/MultiViewsTool.html">MultiViewsTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/view/ViewRenderTool.html">ViewRenderTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/struts/SecureLinkTool.html">SecureLinkTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html">StrutsLinkTool</a>,
+                <a href="javadoc/org/apache/velocity/tools/struts/TilesTool.html">TilesTool</a>
+                and
+                <a href="javadoc/org/apache/velocity/tools/struts/MessageTool.html">MessageTool</a>
+              </td>
             </tr>
           </table>
       </subsection>

Modified: velocity/tools/trunk/xdocs/frameworks.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/frameworks.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/frameworks.xml (original)
+++ velocity/tools/trunk/xdocs/frameworks.xml Mon Dec 10 19:56:55 2007
@@ -27,13 +27,72 @@
     </properties>
 
     <body>
-    <section name="Integrating with Web Frameworks">
+    <section name="Overview">
         <p class="note">
             This page is quite unfinished.
             <a href="index.html#Contribution">Help is welcome!</a>
         </p>
     </section>
-
+    <section name="Integration Via VelocityView">
+        <subsection name="Configuring">
+            <p>
+            <a href="javadoc/org/apache/velocity/tools/view/VelocityView.html">VelocityView</a>
+            supports the following configuration parameters as
+            &lt;init-param&gt;s in web.xml:
+            </p>
+            <dl>
+              <dt>org.apache.velocity.toolbox</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>
+              <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>
+            </dl>
+            <p>
+            TODO: talk about deprecationSupportMode
+            </p>
+        </subsection>
+        <subsection name="Retrieving">
+            <p>
+            TODO: finish this
+            </p>
+        </subsection>
+        <subsection name="Sharing">
+            <p>
+            TODO: finish this
+            </p>
+        </subsection>
+        <subsection name="Using">
+            <p>
+            TODO: finish this
+            </p>
+        </subsection>
+    </section>
+    <section name="Other Ways to Integrate VelocityTools">
+        <subsection name="Direct Use Of Tools">
+            <p>
+            TODO: finish this
+            </p>
+        </subsection>
+        <subsection name="ToolboxFactory">
+            <p>
+            TODO: finish this
+            </p>
+        </subsection>
+        <subsection name="ToolManager">
+            <p>
+            TODO: finish this
+            </p>
+        </subsection>
+    </section>
     </body>
 
 </document>

Modified: velocity/tools/trunk/xdocs/generic.project.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/generic.project.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/generic.project.xml (original)
+++ velocity/tools/trunk/xdocs/generic.project.xml Mon Dec 10 19:56:55 2007
@@ -22,10 +22,10 @@
 <project name="GenericTools" href="index.html"
     logo="images/velocitygenerictools.png">
 
-  <breadcrumb href="generic.index.html">GenericTools</breadcrumb>
+  <breadcrumb href="generic.html">GenericTools</breadcrumb>
   <menu>
-    <group name="GenericTools">
-        <item name="Overview"         href="generic.index.html"/>
+    <group name="GenericTools" href="generic.html">
+        <item name="Overview"         href="generic.html"/>
         <subGroup name="Tools" href="javadoc/org/apache/velocity/tools/generic/package-summary.html">
           <item name="AlternatorTool"       href="javadoc/org/apache/velocity/tools/generic/AlternatorTool.html"/> />
           <item name="ClassTool"            href="javadoc/org/apache/velocity/tools/generic/ClassTool.html"/>

Modified: velocity/tools/trunk/xdocs/generic.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/generic.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/generic.xml (original)
+++ velocity/tools/trunk/xdocs/generic.xml Mon Dec 10 19:56:55 2007
@@ -29,7 +29,6 @@
 
     <body>
 
-
     <section name="Overview">
         <p>
             GenericTools is the set of classes that provide basic 
@@ -41,7 +40,10 @@
             state-changing methods are declared protected with the exception 
             of configure(Map) which is--by default--rendered useless after 
             being used just once.  If you require strict thread-safety, 
-            be very cautious in using any configurable tools.
+            be cautious in using any configurable tools and consider
+            <a href="http://wiki.apache.org/velocity/BuildingSecureWebApplications">restricting
+            the abilities of template authors</a> to prevent circumvention
+            of the lockdown placed on configuration methods.
         </p>
     </section>
 
@@ -49,52 +51,64 @@
         <p>
             The default configuration provided for GenericTools is 
             <a href="http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/tools.xml?view=markup">
-            here</a>.
+            here</a>.  It includes all of the tools listed
+            <a href="generic.html#Tools">below</a>.
         </p>
     </section>
 
     <section name="Dependencies">
         <p>
-            TODO: just link to an anchor in a comprehensive dependencies overview page?
+        The dependencies required for GenericTools vary somewhat depending on which
+        tools you use, whether you will rely on core tool management infrastructure,
+        and if so, how you choose to configure your toolbox.  More details can be found
+        on the
+        <a href="dependencies.html#GenericTools">dependencies chart</a>.
         </p>
-
-        <subsection name="Compile Time Requirements">
-            <ul>
-                <li>commons-beanutils</li>
-                <li>commons-collections</li>
-                <li>commons-digester</li>
-                <li>commons-lang</li>
-                <li>commons-logging</li>
-                <li>velocity</li>
-            </ul>
-        </subsection>
-
-        <subsection name="Runtime Requirements">
-            <ul>
-                <li>commons-beanutils - core infrastructure, <a href="javadoc/org/apache/velocity/tools/generic/MathTool.html"> MathTool</a>, <a href="javadoc/org/apache/velocity/tools/generic/SortTool.html">SortTool</a></li>
-                <li>commons-digester - xml configuration</li>
-                <li>commons-lang - <a href="javadoc/org/apache/velocity/tools/generic/EscapeTool.html">EscapeTool</a></li>
-                <li>velocity - <a href="javadoc/org/apache/velocity/tools/generic/ClassTool.html">ClassTool</a>, <a href="javadoc/org/apache/velocity/tools/generic/IteratorTool.html"> IteratorTool</a>, <a href="javadoc/org/apache/velocity/tools/generic/RenderTool.html">RenderTool</a></li>
-            </ul>
-        </subsection>
     </section>
     <section name="Tools">
         <ul>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/Alternator.html">Alternator</a> &amp; <a href="javadoc/org/apache/velocity/tools/generic/AlternatorTool.html">AlternatorTool</a> - For easily alternating over values in a list or array.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/ClassTool.html">ClassTool</a> - For simplifying reflective lookup of information about Classes and their fields, methods and constructors.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/ConversionTool.html">ConversionTool</a> - For converting String values to richer object types.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/DateTool.html">DateTool</a> &amp; <a href="javadoc/org/apache/velocity/tools/generic/ComparisonDateTool.html">ComparisonDateTool</a> - For manipulating, formatting, and comparing dates.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/DisplayTool.html">DisplayTool</a> - For controlling display of references (e.g. truncating values, "pretty printing" lists, and displaying alternates when a reference is null).</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/EscapeTool.html">EscapeTool</a> - For common escaping needs in Velocity templates (e.g. escaping html, xml, javascript etc.)</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/FieldTool.html">FieldTool</a> - For (easy) access to static fields in a class, such as string constants.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/IteratorTool.html">IteratorTool</a> - Wraps lists to let the designer specify a condition to terminate the loop, and reuse the same list in different loops.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/ListTool.html">ListTool</a> - For working with arrays and lists, treats both transparently the same.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/MathTool.html">MathTool</a> - For performing math functions.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/NumberTool.html">NumberTool</a> - For formatting and converting numbers.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/RenderTool.html">RenderTool</a> - To evaluate and render arbitrary strings of VTL, including recursive rendering.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/ResourceTool.html">ResourceTool</a> - For simplified access to ResourceBundles for internationalization or other dynamic content needs.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/SortTool.html">SortTool</a> - Used to sort collections (or arrays, iterators, etc) on any arbitary set of properties exposed by the objects contained within the collection.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/generic/ValueParser.html">ValueParser</a> - Used to retrieve and parse (aka convert) String values pulled from a map.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/AlternatorTool.html">AlternatorTool</a>
+            - For creating <a href="javadoc/org/apache/velocity/tools/generic/Alternator.html">Alternator</a>s
+            to easily alternate over a set of values.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/ClassTool.html">ClassTool</a>
+            - For simplifying reflective lookup of information about
+            Classes and their fields, methods and constructors.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/ConversionTool.html">ConversionTool</a>
+            - For converting String values to richer object types.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/DateTool.html">DateTool</a>
+            &amp;
+            <a href="javadoc/org/apache/velocity/tools/generic/ComparisonDateTool.html">ComparisonDateTool</a>
+            - For manipulating, formatting, and comparing dates.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/DisplayTool.html">DisplayTool</a>
+            - For controlling display of references (e.g. truncating values,
+            "pretty printing" lists, and displaying alternates when a reference is null).</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/EscapeTool.html">EscapeTool</a>
+            - For common escaping needs in Velocity templates (e.g. escaping
+            html, xml, javascript etc.)</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/FieldTool.html">FieldTool</a>
+            - For (easy) access to static fields in a class, such as string
+            constants.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/LoopTool.html">LoopTool</a>
+            - A convenience tool to use with #foreach loops. It wraps a list
+            with a custom iterator to provide greater control, allowing loops
+            to end early, skip ahead and more.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/ListTool.html">ListTool</a>
+            - For working with arrays and lists, treats both transparently
+            the same.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/MathTool.html">MathTool</a>
+            - For performing math functions.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/NumberTool.html">NumberTool</a>
+            - For formatting and converting numbers.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/RenderTool.html">RenderTool</a>
+            - To evaluate and render arbitrary strings of VTL, including
+            recursive rendering.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/ResourceTool.html">ResourceTool</a>
+            - For simplified access to ResourceBundles for
+            internationalization or other dynamic content needs.</li>
+        <li><a href="javadoc/org/apache/velocity/tools/generic/SortTool.html">SortTool</a>
+            - Used to sort collections (or arrays, iterators, etc) on
+            any arbitary set of properties exposed by the objects contained
+            within the collection.</li>
         </ul>
     </section>
 

Modified: velocity/tools/trunk/xdocs/index.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/index.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/index.xml (original)
+++ velocity/tools/trunk/xdocs/index.xml Mon Dec 10 19:56:55 2007
@@ -43,7 +43,9 @@
             automatically and transparently make these tools available to your 
             Velocity templates.  Other aims of the project include providing 
             easy integration of Velocity into the view-layer of your web 
-            applications (via the VelocityViewTag and VelocityViewServlet) 
+            applications (via the 
+            <a href="view.tag.html">VelocityViewTag</a> and 
+            <a href="view.servlet.html">VelocityViewServlet</a>) 
             and integration with Struts 1.x applications.
         </p>
 
@@ -72,8 +74,10 @@
                 <a href="generic.html">GenericTools</a> structure and 
                 specialized tools for using Velocity in the view layer of web 
                 applications (Java EE projects). This includes the 
-                VelocityViewServlet or VelocityLayoutServlet for processing 
-                Velocity template requests and the VelocityViewTag for 
+                <a href="view.servlet.html">VelocityViewServlet</a> or 
+                <a href="view.layoutservlet.html">VelocityLayoutServlet</a>
+                for processing Velocity template requests and the 
+                <a href="view.tag.html">VelocityViewTag</a> for 
                 embedding Velocity in JSP. Popular tools here are the LinkTool
                 and the ParameterTool.
             </p>
@@ -85,7 +89,7 @@
                 <a href="view.html">VelocityView</a> and <a href="generic.html">
                 GenericTools</a> and adds tools for use in Struts 1.x 
                 applications.  These tools match the functions of the key 
-                Strutstaglibs and provide access to Struts resources, messages, 
+                Struts taglibs and provide access to Struts resources, messages, 
                 tiles, validation functions and more.
             </p>
         </subsection>
@@ -95,7 +99,7 @@
             require a little configuration) are generally useful and may be 
             used within your java classes or even other template languages, 
             though you may need to instantiate and configure them manually (not 
-            difficult) to do so.  VelocityTools2 has been designed with this 
+            difficult) to do so.  VelocityTools 2 has been designed with this 
             in mind.  Ask on the user mailing list if you have questions about 
             using VelocityTools without Velocity.
         </p>
@@ -105,7 +109,7 @@
     <section name="Why 2.0?">
         <p>
             Those already familiar with VelocityTools 1.x may be curious about 
-            the goals and motivations behind developing VelocityTools2. 
+            the goals and motivations behind developing VelocityTools 2. 
             In planning and developing the 2.0 release, there were three main 
             goals:
         </p>
@@ -127,11 +131,14 @@
             </li>
 
             <li>
-                Simpler, more flexible toolbox configuration - Now you can 
-                configure via a properties file, plain java, or really 
+                Simpler, more flexible toolbox 
+                <a href="config.html">configuration</a> - Now you can 
+                configure via a 
+                <a href="config.properties.html">properties file</a>, 
+                <a href="config.java.html">plain java</a>, or really 
                 whatever you want (though perhaps with a bit more work).  No 
-                XML required anymore; though, if you do use it, it's a lot 
-                better than it was.
+                <a href="config.xml.html">XML</a> required anymore; though,
+                if you do use it, it's now a lot better than it was.
             </li>
         </ul>
 
@@ -148,7 +155,8 @@
             the old tools directly will be immediately able to take advantage 
             of the new infrastructure without even updating their 
             configuration, though eventually even the old toolbox.xml format 
-            may be retired.  Don't cry.  You'll like the new one better once 
+            may be retired.  Don't cry.  You'll like the 
+            <a href="config.xml.html">new one</a> better once 
             you get to know it!  It can do much more with much less typing.
         </p>
 
@@ -176,16 +184,19 @@
     <section name="Contribution">
         <p>
             We encourage interested developers to evaluate the 
-            project and send feedback to the velocity-user or 
-            velocity-dev mailing list.
+            project and send feedback to the user@velocity.apache.org or 
+            dev@velocity.apache.org mailing lists.
         </p>
 
         <p>
             Those interested in furthering the development of this 
-            project are especially welcome to jump in and help out. 
-            Patches can be sent to the mailing list or attached to 
-            a JIRA issue. The Wiki can also be a good place to 
-            discuss and develop ideas.
+            project have an open invitation to jump in and help out.
+            We welcome your contributions!
+            Patches can be sent to the
+            mailing list or attached to a
+            <a href="http://issues.apache.org/jira/browse/VELTOOLS">JIRA</a>
+            issue.  The <a href="http://wiki.apache.org/velocity/VelocityTools">Wiki</a>
+            can also be a good place to discuss and develop ideas.
         </p>
 
         <p>A few good places to get started include:</p>
@@ -200,9 +211,16 @@
 
         <p>
             Other project goals and proposals can be found in the project 
-            <a href="http://svn.apache.org/viewcvs.cgi/velocity/tools/trunk/STATUS?view=markup"> 
-            STATUS</a> file.
+            <a href="http://svn.apache.org/viewcvs.cgi/velocity/tools/trunk/STATUS?view=markup">STATUS</a> file.
         </p>
+
+        <p>Checklist for Code Contributions:</p>
+        <ul>
+            <li><a href="http://wiki.apache.org/velocity/CodeStandards">Velocity coding conventions</a></li>
+            <li>Javadoc included (the more detailed the better)</li>
+            <li>Examples included (in JavaDoc or as stand-alone template example)</li>
+            <li>Tests included (not required but <b>GREATLY</b> appreciated)</li>
+        </ul>
 
     </section>
 

Modified: velocity/tools/trunk/xdocs/site.dvsl
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/site.dvsl?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/site.dvsl (original)
+++ velocity/tools/trunk/xdocs/site.dvsl Mon Dec 10 19:56:55 2007
@@ -259,7 +259,12 @@
  *#
 #match( "section" )
 <a name="$attrib.name"></a>##
-<div class="section"><h2>$attrib.name</h2>
+<div class="section">##
+#if( $attrib.href )
+<a href="$attrib.href"><h2>$attrib.name</h2></a>
+#else
+<h2>$attrib.name</h2>
+#end
   $context.applyTemplates("*")
 </div>
 #end
@@ -270,7 +275,12 @@
  *#
 #match( "subsection" )
 <a name="$attrib.name"></a>##
-<div class="subsection"><h3>$attrib.name</h3>
+<div class="subsection">##
+#if( $attrib.href )
+<a href="$attrib.href"><h3>$attrib.name</h3></a>
+#else
+<h3>$attrib.name</h3>
+#end
     $context.applyTemplates("*")
 </div>
 #end

Modified: velocity/tools/trunk/xdocs/standalone.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/standalone.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/standalone.xml (original)
+++ velocity/tools/trunk/xdocs/standalone.xml Mon Dec 10 19:56:55 2007
@@ -30,7 +30,7 @@
 
     <section name="Just Use Them!">
         <p>
-            There's nothing particularly special about the tools in VelocityTools2.  No 
+            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 

Modified: velocity/tools/trunk/xdocs/struts.project.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/struts.project.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/struts.project.xml (original)
+++ velocity/tools/trunk/xdocs/struts.project.xml Mon Dec 10 19:56:55 2007
@@ -22,14 +22,14 @@
 <project name="VelocityStruts" href="index.html"
     logo="images/velocitystruts.png">
 
-  <breadcrumb href="view.index.html">VelocityStruts</breadcrumb>
+  <breadcrumb href="view.html">VelocityStruts</breadcrumb>
   <menu>
-    <group name="VelocityStruts">
-        <item name="Overview"                href="struts.index.html"/>
-        <item name="Benefits"                href="struts.index.html#Benefits"/>
-        <item name="User Guide"              href="struts.userguide.html"/>
-        <item name="Installation"            href="struts.userguide.html#Installation"/>
-        <item name="Examples"                href="index.html#Example Applications"/>
+    <group name="VelocityStruts" href="struts.html">
+        <item name="Overview"       href="struts.html"/>
+        <item name="Benefits"       href="struts.html#Benefits"/>
+        <item name="User Guide"     href="struts.userguide.html"/>
+        <item name="Installation"   href="struts.userguide.html#Installation"/>
+        <item name="Examples"       href="struts.html#Examples"/>
         <subGroup name="Tools" href="javadoc/org/apache/velocity/tools/struts/package-summary.html">
           <item name="ActionMessagesTool" href="javadoc/org/apache/velocity/tools/struts/ActionMessagesTool.html"/>
           <item name="ErrorsTool"         href="javadoc/org/apache/velocity/tools/struts/ErrorsTool.html"/>

Modified: velocity/tools/trunk/xdocs/struts.userguide.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/struts.userguide.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/struts.userguide.xml (original)
+++ velocity/tools/trunk/xdocs/struts.userguide.xml Mon Dec 10 19:56:55 2007
@@ -145,7 +145,7 @@
         to render the web application views in Struts applications.</p>
 
         <p>Setup is almost identical to the standard
-        <a href="view.index.html#Installation">VelocityViewServlet installation</a>,
+        <a href="view.html#Installation">VelocityViewServlet installation</a>,
         please review that for more details. The extended VelocityLayoutServlet, or any
         custom extension, can also be used with Struts. (That particular servlet adds
         the ability to reuse shared html layout across multiple pages.)</p>

Modified: velocity/tools/trunk/xdocs/struts.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/struts.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/struts.xml (original)
+++ velocity/tools/trunk/xdocs/struts.xml Mon Dec 10 19:56:55 2007
@@ -30,6 +30,40 @@
     <body>
 
     <section name="Overview">
+        <p>The VelocityStruts sub-project integrates Velocity with the
+        <a href="http://struts.apache.org/">Apache Struts</a>
+        web application framework and enables the use of Velocity templates
+        interchangeably with JSP pages for the view layer.</p>
+
+        <p>Various other
+        <a href="http://wiki.apache.org/velocity/PoweredByVelocity">web application frameworks</a>
+        offer built-in support for Velocity templates. This project
+        provides the minimal glue necessary to give Struts developers
+        an alternative to JSP. </p>
+
+        <p><img src="images/velstruts_diag1.png" border="0"/></p>
+        <p><strong>Diagram 1.</strong> Comparison of JSP and Velocity for
+        the view layer in a Struts application.</p>
+
+        <p>As we follow the typical Struts process flow in Diagram 1,
+        notice how there is relatively little change except for the addition
+        of Velocity. The velocity-struts.jar leverages a standalone Velocity
+        servlet to process template files (specifically, the jar file is
+        velocity-tools-x.x.jar) and uses some drop-in tools to provide
+        transparent access to Struts specific objects (ex. message resources,
+        form beans, errors, links). The action mapping file will simply contain
+        ActionForwards that send control to a Velocity-based View layer instead
+        of sending to a JSP. </p>
+
+        <p>Also notable is that Velocity and JSP are <strong>not</strong>
+        mutually exclusive. Both technologies can be used in the same
+        application without any problems. This allows developers the option
+        of trying Velocity without heavy modification to existing applications.</p>
+
+        <p>We're convinced that once you give Velocity a try, you'll really like it.</p>
+    </section>
+
+    <section name="Default Configuration">
         <p>
             VelocityStruts includes both the <a href="generic.html">
             GenericTools</a> and <a href="view.html">VelocityView</a> and 
@@ -37,9 +71,6 @@
             the functions of the key Struts taglibs and provide access to 
             Struts resources, messages, tiles, validation functions and more.
         </p>
-    </section>
-
-    <section name="Default Configuration">
         <p>
             The default configuration provided for 
             <a href="struts.html">VelocityStruts</a> is 
@@ -50,65 +81,169 @@
             <a href="http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/struts/tools.xml?view=markup">
             here</a>.
         </p>
-
     </section>
+
     <section name="Dependencies">
         <p>
-            TODO: just link to an anchor in a comprehensive dependencies overview page?
+        The dependencies required for VelocityStruts can be found on our
+        <a href="dependencies.html#VelocityStruts">dependencies chart</a>.
         </p>
+    </section>
 
-        <subsection name="Compile Time Requirements">
-            <ul>
-                <li>commons-beanutils</li>
-                <li>commons-collections</li>
-                <li>commons-digester</li>
-                <li>commons-lang</li>
-                <li>commons-logging</li>
-                <li>commons-validator</li>
-                <li>servlet api</li>
-                <li>ssl-ext</li>
-                <li>struts-core</li>
-                <li>struts-taglib</li>
-                <li>struts-tiles</li>
-                <li>velocity</li>
-            </ul>
-        </subsection>
-
-        <subsection name="Runtime Requirements">
-            <ul>
-                <li>commons-beanutils - core infrastructure, 
-                <a href="javadoc/org/apache/velocity/tools/generic/MathTool.html">MathTool</a>, 
-                <a href="javadoc/org/apache/velocity/tools/generic/SortTool.html">SortTool</a></li>
-                <li>commons-digester - xml configuration</li>
-                <li>commons-lang - <a href="javadoc/org/apache/velocity/tools/generic/EscapeTool.html">EscapeTool</a></li>
-                <li>commons-validator - <a href="javadoc/org/apache/velocity/tools/struts/ValidatorTool.java ">ValidatorTool</a></li>
-                <li>servlet - all 
-                    <a href="javadoc/org/apache/velocity/tools/view/">VelocityView</a>
-                     and <a href="javadoc/org/apache/velocity/tools/struts/">VelocityStruts</a>
-                     tools except <a href="javadoc/org/apache/velocity/tools/view/ViewRenderTool.html">ViewRenderTool</a></li>
-                <li>ssl-ext - <a href="javadoc/org/apache/velocity/tools/struts/SecureLinkTool.java ">SecureLinkTool</a></li>
-                <li>struts-core - all <a href="javadoc/org/apache/velocity/tools/struts/">VelocityStruts</a> tools</li>
-                <li>struts-taglib - <a href="javadoc/org/apache/velocity/tools/struts/FormTool.html">FormTool</a>, <a href="javadoc/org/apache/velocity/tools/struts/SecureLinkTool.html">SecureLinkTool</a>, <a href="javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html">StrutsLinkTool</a></li>
-                <li>struts-tiles - <a href="javadoc/org/apache/velocity/tools/struts/TilesTool.java ">TilesTool</a></li>
-                <li>velocity - <a href="javadoc/org/apache/velocity/tools/generic/ClassTool.html">ClassTool</a>, <a href="javadoc/org/apache/velocity/tools/view/AbstractSearchTool.html">AbstractSearchTool</a>, <a href="javadoc/org/apache/velocity/tools/view/ContextTool.html">ContextTool</a>, <a href="javadoc/org/apache/velocity/tools/view/ImportTool.html">ImportTool</a>, <a href="javadoc/org/apache/velocity/tools/view/IteratorTool.html">IteratorTool</a>, <a href="ttp://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/LinkTool.html">LinkTool</a>, <a href="javadoc/org/apache/velocity/tools/view/MultiViewsTool.html">MultiViewsTool</a>, <a href="javadoc/org/apache/velocity/tools/view/ViewRenderTool.html">ViewRenderTool</a>,  <a href="javadoc/org/apache/velocity/tools/struts/SecureLinkTool.html">SecureLinkTool</a>, <a href="javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html">StrutsLinkTool</a>, <a href="javadoc/org/apache/velocity/
 tools/struts/MessageTool.html">MessageTool</a>.</li>
-            </ul>
-        </subsection>
+    <section name="Tools">
+        <p>
+        These are in addition to tools provided by
+        <a href="generic.html#Tools">GenericTools</a>
+        and
+        <a href="view.html#Tools">VelocityView</a>.
+        </p>
+        <ul>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/struts/ActionMessagesTool.html">ActionMessagesTool</a>
+          - For accessing/displaying Struts action messages.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/struts/ErrorsTool.java ">ErrorsTool</a>
+          - For accessing/displaying Struts error messages.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/struts/FormTool.html">FormTool</a>
+          - For working with HTML forms in Struts apps.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/struts/MessageResourcesTool.html">MessageResourcesTool</a>
+          - Abstract view tool that provides access to Struts
+          message resources.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/struts/MessageTool.html">MessageTool</a>
+          - Provides methods to render Struts application resources
+          (for i18n and other textual content access).
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/struts/SecureLinkTool.html">SecureLinkTool</a>
+          - For using Struts SSL Extensions. It has the same
+          interface as
+          <a href="javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html">StrutsLinkTool</a>
+          and can function as a substitute if Struts 1.x
+          and SSL Ext are installed.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html">StrutsLinkTool</a>
+          - Subclass of 
+          <a href="javadoc/org/apache/velocity/tools/view/LinkTool.html">LinkTool</a>
+          for creating URI links in Struts by adding support
+          for Struts actions and forwards.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/struts/TilesTool.html">TilesTool</a>
+          - For using Struts-Tiles (not for Tiles 2!)
+          in Velocity.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/struts/ValidatorTool.html">ValidatorTool</a>
+          - Uses Struts-Validator to produce client side
+          javascript validation for your forms.
+        </li>
+        </ul>
+    </section>
+
+    <section name="Examples">
+        <p>A Struts application example has been included to demonstrate the use
+        of the VelocityViewServlet with the automatically loaded VelocityStruts tools.</p>
+
+        <p>To run the examples you need Tomcat 4+ or a compatible servlet runner.</p>
+
+        <p>The 'ant examples' target of the build process automatically generates
+        a ready-to-deploy <b>struts.war</b>
+        archive file located in the examples subdirectory of the distribution. 
+        Deploy (i.e. copy) one or both of these war files to the webapps directory
+        of your servlet runner and restart.
+        Now point a web browser at the following url:</p>
+
+        <p><b>http://&lt;your_server&gt;:&lt;port&gt;/struts/</b></p>
+
+        <p>VelocityStruts is also distributed with
+        <a href="view.html#Examples">a couple other examples</a> that use
+        VelocityTools without the Struts 1 tools.</p>
     </section>
 
-d    <section name="Tools">
+    <section name="Benefits">
+        <p>There are many different reasons why people are choosing Velocity
+        technology for the view layer. Here are some:</p>
+        <p>
         <ul>
-            <li><a href="javadoc/org/apache/velocity/tools/struts/ActionMessagesTool.html">ActionMessagesTool</a> - For accessing/displaying Struts action messages.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/struts/ErrorsTool.java ">ErrorsTool</a> - For accessing/displaying Struts error messages.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/struts/FormTool.html">FormTool</a> - For working with HTML forms in Struts apps.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/struts/MessageResourcesTool.html">MessageResourcesTool</a> - Abstract view tool that provides access to Struts message resources.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/struts/MessageTool.html">MessageTool</a> - Provides methods to render Struts application resources (for i18n and other textual content access).</li>
-            <li><a href="javadoc/org/apache/velocity/tools/struts/SecureLinkTool.html">SecureLinkTool</a> - For using Struts SSL Extensions. It has the same interface as <a href="javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html">StrutsLinkTool</a> and can function as a substitute if Struts 1.x and SSL Ext are installed.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html">StrutsLinkTool</a> - Subclass of <a href="javadoc/org/apache/velocity/tools/view/LinkTool.html">LinkTool</a> for creating URI links in Struts by adding support for Struts actions and forwards.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/struts/TilesTool.html">TilesTool</a> - For using Struts-Tiles (not for Tiles 2!) in Velocity.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/struts/ValidatorTool.html">ValidatorTool</a> - Uses Struts-Validator to produce client side javascript validation for your forms.</li>
+            <li>Velocity helps enforce a clean separation between the view
+            layer and the model/control layers. This leads to clean application
+            design and a clear separation of concerns between View Designers
+            and back-end Developers.</li>
+
+            <li><a href="http://velocity.apache.org/engine/devel/vtl-reference-guide.html">Velocity Template Language (VTL)</a>
+            has few directives and is simple and easy to learn. Most
+            people report being productive within a day.</li>
+
+            <li>Velocity is easy to extend with <i>Tools</i> which are simply
+            any class which has public methods. These are typically much cleaner
+            and easier to develop than JSP custom tag libraries.</li>
+
+            <li>Using the TilesTool it is easy
+            to mix Velocity and JSP tiles in the same page/layout. For those
+            using Tiles, this makes gradual migration between or integration of
+            the two view technologies trivially easy!</li>
+
+            <li>Velocity 'macros' are a powerful tool for the View Designer.
+            They enable the creation of reusable snippets of markup, often
+            eliminating what would have been a need to develop a custom tag
+            library or other server-side tool.</li>
+
+            <li>Velocity templates are <strong>not</strong> limited to HTML
+            and can be used to produce any type of text output including XML,
+            SQL, ASCII, PostScript, etc.</li>
+
+            <li>Velocity enables easy access to dynamic data
+            that Web Designers can understand.</li>
+
+            <li>Velocity being interpreted, enables a simple development cycle
+            where template errors can quickly be localized and debugged.</li>
+
+            <li>Velocity, which caches templates for speed, has been reported
+            to have performance comparable or better than JSP.</li>
+
+            <li>Velocity is <strong>supported</strong> by an active and helpful
+            community of users and developers.</li>
         </ul>
+        </p>
     </section>
 
-    </body>
+    <section name="Success Stories">
+        <p>Comments from folks who are using Struts and Velocity:</p>
+        <p>
+        <blockquote>
+          <p>&quot;<i>We've been using Struts/Velocity for some time now and we find it to be
+          an extremely well matched combination.  One of the main advantages of
+          Velocity is that the syntax is incredibly easy.  I can explain it to a
+          designer who has never seen it before and expect them to be useful
+          within an hour.</i>&quot; </p>
+          <p>&quot;<i>One of the nicest things it enforces is the separation of presentation
+          layer and business logic.  It removes the desire to 'fix' problems by
+          just putting a small change into the JSP via scriptlets.  It also makes
+          the code a <strong>lot</strong> more readable which also reduces the
+          development time.</i>&quot;</p>
+          <p>&quot;<i>Struts is a solid framework and Velocity makes it
+          even better.</i>&quot;</p>
+          <p>&quot;<i>I find that the VelocityTools for Struts works as well, or better, with
+          Struts than another other presentation technology, bar none. In fact,
+          most of the tools work just as well with any other framework you might
+          care to name.</i>&quot;
+          --<a href="http://marc.theaimsgroup.com/?l=velocity-user&amp;m=106520662105461&amp;w=25">Ted Husted</a>
+          (author of <a href="http://husted.com/struts/book.html">Struts in Action</a>)</p>
+        </blockquote>
+        </p>
+    </section>
 
+    <section name="License">
+        <p>This software is licensed under the
+        <a href="http://velocity.apache.org/engine/devel/license.html">Apache Software License 2.0</a></p>
+    </section>
+  </body>
 </document>

Modified: velocity/tools/trunk/xdocs/view.layoutservlet.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/view.layoutservlet.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/view.layoutservlet.xml (original)
+++ velocity/tools/trunk/xdocs/view.layoutservlet.xml Mon Dec 10 19:56:55 2007
@@ -22,7 +22,7 @@
 <document>
 
     <properties>
-        <title>Layout Servlet</title>
+        <title>VelocityViewServlet</title>
         <projectfile>xdocs/project.xml</projectfile>
         <subprojectfile>xdocs/view.project.xml</subprojectfile>
     </properties>

Modified: velocity/tools/trunk/xdocs/view.project.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/view.project.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/view.project.xml (original)
+++ velocity/tools/trunk/xdocs/view.project.xml Mon Dec 10 19:56:55 2007
@@ -22,12 +22,13 @@
 <project name="VelocityView" href="index.html"
     logo="images/velocityview.png">
 
-  <breadcrumb href="view.index.html">VelocityView</breadcrumb>
+  <breadcrumb href="view.html">VelocityView</breadcrumb>
   <menu>
-    <group name="VelocityView">
-      <item name="Installation"   href="index.html#Installation"/>
-      <item name="LayoutServlet"  href="view.layoutservlet.html"/>
-      <item name="Examples"       href="index.html#Examples"/>
+    <group name="VelocityView" href="view.html">
+      <item name="VelocityViewServlet"      href="view.servlet.html"/>
+      <item name="VelocityLayoutServlet"    href="view.layoutservlet.html"/>
+      <item name="VelocityViewTag"          href="view.tag.html"/>
+      <item name="Examples"                 href="view.html#Examples"/>
       <subGroup name="Tools" href="javadoc/org/apache/velocity/tools/view/package-summary.html">
         <item name="AbstractSearchTool" href="javadoc/org/apache/velocity/tools/view/AbstractSearchTool.html"/>
         <item name="BrowserTool"        href="javadoc/org/apache/velocity/tools/view/BrowserTool.html"/>

Added: velocity/tools/trunk/xdocs/view.servlet.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/view.servlet.xml?rev=603140&view=auto
==============================================================================
--- velocity/tools/trunk/xdocs/view.servlet.xml (added)
+++ velocity/tools/trunk/xdocs/view.servlet.xml Mon Dec 10 19:56:55 2007
@@ -0,0 +1,277 @@
+<?xml version="1.0"?>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<document>
+    <properties>
+        <title>VelocityViewServlet</title>
+        <projectfile>xdocs/project.xml</projectfile>
+        <subprojectfile>xdocs/view.project.xml</subprojectfile>
+    </properties>
+    <body>
+        <section name="Overview">
+            <p class="note">
+                This page is still unfinished and in dire need of
+                updating to reflect changes in VelocityTools 2.
+                Much of this probably needs to be moved or at least
+                copied to a VelocityView page.
+                <a href="index.html#Contribution">Help is welcome!</a>
+            </p>
+            <p>
+              <a href="javadoc/org/apache/velocity/tools/view/VelocityViewServlet.html">Javadoc is here</a>.
+            </p>
+
+            <p>A typical application use-case for the VelocityViewServlet
+            is to provide the view rendering layer for
+            a servlet-based web application framework. The
+            <a href="struts.html">VelocityStruts</a> subproject
+            uses the approach to bring Velocity templates to the Struts 1
+            application framework.</p>
+
+        </section>
+
+  <section name="Installation">
+    <p>The VelocityViewServlet needs to be installed into your servlet container
+    so it can handle all request for *.vm (velocity template) files. There are
+    only two additional configuration files, and they are shown in
+    detail below.</p>
+
+    <subsection name="Servlet Setup">
+      <p>The servlet configuration (<strong>web.xml</strong>) must be
+      modified to include a reference to the VelocityViewServlet
+      (or subclass thereof) which will perform the rendering. All *.vm files are
+      mapped to this servlet which will populate the 'context' with
+      Request, Session, and Application scopes plus any additional tools
+      specified in the <strong>toolbox.xml</strong> file. The servlet
+      will use this contextual information and the Velocity Engine to
+      render the template file. </p>
+
+      <p><strong>Note:</strong> Additional functionality can be achieved
+      through subclassing the VelocityViewServlet, and will be discussed further in
+      the VelocityLayoutServlet below. </p>
+
+      <p><b>web.xml</b></p>
+      <sourcecode>&lt;!-- Define Velocity template compiler --&gt;
+&lt;servlet&gt;
+  &lt;servlet-name&gt;velocity&lt;/servlet-name&gt;
+  &lt;servlet-class&gt;
+    org.apache.velocity.tools.view.servlet.VelocityViewServlet
+  &lt;/servlet-class&gt;
+
+  &lt;!-- 
+    Unless you plan to put your toolbox.xml and velocity.properties
+    under different folders or give them different names, then these
+    two init-params are unnecessary as of VelocityTools 1.3.  The
+    VelocityViewServlet will automatically look for these files in
+    the following locations.
+  --&gt;
+  &lt;init-param&gt;
+    &lt;param-name&gt;org.apache.velocity.toolbox&lt;/param-name&gt;
+    &lt;param-value&gt;/WEB-INF/toolbox.xml&lt;/param-value&gt;
+  &lt;/init-param&gt;
+
+  &lt;init-param&gt;
+    &lt;param-name&gt;org.apache.velocity.properties&lt;/param-name&gt;
+    &lt;param-value&gt;/WEB-INF/velocity.properties&lt;/param-value&gt;
+  &lt;/init-param&gt;
+&lt;/servlet&gt;
+
+&lt;!-- Map *.vm files to Velocity --&gt;
+&lt;servlet-mapping&gt;
+  &lt;servlet-name&gt;velocity&lt;/servlet-name&gt;
+  &lt;url-pattern&gt;*.vm&lt;/url-pattern&gt;
+&lt;/servlet-mapping&gt;</sourcecode>
+    </subsection>
+
+    <subsection name="Velocity Configuration">
+      <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>
+
+      <p>The location of the configuration file may be specified in web.xml,
+      but it is recommended the file be placed inside the hidden WEB-INF
+      directory of the web application and named 'velocity.properties' which
+      is where the VelocityViewServlet will look for it in the absence of
+      any location specified in the web.xml.
+      An example configuration file is included with the distribution.</p>
+      <p>Please see the
+      <a href="http://velocity.apache.org/engine/devel/user-guide.html">Velocity User's Guide</a>
+      for more information on Velocity configuration.</p>
+
+      <sourcecode>  velocimacro.library = /WEB-INF/VM_global_library.vm
+  velocimacro.permissions.allow.inline = true
+  velocimacro.permissions.allow.inline.to.replace.global = false
+  velocimacro.permissions.allow.inline.local.scope = false
+  velocimacro.context.localscope = false</sourcecode>
+
+    </subsection>
+
+    <subsection name="Toolbox Configuration">
+      <p>The toolbox file, <strong>WEB-INF/toolbox.xml</strong> by
+      default, maps names of our choosing to the classes that they will
+      represent. It's easier than that sounds.</p>
+      <p>Think about asking our friend Jon to grab us a 'wrench' from a
+      real toolbox. Jon just needs to know which wrench we want (metric,
+      pipe, crescent etc,). He doesn't need to know what the wrench does
+      nor what we are planning to do with it.</p>
+      <p>The Velocity Toolbox works the same way, we must only specify
+      which tool to assign to a name, and then the Velocity engine takes
+      care of the rest by making any public method available to the
+      template. For example, from the definitions below, the template
+      could call $wrench.getSize() or $wrench.size .</p>
+
+      <p><b>PipeWrench.java</b></p>
+      <sourcecode>public class PipeWrench {
+  public String getSize() {
+    return "Large Pipe Wrench!";
+  }
+} </sourcecode>
+
+      <p><b>toolbox.xml</b></p>
+      <sourcecode>&lt;?xml version="1.0"?&gt;
+&lt;toolbox&gt;
+  &lt;tool&gt;
+     &lt;key&gt;wrench&lt;/key&gt;
+     &lt;scope&gt;application&lt;/scope&gt;
+     &lt;class&gt;PipeWrench&lt;/class&gt;
+  &lt;/tool&gt;
+&lt;/toolbox&gt;</sourcecode>
+
+      <br clear="all"/>
+
+      <p><b>Tool Scopes</b></p>
+
+      <p>The toolbox support built into the VelocityViewServlet also provides
+      support for specifying the scope of your tool with regards to the
+      servlet environment.  Tools may be placed within the <i>request</i>,
+      <i>session</i>, or <i>application</i> scopes of your web app.</p>
+      <p>The scope that you set for your tool will determine both its
+      lifecycle and, if the tool has a <code>public init(Object)</code> method,
+      then the scope will also determine what data is passed to that method:</p>
+      <ul>
+        <li><i>application</i> scoped tools will be instantiated only once and then
+        reused for each request.  Due to this, it is <em>strongly</em> encouraged
+        that your application scoped tools be completely threadsafe.  The MathTool
+        in the <a href="generic.html">GenericTools</a> section is a good example of tool meant to be application
+        scoped.  If an application scoped tool implements ViewTool, then the
+        javax.servlet.ServletContext for the webapp will be passed to its
+        <code>init(Object)</code> method after it is instantiated.</li>
+
+        <li><i>session</i> scoped tools are instantiated once per unique session and
+        are then reused for every request associated with that particular session. If
+        a session scoped tool implements ViewTool, then its <code>init(Object)</code>
+        method will be passed the
+        <a href="javadoc/org/apache/velocity/tools/view/ViewContext.html">ViewContext</a>
+        of the request during which the session was created.</li>
+
+        <li><i>request</i> is the default scope.  If no scope is specified for a
+        &lt;tool&gt; in your toolbox.xml, then it will be automatically set as
+        <i>request</i> scope.  Tools with this scope are instantiated for every
+        servlet request fed to the VelocityViewServlet.  If a request scoped tool
+        implements ViewTool, then its <code>init(Object)</code> method will be
+        passed the current ViewContext.</li>
+      </ul>
+      <p>You can specify the scope of your tools by adding a &lt;scope&gt;
+      element to your toolbox.xml entries like this:</p>
+
+      <sourcecode>&lt;tool&gt;
+   &lt;key&gt;math&lt;/key&gt;
+   &lt;scope&gt;application&lt;/scope&gt;
+   &lt;class&gt;org.apache.velocity.tools.generic.MathTool&lt;/class&gt;
+&lt;/tool&gt;</sourcecode>
+
+      <br clear="all"/>
+
+      <p><b>Tool Request Paths</b></p>
+
+      <p>You can specify a restriction on the request URIs for which the tool
+      will be put in the context using the &lt;request-path&gt; element.
+      It can be an exact request path (matching one page) or end with the
+      <code>*</code> wildard, meaning that incoming request paths need only
+      start with the provided value for the tool to be available in the context.
+      For instance:</p>
+
+      <sourcecode>&lt;tool&gt;
+   &lt;key&gt;catalog&lt;/key&gt;
+   &lt;scope&gt;request&lt;/scope&gt;
+   &lt;request-path&gt;/catalog/*&lt;/request-path&gt;
+   &lt;class&gt;com.mycompany.tools.CatalogTool&lt;/class&gt;
+&lt;/tool&gt;</sourcecode>
+
+      <p>For now, this request-path filter is only valid for request scoped tools.
+      In VelocityTools 2.0, we plan to support this for session and application
+      scoped tools as well.</p>
+
+      <br clear="all"/>
+
+      <p><b>Tool Parameters</b></p>
+
+      <p>The toolbox support built into the VelocityViewServlet also provides
+      support for passing configuration parameters to tools that have a
+      <code>public void configure(java.util.Map params)</code> method.
+      This method will only be called if parameters have been specified for the tool.</p>
+
+      <p>You can specify parameters for your tools by adding a &lt;parameter&gt;
+      element to your toolbox.xml entries like this:</p>
+
+      <sourcecode>&lt;tool&gt;
+   &lt;key&gt;math&lt;/key&gt;
+   &lt;scope&gt;application&lt;/scope&gt;
+   &lt;class&gt;com.foo.tools.MyTool&lt;/class&gt;
+   &lt;parameter name="my.parameter.name" value="my.parameter.value"/&gt;
+&lt;/tool&gt;</sourcecode>
+
+      <br clear="all"/>
+
+      <p><b>Toolbox Data</b></p>
+
+      <p>In addition to specifiying arbitrary Java classes as <b>tools</b>
+      to be automatically available to your templates, the toolbox support
+      also includes the ability to specify arbitrary strings, booleans, and
+      numbers to be automatically available in your templates.  The format
+      is as follows:</p>
+
+      <sourcecode>&lt;?xml version=&quot;1.0&quot;?&gt;
+&lt;toolbox&gt;
+  &lt;data type=&quot;number&quot;&gt;
+     &lt;key&gt;app_version&lt;/key&gt;
+     &lt;value&gt;0.9&lt;/value&gt;
+  &lt;/data&gt;
+  &lt;data type=&quot;string&quot;&gt;
+     &lt;key&gt;app_name&lt;/key&gt;
+     &lt;value&gt;Jon's Tool Shop&lt;/value&gt;
+  &lt;/data&gt;
+  &lt;data type=&quot;boolean&quot;&gt;
+     &lt;key&gt;debug&lt;/key&gt;
+     &lt;value&gt;true&lt;/value&gt;
+  &lt;/data&gt;
+&lt;/toolbox&gt;</sourcecode>
+
+        <p>As with your tools, your data will be exposed to your templates
+        under the specified key (e.g. $app_version, $app_name, $debug).</p>
+
+        </subsection>
+      </section>
+    </body>
+</document>

Propchange: velocity/tools/trunk/xdocs/view.servlet.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: velocity/tools/trunk/xdocs/view.servlet.xml
------------------------------------------------------------------------------
    svn:mime-type = text/xml

Added: velocity/tools/trunk/xdocs/view.tag.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/view.tag.xml?rev=603140&view=auto
==============================================================================
--- velocity/tools/trunk/xdocs/view.tag.xml (added)
+++ velocity/tools/trunk/xdocs/view.tag.xml Mon Dec 10 19:56:55 2007
@@ -0,0 +1,80 @@
+<?xml version="1.0"?>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<document>
+    <properties>
+        <title>VelocityViewTag</title>
+        <projectfile>xdocs/project.xml</projectfile>
+        <subprojectfile>xdocs/view.project.xml</subprojectfile>
+    </properties>
+    <body>
+        <section name="Overview">
+            <p class="note">
+                This page is still unfinished.
+                <a href="index.html#Contribution">Help is welcome!</a>
+            </p>
+            <p>
+            This is a JSP tag that allows you to use Velocity and VelocityTools
+            from within your JSP tags and files.
+            This tag can both process templates in separate files:
+            </p>
+        <sourcecode>
+&lt;%@taglib prefix="velocity" uri="http://velocity.apache.org/velocity-view" %&gt;
+
+&lt;velocity:view template="foo.vm"/&gt;
+        </sourcecode>
+            <p>
+             VTL in the body of the tag:
+            </p>
+        <sourcecode>
+&lt;%@taglib prefix="velocity" uri="http://velocity.apache.org/velocity-view" %&gt;
+
+&lt;velocity:view&gt;
+#if( $date.E eq 'Friday' )
+ Hooray!
+#else
+ Boo!
+#end
+&lt;/velocity:view&gt;
+        </sourcecode>
+            <p>
+            or combine both by first processing the body of the tag, then
+            inserting the results of that into the context for the separate
+            template as $bodyContent:
+            </p>
+        <sourcecode>
+&lt;%@taglib prefix="velocity" uri="http://velocity.apache.org/velocity-view" %&gt;
+
+&lt;velocity:view template="foo.vm"&gt;
+#if( $date.E eq 'Friday' )
+ Hooray!
+#else
+ Boo!
+#end
+&lt;/velocity:view&gt;
+        </sourcecode>
+            <p>
+            For more information, see the
+            <a href="javadoc/org/apache/velocity/tools/view/jsp/VelocityViewTag.html">Javadoc</a>.
+            </p>
+        </section>
+    </body>
+</document>

Propchange: velocity/tools/trunk/xdocs/view.tag.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: velocity/tools/trunk/xdocs/view.tag.xml
------------------------------------------------------------------------------
    svn:mime-type = text/xml



Mime
View raw message