velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nbu...@apache.org
Subject svn commit: r603409 - in /velocity/tools/trunk/xdocs: config.xml.xml css/print.css css/style.css index.xml project.xml view.servlet.xml view.tag.xml
Date Tue, 11 Dec 2007 23:16:04 GMT
Author: nbubna
Date: Tue Dec 11 15:16:03 2007
New Revision: 603409

URL: http://svn.apache.org/viewvc?rev=603409&view=rev
Log:
more tweaks, updates and whatnot

Modified:
    velocity/tools/trunk/xdocs/config.xml.xml
    velocity/tools/trunk/xdocs/css/print.css
    velocity/tools/trunk/xdocs/css/style.css
    velocity/tools/trunk/xdocs/index.xml
    velocity/tools/trunk/xdocs/project.xml
    velocity/tools/trunk/xdocs/view.servlet.xml
    velocity/tools/trunk/xdocs/view.tag.xml

Modified: velocity/tools/trunk/xdocs/config.xml.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/config.xml.xml?rev=603409&r1=603408&r2=603409&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/config.xml.xml (original)
+++ velocity/tools/trunk/xdocs/config.xml.xml Tue Dec 11 15:16:03 2007
@@ -61,7 +61,7 @@
     </toolbox>
 
     <data type="number" key="version" value="1.1"/>
-    <data key="date" value="Mon Sep 17 10:08:03 PDT 2007" class="java.util.Date" 
+    <data key="startdate" value="Mon Sep 17 10:08:03 PDT 2007" class="java.util.Date"

              converter="org.apache.commons.beanutils.locale.converters.DateLocaleConverter"/>
     <data type="boolean" key="isSimple" value="true"/>
     <data key="foo" value="this is foo."/>

Modified: velocity/tools/trunk/xdocs/css/print.css
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/css/print.css?rev=603409&r1=603408&r2=603409&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/css/print.css (original)
+++ velocity/tools/trunk/xdocs/css/print.css Tue Dec 11 15:16:03 2007
@@ -13,14 +13,16 @@
 }
 h1, h2 {
     padding: 1px 1px 1px 2px;
-    margin: 2px 1px 1px 2px;
+    margin: 10px 1px 1px 2px;
     background-color: white;
     color: black;
 }
 h3, h4, h5 {
     padding: 1px 1px 1px 2px;
+    margin: 8px 0px 0px 20px;
     border: none;
     color: black;
+    background-color: white;
 }
 #title h1 {
     font-size: 16pt;

Modified: velocity/tools/trunk/xdocs/css/style.css
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/css/style.css?rev=603409&r1=603408&r2=603409&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/css/style.css (original)
+++ velocity/tools/trunk/xdocs/css/style.css Tue Dec 11 15:16:03 2007
@@ -15,8 +15,19 @@
     margin-top: 10px;
 }
 
+h3 {
+    margin: 32px 0px 0px 20px;
+    background-color: whiteSmoke;
+}
+
 .note {
     background-color: #ffeeff;
     border: 1px dotted #111111;
     padding: 3px 3px;
+}
+
+.subsubSection {
+    font-weight: bold;
+    margin-top: 30px;
+    margin-bottom: -5px;
 }

Modified: velocity/tools/trunk/xdocs/index.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/index.xml?rev=603409&r1=603408&r2=603409&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/index.xml (original)
+++ velocity/tools/trunk/xdocs/index.xml Tue Dec 11 15:16:03 2007
@@ -181,46 +181,70 @@
 
     </section>
 
-    <section name="Contribution">
-        <p>
-            We encourage interested developers to evaluate the 
-            project and send feedback to the user@velocity.apache.org or 
-            dev@velocity.apache.org mailing lists.
-        </p>
-
-        <p>
+    <section name="Helping Out">
+        <subsection name="Communication">
+            <p>
+            Feedback about the project, whether positive or gently critical,
+            is always helpful to those working on the project.  Such feedback
+            may be sent to either the user@velocity.apache.org or 
+            dev@velocity.apache.org 
+            <a href="http://velocity.apache.org/contact.html">mailing lists</a>.
+            </p>
+            <p>
+            Another great way to help is to simply participate in conversations
+            on the mailing list.  On the user list, you can help answer questions
+            that other users have. This frees the developers to focus on
+            development more than user support.  On the dev list, you can
+            participate in design discussions and release votes to help
+            maintain the high quality of the releases and direct the future
+            directions of the project.
+            </p>
+        </subsection>
+        <subsection name="Contribution">
+            <p>
             Those interested in furthering the development of this 
             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
