Displays error messages that occur during a form submission.
Class Name |
|
---|---|
Component |
|
Required Input Parameters
None
Optional Input Parameters
exceptions
Holds a vector of DropletExceptions
. If omitted, ErrorMessageForEach
uses the list of all exceptions that occurred in this request.
messageTable
Holds a text string that is a mapping of exceptions to error messages. If omitted, ErrorMessageForEach
determines the message to use as described previously.
propertyNameTable
Holds a text string that is a mapping of property names to text strings. If omitted, ErrorMessageForEach
determines the text string to use as described previously.
Output Parameters
message
An error message that maps to the exception’s errorCode
property. This parameter is set once for each exception in the input vector.
propertyName
A text string that maps to the exception’s propertyName
property. This parameter is set once for each exception in the input vector.
Open Parameters
output
Rendered once for each element in the vector of exceptions.
outputStart
If the vector of exceptions is not empty, rendered once before the output
parameter is rendered.
outputEnd
If the vector of exceptions is not empty, rendered once after the output
parameter is rendered for each exception.
empty
Rendered if the vector of exceptions contains no elements.
Usage Notes
ErrorMessageForEach takes a vector of form exceptions and, for each exception, displays an appropriate error message. The exceptions are of class atg.droplet.DropletException
, or a subclass of this class.
The vector of exceptions can be passed automatically by the request that produces the exceptions, or specified explicitly using the exception’s input parameter. For example, any form handler of class atg.droplet.GenericFormHandler
(or a subclass of this class) has a formExceptions
property, which is a vector of the exceptions that occurred during form processing. To pass these exceptions to ErrorMessageForEach , you can use a tag like this:
<dsp:param name="exceptions" bean="MyFormHandler.formExceptions"/>
For each exception, ErrorMessageForEach displays the message associated with that exception’s errorCode
property. For example, if the value of an exception’s errorCode
property is invalidPassword
, ErrorMessageForEach displays the message associated with invalidPassword
. The messages are stored in tables of key/value pairs, where the keys contain error codes and the corresponding values hold user-friendly messages. For example, the entry for invalidPassword
might look like this:
invalidPassword=Your password is incorrect.
Messages can be specified in several ways. ErrorMessageForEach searches for a key that matches errorCode
in the following areas, listed in order of precedence:
The servlet bean’s
messageTable
Input ParametersThe servlet bean’s
messageTable
propertyThe resource bundle specified by servlet bean’s
resourceName
property
If ErrorMessageForEach fails to find the key , it displays the message produced by the exception itself. The vector of exceptions is preserved across redirects, so you can redirect the user to a separate page that displays the errors.
If you specify messages using the messageTable
input parameter or the messageTable
property, use a comma to separate entries. In order to embed a comma in the message itself, enter two consecutive commas. In the following example, two messages are passed in using the messageTable
input parameter:
<dsp:param name="messageTable"
value="invalidPassword=Your password is incorrect., invalidLogin=Your
user name is incorrect. For assistance,, click Help."/>
By default, the messageTable
property is null, so the messages are taken from the resource specified by the resourceName
property. The default resource bundle is atg.droplet.ErrorMessageResources
, and the messages are stored in the ErrorMessageResources.properties
file. This file contains messages for error codes commonly produced by the ATG platform.
Some exceptions passed to the servlet bean can be of class DropletFormException
, which is a subclass of the DropletException
class. In addition to an errorCode
property, a DropletFormException
also has a propertyName
property that stores the name of the property in the form handler that triggered the exception. This propertyName
value can be mapped to a text string, which is passed to the error message through a parameter. For example, if the user leaves a required text field empty, the error message might be:
missingRequiredValue=Must supply a value for the param:propertyName field.
ErrorMessageForEach replaces param:propertyName
with the text associated with the exception’s propertyName
property. For example, if the value of the propertyName
property is login
, ErrorMessageForEach displays the text associated with login
. As with the error messages themselves, these texts are stored in tables of key/value pairs, with the keys being the exceptions’ propertyName
properties and the values being the texts that are mapped to those keys. For example, a table of these texts might look like this:
login=user name,
password=PIN code,
address=home address
ErrorMessageForEach searches for a key that matches the propertyName
in the following areas, listed in order of precedence:
The servlet bean’s
propertyNameTable
Input ParametersThe servlet bean’s
propertyNameTable
propertyThe resource bundle specified by servlet bean’s
resourceName
property
If ErrorMessageForEach fails to find the key, it displays the value of propertyName
itself. By default, the propertyNameTable
property is null, and no mappings are defined in the ErrorMessageResources.properties
file. Unless you define the mappings yourself, the propertyName
value is displayed.
You can use any of the mechanisms described above to extend or modify the messages that ErrorMessageForEach displays. For localization purposes, you can define your own resource bundles, and use these resource bundles to specify the messages and propertyName
parameter values. You can create resource bundles in multiple languages, and have ErrorMessageForEach display different messages depending on the user’s locale. For more information about resource bundles, see the InternationalizingaDynamoWebSite chapter of the ATG Programming Guide.
While you can use resource bundles to define the message text and the propertyName values, you cannot use them to supply other arguments that are replaced by actual values because ErrorMessageForEach cannot retrieve these arguments from the DropletFormException. For example, you might want to display the following error message when a new user enters a login name that is already in use:
Login name {MGarcia} already in use; please choose another login name
In this situation, you can use the resource bundle to supply the static message text, but ErrorMessageForEach cannot replace the login name argument with an actual value. One alternative is to use ForEach rather than ErrorMessageForEach and display the default message from the DropletException. In an internationalized Web site, the form handler defines localized versions of all messages and displays the appropriate version according to the locale of the current request.
Example
The following example displays a list of exceptions that can occur in a form submission. The Switch servlet bean at the start determines whether there were any form errors. The exceptions parameter of the ErrorMessageForEach points to the formExceptions
property of the Survey component. The value of the messageTable
parameter provides two error messages that can be displayed for different errors.
<dsp:droplet name="/atg/dynamo/droplet/Switch"> <dsp:param bean="Test.formError" name="value"/> <dsp:oparam name="true"> <h2>The following Errors were found in your survey</h2> <dsp:droplet name="/atg/dynamo/droplet/ErrorMessageForEach"> <dsp:param name="exceptions" bean="Survey.formExceptions"/> <dsp:param name="messageTable" value="missingRequiredField=You did not answer all the survey questions, oneWordCheckFailed=You did not provide a single word to describe your interests"/> <dsp:oparam name="output"> <b> <dsp:valueof param="message"/> </b> <p> </dsp:oparam> </dsp:droplet> <P> <P> </dsp:oparam> </dsp:droplet>