How to Create Managed Bean Help

Displaying Tips, Messages, and Help 17-21 To use JavaScript to launch an external help window: 1. Create a JavaScript function that uses the launchHelp API to launch a specific URL or page. Example 17–11 shows the launchHelp function used to launch the helpClient.jspx. Example 17–11 JavaScript to Launch an External Help Page af:resource type=javascript function launchHelpevent { AdfPage.PAGE.launchHelpWindowhelpClient.jspx; } af:resource 2. Drag and drop a component whose client event will cause the function to be called. You must set the clientId on this component to true.

3. In the Component Palette, 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 more information about using the clientListener tag, see Section 3.2, Listening for Client Events. Example 17–12 shows the code used to have a click event on a commandToolbarButton component launch the helpClient.jspx page. Example 17–12 Page Code Used to Launch an External Help Window af:toolbar id=tb1 af:commandToolbarButton text=Launch help window id=ctb1 icon=imageshappy_computer.gif af:clientListener method=launchHelp type=click af:commandToolbarButton af:toolbar af:resource type=javascript function launchHelpevent { AdfPage.PAGE.launchHelpWindowhelpClient.jspx; } af:resource

17.5.5 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 17-22 Web User Interface Developers Guide for Oracle Application Development Framework 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 setMyCustomPropertyString 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. ■ 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 17–13 shows an example of a help provider class registered in the adf-settings.xml file. Example 17–13 Registering a Help Provider Class adf-settings xmlns=http:xmlns.oracle.comadfsettings adf-faces-config xmlns=http:xmlns.oracle.comadffacessettings help-provider prefix=MYAPP help-provider-class oracle.adfdemo.view.webapp.MyHelpProvider help-provider-class property property-namemyCustomPropertyproperty-name valuesomeValuevalue property help-provider adf-faces-config adf-settings 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. Displaying Tips, Messages, and Help 17-23

17.5.6 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 17–1 and Table 17–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 17–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.

17.5.7 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 17–21 shows an inputDate component that contains a converter, instruction help, and a tip message. Figure 17–21 Different Message Types Can Be Displayed at One Time