ClassName |
|
---|---|
Component |
|
The ErrorMessageForEach
servlet bean 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 either 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 property named formExceptions
which is a vector of the exceptions that occurred while processing the form. To pass these exceptions to the ErrorMessageForEach
servlet bean, 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, with the keys being the error codes and the values being user-friendly message texts that are mapped to those keys. For example, the entry for invalidPassword
might look like this:
invalidPassword=Your password is incorrect.
Messages can be specified in several different ways. ErrorMessageForEach
looks in the following places (listed in order of precedence) until it finds a key that matches the errorCode
:
the servlet bean’s
messageTable
input parameterthe servlet bean’s
messageTable
propertythe resource bundle specified by servlet bean’s
resourceName
property
If ErrorMessageForEach
does not find the key in any of these places, 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. To include a comma in a message, enter two consecutive commas. In the following example, two messages are passed in using the messageTable
input parameter; the second message includes a comma:
<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 bundle 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 of the 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
looks in the following places (listed in order of precedence), until it finds a key that matches the propertyName
:
the servlet bean’s
propertyNameTable
input parameterthe servlet bean’s
propertyNameTable
propertythe resource bundle specified by servlet bean’s
resourceName
property
If ErrorMessageForEach
does not find the key in any of these places, 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.
Note: 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 the ErrorMessageForEach
servlet bean cannot retrieve these arguments from the DropletFormException
. For example, you 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 the ErrorMessageForEach
servlet bean 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.
Input Parameters
exceptions
This optional parameter holds a vector of DropletExceptions
. If you omit this parameter, ErrorMessageForEach
uses the list of all exceptions that have occurred in this request.
messageTable
This optional parameter holds a text string that is a mapping of exceptions to error messages. If you omit this parameter, ErrorMessageForEach
determines the message to use as described previously.
propertyNameTable
This optional parameter holds a text string that is a mapping of property names to text strings. If you omit this parameter, ErrorMessageForEach
determines the text string to use as described previously.
Output Parameters
message
The error message that maps to the exception’s errorCode
property. This parameter is set once for each exception in the input vector.
propertyName
The 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
This parameter is rendered once for each element in the vector of exceptions.
outputStart
If the vector of exceptions is not empty, this parameter is rendered once, before the output
parameter is rendered.
outputEnd
If the vector of exceptions is not empty, this parameter is rendered once, after the output
parameter is rendered for each exception.
empty
This optional parameter is rendered if the vector of exceptions contains no elements.
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>