8 Working With Text in an ADF Skin

This chapter describes how to work with text in an ADF skin. Key concepts, such as how the resource strings that ADF Faces components render at runtime are stored in resource bundles, are described in addition to how you can specify additional resource bundles with different resource strings.

This chapter includes the following sections:

8.1 About Working with Text in an ADF Skin

The source file for an ADF skin does not store any text that ADF Faces components render in the user interface of your application. Applications that render ADF Faces components abstract the text that these components render as resource strings and store the resource strings in a resource bundle. For example, Figure 8-1 shows an ADF Faces dialog component that renders buttons with OK and Cancel labels.

Figure 8-1 ADF Faces dialog Component

This image is described in the surrounding text

The text that appears as the labels for these buttons (OK and Cancel) is defined in a resource bundle and referenced by a resource string. If you want to change the text that appears in the button labels, you create a resource bundle where you define the values that you want to appear by specifying alternative text for the following resource strings:

  • af_dialog.LABEL_OK

  • af_dialog.LABEL_CANCEL

Note:

By default, a resource bundle (skinBundle.properties) is created in your project when you create a new ADF skin, as described in Creating an ADF Skin File.

In addition to the resource strings that define the text to appear in the user interface for specific components, there are a range of resource strings that define text to appear that is not specific to any particular component. These resource strings are referred to as global resource strings. For more information about the resource strings for ADF Faces components and global resource strings, see the Tag Reference for Oracle ADF Faces Skin Selectors.

ADF Faces components provide automatic translation. The resource bundle used for the ADF Faces components' skin is translated into 28 languages. If, for example, an end user sets the browser to use the German (Germany) language, any text contained within the components automatically displays in German. For this reason, if you create a resource bundle for a new ADF skin, you must also create localized versions of that resource bundle for any other languages your web application supports.

For more information about creating resource bundles, resource strings, and localizing ADF Faces components, see the "Internationalizing and Localizing Pages" chapter in Developing Web User Interfaces with Oracle ADF Faces.

8.2 Using Text From Your Own Resource Bundle

If you enter alternative text in a resource bundle to override the default text values that render in the user interface of the ADF Faces components in your application, you need to specify this resource bundle for your application. At runtime, the application renders the alternative text in your resource bundle for the resource strings that you override. For resource strings that you do not override, the application renders the text defined in the base resource bundle. For example, Figure 8-4 shows an ADF Faces dialog component where the application developer overrides the default value for the af_dialog.LABEL_OK resource string from OK to Yay while the default value for the af_dialog.LABEL_CANCEL resource string remains unchanged. That is, the application developer did not define a value for the af_dialog.LABEL_CANCEL resource string in a resource bundle; the application references the base resource bundle for this resource string's value.

Figure 8-2 Overridden and Default Values Resource Strings

This image is described in the surrounding text

For more information about how to create a resource bundle and how to define string key values, see the "Internationalizing and Localizing Pages" chapter in Developing Web User Interfaces with Oracle ADF Faces.

8.2.1 How to Specify an Additional Resource Bundle for an ADF Skin

You specify a resource bundle for your ADF skin by adding its name and location as a value to the bundle-name property in the trinidad-skins.xml file.

To specify an additional resource bundle for an ADF skin:

  1. In the Applications window, double-click the trinidad-skins.xml file for your application. By default, this is under the Web Content/WEB-INF node.
  2. In the Structure window, right-click the skin node for which you want to add an additional resource bundle and choose Insert inside skin > bundle-name.
  3. In the Properties window, specify the name and location for your resource bundle as a value for the bundle-name property.

    For example, the resource bundle that is created by default after you create the first ADF skin in your project, as illustrated in Figure 8-3, specifies the following value for the <bundle-name> element:

    <bundle-name>resources.skinBundle</bundle-name>

    Figure 8-3 Default Resource Bundle for an ADF Skin

    This image is described in the surrounding text

8.2.2 What Happens When You Specify an Additional Resource Bundle for an ADF Skin

The trinidad-skins.xml file references the resource bundle that you specified as a value for the bundle-name property, as shown in the following example.

<skin>
    <id>skin1.desktop</id>
    <family>skin1</family>
    <extends>skyros-v1.desktop</extends>
    <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
    <style-sheet-name>skins/skin1/skin1.css</style-sheet-name>
    <bundle-name>resources.skinBundle</bundle-name>
</skin>

At runtime, the application renders text values that you specified in your resource bundle to override the default text values. For example, assume that you defined a resource bundle where you specified Yeah as the value for the af_dialog.LABEL_OK resource sting and Oops as the value for the af_dialog.LABEL_CANCEL. Figure 8-4 shows a dialog component that renders labels using these values.

Figure 8-4 Dialog Rendering Labels Defined in a Custom Resource Bundle

This image is described in the surrounding text