19 ADF Rich Client Help Provider

This chapter describes how to integrate online help with the ADF Faces application and how to register OHW as a help provider.

This chapter contains the following sections:

19.1 About ADF Rich Client Help Provider

If you have an ADF Faces application and wish to incorporate online help into your application, ADF Faces, also known as ADF Rich Client, provides an easy way to do that. You can create an online help system with help topics which are integrated with components of the application.

This chapter describes how to configure OHW as a help provider, lists other ADF Rich Client help providers, and also describes how to use HelpTopicId attribute to associate help topics with your application.

19.2 Integrating Online Help With ADF Faces Application

When you integrate a help topic with an ADF Faces component, a help icon (a blue circle with a question mark) appears with the component. When you click the help icon, the related help topic appears in a new window, as shown in Figure 19-1.

Figure 19-1 Help Icon in an ADF Faces Application

This image is described in the surrounding text

Integrating an online help with an application is an easy process, described in the following steps:

  • Register a help provider with your application

  • Create a properties file that contains the topic ID and help text for each help topic

  • Associate the UI components with help topics by using the HelpTopicId attribute

For more information about integrating online help with an application, see "Displaying Help for Components" section in Developing Web User Interfaces with Oracle ADF Faces.

19.3 Registering OHW as an ADF Rich Client Help Provider

ADF Rich Client Faces includes a variety of help providers. You can use a combination of the different help providers or create your own help provider class. You can also use OHW as a help provider.

You need to perform the following tasks in order to set up OHW as a Help Provider in an ADF Rich Client application:

  1. Deploy OHW as a web application:

    1. Deploy an ADF application to web application server.

    2. Note down the context-root of this deployment.

    3. Open the web.xml file in this deployment.

    4. Find the OHW servlet instance.

  2. Develop the jspx Web pages.

    1. Create an ADF Faces-based Web application.

    2. Create a jspx Web page; for some components (input*, select*, etc), where you can find an attribute named helpTopicId, specify the ID you want to display with your OHW instance.

  3. Copy the helpsets into a directory under your <application_root>/public_html folder. For example, let's name this directory helpsets.

  4. Set up the adf-settings.xml file.

    1. Navigate to your application's directory, and look for the.adf/META-INF/ directory. Under that directory you can find the adf-settings.xml file. If the.adf/META-INF directory is not present, create the META-INF directory under the ViewController/src directory.

    2. Enter code into adf-settings.xml; for example:

      <?xml version="1.0" encoding="UTF-8" ?>
<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
  <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
    <help-provider>
      <help-provider-class>
            oracle.help.web.rich.helpProvider.OHWHelpProvider
      </help-provider-class>
      <property>
        <property-name>ohwConfigFileURL</property-name>
        <value>/helpsets/ohwconfig.xml</value>
      </property>
      <!--property>
      <property-name>group</property-name>
      <value>null</value>
    </property-->
      <property>
        <property-name>baseURI</property-name>
        <value>
            http://localhost:8989/help-ohw-rcf-context-root/ohguide/
        </value>
      </property>
    </help-provider>
  </adf-faces-config>
</adf-settings>

      In this adf-settings.xml file:

      • If you want to use OHW as your help provider, then, in this adf-settings.xml file, the class has to be OHWHelpProvider.

      • Set the ohwConfigFileURL property to point to your /helpsets/ohwconfig.xml. Note that you created the helpsets directory in Step 3.

        Note:

        You can also specify ohwConfigURL using the prop system property. For example, in web.xml, the ohwConfigURL would be configured as: 
        <param-name>ohwConfigFileURL</param-name>
<param-value>file:///{%prop}/help/ohwconfig.xml</param-value>

        In adf-settings.xml, the ohwConfigURL would be configured as:

        <property>
    <property-name>ohwConfigFileURL</property-name>
    <value>file:///{%prop}/help/ohwconfig.xml</value>
</property>

        The prop property is predefined, or specified, by starting Oracle WebLogic Server with -Dprop option. For example, -Dprop=/Oracle/help.

      • The group property specifies the group name (which you want to use in the help provider) in your ohwconfig.xml file.

      • The baseURI property specifies the server host, the context root, and the OHW servlet instance of the RCF application that you deployed in Step 1.

19.4 Using HelpTopicId Attribute

To associate a help topic with an ADF component, you must assign the help topic's unique id as the HelpTopicId attribute's value. The HelpTopicId attribute is available in the Appearance section of Properties window.

Figure 19-2 HelpTopicId Attribute

This image is described in the surrounding text

Before associating a help topic with a component, ensure that you have registered a help provider with your application. To register OHW as a help provider, see Section 19.3, "Registering OHW as an ADF Rich Client Help Provider".

For more information about HelpTopicId attribute, see "Displaying Help for Components" section in Developing Web User Interfaces with Oracle ADF Faces.

19.5 Using Other Help Providers

Two common ADF Rich Client help providers are ResourceBundleHelpProvider and ELHelpProvider. The ResourceBundleHelpProvider help provider allows you to display help in your ADF Faces application that is defined in resource bundles. These resource bundles are containers of your help files, control files, graphics, and other related files. The ELHelpProvider help provider allows you to display help text in your ADF Faces application that is defined in the XLIFF files. The XLIFF files get converted into maps, or create a managed bean that contains a map of help text strings. Note that ELHelpProvider does not create help files, but helps you connect those files to the ADF Faces application.

For more information about these and other help providers, see "Displaying Help for Components" section in Developing Web User Interfaces with Oracle ADF Faces.