+            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>
-
-        <ul>
-            <li>Documentation (patches for the site or additions to 
-            the Wiki)</li>
-            <li>Improving the example apps</li>
-            <li>Contributing to the 
-                <a href="http://wiki.apache.org/velocity/VelocimacroLibrary">VelocimacroLibrary</a></li>
-        </ul>
-
-        <p>
+            </p>
+            <p>A few good places to get started include:</p>
+            <ul>
+                <li>Documentation (patches for the site or additions to 
+                the Wiki)</li>
+                <li>Improving the example apps</li>
+                <li>Working on unresolved tasks in
+                    <a href="http://issues.apache.org/jira/browse/VELTOOLS">JIRA</a></li>
+                <li>Contributing to the 
+                    <a href="http://wiki.apache.org/velocity/VelocimacroLibrary">VelocimacroLibrary</a></li>
+            </ul>
+            <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.
-        </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>
+            </p>
+        </subsection>
+        <subsection name="Code">
+            <p>
+            When contributing code, it helps <strong>immensely</strong> if you
follow
+            through with the things on this checklist, especially the coding conventions.
+            Keeping our code style consistent, our codebase stays easy to read and easy
+            to patch.  Adding javadoc (and examples therein) simplifies the documentation
+            process and reduces confusion about the purpose of various methods and classes.
+            Tests make sure that things work as expected, especially as development continues
+            down the road.  Of course, contributions that don't follow the checklist will
+            be considered and often accepted, but you can expect the project committers
+            to be slower and less enthusiastic in doing so. :)
+            </p>
+            <p><b>Checklist for Code Contributions</b>:</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>
+        </subsection>
 
     </section>
 

Modified: velocity/tools/trunk/xdocs/project.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/project.xml?rev=603409&r1=603408&r2=603409&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/project.xml (original)
+++ velocity/tools/trunk/xdocs/project.xml Tue Dec 11 15:16:03 2007
@@ -22,9 +22,9 @@
 <project name="VelocityTools" href="index.html"
     logo="images/velocitytools.png">
 
-    <style href="css/style.css"/>
     <style href="css/maven-theme.css"/>
     <style href="css/maven-base.css"/>
+    <style href="css/style.css"/>
     <breadcrumb href="http://velocity.apache.org">Velocity</breadcrumb>
     <breadcrumb href="index.html">VelocityTools</breadcrumb>
     <sibling href="http://velocity.apache.org/engine/devel/">Engine</sibling>
@@ -66,7 +66,7 @@
 
         <group name="Development">
             <item name="ChangeLog"      href="changes.html"/>
-            <item name="Contributions"  href="index.html#Contribution"/>
+            <item name="Participating"  href="index.html#Helping%20Out"/>
             <item name="Dependencies"   href="dependencies.html"/>
             <item name="Source Code"    href="index.html#Subversion%20Repository"/>
             <item name="Report Issue"   href="http://issues.apache.org/jira/browse/VELTOOLS"/>

Modified: velocity/tools/trunk/xdocs/view.servlet.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/view.servlet.xml?rev=603409&r1=603408&r2=603409&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/view.servlet.xml (original)
+++ velocity/tools/trunk/xdocs/view.servlet.xml Tue Dec 11 15:16:03 2007
@@ -26,65 +26,71 @@
         <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>
+    <section name="Overview">
+        <p class="note">
+        This page is still unfinished.
+        Much of this needs to be moved or at least
+        copied to a VelocityView page, as it
+        applies to anything using a
+        <a href="javadoc/org/apache/velocity/tools/view/VelocityView.html">VelocityView</a>
+        instance under the covers (including the
+        <a href="view.tag.html">VelocityViewTag</a>).
+        <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>
 
-      <p><b>web.xml</b></p>
-      <sourcecode>&lt;!-- Define Velocity template compiler --&gt;
+        <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 by your configuration (or provided as defaults). 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 <a href="view.layoutservlet.html">VelocityLayoutServlet page</a>.
+            </p>
+            <p><b>web.xml</b></p>
+            <sourcecode>
+&lt;!-- Define Velocity template handler --&gt;
 &lt;servlet&gt;
   &lt;servlet-name&gt;velocity&lt;/servlet-name&gt;
   &lt;servlet-class&gt;
-    org.apache.velocity.tools.view.servlet.VelocityViewServlet
+    org.apache.velocity.tools.view.VelocityViewServlet
   &lt;/servlet-class&gt;
 
   &lt;!-- 
