Displays error messages that occur during a form submission.

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:

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:

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 Internationalizing an ATG Web Site chapter of the ATG Platform 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>