Oracle Help for the Web Developer's Guide	Contents	Previous	Next

Implementing Context-Sensitive Help in a Web Application

Oracle Help for the Web (OHW) provides a context-sensitive help mechanism that launches help topics that are associated with some context in the web application user interface. Typically, help topics are written to describe the function of a particular page, table, or input field in a web application. When a user requests help for a user interface control--for example by selecting a Help button--the appropriate topic for that context (control) is displayed.

To provide context-sensitive help for a web application, the help system must include one or more map files and the appropriate help code must be added to the application code.

The following sections describe how to implement context-sensitive help using OHW:

Mapping Topic IDs to Help Topics
Creating Context-Sensitive Links to the Help System
Implementing Context-Sensitive Help in Oracle UIX-based Applications

Mapping Topic IDs to Help Topics

OHW context-sensitive help systems rely on one or more map files that map topic IDs to help topic HTML files. In a helpbook, the map file is in the OHT file format; in a helpset, the map file is in an XML file format.

The map file is usually created by the help author. As a web application developer, when associating web application controls with context-sensitive topics you must use the topic IDs specified in the author's map file. Thus, you will have to coordinate your efforts with the help author.

Sample map file in XML format:

 <?xml version='1.0' ?>

 <map version="1.0">   
   <mapID target="topic_1" url="file_1.html" />        
   <mapID target="topic_2" url="file_2.html#a1" />     
   <mapID target="topic_3" url="file_3.html" wintype="intro" />
 </map>

The attribute target specifies a unique ID for the associated HTML file within a helpset. The attribute url specifies the location of the file to associate with the ID. The wintype attribute is optional; it specifies the name of a window type that the topic will be displayed in. See Oracle Help File Formats for more information about the elements used in the map file.

Creating Context-Sensitive Links to the Help System

Applications that rely on OHW for context-sensitive help request the context-sensitive topics via specially formulated URLs to the OHW servlet. Any user interface control with a URL destination (links, images, etc.) can be associated with a context-sensitive topic.

When creating a link to OHW for context-sensitive help, you can either use the URL destination for the front page (with the Contents, Index, and Search navigators), or you can create a URL destination for a topic using the topic ID.

Linking to the Front Page

The URL to the front page is simply the URL to the OHW servlet:


 http://<server>:<port>/<servlet mapping>

where <server> is the name of your server running the servlet engine, <port> is the port used by the servlet engine, and <servlet mapping> is the servlet mapping set up in the web.xml file for the OHW servlet (by default this is "ohw/help/"). For example:


 http://www.yourcompany.com:8888/ohw/help/

When a user requests help for a user interface control that is linked to the front page, OHW will be displayed in the user's browser, showing the first page of the help system (usually a table of contents).

Linking to a Topic

To create the URL for linking to a topic, add a topic parameter to the URL of the OHW servlet. The value of the topic parameter is the topic ID of the help topic:


 http://<server>:<port>/<servlet mapping>/?topic=<topic-id>

For example, the following URL requests the topic associated with the topic ID topic_1:


 http://www.yourcompany.com:8888/ohw/help/?topic=topic_1

When implementing context-sensitive links to OHW, you may also wish to use JavaScript to open the link in a secondary window rather than replace the main application page.

When a user requests help for a user interface control that is linked to a topic ID, OHW displays the file associated with the topic ID in a window page that does not include the OHW navigators (tabs). However, the topic page has a link to the front page of the help system should the user wish to access the main help.

Implementing Context-Sensitive Help in Oracle UIX-based Applications

UIX (available in Oracle JDeveloper) is an Oracle technology for creating web applications. UIX provides mechanisms that make it easy to provide context-sensitive help via OHW. With UIX, you can implement context-sensitive help programmatically using the UIX Java API, or declaratively using the UIX language (an XML language).

The HelpProvider architecture in UIX provides a generic context-sensitive help mechanism. OHW provides context-sensitive help for UIX applications through a specific implementation of HelpProvider called the OracleHelpProvider.

To use the OracleHelpProvider, you have to register OHW with the application, then specify the context-sensitive help links via databinding.

Registering OHW in the OracleHelpProvider

