Introduction to Displaying Tips and Messages

17-4 Web User Interface Developers Guide for Oracle Application Development Framework Figure 17–5 Definition Messages Display When Mousing Over the Icon ■ Instruction: Depending on the component, this type of help either provides instruction text within the component as with panelHeader components, or displays text in the note window that is opened when the user clicks in the component, as shown in Figure 17–6 . The text can be any length. Figure 17–6 Instruction Messages Display in a Note Window ■ External URL: You can have a help topic that resides in an external application, which will open in a separate browser window. For example, instead of displaying instruction help, Figure 17–7 shows the Select Skin selectOneChoice component configured to open a help topic about skins. When a user clicks the help icon, the help topic opens. Figure 17–7 External URL Help Opens in a New Window For more information about creating help systems, see Section 17.5, Displaying Help for Components. Displaying Tips, Messages, and Help 17-5

17.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 17.5, Displaying Help for Components. Figure 17–8 shows the effect when the cursor hovers over an inputText component. Figure 17–8 Tip for an inputText Component Figure 17–9 shows a tip as displayed for a showDetailItem component. Figure 17–9 Tip for a showDetailItem Component 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. 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 21, Internationalizing and Localizing Pages.

17.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 17–10 . Tip: The value should be less than 80 characters, as some browsers will truncate the tip if it exceeds that length. 17-6 Web User Interface Developers Guide for Oracle Application Development Framework Figure 17–10 Validators and Converters Have Built-in Messages 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 17–11 . Figure 17–11 Validation Error at Runtime 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 17–12 shows the attributes that you can populate to override the messages for the convertDateTime converter, as displayed in the Property Inspector. Figure 17–12 Message Attributes on a Converter 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 17–13 shows how messages are displayed using the message component. Displaying Tips, Messages, and Help 17-7 Figure 17–13 Use the message Component to Display Messages 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.

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

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 17–14 . Figure 17–14 Detail Message at Runtime 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 17.3.3, How to Display Component Messages Inline. 17-8 Web User Interface Developers Guide for Oracle Application Development Framework 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 21, Internationalizing and Localizing Pages.

17.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 21, Internationalizing and Localizing Pages. For message key information, see Appendix B, Message Keys for Converter and Validator Messages.

17.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. If not already set, enter an ID for the component.

2. In the Component Palette, from the Common Components 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. Tip: Use the dropdown menu to view the property help, which includes the parameters accepted by the message. 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 17.3.2, What You May Need to Know About Overriding Default Messages Globally.