Messages can typically be divided into to types: error messages that display when an error occurs in the application, for example when a user enters incompatible information, and informational messages that provide for example, hints for using a component or for completing a task on a page.

Informational messages can range from simple tooltips to comprehensive help systems. Tooltips should be used when the component for which you want to display hints or information does not support help text. However, tooltip text must be very brief. If you have to display more detailed information, or if the text can be reused among many component instances, consider using help text instead.

You create tooltips by configuring the shortDesc attribute on a component. The value of that attribute then displays in a note window when the user hovers over the component or clicks the component (such as inputText component), as shown in Figure 19-7.

Figure 19-7 Tooltip for a Component

For information about tooltips, see Displaying Tips for Components.

Error messages use the JSF messaging API. There are two types of error messages: component messages where the message applies to the specific component only, and global messages, where the message applies to more than one component or the whole page.

By default, the noteWindow component is used for component error messages. When you configure conversion or validation on any input component, validation and conversion hints and errors are automatically displayed in the noteWindow component. You do not need to add the component to the page.

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 19-8. 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 19-8 Attached Converters and Validators Include Messages

If a user enters a date incorrectly in the field shown in Figure 19-8, an error message is displayed, as shown in Figure 19-9. Note that the error message appears in the note window along with the hint.

Figure 19-9 Validation and Conversion Errors Display in Note Window

If you want to display an error 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. When you use this component, messages are displayed next to the component, as shown in Figure 19-10.

Figure 19-10 Use the message Component to Display Messages Inline

Global messages are by default displayed in a dialog, as shown in Figure 19-11. You do not need to add the popup component to the page.

Figure 19-11 Global Messages Display in a Popup Dialog

If instead you want the error messages to display directly on the page, use the messages component. When you use this component, the messages are displayed in a list at the top of the page, as shown in Figure 19-12.

Figure 19-12 Use the messages Component to Display Global Messages on the Page

For information about error messages, see Displaying Hints and Error Messages for Validation and Conversion.

When you want to display more information that can fit in a tooltip, use definition help. When you configure definition help for most components, a help icon is displayed next to the component. The help text is displayed when the mouse hovers over the component, as shown in Figure 19-13.

Figure 19-13 Definition Help for a Column Component

For information about definition help, see Displaying Help for Components.

When you want to display field-level help, configure an input component to use instruction text. When the user clicks in the component, the help text is displayed in a note window, as shown in Figure 19-14.

Figure 19-14 Instruction Text for a Component

When you want to display instructions for a task, configure instruction help for a container component. The text will appear in the header of the component, as shown in Figure 19-15.

Figure 19-15 Instruction Text for the panelHeader Component

When you need to provide comprehensive help, you can use the help icon to link to an external help system available through a URL.

For information about instruction and external help, see Displaying Help for Components.

1. In the Structure window, select the component for which you want to display the tip.
2. In the Properties window, 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 information about using resource bundles, see Internationalizing and Localizing Pages.

1. In the Structure window, select the converter or validator for which you want to create the error message.
2. In the Properties window, 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.

   Tips:

   • If your application uses bidirectional or right-to-left display, do not start the message with the expected format parameter {2}, as it may not display correctly in Internet Explorer.

   • You should try not to display the format parameter {1} in the message. Displaying the user input might be considered as a security violation.

   Using these parameters, you can create the following message:

   The date you have entered in the \"{0}\" field 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 19-22. Note that you might need to change the value Type attribute of the converter to match the parameters.

   Figure 19-22 Detail Message at Runtime

   

   Tip:

   Use the dropdown menu to view the property help, which includes 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 information about using resource bundles, see 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. See How to Define Custom Validator and Converter Messages for All Instances of a Component.

1. Refer to Message Keys for Converter and Validator Messages to determine the message key for the message you want to override. For example, to override the detail message displayed when the input value exceeds the maximum value length, you would use the key org.apache.myfaces.trinidad.validator.LengthValidator. MAXIMUM_detail, as shown in af:validateLength.
2. Create or open a message bundle. For procedures how to create message bundles, see How to Create a Resource Bundle as a Property File or an XLIFF File.
3. Add the key override to the message bundle. For example, to override the message for the input value length, you might add:

   org.apache.myfaces.trinidad.validator.LengthValidator.MAXIMUM_detail: Your value exceeds the limit.
   

4. If the message bundle is a new resource bundle, you need to register the bundle with the application using the faces-config.xml file, following the procedures in How to Register a Resource Bundle in Your Application. However, use the <message-bundle> tag, rather than the <resource-bundle> tag.

