Google Git
Sign in
apache / velocity-site / 89c3a15cf30ab2c0dbdf8253ed5c2eb24d9b1e21 / . / tools / 1.2 / struts / userguide.html
blob: 6da9a36721d23cba78035de26f09f47f27b40caf [file] [log] [blame]
<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://jakarta.apache.org/">
<img src="http://jakarta.apache.org/images/jakarta-logo.gif"
align="left" alt="The Jakarta 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> &nbsp; &nbsp; &nbsp; &nbsp; </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://jakarta.apache.org/velocity/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> &nbsp; &nbsp; &nbsp; &nbsp; </td>
<td>
<p>The documentation will explain the steps necessary to
integrate <a href="http://jakarta.apache.org/velocity/">Velocity</a>
with <a href="http://jakarta.apache.org/struts/">Struts</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://jakarta.apache.org/site/mail.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> &nbsp; &nbsp; &nbsp; &nbsp; </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> &nbsp; &nbsp; &nbsp; &nbsp; </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>
&lt;?xml version="1.0"?&gt;
&lt;toolbox&gt;
&lt;tool&gt;
&lt;key&gt;link&lt;/key&gt;
&lt;scope&gt;request&lt;/scope&gt;
&lt;class&gt;org.apache.velocity.tools.struts.StrutsLinkTool&lt;/class&gt;
&lt;/tool&gt;
&lt;tool&gt;
&lt;key&gt;msg&lt;/key&gt;
&lt;scope&gt;request&lt;/scope&gt;
&lt;class&gt;org.apache.velocity.tools.struts.MessageTool&lt;/class&gt;
&lt;/tool&gt;
&lt;tool&gt;
&lt;key&gt;errors&lt;/key&gt;
&lt;scope&gt;request&lt;/scope&gt;
&lt;class&gt;org.apache.velocity.tools.struts.ErrorsTool&lt;/class&gt;
&lt;/tool&gt;
&lt;tool&gt;
&lt;key&gt;form&lt;/key&gt;
&lt;scope&gt;request&lt;/scope&gt;
&lt;class&gt;org.apache.velocity.tools.struts.FormTool&lt;/class&gt;
&lt;/tool&gt;
&lt;tool&gt;
&lt;key&gt;tiles&lt;/key&gt;
&lt;scope&gt;request&lt;/scope&gt;
&lt;class&gt;org.apache.velocity.tools.struts.TilesTool&lt;/class&gt;
&lt;/tool&gt;
&lt;tool&gt;
&lt;key&gt;validator&lt;/key&gt;
&lt;scope&gt;request&lt;/scope&gt;
&lt;class&gt;org.apache.velocity.tools.struts.ValidatorTool&lt;/class&gt;
&lt;/tool&gt;
&lt;/toolbox&gt;
</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> &nbsp; &nbsp; &nbsp; &nbsp; </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> &nbsp; &nbsp; &nbsp; &nbsp; </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>
&lt;HTML&gt;
&lt;BODY&gt;
&lt;h2&gt;Order Confirmation&lt;/h2&gt;
&lt;h3&gt;Delivery Adress:&lt;/h3&gt;&lt;br&gt;
Name: $customer.name&lt;br&gt;
Street: $customer.street&lt;br&gt;
City: $customer.zip $customer.city
&lt;h3&gt;Ordered Items&lt;/h3&gt;&lt;br&gt;
&lt;table&gt;
#foreach( $item in $order.items )
&lt;tr&gt;
&lt;td&gt;$item.quantity&lt;/td&gt;
&lt;td&gt;$item.description&lt;/td&gt;
&lt;/tr&gt;
#end
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;
</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>
&lt;HTML&gt;
&lt;BODY&gt;
&lt;h2&gt;Order Confirmation&lt;/h2&gt;
&lt;h3&gt;Delivery Address:&lt;/h3&gt;&lt;br&gt;
Name: Peter Pan&lt;br&gt;
Street: Crain St. 10&lt;br&gt;
City: 60201 Evanston IL
&lt;h3&gt;Ordered Items&lt;/h3&gt;&lt;br&gt;
&lt;table&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;Hair Dryer, Philips, 1000W, white&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;Kitchen Mixer, Betty Bossy, 240W, black&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;
</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://jakarta.apache.org/velocity/user-guide.html">Velocity User's Guide</a></li>
<li><a href="http://jakarta.apache.org/velocity/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> &nbsp; &nbsp; &nbsp; &nbsp; </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> &nbsp; &nbsp; &nbsp; &nbsp; </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 )
&lt;b&gt;$header:&lt;/b&gt; $request.getHeader($header)&lt;br&gt;
#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> &nbsp; &nbsp; &nbsp; &nbsp; </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 &#169; 1999-2003, Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>