ATG Page Developer's Guide

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:

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:

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>