velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nbu...@apache.org
Subject svn commit: r603140 [2/2] - /velocity/tools/trunk/xdocs/
Date Tue, 11 Dec 2007 03:56:56 GMT
Modified: velocity/tools/trunk/xdocs/view.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/view.xml?rev=603140&r1=603139&r2=603140&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/view.xml (original)
+++ velocity/tools/trunk/xdocs/view.xml Mon Dec 10 19:56:55 2007
@@ -40,6 +40,21 @@
             processing Velocity template requests and the 
             VelocityViewTag for embedding Velocity in JSP.
         </p>
+        <p>Key features:</p>
+        <ul>
+          <li><b><a href="view.servlet.html">VelocityViewServlet</a></b>
+              - standalone servlet that renders Velocity
+              templates. Invoked directly from web clients requests, or via servlet
+              forwarding similar to how JSP files are rendered by JSPServlet.</li>
+          <li>The HttpServletRequest, HttpSession, ServletContext,
+              and their attributes are automatically available in your templates.</li>
+          <li>Tools can also be made available to your templates, through a
+              <strong>tools</strong> <a href="config.html">configuration</a>
file.</li>
+          <li>A number of useful, extendable tools for developing web applications
are
+              already provided for your convenience.</li>
+          <li>Logging can be directed to the log infrastructure of the Web application.
+              (default is the logging facility provided by the Servlet API).</li>
+        </ul>
     </section>
 
     <section name="Default Configuration">
@@ -54,73 +69,171 @@
 
     <section name="Dependencies">
         <p>
-            TODO: just link to an anchor in a comprehensive dependencies 
-            overview page?
+        The dependencies required for VelocityView can be found on our
+        <a href="dependencies.html#VelocityStruts">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>
-                <li>servlet api</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/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="javadoc/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></li>
-                <li>servlet - all <a href="javadoc/org/apache/velocity/tools/view/">VelocityView</a>
tools except <a href="javadoc/org/apache/velocity/tools/view/ViewRenderTool.html">ViewRenderTool</a></li>
-            </ul>
-        </subsection>
     </section>
 
     <section name="VelocityView Object">
         <p>
-            TODO: a writeup and link for this    
-        </p>
-    </section>
+        The <a href="javadoc/org/apache/velocity/tools/view/VelocityView.html">VelocityView</a>
+        object forms the core of the VelocityView infrastructure.  In particular,
+        it serves as the base class for the following:
+        </p>
+
+        <subsection name="VelocityViewServlet" href="view.servlet.html">
+            <p>
+            The 
+            <a href="javadoc/org/apache/velocity/tools/view/VelocityViewServlet.html">VelocityViewServlet</a>
+            class is a standalone servlet that renders Velocity
+            templates. It can be invoked directly from web client's 
+            requests, or via servlet forwarding similar to how JSP files
+            are rendered by JSPServlet.
+            </p>
+            <p>Detailed documentation is
+            <a href="view.servlet.html">here</a>.
+            </p>
+        </subsection>
 
-    <section name="VelocityViewTag">
-        <p>
-            TODO: a writeup and link for this
-    
-        </p>
-    </section>
-    
-    <section name="VelocityViewServlet">
-        <p>
-            TODO: a writeup and link for this
-        </p>
-    </section>
+        <subsection name="VelocityLayoutServlet" href="view.layoutservlet.html">
+            <p>One derivative of the VelocityViewServlet is the
+            <a href="view.layoutservlet.html"><strong>VelocityLayoutServlet</strong></a>.
+            This servlet performs a simplified 'two-pass render' in order to apply a
+            shared, common layout to all of the web pages in an application.</p>
+
+            <p>The Struts &quot;template&quot; tag library does something similar,
+            but requires a separate file to define which 'layout' file to use and
+            which .jsp files to render into that layout. The VelocityLayoutServlet
+            takes a simpler approach. It first renders the primary template being
+            called (example: showDetails.vm) into a content holder variable
+            (ex. $screen_content). Next, the servlet loads a 'layout' file. It
+            uses the existing data, including any additional variables set or
+            changed by the first template, to render a the layout template.</p>
+
+            <p>The VelocityLayoutServlet also allows you to specify an 'error'
+            template to be displayed when an exception is thrown during the
+            processing of a requested template.  This allows you to provide
+            a customized error screen for a more user-friendly application.</p>
+
+            <p>Detailed documentation is
+            <a href="view.layoutservlet.html">here</a>.
+            </p>
+        </subsection>
 
-    <section name="VelocityLayoutServlet">
-        <p>
-            TODO: a writeup and link for this
-        </p>
+        <subsection name="VelocityViewTag" href="view.tag.html">
+            <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, VTL in the tag body, or combine the two.
+            </p>
+            <p>Detailed documentation is
+            <a href="view.tag.html">here</a>.
+            </p>
+        </subsection>
     </section>
 
     <section name="Tools">
