Integrating Help with your ADF Applications

An Oracle JDeveloper How To Document
Written by  Dana Singleterry and Georg Neumann, Oracle Corporation

Introduction

The Oracle Help technologies provide the means for developing and displaying HTML-based help systems for Java and web applications. Authors can create a single help system that can be displayed - without modification - both in a Java environment, using Oracle Help for Java (OHJ), and in a web environment, using Oracle Help for the Web - Rich Client (OHW-RC).

OHW-RC, similar to OHW-UIX, delivers HTML-based Help content in a Web environment. It uses the Oracle Application Development Framework (ADF) which is based on the Java Server Faces (JSF) technology, to build a user interface that follows Oracle's Browser Look and Feel Plus (BLAF+) behaviors and guidelines. OHW-RC uses the model layer to provide Help content, build the table of contents, process indexes, and execute searches. Users can have access to a single instance of OHW-RC, because the Help contents are processed at the server side.

THE OHW-RC can be used in many different situations:

1. As a help system providing context-sensitive Help to a rich client application in a new browser window.
2. As a standalone document viewer of Help content on a public website.
3. When a user performs  a search on any popular search engine and the results link to indexed OHW-RC content.
4. When an ADF Faces component's runtime implementation requires to retrieve Embedded Help information (Definition Text, Instructions Text, or Full Help) using the HelpProvider interface it defines..

This How To Document demonstrates how to integrate OHW-RC with your ADF Applications and includes a sample application to demonstrate this integration. Specifically this How-To will demonstrate stituation 1 and 4 above and a brief explanation of situation 2 and 3 will be covered first.

Software Requirements

• JDeveloper 11g Release 1 (11.1.1.1.0).
• Download OHW-RC Thick Demo EAR. This can be deployed to a WLS 10.3 server domain that is not configured for ADF as all the ADF and OHW libraries are included. Alternativiely, Download the OHW-RC Thin Demo EAR if you have a WLS 10.3 server domain that is configured for ADF.
• Download OHW-RC application (ohw-links.ear) that supports the sample application that follows.
• Download starter application (MyAppUsingOHW.zip) and unzip the archive to utilize within JDeveloper. You can also download the application ear (MyAppUsingOHW.ear) which is a completed ADF application ready for deployment and testing.
•  

OHW-RC providing context-sensitive Help to a rich client application in a new browser window and using the HelpProvider interface to provide Embedded Help Information to a component's runtime implementation.

You can use both the JDeveloper integrated WLS10.3 server or a standalone server that is configured for ADF. This How-To uses a combination of the two which is not a requirement. In this How-To, the ohw-links.ear file is deployed to the standalone application server while the starter application, MyappUsingOHW.jws) is running in the integrated server. The choice is up to the reader.

This section of the How-To will introduce, in detail, the basics of integrating OHW-RC with your ADF applications. A combination of using a help system providing context-sensitive Help to a rich client application in a new browser window as well as when an ADF Faces component's runtime implementation requires to retrieve Embedded Help information (Definition Text, Instructions Text, or Full Help) using the HelpProvider interface it defines will be demonstrated.

1. Start the Admin Server for WebLogic Server Domain
2. Launch the Admin Server Console

