How to Create XLIFF-Based Help

Displaying Tips, Messages, and Help 17-19 2. Register the managed bean in the faces-config.xml file. Example 17–8 shows the bean shown in Example 17–7 registered in the faces-config.xml file. Example 17–8 Managed Bean Registration in the faces-config.xml File. managed-bean managed-bean-namehelpTranslationMapmanaged-bean-name managed-bean-class oracle.adfdemo.view.webapp.ELHelpProviderMapDemo managed-bean-class managed-bean-scopesessionmanaged-bean-scope managed-bean For more information about using and registering managed beans, see Section 2.6, Creating and Using Managed Beans. 3. Register the managed bean as a help provider in the adf-settings.xml file for information on creating the adf-settings.xml file if one does not exist, see Section A.5.1, How to Configure for ADF Faces in adf-settings.xml . To register the provider, open the adf-settings.xml file and add the following elements: ■ help-provider: Create and 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. The property defines the map of help strings on the managed bean. 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–7 , then both types of help will be displayed by the UI component. Note: If you wish to use external URL help, create a subclass of the ELHelpProvider class. For more information, see Step 4. 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. 17-20 Web User Interface Developers Guide for Oracle Application Development Framework ■ property-name: Create as a child element to the property element and enter a property name, for example helpSource. ■ value: Create as a child element to the property element and enter an EL expression that resolves to the help map on the managed bean. Example 17–9 shows how the bean in Example 17–8 would be registered in the adf-settings.xml file. Example 17–9 Registering a Managed Bean as a Help Provider adf-settings xmlns=http:xmlns.oracle.comadfsettings adf-faces-config xmlns=http:xmlns.oracle.comadffacessettings help-provider prefix=MAPHELP_ help-provider-class oracle.adf.view.rich.help.ELHelpProvider help-provider-class property property-namehelpSourceproperty-name value{helpTranslationMap.helpMap}value property help-provider adf-faces-config adf-settings 4. If you want to use External URL help with the managed bean provider, then extend the ELHelpProvider class and implement the getExternalUrl method. Example 17–10 shows an example method. Example 17–10 Overriding the getExternalURL Method protected String getExternalUrlFacesContext context, UIComponent component, String topicId { if topicId == null return null; if topicId.containsTOPICID_ALL || topicId.containsTOPICID_DEFN_URL || topicId.containsTOPICID_INSTR_URL || topicId.containsTOPICID_URL return http:www.myURL.com; else return null; } In Example 17–10 , all the topics in the method return the same URL. You must create separate if statements to return different URLs. If you want the external window to be launched based on a component’s client event instead of from a help icon, use a JavaScript function. For more information, see Section 17.5.4, How to Use JavaScript to Launch an External Help Window.

17.5.4 How to Use JavaScript to Launch an External Help Window

If you want to use external URL help, by default, the user clicks a help icon to launch the help window. Instead, you can use JavaScript and a client event listener for a specific component’s event to launch the help window. 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