Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31973-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

16 Displaying Tips, Messages, and Help

This chapter describes how to define and display tips and messages for ADF Faces components, and how to provide different levels of help information for users.

This chapter includes the following sections:

16.1 Introduction to Displaying Tips and Messages

ADF Faces provides many different ways for displaying informational text in an application. You can create simple tip text, validation and conversion tip text, validation and conversion failure messages, as well as elaborate help systems.

Many ADF Faces components support the shortDesc attribute, which for most components, displays tip information when a user hovers the cursor over the component. Figure 16-1 shows a tip configured for a toolbar button. For more information about creating tips, see Section 16.2, "Displaying Tips for Components".

Figure 16-1 Tip Displays Information

Tooltip displays information

Along with tips, EditableValueHolder components (such as the inputText component, or the selection components) can display hints used for validation and conversion. When you configure validation or conversion, a default hint automatically displays in a note window (for more information, see Chapter 6, "Validating and Converting Input"). For example, when users click Help > Give Feedback in the File Explorer application, a dialog displays where they can enter a time and date for a customer service representative to call. Because the inputDate component contains a converter, when the user clicks in the field, a note window displays a hint that shows the expected pattern, as shown in Figure 16-2. If the inputDate component was also configured with a minimum or maximum value, the hint would display that information as well. These hints are provided by the converters and validators automatically.

Figure 16-2 Attached Converters and Validators Include Messages

Messages in converters and validators

ADF Faces uses the standard JSF messaging API. JSF supports a built-in framework for messaging by allowing FacesMessage instances to be added to the FacesContext object using the addMessage(java.lang.String clientId, FacesMessage message) method. In general there are two types of messages that can be created: component-level messages, which are associated with a specific component based on any client ID that was passed to the addMessage method, and global-level messages, which are not associated with a component because no the client ID was passed to the addMessage method.When conversion or validation fails on an EditableValueHolder ADF Faces component, FacesMessages objects are automatically added to the message queue on the FacesContext instance, passing in that component's ID. These messages are then displayed in the note window for the component. ADF Faces components are able to display their own messages. You do not need to add any tags.

For example, if a user enters a date incorrectly in the field shown in Figure 16-2, an error message is displayed, as shown in Figure 16-3. Note that the error message appears in the note window along with the hint.

Figure 16-3 Validation and Conversion Errors Display in Note Window

Errors display in note window

If you want to display a message for a non-ADF Faces component, or if you want the message to be displayed inline instead of the note window, use the ADF Faces message component.

Similarly, the document tag handles and displays all global FacesMessages objects (those that do not contain an associated component ID), as well as component FacesMessages. Like component messages, you do not need to add any tags for messages to be displayed. Whenever a global message is created (or more than two component messages), all messages in the queue will be displayed in a popup window, as shown in Figure 16-4.

Figure 16-4 Global and Component Messages Displayed by the Document

Global and component messages

However, you can use the ADF Faces messages component if you want messages to display on the page rather than in a popup window. For more information about displaying hints and messages for components, see Section 16.3, "Displaying Hints and Error Messages for Validation and Conversion".

Tip:

While ADF Faces provides messages for validation and conversion, you can add your own FacesMessages objects to the queue using the standard JSF messaging API. When you do so, ADF Faces will display icons with the message based on the message level, as follows: Message icons

Instead of having each component display its own messages, you can use the panelLabelAndMessage component to group components and display a message in one area. This can be very useful when you have to group components together. For example, the File Explorer application uses a panelLabelAndMessage component where users enter a telephone number. The telephone number input field is actually three separate inputText components. The panelLabelAndMessage component wraps three inputText components. Instead of each having its own label and message, the three have just one label and one message, as shown in Figure 16-3. For more information, see Section 16.4, "Grouping Components with a Single Label and Message".

Instead of configuring messages for individual component instances, you can create a separate help system that provides information that can be reused throughout the application.You create help information using different types of providers, and then reference the help text from the UI components. The following are the three types of help supported by ADF Faces:

16.2 Displaying Tips for Components

ADF Faces components use the shortDesc attribute to display a tip when the user hovers the mouse over the component. Input components display the tips in their note window. Other component types display the tip in a standard tip box. This text should be kept short. If you have to display more detailed information, or if the text can be reused among many component instances, consider using help text, as described in Section 16.5, "Displaying Help for Components".

