Grouping Components with a Single Label and Message

17-12 Web User Interface Developers Guide for Oracle Application Development Framework 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 17–18 shows how the text that typically is displayed as Definition help as shown in Figure 17–17 would be displayed as Instruction help within the panelHeader component. Figure 17–18 Instruction Text for panelHeader All other components that support Instruction help display the text within a note window, as shown in Figure 17–19 . Note that no help icon is displayed. Figure 17–19 Instruction Text for a Component Table 17–2 shows the components that support Instruction help. Table 17–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 Panel Header, PanelBox, Show Detail Header End of header text Panel Window, Dialog Next to close icon in header Columns in table and tree Below header text Displaying Tips, Messages, and Help 17-13 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 17–20 . Instead of clicking a help icon, you can use JavaScript to open a help window based on any client-based event. Figure 17–20 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: ■ Determine the help providers to use and then implement the required artifacts. ■ Register the help providers, specifying the prefix that will be used to access the provider’s help. Each help provider has its own unique prefix, which is used as its identifier. A particular provider will be called to produce help only for help topic IDs that start with the prefix under which the provider is registered. Table 17–2 Components That Support Instruction Help Supported Components Help Placement Example Input components, Choose Color, Choose Date, Quick Query Note window, on focus only Select components Note window, on hover and focus Panel Header, Panel Box, Query Text below header text 17-14 Web User Interface Developers Guide for Oracle Application Development Framework ■ Have the UI components access the help contained in the providers by using the component’s helpTopicId attribute. A helpTopicId attribute contains the following. ■ The prefix that is used by the provider of the help ■ The topic name For example, the value of the helpTopicId attribute on the inputText component shown in Figure 17–19 might be RBHELP_FILE_NAME, where RBHELP is the resource bundle help providers prefix, and FILE_NAME is the help topic name.

17.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. Example 17–2 shows an example resource bundle with three topics. Example 17–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: 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 17–2 , then both types of help will be displayed by the UI component. Note: If you wish to use an external URL help type, create a subclass of the ResourceBundleHelpProvider class. For more information, see Step 3.