+        <p>
+        These are in addition to those provided by
+        <a href="generic.html#Tools">GenericTools</a>
+        </p>
         <ul>
-            <li><a href="javadoc/org/apache/velocity/tools/view/AbstractSearchTool.html">AbstractSearchTool</a>
- For doing "searching" and robust pagination of search results. Requires you to create a
subclass.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/view/BrowserTool.html">BrowserTool</a>
- For identifying the browser and features thereof requesting the template.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/view/ContextTool.html">ContextTool</a>
- For convenient access to ViewContext data and meta-data.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/view/CookieTool.html">CookieTool</a>
- For convenient cookie access and creation.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/view/ImportTool.html">ImportTool</a>
- For pulling down textual content from a URL.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/view/LinkTool.html">LinkTool</a>
- For easy building of URLs (both relative or absolute).</li>
-            <li><a href="javadoc/org/apache/velocity/tools/view/PagerTool.html">PagerTool</a>
- For doing request-based pagination of items in an arbitrary list.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/view/ParameterTool.html">ParameterTool</a>
- For easy retrieval and parsing of ServletRequest parameters.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/view/ViewRenderTool.html">ViewRenderTool</a>
- To evaluate and render arbitrary strings of VTL, including recursive rendering.</li>
-            <li><a href="javadoc/org/apache/velocity/tools/view/ViewResourceTool.html">ViewResourceTool</a>
- For simplified access to ResourceBundles for internationalization or other dynamic content
needs.</li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/AbstractSearchTool.html">AbstractSearchTool</a>
+          - For doing "searching" and robust pagination of search
+          results. Requires you to create a subclass.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/BrowserTool.html">BrowserTool</a>
+          - For identifying the browser and features thereof requesting
+          the template.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/ContextTool.html">ContextTool</a>
+          - For convenient access to ViewContext data and meta-data.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/CookieTool.html">CookieTool</a>
+          - For convenient cookie access and creation.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/ImportTool.html">ImportTool</a>
+          - For pulling down textual content from a URL.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/LinkTool.html">LinkTool</a>
+          - For easy building of URLs (both relative or absolute).
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/PagerTool.html">PagerTool</a>
+          - For doing request-based pagination of items in an
+          arbitrary list.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/ParameterTool.html">ParameterTool</a>
+          - For easy retrieval and parsing of ServletRequest parameters.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/ViewRenderTool.html">ViewRenderTool</a>
+          - To evaluate and render arbitrary strings of VTL,
+          including recursive rendering.
+        </li>
+        <li>
+          <a href="javadoc/org/apache/velocity/tools/view/ViewResourceTool.html">ViewResourceTool</a>
+          - For simplified access to ResourceBundles for
+          internationalization or other dynamic content needs.
+        </li>
         </ul>
     </section>
 
+    <section name="Examples">
+        <p>A simple application example has been included to demonstrate the use
+        of the VelocityViewServlet with automatically loaded view 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
+        ready-to-deploy <b>simple.war</b> and <b>showcase.war</b>
+        archive files 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 urls:</p>
+
+        <p><b>http://&lt;your_server&gt;:&lt;port&gt;/simple/</b></p>
+        <p><b>http://&lt;your_server&gt;:&lt;port&gt;/showcase/</b></p>
+    </section>
+
+<!--  TODO: revise this...
+    <section name="Known Issues">
+        <p>
+          Since Tomcat 5.5 used commons-logging as a complete
+          logging facility, we were no longer able to direct commons-logging
+          output to the servlet log by default.  The result of this is that
+          our example apps can no longer contain a commons-logging.properties
+          on the classpath if we want them to work with all servlet engines.  
+        </p>
+        <p>
+          When using Tomcat 5.5, this means that log messages
+          from our tools and tool management code are by default sent to the Tomcat
+          console, rather than the servlet log.  Velocity Engine and
+          VelocityViewServlet messages will still be sent to the servlet
+          log by default. When using other servlet engines or earlier Tomcat versions
+          (e.g. Jetty or Tomcat 4.x), you must now add a commons-logging.properties
+          file at the root of the classpath that contains:
+          <code>
+          org.apache.commons.logging.Log=org.apache.velocity.tools.generic.log.LogSystemCommonsLog
+          </code>
+          if you wish to have tool and tool management log output sent to the
+          servlet log.  If you are using Tomcat 5.5, do NOT do that, as it will
+          cause an infinite loop.
+        </p>
+        <p>
+          We plan to resolve this in future versions by removing commons-logging
+          from our code in favor of the much improved log wrappers in Velocity Engine 1.5.
+          In the meantime, commons-logging remains the most flexible solution.
+        </p>
+    </section>
+-->
     </body>
 
 </document>



Mime
View raw message