Figure 16-8 shows the effect when the cursor hovers over an inputText component.

Figure 16-8 Tip for an inputText Component

Tooltip displayed in a browser

Figure 16-9 shows a tip as displayed for a showDetailItem component.

Figure 16-9 Tip for a showDetailItem Component

Tip for command component

16.2.1 How to Display Tips for Components

You use the shortDesc attribute on a component to display a tip.

To define a tip for a component:

  1. In the Structure window, select the component for which you want to display the tip.

  2. In the Property Inspector, expand the Appearance section and enter a value for the shortDesc attribute.

    Tip:

    The value should be less than 80 characters, as some browsers will truncate the tip if it exceeds that length.

    If the text to be used is stored in a resource bundle, use the dropdown list to select Select Text Resource. Use the Select Text Resource dialog to either search for appropriate text in an existing bundle, or to create a new entry in an existing bundle. For more information about using resource bundles, see Chapter 20, "Internationalizing and Localizing Pages".

16.3 Displaying Hints and Error Messages for Validation and Conversion

Validators and converters have a default hint that is displayed to users when they click in the associated field. For converters, the hint usually tells the user the correct format to use. For validators, the hint is used to convey what values are valid.

For example, in the File Explorer application, when a user clicks in the input date field on the Speak with Customer Service page, a tip is displayed showing the correct format to use, as shown in Figure 16-10.

Figure 16-10 Validators and Converters Have Built-in Messages

Message is based on converter pattern

When the value of an ADF Faces component fails validation, or cannot be converted by a converter, the component displays the resulting FacesMessage instance.

For example, entering a date that does not match the dateStyle attribute of the converter results in an error message, as shown in Figure 16-11.

Figure 16-11 Validation Error at Runtime

Validation error displayed in a browser

You can override the default validator and converter hint and error messages. Each ADF Faces validator and converter component has attributes you can use to define the detail messages to be displayed for the user. The actual attributes vary according to the validator or converter. Figure 16-12 shows the attributes that you can populate to override the messages for the convertDateTime converter, as displayed in the Property Inspector.

Figure 16-12 Message Attributes on a Converter

Message attributes for convertDateTime

If you do not want messages to be displayed in the note window, you can use the message component, and messages will be displayed inline with the component. Figure 16-13 shows how messages are displayed using the message component.

Figure 16-13 Use the message Component to Display Messages Inline

Messages displayed inline

JSF pages in an ADF Faces application use the document tag, which among other things, handles displaying all global messages (those not associated with a component) in a popup window. However, if you want to display global messages on the page instead, use the messages component.

16.3.1 How to Define Custom Validator and Converter Messages

To override the default validator and converter messages, set values for the different message attributes.

To define a validator or converter message:

  1. In the Structure window, select the converter or validator for which you want to create the error message.

    Note:

    You can override messages only for ADF Faces components. If you want to create a message for a non-ADF Faces component (for example for the f:validator component), then use the message component. For more information, see Section 16.3.3, "How to Display Component Messages Inline".
  2. In the Property Inspector, expand the Messages section and enter a value for the attribute for which you want to provide a message.

    The values can include dynamic content by using parameter placeholders such as {0}, {1}, {2}, and so on. For example, the messageDetailConvertDate attribute on the convertDateTime converter uses the following parameters:

    • {0} the label that identifies the component

    • {1} the value entered by the user

    • {2}an example of the format expected by the component.

    Using these parameters, you could create this message:

    {1} is not using the correct date format. Please enter the date as follows: {2}. 
    

    The error message would then be displayed as shown in Figure 16-14.

    Figure 16-14 Detail Message at Runtime

    Inline detail message displayed in a browser

    Tip:

    The grey area below the Property Inspector fields provides tag documentation, as shown in Figure 16-12. Refer to this documentation to determine the parameters accepted by the message.

    If the text to be used is stored in a resource bundle, use the dropdown list to select Select Text Resource. Use the Select Text Resource dialog to either search for appropriate text in an existing bundle, or to create a new entry in an existing bundle. For more information about using resource bundles, see Chapter 20, "Internationalizing and Localizing Pages".

    Note:

    The message text is for the detail message of the FacesMessage object. If you want to override the summary (the text shown at the top of the message), you can only do this globally. For more information, see Section 16.3.2, "What You May Need to Know About Overriding Default Messages Globally".