The first step in using the OracleHelpProvider is to register your OracleHelpProvider instance (i.e., OHW) with the UIX Configuration object. In UIX, the HelpProvider appears as a special UIX DataProvider that can be used for databinding. It is special in that you don't need to declare it in your UIX page, it is available in all pages once you register your HelpProvider with the Configuration object.

In UIX versions prior to 2.1.6, the way you typically modify the UIX Configuration is to write a PageBroker subclass and override the createDefaultConfiguration method. From UIX 2.1.6 onwards, you can use the uix-config.xml file and ApplicationConfiguration API to create a set of Configuration objects without writing a line of code, and update configuration properties in the field without recompiling code. (However, this feature is only available to developers using Servlet 2.1 or later, so applications deployed on Apache JServ must continue using Java code.) More information about the uix-config.xml file is available in the "Configuration" chapter of the UIX Developer's Guide, which is available in the JDeveloper online help, with the UIX download bundles, and in the JDeveloper documentation on OTN at http://helponline.oracle.com/jdeveloper/help/.

To register OHW with your application, you simply modify the uix-config.xml file to point UIX to an instance of the OHW servlet.

Sample uix-config.xml file

 <?xml version="1.0" encoding="ISO-8859-1"?>

 <configurations xmlns="http://xmlns.oracle.com/uix/config">
   ... 

   <default-configuration>

     <help-provider>
       <ohw-servlet-url>http://www.yourcompany.com:8888/ohw</ohw-servlet-url>
     </help-provider>

   </default-configuration>

   ...
 </configurations>

The <help-provider> element allows configuration of a help provider. The only supported syntax at this time is a contained <ohw-servlet-url> element. The ohw-servlet-url must contain an URL that points to an installation of OHW. Once you've set this property, all uiXML and UIX Java pages have access to two data providers: ui:helpTopics and ui:helpSystem. See Databinding a Destination for instructions on how to specify context-sensitive help declaratively.

In UIX 2.1.6 and later, if you still need to use Java code to create your Configuration object but want to use the default properties defined in the uix-config.xml file, you would use the following code:


 ApplicationConfiguration appConfig = 
   ApplicationConfiguration.getInstance(servletContext);
 configurationImpl impl = 
   new ConfigurationImpl ("someName", appConfig.getDefault());
 impl.register(servletContext);

To register OHW with your application programmatically in pre-2.1.6 versions of UIX, see the following sample code.

Sample code for the createDefaultConfiguration() method in pre-2.1.6 versions of UIX:


 protected ConfigurationImpl createDefaultConfiguration()
 {
   ConfigurationImpl cfg = super.createDefaultConfiguration();
   //For your application you'd likely pull the location of the
   //OHW servlet out of a servlet init parameter

   OracleHelpProvider provider = new OracleHelpProvider("http://www.yourcompany.com:8888/ohw/help/")
   cfg.setProperty(Configuration.HELP_PROVIDER, provider);
   return cfg;
 }

The HelpProvider sets up two special data objects (helpTopics and helpSystem in the UIX UI Components namespace). See Databinding a Destination for instructions on how to specify context-sensitive help declaratively.

Databinding a Destination

The HelpProvider sets up two data providers--ui:helpTopics and ui:helpSystem. (Here, ui is used as the prefix for the UIX UI namespace.) They are used for databinding the destination attribute of links or buttons (or any control that has a destination) from which you want to connect to the help system.

After registering OHW with your UIX-based application, you can then specify context-sensitive help declaratively using the data objects ui:helpTopics and ui:helpSystem.

Databinding a Destination to the Front Page

Using declarative UIX, a destination can be created for the front page by using the special frontPage key for the ui:helpSystem data object. For example:


 <globalButton icon="globalhelp.gif" text="Help" data:destination="frontPage@ui:helpSystem"/>

Databinding a Destination to a Topic

To show a topic, use the unique topic ID as the key for the ui:helpTopics data object. For example:


 <button text="Button To Help" data:destination="myTopicID@ui:helpTopics" />
 <link text="Link To Help" data:destination="someOtherTopicID@ui:helpTopics" />

At runtime, UIX uses the OracleHelpProvider instance to resolve the value of these destinations. The OracleHelpProvider automatically returns a destination that includes JavaScript to launch help in a separate, smaller browser window. This window has a link to the front page of the help system should the user wish to access the main help.