ADF skinning and resources

With my current, ADF Faces 11g, project, we have a requirement that the default text in the error message box is customized. Instead of ‘Messages for this page are listed below.’ it should read some other text. When you talk about customization you say ‘skinning’. Skinning allows you to customize the userinterface, i.e. change the look and feel of the standard components. But besides the looks, it also allows you to change the default text messages that are sometimes included with the component.

The af:messages component presents errors and other messages in a comprehensible way to the users. It’s as easy as to put <af:messages id=”m1″ /> in the .jspx page and you’re done:

Now, let’s see how we can change the default texts like ‘Messages for this page are listed below.’ and ‘OK’…

For demonstration purposes, we use simple ADF Faces page, based on the HR.employees table. The Employees has been dropped as an ADF Form with Navigation Controls and a submit button. We can test the messages by clearing two required fields like lastname and email and then press submit.

Changing the default text is actually quite easy and well documented in the ADF manuals:

1. Create the resourcebundle class, e.g. nl.amis.demo.cm.resources.MyMessageBundle. Extend from java.util.ListResourceBundle and override the getContents() method that provides the skin selector and the new text (see below).
2. Create an (empty, but required) skin css file, e.g. skins/myskin.css
3. Create WEB-INF\trinidad-skins.xml and add the skin and include the resourcebundle (bundle-name):

  <skin>
    <id>myskin.desktop</id>
    <family>myskin</family>
    <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
    <bundle-name>nl.amis.demo.cm.resources.MyMessageBundle</bundle-name>
    <style-sheet-name>skins/myskin.css</style-sheet-name>
  </skin>

4. Define the skin in the trinidad-config.xml : <skin-family>myskin</skin-family>
5. Run the application

The challenge is to find the correct skin selector. You can find the whole list in the JDeveloper Help Center (-> Designing and Developing Applications -> Developing Oracle ADF Applications ->Oracle ADF Faces Skin Selectors). Search for messages (yes, plural because we use the af_messages component) and you’ll find a list of icon (style) selectors for the skin css and some Resource Strings. You can override all these resources, just add the one you like to the resourcebundle class. In our case we override the label_combined_message_intro for the header text and the label_ok for the text on the ok button:

  @Override
  protected Object[][] getContents()
    return new Object[][]
      {
        {"af_messages.LABEL_COMBINED_MESSAGES_INTRO", "This is all what you did wrong :"},
        {"af_dialog.LABEL_OK", "I'll do better"},
      };
  }

If you now run the application, you’ll notice that the text of the OK button has changed and hopefully the default intro tekst too. If the latter didn’t change, clear your browser cache and run again. It took me ages to find that out :-(.

By the way, the intro text can also be changed with the attribute message and the text on top, Error, can be changed with the attribute text of the <span af:messages component.

Now, one of the great advantages of using the resourcebundle is that you can easily make it multilingual. Copy the resourcebundle class for every language you need and extend the name with the language code (e.g. nl for Dutch, fr for French etc.), like MyMessageBundle_nl and provide the right translations. Now define all the languages that you support in the faces-config.xml:

  <locale-config>
    <default-locale>en</default-locale>
    <supported-locale>nl</supported-locale>
  </locale-config>

Run the application again, switch the browser language (FireFox -> Tools -> Options -> Content -> Choose Languages and move the preferred language to the top and reload the page or use for example the Quick Locale Switcher add-on) and notice the difference.