16.3.2 What You May Need to Know About Overriding Default Messages Globally

Instead of changing the message string per component instance with the messageDetail[XYZ] attributes, override the string globally so that the string will be displayed for all instances. To override globally, create a message bundle whose contents contain the key for the message and the message text you wish to use.

You create and use a message bundle in the same way you create and use resource bundles for translation, using either Java classes or properties files. For procedures and information, see Chapter 20, "Internationalizing and Localizing Pages".

For message key information, see Appendix B, "Message Keys for Converter and Validator Messages".

16.3.3 How to Display Component Messages Inline

Instead of having a component display its messages in the note window, use the message component to display the messages inline on the page. In order for the message component to display the correct messages, associate it with a specific component.

To display component messages inline:

  1. In the Structure window, select the component that will display its messages using the message component.

  2. In the Property Inspector, set the ID for component.

  3. From the Component Palette, drag a Message and drop it where you want the message to be displayed on the page.

  4. Use the dropdown list for the for attribute to select Edit.

  5. In the Edit Property dialog, locate the component for which the message component will display messages. Only components that have their ID set are valid selections.

    Note:

    The message icon and message content that will be displayed are based on what was given when the FacesMessage object was created. Setting the messageType or message attributes on the message component causes the messageType or message attribute values to be displayed at runtime, regardless of whether or not an error has occurred. Only populate these attributes if you want the content to always be displayed when the page is rendered.

16.3.4 How to Display Global Messages Inline

Instead of displaying global messages in a popup window for the page, display them inline using the messages component.

  1. From the Component Palette, drag a Messages and drop it onto the page where you want the messages to be displayed.

  2. In the Property Inspector set the following attributes:

    • globalOnly: By default, ADF Faces displays global messages (messages that are not associated with components) followed by individual component messages. If you want to display only global messages in the box, set this attribute to true. Component messages will continue to be displayed with the associated component.

    • inline: Set to true to show messages at the top of the page. Otherwise, messages will be displayed in a dialog.

16.4 Grouping Components with a Single Label and Message

By default, ADF Faces input and select components have built-in support for label and message display. If you want to group components and use a single label, wrap the components using the panelLabelAndMessage component.

For example, the File Explorer application collects telephone numbers using four separate inputText components; one for the area code, one for the exchange, one for the last four digits, and one for the extension. Because a single label is needed, the four inputText components are wrapped in a panelLabelAndMessage component, and the label value is set on that component. However, the input component for the extension requires an additional label, so an outputText component is used. Example 16-1 shows the JSF code for the panelLabelAndMessage component.

Example 16-1 panelLabelAndMessage Can Display a Single Label and Help Topic

<af:panelLabelAndMessage labelAndAccessKey="#{explorerBundle['help.telephone']}"
                         helpTopicId="HELP_TELEPHONE_NUMBER"
                         labelStyle="vertical-align: top;  
                         padding-top: 0.2em;">
  <af:inputText autoTab="true" simple="true" maximumLength="3"
                columns="3">
    <af:convertNumber type="number" integerOnly="true"/>
  </af:inputText>
  <af:inputText autoTab="true" simple="true" maximumLength="3"
                columns="3">
    <af:convertNumber type="number" integerOnly="true"/>
  </af:inputText>
  <af:inputText autoTab="true" simple="true" maximumLength="4"
                columns="4">
    <af:convertNumber type="number" integerOnly="true"/>
  </af:inputText>
  <af:outputText value="#{explorerBundle['help.extension']}"/>
  <af:inputText simple="true" columns="4">
    <af:convertNumber type="number" integerOnly="true"/>
  </af:inputText>
</af:panelLabelAndMessage>

Figure 16-15 shows how the panelLabelAndMessage and nested components are displayed in a browser.

Figure 16-15 Examples Using the panelLabelAndMessage Component

Examples using PanelLabelAndMessage

The panelLabelAndMessage component also includes an End facet that can be used to display additional components at the end of the group. Figure 16-16 shows how the telephone number fields would be displayed if the End facet was populated with an outputText component.

Figure 16-16 End Facet in a panelLabelAndMessage Component

End facet text

Use a panelGroupLayout component within a panelLabelAndMessage component to group the components for the required layout. For information about using the panelGrouplayout component, see Section 8.11, "Grouping Related Items".

