6.5 Defining Attribute Control Hints

With your basic business domain layer of entity objects in place, you can immediately add value by defining UI control hints to ensure that your domain data gets displayed consistently to your end users in locale-sensitive way. JDeveloper manages storing the hints in a way that is easy to localize for multilingual applications. This section explores how to define label text, tooltip, and format mask hints for entity object attributes. As you'll see in Chapter 7, "Building an Updatable Data Model With Entity-Based View Objects", the UI hints you define on your business domain layer are automatically inherited by any entity-based view objects.

6.5.1 How to Add Attribute Control Hints

To add attribute control hints to an entity object, open the Entity Object Editor and expand the Attributes node in the left-side panel to reveal the list of the entity's attributes. Figure 6-12 shows what this would look like for the ServiceRequest entity object. Selecting a particular attribute name like RequestDate and selecting the Control Hints tab, you can set its:

• Label Text hint to "Requested On"

• Tooltip Text hint to "The date on which the service request was created"

• Format Type to Simple Date

• Format mask of MM/dd/yyyy HH:mm

You can select the other attributes in turn to define appropriate control hints for them as well.

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 6-12 Setting UI Control Hints for Label for Format Mask for Entity Object Attributes

6.5.2 What Happens When You Add Attribute Control Hints

When you define attribute control hints for an entity object, JDeveloper creates a standard Java message bundle file in which to store them. The file is specific to the entity object component to which its related, and it is named accordingly. For the ServiceRequest entity in the devguide.model.entities package, the message bundle file created will be named ServiceRequestImplMsgBundle.java and it will be created in the devguide.model.entities.common subpackage. By selecting the ServiceRequest 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 component. Example 6-2 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 6-2 Entity Object Component Message Bundle Class Stores Locale-Sensitive Control Hints

package devguide.model.entities.common;
import oracle.jbo.common.JboResourceBundle;
// ---------------------------------------------------------------------
// ---    File generated by Oracle ADF Business Components Design Time.
// ---------------------------------------------------------------------
public class ServiceRequestImplMsgBundle extends JboResourceBundle {
  static final Object[][] sMessageStrings = {
  { "AssignedDate_FMT_FORMAT", "MM/dd/yyyy HH:mm" },
  { "AssignedDate_FMT_FORMATTER", "oracle.jbo.format.DefaultDateFormatter" },
  { "AssignedDate_LABEL", "Assigned On" },
  { "AssignedTo_LABEL", "Assigned To" },
  { "CreatedBy_LABEL", "Requested By" },
  { "ProblemDescription_DISPLAYWIDTH", "60" },
  { "ProblemDescription_LABEL", "Problem" },
  { "RequestDate_FMT_FORMAT", "MM/dd/yyyy HH:mm" },
  { "RequestDate_FMT_FORMATTER", "oracle.jbo.format.DefaultDateFormatter" },
  { "RequestDate_LABEL", "Requested On" },
  { "RequestDate_TOOLTIP", 
    "The date on which the service request was created" },
  { "Status_LABEL", "Status" },
  { "SvrId_LABEL", "Request" }
  };
// etc.

6.5.3 Internationalizing the Date Format

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 ServiceRequestImplMsgBundle message bundle would be a class named ServiceRequestImplMsgBundle_it and a more specific Swiss Italian version would have the name ServiceRequestImplMsgBundle_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, the Italian version of the ServiceRequest entity object message bundle would look like what you see in Example 6-3. Notice that in the Italian translation, the format masks for the RequestDate and AssignedDate have been changed to dd/MM/yyyy HH:mm. This ensures that an Italian user will see a date value like May 3rd, 2006, as 03/05/2006 15:55, instead of 05/03/2006 15:55, which the format mask in the default message bundle would produce. 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 6-3 Localized Entity Object Component Message Bundle for Italian

package devguide.model.entities.common;
import oracle.jbo.common.JboResourceBundle;
public class ServiceRequestImplMsgBundle_it 
       extends ServiceRequestImplMsgBundle {
  static final Object[][] sMessageStrings = {
    { "AssignedDate_FMT_FORMAT", "dd/MM/yyyy HH:mm" }, 
    { "AssignedDate_LABEL", "Assegnato il" }, 
    { "AssignedTo_LABEL", "Assegnato a" }, 
    { "CreatedBy_LABEL", "Aperto da" }, 
    { "ProblemDescription_LABEL", "Problema" }, 
    { "RequestDate_FMT_FORMAT", "dd/MM/yyyy HH:mm" },
    { "RequestDate_LABEL", "Aperto il" }, 
    { "RequestDate_TOOLTIP", "La data in cui il ticket è stato aperto" },
    { "Status_LABEL", "Stato" }, 
    { "SvrId_LABEL", "Ticket" }
  };
  public Object[][] getContents() {    return super.getMergedArray(sMessageStrings, super.getContents());  }
}