Integrating Help with your ADF Applications
An Oracle JDeveloper How To Document
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:
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.
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.
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:
These steps will be demonstrated through the use of the MyAppUsingOHW.jws application.
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.
In this adf-settings.xml file:
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.
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.
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. 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.
Note the Oracle Help for the Web configuration file is an XML file that defines a OHW configuration. This configuration controls all adjustable features of the OHW-RC and OHW-UIX servlet. A typical name for this file is ohwconfig.xml, but it can have any name, as long as that name is specified as the value of the configFileName initialization parameter for the servlet. This file will be covered in more detail in the prior section.