You set the simple attribute to true on each of the input components so that their individual labels are not displayed. However, you may want to set a value for the label attribute on each of the components for messaging purposes and for accessibility.

Tip:

If you have to use multiple panelLabelAndMessage components one after another, wrap them inside an af:panelFormLayout component, so that the labels line up properly. For information about using the panelFormLayout component, see Section 8.6, "Arranging Content in Forms".

16.4.1 How to Use a panelLabelAndMessage Component

Group and wrap components using the panelLabelAndMessage component. The panelLabelAndMessage component can be used to wrap any components, not just those that typically display messages and labels.

To arrange form input components with one label and message:

  1. Add a panelLabelAndMessage component to the JSF page by dropping a Panel Label And Message from the Component Palette onto the JSF page.

  2. In the Property Inspector, set the following attributes:

    • label: Enter the label text to be displayed for the group of components.

    • for: Enter the ID of the child input component. If there is more than one input component, enter the ID of the first component.

      Set the for attribute to the first inputComponent to meet accessibility requirements.

    If one or more of the nested input components is a required component and you want a marker to be displayed indicating this, set the showRequired attribute to true.

  3. Add components as child components to the panelLabelAndMessage component.

    For each input and select component:

    • Set the simple attribute to true.

    • For accessibility reasons, set the label attribute to a label for the component.

  4. To place content in the End facet, drag and drop the desired component into the facet.

    Because facets accept one child component only, if you want to add more than one child component, you must wrap the child components inside a container, such as a panelGroupLayout or group component.

    Tip:

    If the facet is not visible in the visual editor:
    1. Right-click the panelLabelAndMessage component in the Structure window.

    2. From the context menu, choose Facets - Panel Label And Message >facet name. Facets in use on the page are indicated by a checkmark in front of the facet name.

16.5 Displaying Help for Components

ADF Faces provides a framework that allows you to create and display three different types of help whose content comes from an external source, rather than as text configured on the component. Because it is not configured directly on the component, the content can be used by more than one component, saving time in creating pages and also allowing you to change the content in one place rather than everywhere the content appears.

The first type of external help provided by ADF Faces is Definition help. Like a standard tip, the content appears in a message box. However, instead of appearing when the user mouses over the component, Definition help provides a help icon (a blue circle with a question mark). When the user mouses over the icon, the content is displayed, as shown in Figure 16-17.

Figure 16-17 Definition Text for a Component

Help text displayed for inputText component

Table 16-1 shows the components that support Definition help.

Table 16-1 Components That Support Definition Help

Supported Components Help Icon Placement Example

All input components, Select components, Choose Color, Choose Date, Query components

Before the label, or if no label exists, at the start of the field

inputComponent with message

Panel Header, Show Detail Header

End of header text

panelHeader definition

Columns in table and tree

Below header text

Definition in a column


The second type of help is Instruction help. Where Instruction help is displayed depends on the component with which it is associated. The panelHeader and Search panel components display Instruction help within the header. Figure 16-18 shows how the text that typically is displayed as Definition help as shown in Figure 16-17 would be displayed as Instruction help within the panelHeader component.

Figure 16-18 Instruction Text for panelHeader

Definition help

All other components that support Instruction help display the text within a note window, as shown in Figure 16-19. Note that no help icon is displayed.

Figure 16-19 Instruction Text for a Component

Instruction text displayed for input text component

Table 16-2 shows the components that support Instruction help.

Table 16-2 Components That Support Instruction Help

Supported Components Help Icon Placement Example

Input components, Choose Color, Choose Date, Quick Query

Note window, on focus only

inputComponent with instruction help

Select components

Note window, on hover and focus

panelHeader definition

Panel Header, Query

Text below header text

panelHeader with Instruction help


The last type of help is External URL help. You provide a URL to a web page in an external application, and when the help icon is clicked, the web page opens in a separate browser window, as shown in Figure 16-20.

Figure 16-20 External URL Help

External URL help

ADF Faces includes a variety of help providers. The ResourceBundleHelpProvider help provider allows you to create resource bundles that hold the help content. The ELHelpProvider help provider allows you to create XLIFF files that get converted into maps, or create a managed bean that contains a map of help text strings. You can use a combination of the different help providers. You can also create your own help provider class.

To create help for your application, do the following:

To access help on a page, you enter a value for the helpTopicId attribute on a component. A helpTopicId attribute contains the following:

For example, the value of the helpTopicId attribute on the inputText component shown in Figure 16-19 might be RBHELP_FILE_NAME, where RBHELP is the resource bundle help providers prefix, and FILE_NAME is the help topic name.

16.5.1 How to Create Resource Bundle-Based Help

You can store help text within standard resource bundle property files and use the ResourceBundleHelpProvider class to deliver the content.

To create resource bundle-based help:

  1. Create a properties file that contains the topic ID and help text for each help topic. The topic ID must contain the following:

    • The prefix that will be used by this provider, for example, RBHELP.

    • The topic name, for example, TELEPHONE_NUMBER.

    • The help type, for example, DEFINITION.

    For example, a topic ID might be RBHELP_TELEPHONE_NUMBER_DEFINITION.

    Note:

    All prefixes under which help providers are registered must be unique. It is also not permissible for one prefix to begin with the same characters as another prefix. For example, if help providers have already been registered for the two prefixes AAB and AC, then the following prefixes are all invalid and will cause an exception to be thrown at registration time: AABC, A, AA, AC, ACB. However, the following are valid: AAD, AB, and so on.

    UI components access the help content based on the topic name. Therefore, if you use the same topic name for two different types of help (as shown in Example 16-2), then both types of help will be displayed by the UI component.

    Example 16-2 shows an example resource bundle with three topics.

    Example 16-2 Resource Bundle Help

    RBHELP_CUST_SERVICE_EMAIL_DEFINITION=For security reasons, 
                         we strongly discourage the submission of credit card numbers.
    RBHELP_TELEPHONE_NUMBER_DEFINITION=We only support calling telephone numbers 
                                                    in the United States at this time.
    RBHELP_TELEPHONE_NUMBER_INSTRUCTIONS=Enter a telephone number.
    

    Note:

    If you wish to use an external URL help type, create a subclass of the ResourceBundleHelpProvider class. For more information, see Step 3.
  2. Register the resource bundle as a help provider in the adf-settings.xml file (for information on creating the adf-settings.xml file if one does not exist, see Section A.5.1, "How to Configure for ADF Faces in adf-settings.xml").

    To register the provider, open the adf-settings.xml file and add the following elements:

    • <help-provider>: Use the prefix attribute to define the prefix that UI components will use to access this help provider. This must be unique in the application, and must match the prefix used in the resource bundle.

      Note:

      If the prefix attribute is missing, or is empty, then the help provider will be registered as a special default help provider. It will be used to produce help for help topic IDs that cannot be matched with any other help provider. Only one default help provider is permitted.
    • <help-provider-class>: Create as a child element to the <help-provider> element and enter oracle.adf.view.rich.help.ResourceBundleHelpProvider.

    • <property>: Create as a child element to the <help-provider> element. The property defines the actual help source.

    • <property-name>: Create as a child element to the <property> element, and enter a name for the source, for example, baseName.

    • <value>: Create as a child element to the <property> element and enter the fully qualified class name of the resource bundle. For example, the qualified class name of the resource bundle used in the ADF Faces demo application is oracle.adfdemo.view.resource.DemoResources.

    Example 16-3 shows how the resource bundle in Example 16-2 would be registered in the adf-settings.xml file.

    Example 16-3 Registering a Resource Bundle as a Help Provider

    <adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
    <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
      <help-provider prefix="RBHELP_">
        <help-provider-class>
          oracle.adf.view.rich.help.ResourceBundleHelpProvider
        </help-provider-class>
        <property>
          <property-name>baseName</property-name>
          <value>oracle.adfdemo.view.resource.DemoResources</value>
        </property>
      </help-provider>
    </adf-faces-config>
    </adf-settings>
    
  3. If you want to use External URL help, then you also must extend the ResourceBundleHelpProvider class and implement the getExternalUrl method. Example 16-4 shows an example method.

    Example 16-4 Overriding the getExternalURL Method

    protected String getExternalUrl(FacesContext context, UIComponent component,
                                                                       String topicId)
      {
        if (topicId == null)
          return null;
        if (topicId.contains("TOPICID_ALL") ||
            topicId.contains("TOPICID_DEFN_URL") ||
            topicId.contains("TOPICID_INSTR_URL") ||
            topicId.contains("TOPICID_URL"))
          return http://www.myURL.com;
        else
          return null;
      }
    

    In Example 16-4, all the topics in the method return the same URL. You would have to create separate if statements to return different URLs.