3. Select "Deployments".
4. Select "Install".
5. Navigate to the location of the ohw-links.ear. Note that your domain must be configured for ADF application deployments.
6. Select the deployment and select "Next".
7. Select  "Install this deployment as an application" and selet "Next".
8. On the "Optional Settings" page select "Next".
9. Review your choices and click "Finish".
10. Select "Save" on the last page "Setting for ohw-link".
11. The ohw-links application which is the same as the ohw-rcf-demo-thick or ohw-rcf-demo-thin ear, except for a different helpset, can be accessed via a url (http://localhost:7001/ohw-links/newhelp) but the key here is that the ADF application that your are going to develop now will utilize the ohw-links application to display help content. Note also that your port may be different than the one specified here.

Now proceed with adding help to a simple ADF application that will provide both Help in a separate browser window as well as embedded help. Note that authoring Help Sets is outside the scope of this How-To document and for details on this please refer to the "Authoring Oracle Help Systems" section of the Oracle Fusion Middleware Developer's Guide for Oracle Help available on Oracle Help OTN page.

The following is an overview of the easy steps to follow in adding OHW-RC to an ADF application:

• 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.

These steps will be demonstrated through the use of the MyAppUsingOHW.jws application.

1. 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 illustrated here. Also worth noting is that context sensitive help is also available with Oracle Help and the application that we're using here will provide both. That is to say, if you see the blue icon with the question mark, you can select it and help will be provided in a separate browser window. You can also select in the input field and context sensitive help will be provided.

2. The application you're working with here is much simpler, and so is the help content provided, than the one illustrated above. Now open the provided starter application workspace that you downloaded - MyAppUsingOHW.jws.

Note: As previously mentioned, very little attention will be given to the helpsets content itself except where required. The more important aspects of adding help to components lie within the adf-setting.xml, ohwconfig.xml, and on the component itself where a topicID is provided. Where necessary, specifics within the helpset will be outlined.

3. Register OHW-RC as an ADF Rich Client Help Provider
4. 1. You've already deployed OHW-RC as a web application (ohw-links.ear) but here are the points to note about this deployment.
   2. 1. Deploy an OHW-RC 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-RC servlet instance.
5. Develop the jspx Web pages.
6. 1. Create an ADF Faces-based Web application. The starter application (MyAppUsingOHW) provided is an ADF Faces 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-RC instance. In this case the HelpTopicId is named concise_expanded.

5. Copy the helpsets into a directory under your <application_root>/public_html folder. For example, let's name this directory helpsets. This is already done in the provided starter application.

1. Review the ohwconfig.xml. Of particular interest here is the brandings, locales and customProtocolRegistry. The brandings element is for labeling your help system which you will see when you run the sample application. The locales element is to specify multilingual helpsets and the helpset element within the locale element is to specify the helpset file for the helpset in use. The customProtocolRegistry in this instance is to specify the OHW-RC (ohw-links) that was deployed earlier and to utilize that when it is needed (i.e. when the icon next to the component is selected) it will be launched with the requested help content into a separte browser window.

6. Set up the adf-settings.xml file. 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.  For example:

7. 1. <adf-settings xmlns="http://xmlns.oracle.com/adf/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-settings>
                                                  

2. Our adf-settings.xml file is as illustrated here and as you'll see, we've specified all these properties except for the group property which is not needed in this instance.

7. The last step is to associate a help topic with the Input Text component that was added to the JSF page earlier. We've already assigned the help topic's unique id of consise_expanded as the HelpTopicId attribute's value which is available in the Appearance section of the Property Inspector. Refer to step 4 above. So in order for the Input Text component's help to show, the unique topic id must be associated to help content in the map.xml file as illustrated here:

8. This is the content of the help file that will be accessed for the topic Id of concise_expanded.

9. Now you can test the application.
10. 1. Assuming your standalone instance of WLS is running and the ohw-links application has been deployed and is active, you can simply right select on the JSF page that you've created and select run from context. This is the simple ADF application with one input field. Notice the blue question mark icon that was added as an artifact of the HelpProvider and the fact that a HelpTopicId is associated with help content for this Input Text component.

2. If I put the cursor in the box, we get embedded Help as expected.

3. Upon selecting the blue question mark icon we get a new window with OHW-RC Help system providing the content for this component.

We'll now take a look at using OHW-RC as a standalone document viewer of Help content.

OHW-RC as a standalone document viewer of Help content

This section of the How-To provides a rather high-level overview of using OHW-RC as a standalone document viewer of Help content. This simply requires swapping out the helpsets in the provided OHW-RC Thick or Thin Demo Ear that is provided on the Oracle Help page on OTN.

1. Start the Admin Server for WebLogic Server Domain
2. Launch the Admin Server Console

3. Select "Deployments".
4. Select "Install".
5. Navigate to the location of the ohw-rcf-demo-thick.ear if you are deploying to a WLS Server Domain that is not configured for ADF. Otherwise, if the domain is configured for ADF, navigate to the ohw-rcf-demo-thin.ear.
6. Select the applicable deployment based on your environment and select "Next".
7. Select  "Install this deployment as an application" and selet "Next".
8. On the "Optional Settings" page select "Next".
9. Review your choices and click "Finish".
10. Select "Save" on the last page "Setting for ohw-rcf-demo-thick".
11. To test the application access it via  the following url "http://localhost:7001/ohw-rcf-demo/faces/helppages/main.jspx?config=OHW+Servlet+1".

Note this demo of the OHW-RC is also available via the Oracle Help Page on Oracle's Technology Network (OTN). 

For a complete understanding of what this demo provides please experiment with it. Notice that it contains the complete Oracle Help Guide along with an additional helpset on Shakespeare's Passages. Search is enabled as well as a table of contents and index. Additional functionality is also provided and left to the reader to explore.

14. To create an additional helpset, you can import the OHW-RC Thick Demo EAR into JDeveloper and explore the application workspace by selecting File | Import from the JDeveloper Menu. You can then create a new helpset that you would like to include and replace the existing helpsets if needed.

15. Select EAR as the file type.

16. Select "Copy Files to Application".

17. Explore the ohwconfig.xml file and helpsets directory  which consists of html essentially.

18.  To add a custom helpset one simply needs to create the html in a similar fashion as is illustrated in the helpset for ohw-rcf-demo-thick application. Further detail can be found on authoring helpsets in the Fusion Middleware Developer's Guide for Oracle Help on OTN.

This How-To has demonstrated both integrating OHW-RC with an ADF application as well as utilizing OHW-RC as a stand alone Help System. For further information on integrating OHW-RC with your ADF Applications please refer to the Oracle Fusion Middleware Developer's Guide for Oracle Help 11 g Release 1 (5.0) .