<html> | |
<head> | |
<title>VelocityStruts - ErrorsTool</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="ErrorsTool Reference Documentation"> | |
<strong>ErrorsTool Reference Documentation</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
This tool deals with Struts error messages. Errors may stem from the validation | |
of a submitted form or from the processing of a request. If there are errors, | |
they are made available to the view to render. A few important aspects about errors | |
are:</p> | |
<ul> | |
<li>Error message strings are looked up in the message resources. Support | |
for internationalized messages is provided.</li> | |
<li>Error messages can have up to five replacement parameters.</li> | |
<li>Errors have an attribute <code>property</code> that describes the category of | |
error. This allows the view designer to place error messages precisely where an | |
error occurred. For example, errors that apply to the entire page can be rendered | |
at the top of the page, errors that apply to a specific input field can be rendered | |
next to this input field. Several methods of this tool provide a parameter | |
<code>property</code> that allows to select a specific category of errors to operate | |
on. Without the <code>property</code> parameter, methods operate on all error messages.</li> | |
</ul> | |
<p>See the Struts User's Guide, section | |
<a href="http://struts.apache.org/struts-doc-1.2.7/userGuide/building_view.html">Building View Components</a> | |
for more information on this topic.</p> | |
<table cellpadding="0" cellspacing="0"> | |
<tr><td colspan="2"><strong>Class</strong></td></tr> | |
<tr><td> </td><td>org.apache.velocity.tools.struts.ErrorsTool</td></tr> | |
<tr><td colspan="2"><strong>Name</strong></td></tr> | |
<tr><td> </td><td>$errors (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>errors</key> | |
<scope>request</scope> | |
<class>org.apache.velocity.tools.struts.ErrorsTool</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="#exist()">exist()</a></td> | |
<td bgcolor="EEEEEE"> | |
Returns <code>true</code> if there are errors queued, otherwise <code>false</code>. | |
</td> | |
</tr> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#getSize()">getSize()</a></td> | |
<td bgcolor="EEEEEE"> | |
Returns the number of error messages queued. | |
</td> | |
</tr> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#getGlobal()">getGlobal()</a></td> | |
<td bgcolor="EEEEEE"> | |
This a convenience method and the equivalent of | |
<code>$errors.get($errors.globalName)</code> | |
</td> | |
</tr> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#getAll()">getAll()</a></td> | |
<td bgcolor="EEEEEE"> | |
Returns a list of localized error messages for all errors queued. | |
</td> | |
</tr> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#get()">get()</a></td> | |
<td bgcolor="EEEEEE"> | |
Returns a list of localized error messages for a particular category | |
of errors. | |
</td> | |
</tr> | |
<tr> | |
<td bgcolor="EEEEEE" nowrap> | |
<a href="#getMsgs()">getMsgs()</a></td> | |
<td bgcolor="EEEEEE"> | |
Renders the queued errors messages. | |
</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="exist()"> | |
<strong>exist()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Returns <code>true</code> if there are errors queued, otherwise <code>false</code>. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
boolean exist() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
boolean exist(String property) | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Parameters</strong></dt> | |
<dd> | |
<dl> | |
<dt>property</dt> | |
<dd> | |
<parameter name="property"> | |
The category of errors to check for. | |
</parameter> | |
</dd> | |
</dl> | |
</dd> | |
</dl> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
<code>true</code> if there are error messages queued. <code>false</code> otherwise. | |
</returns> | |
</dd> | |
</dl> | |
<p>Calling <code>exist()</code> without the <code>property</code> parameter checks for error messages of | |
any category. The <code>property</code> parameter can be used to limit the check to | |
error messages of a specific category.</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>$errors.exist() | |
$errors.exist("password") | |
</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="getSize()"> | |
<strong>getSize()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Returns the number of error messages queued. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
int getSize() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
int getSize(String property) | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Parameters</strong></dt> | |
<dd> | |
<dl> | |
<dt>property</dt> | |
<dd> | |
<parameter name="property"> | |
The category of errors to operate on. | |
</parameter> | |
</dd> | |
</dl> | |
</dd> | |
</dl> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
The number of error messages. | |
</returns> | |
</dd> | |
</dl> | |
<p>Calling <code>getSize()</code> without the <code>property</code> parameter returns the total | |
number of queued error messages. The <code>property</code> parameter can be used to | |
obtain the number of queued error messages for a specific category.</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>$errors.getSize() | |
$errors.size | |
$errors.getSize("password")</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="getGlobal()"> | |
<strong>getGlobal()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
This a convenience method and the equivalent of | |
<code>$errors.get($errors.globalName)</code> | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
List getGlobal() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
A list of all errors stored under the "global" property. | |
</returns> | |
</dd> | |
</dl> | |
<p>See the section on get() for more information.</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="getAll()"> | |
<strong>getAll()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Returns a list of localized error messages for all errors queued. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
List getAll() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
List getAll(String bundle) | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Parameters</strong></dt> | |
<dd> | |
<dl> | |
<dt>bundle</dt> | |
<dd> | |
<parameter name="bundle"> | |
The (non-default) message-resources bundle that holds the error messages. | |
</parameter> | |
</dd> | |
</dl> | |
</dd> | |
</dl> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
If the message resources are lacking an error message for a | |
particular message key, the key itself is used as an error message | |
and a warning is logged. | |
</returns> | |
</dd> | |
</dl> | |
<p>The following example shows a macro to render the error messages:</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>#macro (errorMarkup) | |
#if ($errors.exist()) | |
<ul> | |
#foreach ($e in $errors.all ) | |
<li>$e</li> | |
#end | |
</ul> | |
#end | |
#end</sourcecode></pre> | |
</td></tr></table> | |
</td></tr></table> | |
<p>This produces 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><ul> | |
<li>The field Expiration Date is required.</li> | |
<li>The provided number is not a valid credit card number</li> | |
</ul></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="get()"> | |
<strong>get()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Returns a list of localized error messages for a particular category | |
of errors. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
List get(String property) | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
List get(String property, String bundle) | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Parameters</strong></dt> | |
<dd> | |
<dl> | |
<dt>property</dt> | |
<dd> | |
<parameter name="property"> | |
The category of error messages to return. | |
</parameter> | |
</dd> | |
<dt>bundle</dt> | |
<dd> | |
<parameter name="bundle"> | |
The (non-default) message-resources bundle that holds the error messages. | |
</parameter> | |
</dd> | |
</dl> | |
</dd> | |
</dl> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
A <code>java.util.List</code> of <code>java.lang.String</code>. | |
If no error messages exist for the specified category, | |
<code>null</code> is returned. | |
If the message resources are lacking an error message for a | |
particular message key, the key itself is used as an error message | |
and a warning is logged. | |
</returns> | |
</dd> | |
</dl> | |
<p>The following example shows a macro to render the error messages for a | |
particular category of errors:</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>#macro (errorMarkup $property) | |
#if ($errors.exist($property)) | |
<ul> | |
#foreach ($er in $errors.get($property) ) | |
<li>$er</li> | |
#end | |
</ul> | |
#end | |
#end</sourcecode></pre> | |
</td></tr></table> | |
</td></tr></table> | |
<p>This produces 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><ul> | |
<li>The field Expiration Date is required.</li> | |
<li>The provided number is not a valid credit card number</li> | |
</ul></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="getMsgs()"> | |
<strong>getMsgs()</strong></a></font> | |
</td> | |
</tr> | |
<tr> | |
<td NOWRAP> </td> | |
<td> | |
<p> | |
<abstract> | |
Renders the queued errors messages. | |
</abstract> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
String getMsgs() | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
String getMsgs(String property) | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<p> | |
<table width="100%"><tr><td bgcolor="EEEEEE"> | |
<font size="+1"><code> | |
<signature> | |
String getMsgs(String property, String bundle) | |
</signature> | |
</code></font> | |
</td></tr></table> | |
</p> | |
<dl> | |
<dt><strong>Parameters</strong></dt> | |
<dd> | |
<dl> | |
<dt>property</dt> | |
<dd> | |
<parameter name="property"> | |
The category of errors messages to render. | |
</parameter> | |
</dd> | |
<dt>bundle</dt> | |
<dd> | |
<parameter name="bundle"> | |
The (non-default) message-resources bundle that holds the error messages. | |
</parameter> | |
</dd> | |
</dl> | |
</dd> | |
</dl> | |
<dl> | |
<dt><strong>Returns</strong></dt> | |
<dd> | |
<returns> | |
The formatted error messages. If no errors are queued, an | |
empty <code>String</code> is returned. | |
</returns> | |
</dd> | |
</dl> | |
<p>This method renders the queued error messages as a list. If the method | |
is called without a parameter, all queued errors are rendered. With the | |
parameter <code>property</code> the list of rendered messages can be | |
limited to a specific category of errors. Error message texts | |
are looked up in the message resources. If a message text | |
cannot be found, the message key will be displayed instead.</p> | |
<p>The method expects a message header, a message footer, a message prefix | |
and a message suffix to be defined in the message resources. The corresponding | |
message keys are <code>errors.header</code>, <code>errors.footer</code>, | |
<code>errors.prefix</code> and <code>errors.suffix</code>.</p> | |
<p>Assuming that the message resources contain the following | |
definitions:</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>errors.header=Please correct the following errors before proceeding:<ul> | |
errors.footer=</ul> | |
errors.prefix=<li> | |
errors.suffix=</li> | |
error01=The field Expiration Date is required. | |
error02=The input is not a valid credit card number. | |
...</sourcecode></pre> | |
</td></tr></table> | |
</td></tr></table> | |
<p>an error message would be rendered as follows:</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>Please correct the following errors before proceeding:<ul> | |
<li>The field Expiration Date is required.</li> | |
<li>The input is not a valid credit card number.</li> | |
</ul></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> |