Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## Using Localized Data

> JavaServer Faces applications make use of three different kinds of data that can be localized:

> - Static text, such as labels, alternative text, and tool tips
> - Error messages, such as those displayed when validation of user input data fails
> - Dynamic data, which is data that must be set dynamically by server-side objects, such as by backing beans

> This section discusses how to access the first two kinds of data from the page. Performing Localization (page 392) explains how to produce localized error messages as well as how to localize dynamic data. If you are not familiar with the basics of localizing web applications, see Chapter 14.

> All data in the Duke's Bookstore application have been localized for Spanish, French, German, and American English. The image map on the first page allows you to select your preferred locale. See Chapter 12 for information on how the image map custom component was created.

> All the localized data is stored in resource bundles, which are represented as either `ResourceBundle` classes or text files, usually with the extension `.properties`. For more information about resource bundles, see

>     http://java.sun.com/docs/books/tutorial/i18n/index.html

> After the application developer has produced a resource bundle, the application architect puts it in the same directory as the application classes. The static text data for the Duke's Bookstore application is stored in a `ResourceBundle` class called `BookstoreMessages`. The error messages are stored in another resource bundle called `ApplicationMessages`. After the resource bundles have been created and before their data can be accessed, they must be made available to the application, as explained in the following section.

> ### Loading a Resource Bundle

> To reference error messages or static data from the page, you first need to make available the resource bundle containing the data.

> To make available resource bundles that contain static data, you need to do one of two things:

> - Register the resource bundle with the application in the configuration file using the `resource-bundle` element, as explained in Registering Custom Localized Static Text (page 462).
> - Load the resource bundle into the current view using the `loadBundle` tag.

> Here is an example `loadBundle` tag from `bookstore.jsp`:

>     <f:loadBundle var="bundle"
>       basename="messages.BookstoreMessages" />

> The `basename` attribute value specifies the fully-qualified class name of the `ResourceBundle` class, which in this case is located in the `messages` package of the `bookstore` application.

> The `var` attribute is an alias to the `ResourceBundle` class. This alias can be used by other tags in the page in order to access the localized messages.

> In the case of resource bundles that contain error messages, you need to register the resource bundle with the application in the configuration file using the `message-bundle` element, as explained in Registering Custom Error Messages (page 461). One exception is if you are referencing the error messages from the input component attributes described in Referencing Error Messages. In that case, you load the resource bundles containing these messages in the same way you load resource bundles containing static text.

> ### Referencing Localized Static Data

> To reference static localized data from a resource bundle, you use a value expression from an attribute of the component tag that will display the localized data. You can reference the message from any component tag attribute that is enabled to accept value expressions.

> The value expression has the notation "`var.message`", in which `var` matches the `var` attribute of the `loadBundle` tag or the var element in the configuration file, and `message` matches the key of the message contained in the resource bundle, referred to by the `var` attribute. Here is an example from `bookstore.jsp`:

>     <h:outputText value="#{bundle.Talk}"/>

> Notice that `bundle` matches the `var` attribute from the `loadBundle` tag and that `Talk` matches the key in the `ResourceBundle`.

> Another example is the `graphicImage` tag from `chooselocale.jsp`:

>     <h:graphicImage id="mapImage" url="/template/world.jpg"
>       alt="#{bundle.ChooseLocale}"
>       usemap="#worldMap" />

> The `alt` attribute is enabled to accept value expressions. In this case, the `alt` attribute refers to localized text that will be included in the alternative text of the image rendered by this tag.

> See Creating Custom Component Classes (page 427) and Enabling Component Properties to Accept Expressions (page 433) for information on how to enable value binding on your custom component's attributes.

> ### Referencing Error Messages

> A JavaServer Faces page uses the `message` or `messages` tags to access error messages, as explained in Displaying Error Messages with the message and messages Tags.

> The error messages that these tags access include:

> - The standard error messages that accompany the standard converters and validators that ship with the API. See section 2.5.4 of the JavaServer Faces specification, version 1.2, for a complete list of standard error messages.
> - Custom error messages contained in resource bundles registered with the application by the application architect using the `message-bundle` element in the configuration file.
> - Custom error messages hardcoded in custom converter and validator classes.

> When a converter or validator is registered on an input component, the appropriate error message is automatically queued on the component.

> A page author can override the error messages queued on a component by using the following attributes of the component's tag:

> - `converterMessage`: References the error message to display when the data on the enclosing component can not be converted by the converter registered on this component.
> - `requiredMessage`: References the error message to display when no value has been entered into the enclosing component.
> - `validatorMessage`: References the error message to display when the data on the enclosing component cannot be validated by the validator registered on this component.

> All three attributes are enabled to take literal values and value expressions. If an attribute uses a value expression, this expression references the error message in a resource bundle. This resource bundle must be made available to the application in one of the following ways:

> - By the page author using the `loadBundle` tag
> - By the application architect using the `resource-bundle` element in the configuration file.

> Conversely, the `message-bundle` element must be used to make available to the application those resource bundles containing custom error messages that are queued on the component as a result of a custom converter or validator being registered on the component.

> The `bookcashier.jsp` page includes an example of the `requiredMessage` attribute using a value expression to reference an error message:

>     <h:inputText id="ccno" size="19"
>       required="true"
>       requiredMessage="#{customMessages.ReqMessage}" >
>       ...
>     </h:inputText>
>     <h:message styleClass="error-message"  for="ccno"/>

> The value expression that `requiredMessage` is using in this example references the error message with the `ReqMessage` key in the resource bundle, `customMessages`.

> This message replaces the corresponding message queued on the component and will display wherever the `message` or `messages` tag is placed on the page.

> See Registering Custom Error Messages (page 461) and Registering Custom Localized Static Text (page 462) for information on how to use the `message-bundle` and `resource-bundle` element to register resource bundles that contain error messages.