16.5.2 How to Create XLIFF-Based Help

You can store the help text in XLIFF XML files and use the ELHelpProvider class to deliver the content. This class translates the XLIFF file to a map of strings that will be used as the text in the help.

To create XLIFF help:

  1. Create an XLIFF file that defines your help text, using the following elements within the <body> tag:

    • <trans-unit>: Enter the topic ID. This must contain the prefix, the topic name, and the help type, for example, XLIFFHELP_CREDIT_CARD_DEFINITION. In this example, XLIFFHELP will become the prefix used to access the XLIFF file. CREDIT_CARD is the topic name, and DEFINITION is the type of help.

      Note:

      All prefixes under which help providers are registered must be unique. It is also not permissible for one prefix to begin with the same characters as another prefix. For example, if help providers have already been registered for the two prefixes AAB and AC, then the following prefixes are all invalid and will cause an exception to be thrown at registration time: AABC, A, AA, AC, ACB. However, the following are valid: AAD, AB, and so on.

      UI components access the help content based on the topic name. Therefore, if you use the same topic name for two different types of help (as shown in Example 16-5), then both types of help will be displayed by the UI component.

    • <source>: Create as a direct child of the <trans-unit> element and enter a unique name.

    • <target>: Create as a direct child of the <trans-unit> element and leave it blank.

    • <note>: Create as a direct child of the <trans-unit> element and enter the help text.

    Example 16-5 shows an example of an XLIFF file that contains two topics.

    Example 16-5 XLIFF Help

    <?xml version="1.0" encoding="UTF-8" ?>
    <xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
      <file source-language="en" original="this" datatype="xml">
        <body>
          <trans-unit id="XLIFF_CREDIT_CARD_DEFINITION">
            <source>Credit Card Definition</source>
            <target/>
            <note>Credit Card definition text.</note>
          </trans-unit>
          <trans-unit id="XLIFF_CREDIT_CARD_INSTRUCTIONS">
            <source>Credit Card Instructions</source>
            <target/>
            <note>Credit card instruction text.</note>
          </trans-unit>
        </body>
      </file>
    </xliff>
    
  2. Register XLIFF as a help provider in the adf-settings.xml file (for information on creating the adf-settings.xml file if one does not exist, see Section A.5.1, "How to Configure for ADF Faces in adf-settings.xml").

    To register the provider, open the adf-settings.xml file and add the following elements:

    • <help-provider>: Use the prefix attribute to define the prefix that UI components will use to access this help provider. This must be unique in the application, and must match the prefix used in the XLIFF file.

      Note:

      If the prefix attribute is missing, or is empty, then the help provider will be registered as a special default help provider. It will be used to produce help for help topic IDs that cannot be matched with any other help provider. Only one default help provider is permitted.
    • <help-provider-class>: Create as a child element to the <help-provider> element and enter oracle.adf.view.rich.help.ELHelpProvider.

    • <property>: Create as a child element to the <help-provider> element. The property values define the actual help source.

    • <property-name>: Create as a child element to the <property> element and enter a name for the help, for example, helpSource.

    • <value>: Create as a child element to the <property> element and enter an EL expression that resolves to the XLIFF file, wrapped in the adfBundle EL function, for example, #{adfBundle['project1xliff.view.Project1XliffBundle']}.

    Example 16-6 shows how the XLIFF file in Example 16-5 would be registered in the adf-settings.xml file.

    Example 16-6 Registering an XLIFF File as a Help Provider

    <adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
    <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
      <help-provider prefix="XLIFF">
        <help-provider-class>
          oracle.adf.view.rich.help.ELHelpProvider
        </help-provider-class>
        <property>
          <property-name>helpSource</property-name>
          <value>#{adfBundle['project1xliff.view.Project1XliffBundle']}</value>
          </property>
        </help-provider>
      </adf-faces-config>
    </adf-settings>
    

16.5.3 How to Create Managed Bean Help

To implement managed bean help, create a managed bean that contains a map of strings that will be used as the text in the help. Managed bean help providers use the ELHelpProvider class to deliver the help.

