|
|
|
|
| <html>
|
| <head>
|
| <title>VelocityStruts - User Guide</title>
|
|
|
| <meta name="author" value="Gabriel Sidler"/>
|
| <meta name="email" value="sidler@apache.org" />
|
|
|
|
|
| </head>
|
|
|
| <body bgcolor="#ffffff" text="#000000" link="#525D76"
|
| alink="#525D76" vlink="#525D76">
|
|
|
| <table border="0" width="100%" cellspacing="4">
|
|
|
| <tr><td colspan="2">
|
|
|
| <a href="http://velocity.apache.org/">
|
| <img src="http://velocity.apache.org/images/velocity_project_wide.png"
|
| align="left" alt="The Velocity Project" border="0"/>
|
| </a>
|
|
|
|
|
|
|
| <a href="index.html">
|
| <img src="../images/velocitystruts.png" align="right" alt="< Velocity Tools - Struts >" border="0"/>
|
| </a>
|
|
|
| </td></tr>
|
|
|
| <tr>
|
| <td colspan="2">
|
| <hr noshade="" size="1"/>
|
| </td>
|
| </tr>
|
|
|
| <tr>
|
|
|
| <td width="20%" valign="top" nowrap="true">
|
|
|
| <p><strong><a href="../">Velocity Tools</a></strong></p>
|
|
|
| <p>
|
| <strong>VelocityStruts</strong>
|
| </p>
|
| <ul>
|
| <li><a href="index.html">Overview</a></li>
|
| <li><a href="index.html#Benefits">Benefits</a></li>
|
| <li><a href="../index.html#Download">Download</a></li>
|
| <li><a href="userguide.html">User Guide</a></li>
|
| <li><a href="userguide.html#Installation">Installation</a></li>
|
| <li><a href="../index.html#Example Applications">Examples</a></li>
|
| <li><a href="../javadoc/index.html">Javadoc</a></li>
|
|
|
| </ul>
|
| <p>
|
| <a href="StrutsTools.html"><strong>VelocityStruts Tools</strong></a>
|
| </p>
|
| <ul>
|
| <li><a href="ActionMessagesTool.html">ActionMessagesTool</a></li>
|
| <li><a href="ErrorsTool.html">ErrorsTool</a></li>
|
| <li><a href="FormTool.html">FormTool</a></li>
|
| <li><a href="MessageTool.html">MessageTool</a></li>
|
| <li><a href="StrutsLinkTool.html">StrutsLinkTool</a></li>
|
| <li><a href="SecureLinkTool.html">SecureLinkTool</a></li>
|
| <li><a href="TilesTool.html">TilesTool</a></li>
|
| <li><a href="ValidatorTool.html">ValidatorTool</a></li>
|
|
|
| </ul>
|
| <p>
|
| <strong>Other Subprojects</strong>
|
| </p>
|
| <ul>
|
| <li><a href="../generic/">GenericTools</a></li>
|
| <li><a href="../view/">VelocityView</a></li>
|
|
|
| </ul>
|
|
|
| <p>
|
| </p>
|
|
|
| </td>
|
|
|
| <!-- RIGHT SIDE MAIN BODY -->
|
| <td colspan="1" valign="top" align="left">
|
| <table border="0" cellspacing="0" cellpadding="2" width="100%">
|
| <tr>
|
| <td colspan="2" bgcolor="#525D76">
|
| <font color="#ffffff" face="arial,helvetica.sanserif">
|
| <a name="VelocityStruts User Guide">
|
| <strong>VelocityStruts User Guide</strong></a></font>
|
| </td>
|
| </tr>
|
| <tr>
|
| <td NOWRAP> </td>
|
| <td>
|
| <p>This guide explains how to setup and configure a VelocityViewServlet |
| which can render the views of a Struts-based web application. The servlet |
| will create a VelocityEngine to render *.vm (velocity template) files using |
| contextual information provided by a Struts Controller action.</p>
|
| <p>A set of built-in tools have been created which provide the same |
| functions as the Struts JSP Tag libraries for Tiles, Validator, forms, links, |
| messages, and errors.</p>
|
| <p>The distribution contains examples which demonstrate the use of the |
| built-in Struts tools. The examples are packaged into a web archive file |
| (velstruts.war). </p>
|
| <p> |
| This document is <strong>not</strong> a general introduction to the Velocity |
| template language and its syntax. If you are new to Velocity, please consult |
| <a href="http://velocity.apache.org/engine/devel/getting-started.html">Getting |
| Started with Velocity</a>. |
| </p>
|
| <p><strong>Table of Contents</strong></p>
|
| <ol> |
| <li><a href="#Background">Background</a></li> |
| <li><a href="#Model 2 Architecture">Model 2 Architecture</a></li> |
| <li><a href="#Installation">Installation</a></li> |
| <li><a href="#Rendering the View">Rendering the View</a> |
| <ol> |
| <li><a href="#Velocity Template Language">Velocity Template Language</a></li> |
| <li><a href="#Exposing Data">Exposing Data</a></li> |
| <li><a href="#Access to Servlet Resources">Access to Servlet Resources</a></li> |
| <li><a href="#Access to Struts Framework Resources">Access to Struts Framework Resources</a></li> |
| </ol> |
| </li> |
| </ol>
|
| <br clear="all"/>
|
|
|
| </td>
|
| </tr>
|
| </table>
|
| <table border="0" cellspacing="0" cellpadding="2" width="100%">
|
| <tr>
|
| <td colspan="2" bgcolor="#525D76">
|
| <font color="#ffffff" face="arial,helvetica.sanserif">
|
| <a name="Background">
|
| <strong>Background</strong></a></font>
|
| </td>
|
| </tr>
|
| <tr>
|
| <td NOWRAP> </td>
|
| <td>
|
| <p>The documentation will explain the steps necessary to |
| integrate <a href="http://velocity.apache.org/">Velocity</a> |
| with <a href="http://struts.apache.org/1.x/index.html">Struts 1.x</a> applications. |
| It is expected that the reader already has a basic understanding of those |
| projects.</p>
|
| <p>To start working with Velocity and Struts we recommend reading the |
| user guide, installing and browsing the example applications and reference |
| documentation, then installing the VelocityStruts view layer into your own |
| application.</p>
|
| <p>If this documentation does not answer all your questions, please post |
| questions to the |
| <a href="http://velocity.apache.org/contact.html">Velocity-User mailing list</a> |
| and we'll be happy to help! (And we'll update this doc!)</p>
|
| <br clear="all"/>
|
|
|
| </td>
|
| </tr>
|
| </table>
|
| <table border="0" cellspacing="0" cellpadding="2" width="100%">
|
| <tr>
|
| <td colspan="2" bgcolor="#525D76">
|
| <font color="#ffffff" face="arial,helvetica.sanserif">
|
| <a name="Model 2 Architecture">
|
| <strong>Model 2 Architecture</strong></a></font>
|
| </td>
|
| </tr>
|
| <tr>
|
| <td NOWRAP> </td>
|
| <td>
|
| <p>In the JSP world, the terms <i>Model 1</i> architectures and |
| <i>Model 2</i> architectures were coined to refer to particular ways of |
| designing and building web applications. It is important that you understand |
| the fundamental difference between these two architectural approaches. JSP |
| can be used in applications designed after Model 1 architectures as well as |
| Model 2 architectures. Velocity cannot. It has been designed very consciouly |
| as a view technology for web application architectures based on Model 2.</p>
|
| <p><strong>Model 1 Architectures</strong></p>
|
| <p>In a Model 1 architecture, the JSP page alone is responsible for |
| processing the incoming request and replying back to the client. Using |
| MVC speak, the controller and the view are implemented within the same |
| JSP page. Model 1 architecture are suitable only for very simple application |
| scenarios. In medium size to large projects, the lack of a separation between |
| business logic and view oftentimes leads to difficulties in separating the |
| web designer's works from the server developer's work and causes project |
| management headaches.</p>
|
| <p><strong>Model 2 Architectures</strong></p>
|
| <p>In a Model 2 architecture, the control component, including business logic, |
| data access and request handling, are strictly separated from the view component. |
| The view does not contain any processing logic. It is simply responsible for |
| displaying the data that resulted from processing the request. This may be a |
| static page or more often a dynamic page. Such an approach typically facilitates |
| are clear delineation of the roles and responsibilities of the developers and |
| the web designers. The more complex an application, the greater the benefits of |
| using a Model 2 architecture will be.</p>
|
| <p>The paper |
| <a href="http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html">Understanding JavaServer Pages Model 2 Architecture</a> |
| provides a more in-depth discussion of Model 1 and Model 2 architectures.</p>
|
| <p><strong>What does this mean?</strong></p>
|
| <p>The Struts framework can support both architectures, but all the |
| facilities it provides are really aimed at making the construction of |
| Model 2 applications easy. Velocity on the other hand cannot be used |
| to build Model 1 architectures. It lacks the libraries to support such |
| a design. I am emphasizing this here because I want to make sure that |
| you have all the relevant facts before you decide on Velocity for your |
| projects. This is especially important for people considering to port |
| existing application built on the Model 1 approach or a mixed Model 1 |
| / Model 2 approach. The good news is, that today for any serious application |
| Model 2 is state of the art and Velocity will support you very well on |
| that route.</p>
|
| <br clear="all"/>
|
|
|
| </td>
|
| </tr>
|
| </table>
|
| <table border="0" cellspacing="0" cellpadding="2" width="100%">
|
| <tr>
|
| <td colspan="2" bgcolor="#525D76">
|
| <font color="#ffffff" face="arial,helvetica.sanserif">
|
| <a name="Installation">
|
| <strong>Installation</strong></a></font>
|
| </td>
|
| </tr>
|
| <tr>
|
| <td NOWRAP> </td>
|
| <td>
|
| <p>This section explains the basic setup to configure the VelocityViewServlet |
| 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>, |
| 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>
|
| <p>Steps by step:</p>
|
| <ol> |
| <li><strong>velocity-tools-x.x.jar</strong> which contains the VelocityStruts |
| and VelocityView classes must be added to the WEB-INF/lib directory.</li> |
| <li>VelocityViewServlet needs to be installed into the servlet container |
| (web.xml) so it can handle all request for *.vm files.</li> |
| <li>velocity.properties configuration file must be added </li> |
| <li>toolbox.xml file must be added, and mappings must be setup for the |
| standard tools which expose the Struts objects to the template. (sample |
| toolbox.xml file below)</li> |
| </ol>
|
| <p>And that's all there is to it!</p>
|
| <p>At this point, it should be possible to change a Struts ActionMapping |
| to 'forward' to a *.vm file placed in the webapp root directory and have |
| it be displayed!</p>
|
| <p><b>toolbox.xml</b></p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode> |
| <?xml version="1.0"?> |
| |
| <toolbox> |
| <tool> |
| <key>link</key> |
| <scope>request</scope> |
| <class>org.apache.velocity.tools.struts.StrutsLinkTool</class> |
| </tool> |
| <tool> |
| <key>msg</key> |
| <scope>request</scope> |
| <class>org.apache.velocity.tools.struts.MessageTool</class> |
| </tool> |
| <tool> |
| <key>errors</key> |
| <scope>request</scope> |
| <class>org.apache.velocity.tools.struts.ErrorsTool</class> |
| </tool> |
| <tool> |
| <key>form</key> |
| <scope>request</scope> |
| <class>org.apache.velocity.tools.struts.FormTool</class> |
| </tool> |
| <tool> |
| <key>tiles</key> |
| <scope>request</scope> |
| <class>org.apache.velocity.tools.struts.TilesTool</class> |
| </tool> |
| <tool> |
| <key>validator</key> |
| <scope>request</scope> |
| <class>org.apache.velocity.tools.struts.ValidatorTool</class> |
| </tool> |
| </toolbox> |
| </sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <br clear="all"/>
|
|
|
| </td>
|
| </tr>
|
| </table>
|
| <table border="0" cellspacing="0" cellpadding="2" width="100%">
|
| <tr>
|
| <td colspan="2" bgcolor="#525D76">
|
| <font color="#ffffff" face="arial,helvetica.sanserif">
|
| <a name="Rendering the View">
|
| <strong>Rendering the View</strong></a></font>
|
| </td>
|
| </tr>
|
| <tr>
|
| <td NOWRAP> </td>
|
| <td>
|
| <p>This section introduces you to the key concepts of rendering |
| the view with Velocity in a Struts application.</p>
|
| <table border="0" cellspacing="0" cellpadding="2" width="100%">
|
| <tr>
|
| <td colspan="2" bgcolor="#828DA6">
|
| <font color="#ffffff" face="arial,helvetica.sanserif">
|
| <a name="Velocity Template Language">
|
| <strong>Velocity Template Language</strong></a></font>
|
| </td>
|
| </tr>
|
| <tr>
|
| <td NOWRAP> </td>
|
| <td>
|
| <p>Velocity is a template engine implemented in Java. Velocity |
| templates typically are HTML pages with embedded scripts (although |
| Velocity has been used for many other application scenarios). Scripts |
| are written in the Velocity Template Language (VTL). Following is a |
| simple example of a HTML view with embedded VTL statements:</p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode> |
| <HTML> |
| <BODY> |
| <h2>Order Confirmation</h2> |
| |
| <h3>Delivery Adress:</h3><br> |
| Name: $customer.name<br> |
| Street: $customer.street<br> |
| City: $customer.zip $customer.city |
| |
| <h3>Ordered Items</h3><br> |
| <table> |
| #foreach( $item in $order.items ) |
| <tr> |
| <td>$item.quantity</td> |
| <td>$item.description</td> |
| </tr> |
| #end |
| </table> |
| </body> |
| </html> |
| </sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>When processed this will produce output similar to the following.</p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode> |
| <HTML> |
| <BODY> |
| <h2>Order Confirmation</h2> |
| |
| <h3>Delivery Address:</h3><br> |
| Name: Peter Pan<br> |
| Street: Crain St. 10<br> |
| City: 60201 Evanston IL |
| |
| <h3>Ordered Items</h3><br> |
| <table> |
| <tr> |
| <td>1</td> |
| <td>Hair Dryer, Philips, 1000W, white</td> |
| </tr> |
| <tr> |
| <td>1</td> |
| <td>Kitchen Mixer, Betty Bossy, 240W, black</td> |
| </tr> |
| </table> |
| </body> |
| </html> |
| </sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>VTL has been designed from the ground up as a simple template |
| language for view designers. With less than ten supported directives |
| it is easy to learn. In fact, most people are up and productive within |
| less than a day.</p>
|
| <p>Velocity does not allow Java scriptlets, which helps enforce a |
| strict MVC separation.</p>
|
| <p>Please consult the following two documents for an in-depth coverage |
| of VTL:</p>
|
| <ul> |
| <li><a href="http://velocity.apache.org/engine/devel/user-guide.html">Velocity User's Guide</a></li> |
| <li><a href="http://velocity.apache.org/engine/devel/vtl-reference-guide.html">VTL Reference Guide</a></li> |
| </ul>
|
| <br clear="all"/>
|
|
|
| </td>
|
| </tr>
|
| </table>
|
| <table border="0" cellspacing="0" cellpadding="2" width="100%">
|
| <tr>
|
| <td colspan="2" bgcolor="#828DA6">
|
| <font color="#ffffff" face="arial,helvetica.sanserif">
|
| <a name="Exposing Data">
|
| <strong>Exposing Data</strong></a></font>
|
| </td>
|
| </tr>
|
| <tr>
|
| <td NOWRAP> </td>
|
| <td>
|
| <p>The main purpose of Velocity in a web application is typically to |
| merge HTML templates with dynamic application data to generate |
| dynamic views. An essential aspect of Velocity is therefore the |
| mechanism that allows the application controller (in MVC speak) to |
| expose data to the template.</p>
|
| <p>It is important to understand the relationship between a |
| Struts-based application and the Velocity template servlet. Both |
| are simply Java Servlets which perform a specific task.</p>
|
| <p> Requests to the Struts application are processed, application data |
| is manipulated and eventually all data and control is forwarded to a |
| View layer.</p>
|
| <p>The Velocity servlet in this case is responsible for merging the |
| provided application data with a template to produce HTML output.</p>
|
| <p>We should note that the Velocity servlet is not exclusively tied |
| to the Struts application. It can serve requests from web clients |
| directly or any other servlet application as well. Technically, the |
| Struts application hands over a request to Velocity through the |
| <code>forward</code> method of <code>javax.servlet.RequestDispatcher</code>. |
| </p>
|
| <p>Application data is passed from the Struts servlet to the Velocity |
| servlet as attributes of either the servlet request, session or context.</p>
|
| <p>Therefore a developer simply needs to set an attribute to pass data |
| to the View layer and make that data available for the template. For example: |
| </p>
|
| <p> |
| <sourcecode>request.setAttribute("Customer", CustomerObj);</sourcecode> |
| Whatever public methods are available on the CustomerObj instance will be |
| made available to the template designer. Assuming there is a public |
| getName() method, they may for example write: $Customer.name or |
| $Customer.getName(). |
| </p>
|
| <p>There is a heirarchy to the objects exposed to the template designer. |
| For instance, if you have set an attribute "foo" in both the session and |
| the request,</p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode>request.setAttribute("foo", "request foo"); |
| session.setAttribute("foo", "session foo");</sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>then the request attribute will take priority, and using </p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode>$foo</sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>in the template will give you</p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode>request foo</sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>Priority is given in the following order: |
| <ol> |
| <li>Tools specified in the toolbox.xml (e.g. $link, $tiles, etc.)</li> |
| <li>The servlet classes (e.g. $request, $response, $session, $application)</li> |
| <li>References set locally within the template</li> |
| <li>Request attributes</li> |
| <li>Session attributes</li> |
| <li>Servlet context (application) attributes</li> |
| </ol> |
| </p>
|
| <p>This heirarchy allows the developer to reserve control of key references |
| (for tools and servlet resources) from the template designer and allows for |
| values to be set at various servlet scopes in a manner similar to working |
| with JSP and Struts.</p>
|
| <br clear="all"/>
|
|
|
| </td>
|
| </tr>
|
| </table>
|
| <table border="0" cellspacing="0" cellpadding="2" width="100%">
|
| <tr>
|
| <td colspan="2" bgcolor="#828DA6">
|
| <font color="#ffffff" face="arial,helvetica.sanserif">
|
| <a name="Access to Servlet Resources">
|
| <strong>Access to Servlet Resources</strong></a></font>
|
| </td>
|
| </tr>
|
| <tr>
|
| <td NOWRAP> </td>
|
| <td>
|
| <p>VelocityStruts automatically populates the context with the following |
| objects of the Servlet API on each template processing request:</p>
|
| <table>
|
| <tr>
|
|
|
| <td bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Context Key
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Class
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Remarks
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $request
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| javax.servlet.http.HttpServletRequest
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| the current servlet request
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $session
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| javax.servlet.http.HttpSession
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| the current session, if one exists
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $application
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| javax.servlet.ServletContext
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| the servlet context
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $response
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| javax.servlet.http.HttpServletResponse
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| the current servlet response
|
| </font>
|
| </td>
|
|
|
| </tr>
|
|
|
| </table>
|
| <br clear="all"/>
|
| <p>The following examples illustrates how servlet resources are |
| accessed from within Velocity template. The example renders |
| the list of HTTP header fields of the current servlet request. |
| In the same way, any public method of the above listed objects can |
| be called from within templates:</p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode>#foreach( $header in $request.HeaderNames ) |
| <b>$header:</b> $request.getHeader($header)<br> |
| #end</sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>The resulting output is something like this:</p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode><b>Referer:</b> http://localhost:8080/struts/doc/examples.html |
| <b>Connection:</b> Keep-Alive |
| <b>User-Agent:</b> Mozilla/4.79 [en] (Windows NT 5.0; U) |
| <b>Pragma:</b> no-cache |
| <b>Host:</b> localhost:8080 |
| <b>Accept:</b> image/gif, image/jpeg, image/pjpeg, image/png, */* |
| <b>Accept-Encoding:</b> gzip |
| <b>Accept-Language:</b> en |
| <b>Accept-Charset:</b> iso-8859-1,*,utf-8 |
| <b>Cookie:</b> JSESSIONID=aaaecXd7bnLPAr |
| </sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <br clear="all"/>
|
|
|
| </td>
|
| </tr>
|
| </table>
|
| <table border="0" cellspacing="0" cellpadding="2" width="100%">
|
| <tr>
|
| <td colspan="2" bgcolor="#828DA6">
|
| <font color="#ffffff" face="arial,helvetica.sanserif">
|
| <a name="Access to Struts Framework Resources">
|
| <strong>Access to Struts Framework Resources</strong></a></font>
|
| </td>
|
| </tr>
|
| <tr>
|
| <td NOWRAP> </td>
|
| <td>
|
| <p>The Struts framework provides resources that |
| are useful to template designers. These include logical names for |
| physical resources, internationalized messages, error handling, |
| form handling, etc. The interesting question is now how template |
| designers can gain access these framework resources. In the JSP world, a set |
| of custom tag libraries provide template |
| designers access to the Struts framework resources. In the Velocity |
| world, the equivalent of the JSP custom tag libraries are <b>view |
| tools</b>. View tools are a very simple concept. They are Java objects |
| with public methods that are put into the Velocity context. Tools are |
| accessed by key and allows template designers to call on their public methods.</p>
|
| <p>A set of seven view tools is included with VelocityStruts |
| that provide template designers access to Struts framework resources. |
| These seven view tools essentially achieve the integration between |
| Struts and Velocity and they can be considered the core of this |
| project.</p>
|
| <table>
|
| <tr>
|
|
|
| <td bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Context Key
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Class
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Remarks
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $text
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| <a href="MessageTool.html">MessageTool</a>
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Provides access to the Struts application resources for internationalized text.
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $errors
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| <a href="ErrorsTool.html">ErrorsTool</a>
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Provides methods to check for and output Struts error messages.
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $messages
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| <a href="ActionMessagesTool.html">ActionMessagesTool</a>
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Provides methods to work with Struts action messages.
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $link
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| <a href="StrutsLinkTool.html">StrutsLinkTool</a>
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Provides methods to work with URIs.
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $form
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| <a href="FormTool.html">FormTool</a>
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Provides miscellaneous methods to work with forms and form |
| beans in the context of Struts applications.
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $tiles
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| <a href="TilesTool.html">TilesTool</a>
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Provides miscellaneous methods to work with Tiles in the |
| context of Struts applications.
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| $validator
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| <a href="ValidatorTool.html">ValidatorTool</a>
|
| </font>
|
| </td>
|
|
|
| <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Provides methods to dynamically generate javascript validation |
| in the context of Struts applications.
|
| </font>
|
| </td>
|
|
|
| </tr>
|
| <tr>
|
|
|
| <td bgcolor="#a0ddf0" colspan="3" rowspan="" valign="top" align="left">
|
| <font color="#000000" size="-1" face="arial,helvetica,sanserif">
|
| Note: The shown keys are the recommended values. |
| They can be changed in the configuration.
|
| </font>
|
| </td>
|
|
|
| </tr>
|
|
|
| </table>
|
| <p>The following example illustrates some of the features of the MessageTool |
| for working with internationalized messages. For the example we assume that |
| the Struts message resources contain the following two key=value pairs:</p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode> |
| title=Struts Example Application |
| test=This string has 4 replacement parameters: {1}, {2}, {3}, {4} |
| foo.bar=whatever |
| </sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>Then, the following script...</p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode> |
| $text.title |
| $text.get('test', ['bear', 'dog', 'cat']) |
| $text.exists('tutle') |
| $text.foo.bar |
| </sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>..will produce this output:</p>
|
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000">
|
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF">
|
| <pre><sourcecode> |
| Struts Example Application |
| This string has 4 replacement parameters: bear, dog, cat, {4} |
| false |
| whatever |
| </sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>Please see the <a href="StrutsTools.html">Tool Reference Documentation</a> |
| for more details about the view tools. Furthermore, the Velocity/Struts |
| <a href="index.html#Download">example application</a> comes with several |
| working examples that show how these tools are used.</p>
|
| <br clear="all"/>
|
|
|
| </td>
|
| </tr>
|
| </table>
|
| <br clear="all"/>
|
|
|
| </td>
|
| </tr>
|
| </table>
|
|
|
| </td>
|
|
|
| </tr>
|
|
|
| <!-- FOOTER SEPARATOR -->
|
| <tr>
|
| <td colspan="2">
|
| <hr noshade="" size="1"/>
|
| </td>
|
| </tr>
|
|
|
| <!-- PAGE FOOTER -->
|
| <tr><td colspan="2">
|
| <div align="center"><font color="#525D76" size="-1"><em>
|
| Copyright © 1999-2003, Apache Software Foundation
|
| </em></font></div>
|
| </td></tr>
|
|
|
| </table>
|
| </body>
|
| </html>
|