5.4 Defining Attribute Control Hints

One of the many powerful, built-in features of the ADF Business Components is the ability to define control hints on attributes. Control hints are additional attribute settings that the view layer can use to automatically display the queried information to the user in a consistent, locale-sensitive way. JDeveloper manages storing the hints in a way that is easy to localize for multi-lingual applications.

5.4.1 How to Add Attribute Control Hints

To add attribute control hints for the attributes of the UserList view object, open the View Object Editor and expand the Attributes node in the left-side tree to reveal the list of the view object's attributes. As shown in Figure 5-13, by selecting a particular attribute name like UserId and selecting the Control Hints tab, you can enter a value for its Label Text hint like "Id". You can also set the Format Type to Number, and enter a Format mask of 00000. You could select the other attributes in turn to define Label Text hints like "Email Address", "Given Name", and "Surname" for the Email, FirstName, and LastName attributes respectively.

Note: Java defines a standard set of format masks for numbers and dates that are different from those used by the Oracle database's SQL and PL/SQL languages. For reference, see the Javadoc for the java.text.DecimalFormat and java.text.SimpleDateFormat classes.

Figure 5-13 Setting UI Control Hints for View Object Attributes

5.4.2 What Happens When You Add Attribute Control Hints

When you define attribute control hints for a view object, JDeveloper creates a standard Java message bundle file in which to store them. The file is specific to the view object component to which it's related, and it is named accordingly. For the UserList view object in the devguide.examples package, the message bundle file created will be named UserListRowImplMsgBundle.java and it will be created in the devguide.examples.common subpackage. By selecting the UserList component in the Application Navigator, you'll see that this new file gets added to the Sources folder in the Structure window that shows the group of implementation files for each business component. Example 5-3 shows how the control hint information appears in the message bundle file. The first entry in each String array is a message key; the second entry is the locale-specific String value corresponding to that key.

Example 5-3 View Object Component Message Bundle Class Stores Locale-Sensitive Control Hints

package devguide.examples.common;
import oracle.jbo.common.JboResourceBundle;
// ---------------------------------------------------------------------
// ---    File generated by Oracle ADF Business Components Design Time.
// ---------------------------------------------------------------------
public class UsersRowImplMsgBundle extends JboResourceBundle {
  static final Object[][] sMessageStrings = 
  {
    { "UserId_LABEL", "Id" },
    { "UserId_FMT_FORMATTER", "oracle.jbo.format.DefaultNumberFormatter" },
    { "UserId_FMT_FORMAT", "00000" },
    { "Email_LABEL", "Email Address" },
    { "FirstName_LABEL", "Given Name" },
    { "LastName_LABEL", "Surname" }
  };

5.4.3 What You May Need to Know About Message Bundles

Internationalizing the model layer of an application built using ADF Business Components entails producing translated versions of each component message bundle file. For example, the Italian version of the UsersRowImplMsgBundle message bundle would be a class named UsersRowImplMsgBundle_it, and a more specific Swiss Italian version would have the name UsersRowImplMsgBundle_it_ch. These classes typically extend the base message bundle class, and contain entries for the message keys that need to be localized, together with their localized translation. For example, assuming you didn't want to translate the number format mask for the Italian locale, the Italian version of the UserList view object message bundle would look like what you see in Example 5-4. Notice the overridden getContents() method. It returns an array of messages with the more specific translated strings merged together with those that are not overridden from the superclass bundle. At runtime, the appropriate message bundles are used automatically, based on the current user's locale settings.

Example 5-4 Localized View Object Component Message Bundle for Italian

package devguide.examples.common;
import oracle.jbo.common.JboResourceBundle;
public class UsersRowImplMsgBundle_it extends UsersRowImplMsgBundle {
  static final Object[][] sMessageStrings = 
  {
    { "UserId_LABEL", "Codice Utente" },
    { "Email_LABEL", "Indirizzo Email" },
    { "FirstName_LABEL", "Nome" },
    { "LastName_LABEL", "Cognome" }  
  };
  // merge this message bundles messages with those in superclass bundle
  public Object[][] getContents() {
    return super.getMergedArray(sMessageStrings, super.getContents());
  }  
}