To create managed bean help:

  1. Create a managed bean that returns a map of strings, each of which is the ID and content for a help topic, as shown in Example 16-7.

    Example 16-7 Managed Bean that Returns a Map of Help Text Strings

    public class ELHelpProviderMapDemo
    {
      public ELHelpProviderMapDemo()
      {
      }
     
      /* To use the ELHelpProvider, the EL expression must point to a Map, otherwise
       * you will get a coerceToType error. */
    
      public Map<String, String> getHelpMap()
      {
        return _HELP_MAP;
      }
     
        static private final Map<String, String> _HELP_MAP = 
                                                        new HashMap<String, String>();
        static
        {
          _HELP_MAP.put("MAPHELP_CREDIT_CARD_DEFINITION", 
                                            "Map value for credit card definition");
          _HELP_MAP.put("MAPHELP_CREDIT_CARD_INSTRUCTIONS", 
                                            "Map value for credit card instructions");
          _HELP_MAP.put("MAPHELP_SHOPPING_DEFINITION", 
                                            "Map value for shopping definition");
          _HELP_MAP.put("MAPHELP_SHOPPING_INSTRUCTIONS", 
                                            "Map value for shopping instructions");
        }
     
    }
    

    The first string must contain the prefix, the topic name, and the help type, for example, MAPHELP_CREDIT_CARD_DEFINITION. In this example, MAPHELP will become the prefix used to access the bean. CREDIT_CARD is the topic name, and DEFINITION is the type of help. The second string is the help text.

    Note:

    All prefixes under which help providers are registered must be unique. It is also not permissible for one prefix to begin with the same characters as another prefix. For example, if help providers have already been registered for the two prefixes AAB and AC, then the following prefixes are all invalid and will cause an exception to be thrown at registration time: AABC, A, AA, AC, ACB. However, the following are valid: AAD, AB, and so on.

    UI components access the help content based on the topic name. Therefore, if you use the same topic name for two different types of help (as shown in Example 16-7), then both types of help will be displayed by the UI component.

    Note:

    If you wish to use external URL help, create a subclass of the ELHelpProvider class. For more information, see Step 4.
  2. Register the managed bean in the faces-config.xml file. Example 16-8 shows the bean shown in Example 16-7 registered in the faces-config.xml file.

    Example 16-8 Managed Bean Registration in the faces-config.xml File.

    <managed-bean>
      <managed-bean-name>helpTranslationMap</managed-bean-name>
        <managed-bean-class>
          oracle.adfdemo.view.webapp.ELHelpProviderMapDemo
        </managed-bean-class>
      <managed-bean-scope>session</managed-bean-scope>
    </managed-bean>
    

    For more information about using and registering managed beans, see Section 2.6, "Creating and Using Managed Beans".

  3. Register the managed bean as a help provider in the adf-settings.xml file (for information on creating the adf-settings.xml file if one does not exist, see Section A.5.1, "How to Configure for ADF Faces in adf-settings.xml").

    To register the provider, open the adf-settings.xml file and add the following elements:

    • <help-provider>: Create and use the prefix attribute to define the prefix that UI components will use to access this help provider. This must be unique in the application.

      Note:

      If the prefix attribute is missing, or is empty, then the help provider will be registered as a special default help provider. It will be used to produce help for help topic IDs that cannot be matched with any other help provider. Only one default help provider is permitted.
    • <help-provider-class>: Create as a child element to the <help-provider> element and enter the fully qualified class path to the class created in Step 1.

    • <property>: Create as a child element to the <help-provider> element. The property defines the map of help strings on the managed bean.

    • <property-name>: Create as a child element to the <property> element and enter a property name, for example helpSource.

    • <value>: Create as a child element to the <property> element and enter an EL expression that resolves to the help map on the managed bean.

    Example 16-9 shows how the bean in Example 16-8 would be registered in the adf-settings.xml file.

    Example 16-9 Registering a Managed Bean as a Help Provider

    <adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
    <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
       <help-provider prefix="MAPHELP_">
       <help-provider-class>
         oracle.adf.view.rich.help.ELHelpProvider
       </help-provider-class>
       <property>
         <property-name>helpSource</property-name>
         <value>#{helpTranslationMap.helpMap}</value>
       </property>
     </help-provider>
     </adf-faces-config>
    </adf-settings>
    
  4. If you want to use External URL help with the managed bean provider, then extend the ELHelpProvider class and implement the getExternalUrl method. Example 16-10 shows an example method.

    Example 16-10 Overriding the getExternalURL Method

    protected String getExternalUrl(FacesContext context, UIComponent component,
                                                                       String topicId)
      {
        if (topicId == null)
          return null;
        if (topicId.contains("TOPICID_ALL") ||
            topicId.contains("TOPICID_DEFN_URL") ||
            topicId.contains("TOPICID_INSTR_URL") ||
            topicId.contains("TOPICID_URL"))
          return http://www.myURL.com;
        else
          return null;
      }
    

    In Example 16-10, all the topics in the method return the same URL. You must create separate if statements to return different URLs.