-    Unless you plan to put your toolbox.xml and velocity.properties
+    Unless you plan to put your tools.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
+    two init-params are unnecessary.  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;param-value&gt;/WEB-INF/tools.xml&lt;/param-value&gt;
   &lt;/init-param&gt;
 
   &lt;init-param&gt;
@@ -97,181 +103,211 @@
 &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>
+&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>
 
-    <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>
+            <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 (located at <strong>/WEB-INF/tools.xml</strong>
by
+            convention), maps out the "tools" and data we want available for
+            our templates to use. 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 we want, 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 <code>$wrench.size</code>.
+            </p>
+            <p><b>PipeWrench.java</b></p>
+            <sourcecode>
+public class PipeWrench {
+    public String getSize() {
+        return "Large Pipe Wrench!";
+    }
+}
+            </sourcecode>
+
+            <p><b>tools.xml</b></p>
+            <sourcecode>
+&lt;?xml version="1.0"?&gt;
+&lt;tools&gt;
+&lt;toolbox scope="application"&gt;
+ &lt;tool key="wrench" class="PipeWrench"/&gt;
+&lt;/toolbox&gt;
+&lt;/tools&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>
+            <p class="subsubSection">Toolbox Scopes</p>
 
+            <p>
+            You may have noticed that toolbox support built into VelocityView
+            also provides support for specifying the scope of your toolbox with
+            regards to the servlet environment.
+            Toolboxes 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 toolbox will determine the
+            lifecycle of the tools within it:
+            </p>
+            <ul>
+                <li>
+                <i>application</i> scoped tools will be instantiated only once
when
+                first used by a template and then reused by all templates for each
+                subsequent request.  Due to this, it is <em>strongly</em> encouraged
+                that your application scoped tools be completely threadsafe.  The 
+                <a href="javadoc/org/apache/velocity/tools/generic/MathTool.html">MathTool</a>
+                (one of the <a href="generic.html">GenericTools</a>) is a good
example
+                of tool meant to be application scoped.
+                </li>
+
+                <li>
+                <i>session</i> scoped tools are instantiated at most once
+                per unique session (if they are used by a template processed
+                for that session) and are then reused for every request
+                associated with that particular session.
+                </li>
+
+                <li>
+                <i>request</i> is the most common scope.
+                Tools with this scope are instantiated at most once per
+                servlet request fed to that VelocityView (if they are used by
+                a template processed during that request).
+                </li>
+            </ul>
+
+            <p class="subsubSection">Tool Path Restrictions</p>
+
+            <p>You can specify a restriction on the request URIs for which the tool
+            will be available in the context using the "restrictTo" attribute of
+            your tool configuration.
+            It can be an exact request path (matching one page) or end with the
+            <code>*</code> wildcard, meaning that incoming request paths need
only
+            start with the provided value for the tool to be available.
+            For instance:</p>
+
+            <sourcecode>
+&lt;tool restrictTo="/catalog/*"
+      class="com.mycompany.tools.CatalogTool"/&gt;
+            </sourcecode>
+
+            <p>
+            You may have noticed that this example tool configuration doesn't
+            have a "key" attribute.  This is because VelocityTools 2 honors the
+            [Key]Tool naming convention.  So a tool with the simple name of
+            "CatalogTool" will automatically be given the key "catalog" unless
+            another key is specified in the tool configuration or using the
+            <a href="javadoc/org/apache/velocity/tools/config/DefaultKey.html">DefaultKey</a>
+            annotation on the class.
+            </p>
+
+            <p class="subsubSection">Tool Properties</p>
+            <p>
+            The toolbox support built into VelocityTools also provides
+            support for passing configuration properties to tools.
+            If a tool has a
+            <code>public void configure(java.util.Map params)</code> method,
+            then VelocityTools will pass that method a map of all properties
+            set on the tool configuration, the toolbox to which it belongs and
+            properties set for the whole configuration.
+            </p>
+            <p>
+            VelocityTools will also use Commmons-BeanUtils to set any or all
+            of those same properties directly on the tool if their keys and types
+            have a matching public set[Key](Type) method on that tool.
+            
+            </p>
+            <p>
+            These things happen immediately
+            after a tool instance is instantiated and before it is available to
+            your templates.  This gives much flexibility in designing and configuring
+            your tools.</p>
+            <p>
+            You can specify properties for your tools, toolboxes or all tools
+            either as &lt;property&gt; tags or as attributes:
+            </p>
+            <sourcecode>
+&lt;tools foo="true"&gt;
+&lt;toolbox scope="application" someProperty="whatever"&gt;
+    &lt;property key="bar"&gt;woogie&lt;/property&gt;
+    &lt;tool key="myTool" class="com.foo.tools.MyTool"&gt;
+        &lt;property name="my.parameter.name" value="my.parameter.value"/&gt;
+    &lt;/tool&gt;
+&lt;/toolbox&gt;
+&lt;/tools&gt;
+            </sourcecode>
+
+            <p class="subsubSection">Static Data</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,
+            numbers, lists of those, and even BeanUtils-convertable types to be
+            automatically available in your templates.  The format
+            is as follows:
+            </p>
+            <sourcecode>
+&lt;?xml version=&quot;1.0&quot;?&gt;
+&lt;tools&gt;
+    &lt;data type="number" key="version" value="1.1"/&gt;
+    &lt;data key="startdate" value="Mon Sep 17 10:08:03 PDT 2007" class="java.util.Date"

