Previous Section  < Day Day Up >  Next Section

7.3 Defining Custom Error Messages

As you can see in Figure 7-1, the default error messages that the JSF reference implementation produces are generic. Also, they might differ between JSF implementations, so you'll probably want to define your own messages.

All standard messages are defined as resources of a Java resource bundle, and you can create your own bundle and selectively override the standard messages with your own versions. Your own bundle must be declared in the faces-config.xml file, like this:

<faces-config>

  <application>

    <message-bundle>custMessages</message-bundle>

  </application>

  ...

</faces-config>

The value of the <message-bundle> element is the so-called bundle base name. If you're unfamiliar with resource bundles, don't worry. Even though there's more than one way to make a bundle (as well as to skin a cat), the easiest way is to create a text file that contains all the resources as text strings identified by keys. The name of the file is the base name followed by a .properties extension, and the file must be stored somewhere in the application's classpath. I recommend putting it in the application's WEB-INF/classes directory, because it's always included in the classpath. Here's the sample application's custMessage.properties file with the replacement text for the message generated by the DoubleRangeValidator when the value is below the specified minimum:

javax.faces.validator.DoubleRangeValidator.MINIMUM=Please enter a value greater \

than {0}.

Each message is declared as a key, an equal sign, and a text value. The keys for all standard messages are defined by the JSF specification. They use a long prefix to avoid clashes with other standard messages and application-specific message. For your own message keys, you can use whatever unique string you want, but some kind of prefix is often a good idea for a large application. The value in this case is so long that it doesn't fit on one line, so I use a backslash at the end of the first line to indicate that the value continues on the next line.

Messages often contain placeholders, such as the {0} placeholder in this example. The placeholders for standard message are replaced with real values at runtime, typically representing validator properties, the submitted value, or a component identifier. The placeholder used in this example is replaced with the minimum allowed value.

Be careful with messages that contain single quotes. If the message text contains both a single quote and at least one placeholder, you must double the single quote, e.g., "This value isn'`t larger than {0}". For messages without placeholders, single quotes must not be duplicated, e.g., "Single quote usage isn't consistent".


Two texts can be defined for each message: a summary and a detailed description. The <h:message> and <h:messages> actions shows either one or both depending on which attributes you use, as described in Appendix A. To define the detailed description for a message, use the standard key plus the string "_detail":

javax.faces.validator.DoubleRangeValidator.MINIMUM=Please enter a value greater \

than {0}.

javax.faces.validator.DoubleRangeValidator.MINIMUM_detail=The value you entered \

is smaller than the smallest value allowed
    Previous Section  < Day Day Up >  Next Section