How to Allow Playing of Audio and Video Clips

16-20 Web User Interface Developers Guide for Oracle Application Development Framework 17 Displaying Tips, Messages, and Help 17-1 17 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: ■ Section 17.1, Introduction to Displaying Tips and Messages ■ Section 17.2, Displaying Tips for Components ■ Section 17.3, Displaying Hints and Error Messages for Validation and Conversion ■ Section 17.4, Grouping Components with a Single Label and Message ■ Section 17.5, Displaying Help for Components

17.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 17–1 shows a tip configured for a toolbar button. For more information about creating tips, see Section 17.2, Displaying Tips for Components. Figure 17–1 Tip 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 17-2 Web User Interface Developers Guide for Oracle Application Development Framework converter, when the user clicks in the field, a note window displays a hint that shows the expected pattern, as shown in Figure 17–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 17–2 Attached Converters and Validators Include Messages 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 addMessagejava.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 17–2 , an error message is displayed, as shown in Figure 17–3 . Note that the error message appears in the note window along with the hint. Figure 17–3 Validation and Conversion 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 17–4 . Displaying Tips, Messages, and Help 17-3 Figure 17–4 Global and Component Messages Displayed by the Document 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 17.3, Displaying Hints and Error Messages for Validation and Conversion. 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 17–3 . For more information, see Section 17.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: ■ Definition: Provides a help icon question mark in a blue circle with the help text appearing when the user mouses over the icon, as shown in Figure 17–5 . 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: 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.