16.5.4 How to Create a Java Class Help Provider

Instead of using one of the ADF Faces help providers, create your own. Create the actual text in some file that your help provider will be able to access and display. To create a Java class help provider, extend the HelpProvider class. For more information about this class, refer to the ADF Faces Javadoc.

To create a Java class help provider:

  1. Create a Java class that extends oracle.adf.view.rich.help.HelpProvider.

  2. Create a public constructor with no parameters. You also must implement the logic to access and return help topics.

  3. This class will be able to access properties and values that are set in the adf-settings.xml file when you register this provider. For example, the ADF Faces providers all use a property to define the actual source of the help strings. To access a property in the adf-settings.xml file, create a method that sets a property that is a String. For example:

    public void setMyCustomProperty(String arg)
    
  4. To register the provider, open the adf-settings.xml file and add the following elements:

    • <help-provider>: Use the prefix attribute to define the prefix that UI components will use to access this help provider. This must be unique in the application.

      Note:

      If the prefix attribute is missing, or is empty, then the help provider will be registered as a special default help provider. It will be used to produce help for help topic IDs that cannot be matched with any other help provider. Only one default help provider is permitted. All prefixes under which help providers are registered must be unique. It is also not permissible for one prefix to begin with the same characters as another prefix. For example, if help providers have already been registered for the two prefixes AAB and AC, then the following prefixes are all invalid and will cause an exception to be thrown at registration time: AABC, A, AA, AC, ACB. However, the following are valid: AAD, AB, and so on.
    • <help-provider-class>: Create as a child element to the <help-provider> element and enter the fully qualified class path to the class created in Step 1.

    • <property>: Create as a child element to the <help-provider> element and use it to define the property that will be used as the argument for the method created in Step 3.

    • <property-name>: Create as a child element to the <property> element and enter the property name.

    • <value>: Create as a child element to the <property> element and enter the value for the property.

    Example 16-11 shows an example of a help provider class registered in the adf-settings.xml file.

    Example 16-11 Registering a Help Provider Class

    <adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
    <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
      <help-provider prefix="MYAPP">
        <help-provider-class>
          oracle.adfdemo.view.webapp.MyHelpProvider
        </help-provider-class>
        <property>
          <property-name>myCustomProperty</property-name>
          <value>someValue</value>
        </property>
      </help-provider>
    </adf-faces-config>
    </adf-settings>
    

16.5.5 How to Access Help Content from a UI Component

Use the HelpTopicId attribute on components to access and display the help.

To access help from a component:

  1. In the Structure window, select the component to which you want to add help. For a list of components that support help, see Table 16-1 and Table 16-2.

  2. In the Property Inspector, expand the Appearance section, and enter a value for the helpTopicId attribute. This should include the prefix to access the correct help provider and the topic name. It should not include the help type, as all help types registered with that name will be returned and displayed, for example:

    <af:inputText label="Credit Card" helpTopicId="XLIFF_CREDIT_CARD"/>
    

    This example will return both the definition and instruction help defined in the XLIFF file in Example 16-5.

  3. If you want to provide help for a component that does not support help, you can instead add an outputText component to display the help text, and then bind that component to the help provider, for example:

    <af:outputFormatted
     value="#{adfFacesContext.helpProvider['XLIFF_CREDIT_CARD'].instructions}"/>
    

    This will access the instruction help text.

16.5.6 What You May Need to Know About Combining Different Message Types

When you add help messages to input components that may already display messages for validation and conversion, ADF Faces displays the messages in the following order within the note window:

  1. Validation and conversion error messages.

  2. Validation and conversion hints.

  3. For input and select components only, Instruction help. For panelHeader components, Instruction help is always displayed below the header.

  4. Value for shortDesc attribute.

Figure 16-21 shows an inputDate component that contains a converter, instruction help, and a tip message.

Figure 16-21 Different Message Types Can Be Displayed at One Time

Different message types displayed