<html> | |
<head> | |
<title>VelocityStruts - FormTool</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="FormTool Reference Documentation"> | |
<strong>FormTool Reference Documentation</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p>Struts has support to parse incoming HTTP requests and populate a Java bean | |
with the submitted request parameters. The same Java bean is used to populate | |
forms with initial values. Additionally, a hook allows the application developer | |
to include automatic form validation code.</p> | |
<p>FormTool provides miscellaneous methods to work with forms and form bean in | |
the context of Struts applications.</p> | |
<table cellpadding="0" cellspacing="0"> | |
<tr><td colspan="2"><strong>Class</strong></td></tr> | |
<tr><td> </td><td>org.apache.velocity.tools.struts.FormTool</td></tr> | |
<tr><td colspan="2"><strong>Name</strong></td></tr> | |
<tr><td> </td><td>$form (this is the recommended name of the tool in | |
the Velocity context)</td></tr> | |
<tr><td colspan="2"><strong>Toolbox Configuration Example</strong></td></tr> | |
<tr><td> </td><td><pre><tool> | |
<key>form</key> | |
<scope>request</scope> | |
<class>org.apache.velocity.tools.struts.FormTool</class> | |
</tool></pre></td></tr> | |
<tr><td colspan="2"><strong>Author(s)</strong></td></tr> | |
<tr><td> </td><td><a href="mailto:sidler@teamup.com">Gabriel Sidler</a><br></td></tr> | |
</table> | |
<dl> | |
<dt><strong>Method Overview</strong></dt> | |
<dd> | |
<table cellpadding="2" cellspacing="2" border="0"> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#getBean()">getBean()</a></td> | |
<td bgcolor="EEEEEE"> | |
Retrieve and return the form bean associated with this request. | |
</td> | |
</tr> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#getCancelName()">getCancelName()</a></td> | |
<td bgcolor="EEEEEE"> | |
Returns the query parameter name under which a cancel button press | |
must be reported if form validation is to be skipped. | |
</td> | |
</tr> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#getName()">getName()</a></td> | |
<td bgcolor="EEEEEE"> | |
Returns the form bean name associated with this action mapping. | |
</td> | |
</tr> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#getToken()">getToken()</a></td> | |
<td bgcolor="EEEEEE"> | |
Retrieves and returns the transaction control token for this session. | |
</td> | |
</tr> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#getTokenName()">getTokenName()</a></td> | |
<td bgcolor="EEEEEE"> | |
Returns the query parameter name under which a transaction token | |
must be reported. | |
</td> | |
</tr> | |
</table> | |
</dd> | |
</dl> | |
</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="getBean()"> | |
<strong>getBean()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Retrieve and return the form bean associated with this request. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
ActionForm getBean() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
The <code>ActionForm</code> associated with this request/session or | |
<code>null</code> if there is no form bean associated with this mapping. | |
</returns> | |
</dd> | |
</dl> | |
<p>This is a convenience method. The form bean is automatically | |
available in the Velocity context under the name defined in the | |
Struts configuration.</p> | |
<p>If the form bean is used repeatedly, it is recommended to create a | |
local variable referencing the bean rather than calling getBean() | |
multiple times.</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>## Populating an input field with a default value | |
<input type="text" name="username" value="$form.getBean().username"> | |
## The same can be written as | |
<input type="text" name="username" value="$form.bean.username"> | |
## For repeated use create a local reference | |
#set ($defaults = $form.bean) | |
<input type="text" name="username" value="$defaults.username"> | |
## Accessing the form using the form name defined in struts-config.xml | |
## Velocity searches the request and session attributes for loginForm | |
<input type="text" name="username" value="$loginForm.username"></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="getCancelName()"> | |
<strong>getCancelName()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Returns the query parameter name under which a cancel button press | |
must be reported if form validation is to be skipped. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
String getCancelName() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
The value of <code>org.apache.struts.taglib.html.Constants.CANCEL_PROPERTY</code> | |
</returns> | |
</dd> | |
</dl> | |
<p>If a request contains a request parameter with key equal to the return value | |
of this method, then automatic form validation is skipped. A typical application | |
case is to use this magic string for the name attribute of a cancel button in a form. | |
If this button is pressed, automatic form validation is skipped. If automatic form | |
validation is not used, this magic string is irrelevant.</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>## A cancel button | |
<input type="submit" name="$form.getCancelName()" value="Cancel"> | |
## Can also be written as | |
<input type="submit" name="$form.cancelName" value="Cancel"></sourcecode></pre> | |
</td></tr></table> | |
</td></tr></table> | |
<p>This produces the following 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><input type="submit" name="org.apache.struts.taglib.html.CANCEL" | |
value="Cancel"></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="getName()"> | |
<strong>getName()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Returns the form bean name associated with this action mapping. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
String getName() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
The name of the ActionForm associated with this request or | |
<code>null</code> if there is no form bean associated with this mapping. | |
</returns> | |
</dd> | |
</dl> | |
<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="getToken()"> | |
<strong>getToken()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Retrieves and returns the transaction control token for this session. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
String getToken() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
The token <code>String</code> or <code>null</code> if no token exists. | |
</returns> | |
</dd> | |
</dl> | |
<dl> | |
<dt><strong>See Also</strong></dt> | |
<dd> | |
<see> | |
Method <a href="#getTokenName()"><code>getTokenName()</code></a> for examples. | |
</see> | |
</dd> | |
</dl> | |
<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="getTokenName()"> | |
<strong>getTokenName()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Returns the query parameter name under which a transaction token | |
must be reported. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
int getTokenName() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
The value of <code>org.apache.struts.taglib.html.Constants.TOKEN_KEY</code> | |
</returns> | |
</dd> | |
</dl> | |
<dl> | |
<dt><strong>See Also</strong></dt> | |
<dd> | |
<see> | |
<a href="http://jakarta.apache.org/struts/api/org/apache/struts/action/Action.html"> | |
JavaDoc of class <code>org.apache.struts.action.Action</code></a> for more information on the | |
transaction token mechanism (I don't know of any better documentation of this Struts | |
feature). | |
</see> | |
</dd> | |
</dl> | |
<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>## A hidden form field with the transaction token | |
<input type="hidden" name="$form.getTokenName()" | |
value="$form.getToken()"> | |
## Can also be written as | |
<input type="hidden" name="$form.tokenName" | |
value="$form.token"></sourcecode></pre> | |
</td></tr></table> | |
</td></tr></table> | |
<p>This produces output similar to:</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><input type="hidden" name="org.apache.struts.taglib.html.TOKEN" | |
value="84c29b4dea56ecf69524ef6b965c5e80"></sourcecode></pre> | |
</td></tr></table> | |
</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> |