+             converter="org.apache.commons.beanutils.locale.converters.DateLocaleConverter"/&gt;
+    &lt;data type="boolean" key="isSimple" value="true"/&gt;
+    &lt;data key="foo" value="this is foo."/&gt;
+    &lt;data key="bar"&gt;this is bar.&lt;/data&gt;
+    &lt;data type="list" key="dataKeys"
+             value="version,date,isSimple,foo,bar,dataKeys,switches"/&gt;
+    &lt;data type="list.boolean" key="switches" value="true,false,false,true"/&gt;
+&lt;/tools&gt;
+            </sourcecode>
+
+            <p>
+            As with your tools, your data will be exposed to your templates
+            under the specified key (e.g. $version, $startdate, $isSimple,
+            $foo, $bar, $dataKeys and $switches). Unlike
+            tools, data does not go in a toolbox and is not scoped (as it is
+            necessarily static).
+            </p>
         </subsection>
-      </section>
+    </section>
     </body>
 </document>

Modified: velocity/tools/trunk/xdocs/view.tag.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/view.tag.xml?rev=603409&r1=603408&r2=603409&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/view.tag.xml (original)
+++ velocity/tools/trunk/xdocs/view.tag.xml Tue Dec 11 15:16:03 2007
@@ -28,13 +28,24 @@
     <body>
         <section name="Overview">
             <p class="note">
-                This page is still unfinished.
-                <a href="index.html#Contribution">Help is welcome!</a>
+            This page is still unfinished. For details on configuring
+            the VelocityViewTag, you can follow most of the instructions
+            for the <a href="view.servlet.html">VelocityViewServlet</a>
+            and of course on the <a href="config.html">configuration pages</a>.
+            <a href="index.html#Contribution">Help finishing this 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:
+            from within a JSP page or tag.  There are many ways to use this tag.
+            This simplest is to have it process an external template using the
+            current page context.  Assuming you have a template called "foo.vm"
+            that can be found by your resource loader(s) that looks like this:
+            </p>
+        <sourcecode>
+Hello $!bodyContent World!
+        </sourcecode>
+            <p>
+            This tag can process that template by doing:
             </p>
         <sourcecode>
 &lt;%@taglib prefix="velocity" uri="http://velocity.apache.org/velocity-view" %&gt;
@@ -49,9 +60,9 @@
 
 &lt;velocity:view&gt;
 #if( $date.E eq 'Friday' )
- Hooray!
+ Happy
 #else
- Boo!
+ Sad
 #end
 &lt;/velocity:view&gt;
         </sourcecode>
@@ -65,15 +76,32 @@
 
 &lt;velocity:view template="foo.vm"&gt;
 #if( $date.E eq 'Friday' )
- Hooray!
+ Happy
+#else
+ Sad
+#end
+&lt;/velocity:view&gt;
+        </sourcecode>
+            <p>
+            You can also store the results of any of the options above into
+            a variable of any name and scope (default scope is "page"):
+            </p>
+        <sourcecode>
+&lt;%@taglib prefix="velocity" uri="http://velocity.apache.org/velocity-view" %&gt;
+
+&lt;velocity:view var="foo" scope="request" template="foo.vm"&gt;
+#if( $date.E eq 'Friday' )
+ Happy
 #else
- Boo!
+ Sad
 #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>.
+            For more details, see the
+            <a href="javadoc/org/apache/velocity/tools/view/jsp/VelocityViewTag.html">Javadoc</a>
+            or the
+            <a href="http://svn.apache.org/repos/asf/velocity/tools/trunk/src/main/java/META-INF/velocity-view.tld">TLD</a>.
             </p>
         </section>
     </body>



Mime
View raw message