Using Localized Data

Loading a Resource Bundle

Referencing Localized Static Data

Referencing Error Messages

Using Localized Data

JavaServer Faces applications make use of three different kinds of data that canbe 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 datafrom the page.Performing Localization explains how to produce localized error messages as well ashow to localize dynamic data. If you are not familiar with the basicsof localizing web applications, seeChapter 15, Internationalizing and Localizing Web Applications.

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 youto select your preferred locale. SeeChapter 13, Creating Custom UI Components for information on how theimage map custom component was created.

All the localized data is stored in resource bundles, which are represented aseitherResourceBundle classes or text files, usually with the extension.properties. For moreinformation about resource bundles, seehttp://download.oracle.com/javase/tutorial/i18n/index.html.

After the application developer has produced a resource bundle, the application architect putsit in the same directory as the application classes. The static text datafor the Duke’s Bookstore application is stored in aResourceBundle class calledBookstoreMessages. Theerror messages are stored in another resource bundle calledApplicationMessages. After theresource bundles have been created and before their data can be accessed, theymust 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 needto make available the resource bundle containing the data.

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

• Register the resource bundle with the application in the configuration file using theresource-bundle element, as explained inRegistering Custom Localized Static Text.

• Load the resource bundle into the current view using theloadBundle tag.

Here is an exampleloadBundle tag frombookstore.jsp:

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

Thebasename attribute value specifies the fully-qualified class name of theResourceBundle class, whichin this case is located in themessages package of thebookstore application.

Thevar attribute is an alias to theResourceBundle class. This alias can beused by other tags in the page in order to access thelocalized messages.

In the case of resource bundles that contain error messages, you need toregister the resource bundle with the application in the configuration file using themessage-bundle element, as explained inRegistering Custom Error Messages. One exception is if you are referencingthe error messages from the input component attributes described inReferencing Error Messages. In that case,you load the resource bundles containing these messages in the same way youload resource bundles containing static text.

Referencing Localized Static Data

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

The value expression has the notationvar.message, in whichvar matches thevarattribute of theloadBundle tag or thevar element in the configuration file, andmessage matches the key of the message contained in the resource bundle, referredto by thevar attribute. Here is an example frombookstore.jsp:

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

Notice thatbundle matches thevar attribute from theloadBundle tag and thatTalk matches the key in theResourceBundle.

Another example is thegraphicImage tag fromchooselocale.jsp:

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

Thealt attribute is enabled to accept value expressions. In this case, thealt attribute refers to localized text that will be included in the alternativetext of the image rendered by this tag.

SeeCreating Custom Component Classes andEnabling Component Properties to Accept Expressions for information on how to enable value binding onyour custom component’s attributes.

Referencing Error Messages

A JavaServer Faces page uses themessage ormessages tags to accesserror messages, as explained inDisplaying Error Messages with themessage andmessages 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 themessage-bundle element in the configuration file.

• Custom error messages hard coded in custom converter and validator classes.

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

A page author can override the error messages queued on a component byusing 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. Ifan attribute uses a value expression, this expression references the error message ina resource bundle. This resource bundle must be made available to the applicationin one of the following ways:

• By the page author using theloadBundle tag

• By the application architect using theresource-bundle element in the configuration file

Conversely, themessage-bundle element must be used to make available to the applicationthose resource bundles containing custom error messages that are queued on the componentas a result of a custom converter or validator being registered on thecomponent.

Thebookcashier.jsp page includes an example of therequiredMessage attribute using a valueexpression to reference an error message:

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

The value expression thatrequiredMessage is using in this example references the errormessage with theReqMessage key in the resource bundle,customMessages.

This message replaces the corresponding message queued on the component and will displaywherever themessage ormessages tag is placed on the page.

SeeRegistering Custom Error Messages andRegistering Custom Localized Static Text for information on how to use themessage-bundle andresource-bundle element to register resource bundles that contain error messages.

Copyright © 2010, Oracle and/or its affiliates. All rights reserved.Legal Notices