1. In the Structure window, select the component that will display its messages using the message component. If not already set, enter an ID for the component.
2. In the Components window, from the Text and Selection panel, drag a Message and drop it where you want the message to be displayed on the page.
3. Use the dropdown menu for the for attribute to select Edit.
4. 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.

1. In the Components window, from the Text and Selection panel, drag a Messages and drop it onto the page where you want the messages to be displayed.
2. In the Properties window, 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.

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. Component-level messages 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 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.

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 one component message), all messages in the queue will be displayed in a popup window, as shown in Figure 19-23.

Figure 19-23 Global and Component Messages Displayed by the Document

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:

1. In the Applications window, from the META-INF node, open the adf-settings.xml file.
2. Click the Source tab, 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.

   • <help-provider-class>: Create as a child element to the <help-provider> element.

     • If you are using a resource bundle, enter the value as oracle.adf.view.rich.help.ResourceBundleHelpProvider.

     • If you are using an XLIFF file, enter the value as oracle.adf.view.rich.help.ELHelpProvider.

     • If you are using a managed bean or external URL provider, enter the fully qualified class path.

     Note:

     For external URL help, the provider class should reflect the class that your provider extended.

   • <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.

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

     • If you are using a resource bundle, 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 Components Demo application is oracle.adfdemo.view.resource.DemoResources.

     • If you are using an XLIFF file, enter an EL expression that resolves to the XLIFF file, wrapped in the adfBundle EL function, for example, #{adfBundle['project1xliff.view.Project1XliffBundle']}.

     • If you are using a managed bean, enter an EL expression that resolves to the help map on the managed bean.

     • If your are using external URL help, enter the fully qualified class name of the provider class you created.

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
  <help-provider prefix="HELP_">
    <help-provider-class>
      oracle.adf.view.rich.help.ResourceBundleHelpProvider
    </help-provider-class>
    <property>
        <property-name>baseName</property-name>
        <value>oracle.adfdemo.view.resource.fileExplorer.helpStrings</value>
    </property>
  </help-provider>
</adf-faces-config>
</adf-settings>

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
  <help-provider prefix="HELP">
    <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>

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
   <help-provider prefix="HELP_">
   <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>

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
  <help-provider prefix="HELP_">
  <help-provider-class>
    oracle.adf.view.rich.help.ResourceBundleHelpProvider
  </help-provider-class>
  <property>
    <property-name>baseName</property-name>
    <value>oracle.adfdemo.view.resource.DemoHelp</value>
  </property>
  </help-provider>
 </adf-faces-config>
</adf-settings>

<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>

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 19-1 and Table 19-2.
2. In the Properties window, expand the Appearance section, and enter a value for the helpTopicId attribute.

   For definition and instruction help, this value 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="Customer Service E-Mail" helpTopicId="HELP_CUST_SERVICE_EMAIL"/>
   

   This example will return both the definition and instruction help defined in the XLIFF file in the example in How to Create an XLIFF Provider..

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['HELP_CUST_SERVICE_  EMAIL'].instructions}"/>
   

   This accesses the instruction help text.

1. Create a JavaScript function that uses the launchHelp API to launch a specific URL or page.

   The following example shows the launchHelp function used to launch the helpClient.jspx.

   <af:resource type="javascript">
     function launchHelp(event)
       {
         AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
       }
   </af:resource>
   

2. In the ADF Faces page, drag and drop the component whose client event will cause the launchHelp function to be called. You must set the clientId on this component to true.
3. In the Components window, from the Operations panel, drag and drop a Client Listener as a child to the component created in Step 2. Configure the clientListener to invoke the function created in Step 1. For information about using the clientListener tag, see Listening for Client Events.

   The following example shows the code used to assign the click event of button component to launch the helpClient.jspx page.

   <af:toolbar id="tb1">
     <af:button text="Launch help window" id="ctb1"
                              icon="/images/happy_computer.gif">
       <af:clientListener method="launchHelp" type="click"/>
     </af:button>
   </af:toolbar>
   <af:resource type="javascript">
     function launchHelp(event)
       {
         AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
       }
   </af:resource>
   

By default, when definition help is associated with a component, a question mark icon is displayed. The user clicks that icon to display the help. You can configure a custom skin to instead display a dotted line under the label of the component. This line denotes that the text is clickable. When the user clicks the text, the help is displayed.

Figure 19-31 shows an inputText component with the default question mark icon.

Figure 19-31 Definition Help Icon

Figure 19-32 shows the same inputText component, but configured to display a link instead of the question mark.

Figure 19-32 Definition Help Text Link

You use the -tr-help-def-location skin selector key to configure the display. Set it to icon to display the icon. Set it to label to display the underline. The following example shows the help configured to display the underline.

af|help {
  -tr-help-def-location: label; 
}