D Oracle Help for the Web – UIX

This appendix describes Oracle Help for the Web – UIX (OHW-UIX). OHW-UIX is a Java servlet and a file formats specification for developing and delivering HTML-based help content in a web environment.

OHW-UIX can be used to provide context-sensitive help for web applications or as means for processing and displaying structured views of independent HTML content on the web. With OHW-UIX, a user needs only a web browser to navigate and view help content. The processing takes place on the server, through the OHW-UIX servlet. Because the help content is managed on a server and displayed in any number of web browsers, many users have access to a single installation of the help.

This appendix includes the following sections:

D.1 About Oracle Help for the Web – UIX

OHW-UIX is the previous version of Oracle Help for the Web. If you are creating a new help system, it is recommended that you create the help system using Oracle Help for the Web, instead of choosing OHW-UIX. You should use OHW-UIX if you are building applications with Oracle's ADF UIX technology.

OHW-UIX includes the following:

  • The OHW-UIX servlet: The OHW-UIX servlet is installed on a web server to provide help to multiple users who access the help system through a web browser. Among other tasks, the OHW-UIX servlet does the following:

    • Parses and merges helpsets

    • Processes searches

    • Generates the OHW-UIX user interface and delivers it to users' web browsers

    • Delivers the help content for display through OHW-UIX in users' web browsers

    The OHW-UIX user interface includes all features available in OHJ's Java user interface, but they are rendered as HTML in users' browsers. Features include a table of contents, index, and text search.

    The help content files and control files (the same HTML and XML files that are used in OHJ) can be stored on the same server as the servlet or can be spread out over multiple servers in different locations.

  • Documentation: Documentation includes this Guide.

D.2 OHW-UIX User Interface

The Oracle Help for the Web – UIX (OHW-UIX) user interface provides the same features as that of Oracle Help for Java (OHJ). However, since OHW-UIX is a web application, there are some differences in appearance and behavior.

OHW-UIX help system is recommended if you are building applications with Oracle ADF UIX technology. If you are not using ADF UIX technology, you must use Oracle Help for the Web – Rich Client help system. For more information, see Chapter 3, "Oracle Help for the Web User Interface".

Figure D-1 OHW-UIX User Interface

Description of Figure D-1 follows
Description of "Figure D-1 OHW-UIX User Interface"

Figure D-1 numbered callouts identify the following user interface components:

  1. Branding area: This area can contain text, an image, or both. Typically, this area identifies the help content or provides company information, such as the name and logo.

  2. Helpset switcher: If you have more than one helpset, you can specify whether to merge them or to enlist them separately in this dropdown.

  3. Tab bar: The default tabs are Contents, Index, Search, and View Topic.

  4. Content area: When a tab is selected, the content associated with that tab appears in this area.

With the exception of the branding area, these elements are configured in the helpset file. OHW-UIX and OHJ use the exact same file formats, including the helpset file. That means that you can take an existing OHJ help system and deploy it as an OHW-UIX system, without changing any of your existing control files. OHW-UIX uses the same directives from the helpset file to construct its user interface as are used by OHJ to configure its user interface. To deploy a help system as an OHW-UIX system, you must configure and deploy a servlet container, and you must add an OHW-UIX configuration file. The branding information is specified in this file, among other configuration parameters.

For more information about deploying OHW-UIX system, see Section D.4, "Understanding OHW-UIX Deployment".

Comparing OHW-UIX Tabs with OHJ Tabs

The standard tabs (also called Navigators) in OHW-UIX are Contents, Index, Search, and View Topic. The Contents, Index, and Search tabs correspond to the same tabs that appear in an OHJ navigation window for a helpset. The View Topic tab takes the place of the topic window in OHJ.The OHW-UIX navigators remember their state for the current user. That means that if you switch from one tab to another, or follow a series of links from a topic, the previously visited tabs retain their contents. For example, if you perform a search in the Search tab and then follow several links from one of the topics found in your search, when you return to the Search tab, your most recent search criteria and results are displayed. This is not a surprising feature for an application that resides on a local system (such as OHJ), but it is an important feature for a web application, where the application runs on a server and can be accessed by many remote users at the same time.The following topics describe the OHW-UIX user interface elements in more detail, including comparisons to OHJ:

D.2.1 OHW-UIX Table of Contents

In contrast to OHJ, which shows the Table of Contents (TOC) as a tree, the OHW-UIX TOC displays the hierarchy of a help system as a sequence of pages. Each page shows one node in the hierarchy, and that page can list both, topics and child nodes (that is, nodes that fall under the current node). When you select a topic title, OHW-UIX switches to the View Topic tab, where the contents of that topic are displayed. When you click the title of a node in the Contents tab, the page is refreshed to show the listing for that node. When you navigate through a hierarchy, the navigation trail, or breadcrumbs, is shown as a set of links at the top of the page. This provides a quick way to navigate back to a previous level in the hierarchy.

Figure D-2 Table of Contents View in OHW-UIX

Description of Figure D-2 follows
Description of "Figure D-2 Table of Contents View in OHW-UIX"

D.2.2 OHW-UIX Index

The OHW-UIX keyword index is also slightly different from the one in OHJ. As in OHJ, the OHW-UIX index has a text field labelled Go to where you can enter words you want to find in the index. In contrast to OHJ, you must select Go or press the Enter key before the associated words are displayed. OHW-UIX displays only 10 items at a time, but it also has controls for navigating through the entire list of items that match what was entered in the Go To field. If there is no entry in the Go To field, you can navigate through the entire keyword list.

When you select an item from the list of keywords, the page is refreshed with a list of topics associated with the selected keyword. This is equivalent to the list of found topics at the bottom of the OHJ Index tab. When you select an item from the list, OHW-UIX switches to the View Topic tab, where the topic is displayed.

The Topics for page in the index has navigation links at the top of the page, similar to the one described for the table of contents. However, this link always takes you back to the list of keywords.

Figure D-4 Index Views in OHW-UIX

Description of Figure D-4 follows
Description of "Figure D-4 Index Views in OHW-UIX"

D.2.3 OHW-UIX Search

The OHW-UIX text search is similar to the index. You enter a word or phrase in the Search text field, press Enter, and OHW-UIX displays a list of associated topics. The first ten items are displayed (the list is sorted by rank), and you can navigate through further items in the list. In Advanced Search mode, you can also specify options for your search, like case sensitivity, match all words, match any words, or use a boolean expression.

As in the index, when you select an item from the list of topics found, the topic is displayed in the View Topic tab.

Figure D-5 Search Navigator in OHW-UIX

Description of Figure D-5 follows
Description of "Figure D-5 Search Navigator in OHW-UIX "

Figure D-6 Advanced Search Navigator in OHW-UIX

Description of Figure D-6 follows
Description of "Figure D-6 Advanced Search Navigator in OHW-UIX"

D.2.4 OHW-UIX Topics

Topics in OHW-UIX are displayed in the View Topics tab. This navigator supports several special features from OHJ, including topic ID links, associative links, and popups. In OHJ, these features were processed by the ICEbrowser display engine. In OHW-UIX they work in any browser. For more information about these features, see Chapter 7, "Topic Files".

Figure D-7 Content (Topic) Views in OHW-UIX

Description of Figure D-7 follows
Description of "Figure D-7 Content (Topic) Views in OHW-UIX "

To locate the topic in Table of Contents, click Locate in 'Contents'. To take a print of the topic, click Printable Page. A new printable page is created without navigation tabs, help title, and helpset switcher.

D.3 Deploying OHW-UIX Demo File

This chapter describes how to deploy OHW-UIX demo file on Oracle WebLogic Server.

The OHW-UIX demo EAR file contains the class libraries that you must view the demo and try out the release. It includes sample helpsets, OHW-UIX servlet file, and XML configuration files. You can deploy the demo file to experience the OHW-UIX interface, or replace the existing helpsets and add your own.

The following sections help you understand the demo file, deploy and test the sample helpset in your environment, and optionally add your own helpset for testing and deployment:

D.3.1 Understanding the OHW-UIX Demo File

The OHW-UIX demo file, ohw-uix-demo.ear, contains three OHW-UIX sample helpsets along with their help topics, helpset file, and control files. It also contains ohwconfig.xml which is needed to configure OHW-UIX.

The OHW demo EAR file extracts files into the ohw-uix-demo directory. The EAR file, when extracted, contains an ohw-uix-demo.war file and creates the META-INF directory, which contains the application.xml file. The ohw-uix-demo.war when extracted into ohw-uix-demo directory contains the helpsets directories along with their help topics, helpset file, and control files.

Table D-1 describes the files and directories in OHW-UIX demo file.

Table D-1 OHW-UIX Demo Files

Directory Location Description

application.xml

Java EE application: a simple OHW-UIX application.

The file is available in META-INF directory.

helpsets

A web module containing three helpsets: blafdoc, ohguide, and the sample shakespeare, in their respective directories.

The helpsets directory exists in the ohw-uix-demo.war file.

cabo

The UIX installable resource files.

The cabo directory exists in the ohw-uix-demo.war file.

web.xml

Contains configuration and deployment information that affects OHW-UIX.

The file ise available in WEB-INF directory of ohw-uix-demo.war file.

ohwconfig.xml

OHW-UIX configuration file.

The file is available in helpsets directory.


D.3.2 Installing the OHW-UIX Demo EAR File on Oracle WebLogic Server

Installing the demo EAR file is a very simple process:

  1. Download the OHW-UIX demo EAR file from OTN. The name of the demo file is ohw-uix-demo.ear. This file includes OHW-UIX and sample helpsets.

  2. Start the Oracle WebLogic Administration Console and navigate to Deployments page.

  3. In the Deployments page, click Install to start the deployment wizard.

  4. In the Path field, enter the location where you saved the ohw-uix-demo.ear file, and click Next.

  5. In the Choose targeting style page, select Install this deployment as an application, and click Next.

  6. In the Optional Settings page, verify the settings. It is recommended that you leave the settings as default. Click Next to continue, or click Finish to complete the deployment.

  7. In the Additional Configuration page, select Yes, take me to the deployment's configuration screen and click Finish to complete the deployment.

    The deployment wizard, after successful deployment, returns you to the Settings page of ohw-uix-demo.ear. If there are errors while deploying the file, you are navigated to Deployment home page where the errors are listed in red text.

D.3.3 Installing the OHW-UIX Demo EAR File using Oracle JDeveloper

To install the demo file on Oracle JDeveloper, follow these steps:

  1. Download the OHW-UIX demo EAR file from OTN. The name of the demo file is ohw-uix-demo.ear. This file includes OHW-UIX and sample helpsets.

  2. Start JDeveloper.

  3. Create a new application from the ohw-uix-demo.ear file. From the File menu, select New. In the New Gallery dialog, select Applications under General category, and then select Application from EAR File from the Items list.

  4. In the Location page of Create Application from EAR File wizard, browse and select the ohw-uix-demo.ear file. You may also change the application name and the location of application. Click Next to continue.

  5. The EAR Modules page of the wizard shows the project name and the module name. Click Next to continue, or click Finish to create the application from EAR file.

  6. The Finish page of the wizard shows a summary of your settings for the application. Click Finish to create the application from EAR file. JDeveloper extracts all files from the EAR file and creates an application which is ready to edit and deploy.

  7. In the Applications window, open the project and edit desired files.

  8. To deploy the application, start the integrated Oracle WebLogic Server instance. From Run menu, choose Start Server Instance to start the integrated Oracle WebLogic Server.

  9. In the Applications window, select the ohw-uix-demo project. From the Application menu, select Deploy. Then from the submenu, select ohw-uix-demo, to, and then select IntegratedWLSConnection. JDeveloper starts the deployment process and the status of the deployment is reflected in the Log window.

    When the application is successfully deployed, JDeveloper prompts with Deployment finished message in the Log window.

D.3.4 Running the OHW-UIX Demo EAR File

After successful deployment of ohw-uix-demo.ear, open your browser and navigate to the following URL:

http://<yourHost>:<yourPort>/ohw-uix-demo/help/ 

For example:

If you have installed Oracle WebLogic Server on your local system, you can open the demo help file with the following URL:

http://localhost:7101/ohw-uix-demo/help/

The URL automatically changes to http://localhost:7101/ohw-uix-demo/help/state?navSetId=ohguide&navId=0&destination= and the help opens with Table of Contents view. For more information on user interface of OHW-UIX, see Section D.2, "OHW-UIX User Interface".

D.4 Understanding OHW-UIX Deployment

Help authors create help content using the authoring tools of their choice. Help authors usually also create the Oracle Help control files that are needed for deploying the help content as OHW-UIX help systems. OHW-UIX administrators typically perform all tasks necessary to deploy a helpset.

Because both help authors and OHW-UIX administrators may want to perform deployments for testing or production, demo deployment files are provided. You can download the latest demo files from OTN.

If you are new to OHW-UIX, you may start with deploying the demo ohw-uix-demo.ear file. For more information, see Section D.3.1, "Understanding the OHW-UIX Demo File". The demo EAR file includes the files needed to deploy the sample helpsets immediately.

If you are creating a new OHW-UIX helpset, the following sections help you understand the OHW-UIX deployment process and describe the steps required to create and deploy your own OHW-UIX help system.

Unless configuration files have already been created and the application server configured, the OHW-UIX administrator needs to perform these tasks to deploy an OHW-UIX help system:

D.4.1 Verifying Requirements and Dependencies

Verify all requirements and dependencies before beginning any deployment:

Table D-2 OHW-UIX Deployment Minimum Requirements

Requirement Description

Servlet Container

OHW-UIX requires a JavaEE 1.5 compatible application server. Oracle WebLogic Server, standalone or integrated with JDeveloper, is recommended as it requires minimal configuration effort.

Client

The client receives only HTML, and all it requires is a web browser to display and view the OHW-UIX help content. The web browser must have JavaScript support enabled.

OHW-UIX is supported on Microsoft Internet Explorer 7, Microsoft Internet Explorer 8, Mozilla FireFox 2, Mozilla FireFox 3, Apple Safari, and Google Chrome.

UIX

OHW-UIX is a UIX application.

UNIX Only:X Server

On Unix, the servlet container must be configured to connect to an X server in order for dynamic image generation to succeed.


D.4.2 Understanding OHW-UIX Configuration Files

Before you start deploying the OHW-UIX helpset, there are some files that must be modified to configure OHW-UIX correctly. The following information helps you understand the XML configuration files:

  • application.xml: A manifest of all web modules that run under a given Java EE application. It points to each web module of each product that is deployed. Oracle recommends using two instances of application.xml:

    • A relatively stable version for the UIX application (optional).

    • A version for the OHW-UIX application that changes frequently as web modules are added or reconfigured.

    The name and location of application.xml is fixed by the Java EE standard. In OHW-UIX, the file must be located <OHW-UIX_HOME>\META-INF directory.

  • web.xml: Sets the initialization parameters for the servlet, including the location of the OHW-UIX configuration file. There is one instance of web.xml for each web module. If OHW-UIX configuration files are located and named in a uniform manner, then this file should be the same for all OHW-UIX web modules. The file must be located in <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF\directory.

  • ohwconfig.xml (default file name): Specify which helpsets to display and how to present them. You can also specify locales, branding information, and various other settings. For information about the configuration file, see Chapter 8, "Oracle Help for the Web Configuration File". The name and location of this file is set as a servlet initialization parameter, which is handled differently for each servlet container. The file must be located in <OHW-UIX_HOME>\<OHW-UIX_deployment_name> directory.

D.4.3 Configuring OHW-UIX to Display Custom Helpsets

The instructions in this section helps you create the directory structure required for OHW-UIX help system, add your custom helpset files in the correct location, create or modify the configuration files, and deploy the help system on application server.

The instructions in this section also assume that you have installed the OHW-UIX demo EAR file and you have a knowledge of the demo EAR file's directory structure. If you have not installed the demo file, install it following instructions in Section D.3.1, "Understanding the OHW-UIX Demo File".

Follow these steps to set up OHW-UIX help system:

  1. Set up the directory structure as following:

    <OHW-UIX_HOME>
      |
      — <OHW-UIX_deployment_name>
          |
          — cabo
          — helpsets
              |
              — <custom_helpset_directory>
          — META-INF
          — WEB-INF
              |
              — lib
      — META-INF
    

    For example:

    my_module
      |
      — my_module_help
          |
          — cabo
          — helpsets
              |
              — my_ModuleHelpset
          — META-INF
          — WEB-INF
              |
              — lib
      — META-INF
    
  2. Create your own helpset directory. Place all your help files in or under <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\helpsets\<custom_helpset_directory> directory, including the helpset file, topic files, and the other control files (index, table of contents, and so on). Also, place any JAR files here, if you are using JAR files for your helpset. You can use JARred and unJARred helpsets together in the same deployment.

  3. Copy the ohwconfig.xml from ohw-uix-demo\ohw-uix-demo\helpsets directory and save it in <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\helpsets directory. Then, update and configure the configuration file:

    1. Modify the <books></books> section to direct it to your helpset. For example:

      <books>
        <helpSet id="myModule" location="my_ModuleHelpset/my_ModuleHelpset.hs" />
      </books>
      
    2. Remove the helpsets which you do not want to provide from the <books></books> section. If removed, the helpsets would not appear in the helpset switcher dropdown list of the OHW-UIX user interface. If you have only one <helpSet> element in the <books></books> section, the helpset switcher is not available.

    3. Update the <brandings></brandings> section to display your own brand. For example:

      <brandings>  <branding text="My Module" /></brandings>
      
  4. Copy the cabo files from ohw-uix-demo\ohw-uix-demo\cabo directory to <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\cabo, and library files from ohw-uix-demo\ohw-uix-demo\WEB-INF\lib directory to <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF\lib directory.

  5. Copy the uix-config.xml from ohw-uix-demo\ohw-uix-demo\WEB-INF directory and save it in <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF directory. Then, edit the file to your requirements.

  6. Copy the web.xml from ohw-uix-demo\ohw-uix-demo\WEB-INF directory and save it in <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF directory. Then, edit it to your requirements:

    1. Modify the <display-name></<display-name> and <description></description> section to display your custom helpset name. For example:

      <web-app>
        <display-name>My Module</display-name>
        <description>My module help</description>
      </web-app>
      
    2. Optionally, you may want to edit the <servlet-name> element under <servlet> element to change your URL used to access OHW-UIX. For more information about changing the access URL, see Changing the OHW-UIX Access URL.

  7. Compress the <OHW-UIX_deployment_name> directory into a WAR file.

  8. Copy the application.xml from ohw-uix-demo\META-INF directory and save it in <OHW-UIX_HOME>\META-INF directory. Then, edit it to your requirements. In this file, you provide the web module name of each product that you deploy. Specify the WAR file name, created in step 7, in <web-uri></web-uri> element. If you want to change the access URL of the application, update the <context-root></context-root> element. For more information, see Section D.4.4, "Changing the OHW-UIX Access URL".

  9. Compress the <OHW-UIX_HOME> directory into a EAR file.

  10. Start the Oracle WebLogic Server and deploy the EAR file. If Oracle WebLogic Server is already running, you must shut it down and then restart it before the changes made since you last started the servlet is available.

  11. Direct the browser to http://<hostname>:<port>/<OHW-UIX_deployment_name>/help/, where <hostname> is the name of the system on which OHW-UIX and Oracle WebLogic Server are installed.

    The first page of the demo help system displays in the browser. If there is more than one helpset, use the dropdown list in the toolbar to select a helpset, then click the helpset switcher to display the TOC and index from the selected helpset only. The text search searches only for items in the selected helpset.

D.4.4 Changing the OHW-UIX Access URL

The URL to access OHW-UIX is http://<hostname>:<port>/mymodule/help/, where <hostname> is the name of the system on which OHW-UIX and Oracle WebLogic Server are installed.

You can change this URL in the following ways:

D.4.4.1 Changing the final URL element of the access URL

To change the help at the end of the URL, edit web.xml in <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF.

The <servlet-mapping> parameter <url-pattern> specifies the URL used to access OHW-UIX. For example, if you change <url-pattern> from the default /help/* to /onlinereference/*, the URL used to access OHW-UIX would become http://<hostname>:<port>/mymodule/onlinereference/.

For example:

<servlet-mapping>
   <servlet-name>mymodule</servlet-name>
   <url-pattern>/onlinereference/*</url-pattern>
</servlet-mapping>

D.4.4.2 Changing the access URL to another name

To change the access URL for your application, edit the <context-root> element entry under <web> element in application.xml, located in <OHW-UIX_HOME>\META-INF:

<web>
   <web-uri>my_module.war</web-uri>
   <context-root>my_module</context-root>
</web>

For example, if you want the OHW-UIX access URL to be http://<hostname>:<port>/jdeveloper/help/, modify the root element:

<web>
   <web-uri>my_module.war</web-uri>
   <context-root>jdeveloper</context-root>
</web>

D.4.5 Upgrading OHW-UIX and UIX

When new versions of OHW-UIX and UIX are released, be sure to check the OHW-UIX and UIX download pages for the latest download and install instructions before upgrading your OHW-UIX installation.

  • To upgrade OHW-UIX to a newer version, you must replace the OHW-UIX JAR file located in the WEB-INF/lib directory.

  • To upgrade UIX to a newer version, you must replace the UIX JAR file located in the WEB-INF/lib directory, and also replace the UIX installable resource files (distributed in uix2-install.zip) by unpacking them into the cabo directory.

To test your upgrade, restart the servlet container and point your browser to http://<hostname>:<port>/ohw-uix-demo/help/, or wherever you have mapped the OHW-UIX application.

D.5 Implementing Context-Sensitive Help in a Web Application

Oracle Help for the Web – UIX (OHW-UIX) 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, or 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-UIX:

D.5.1 Mapping Topic IDs to Help Topics

OHW-UIX context-sensitive help systems rely on one or more map files that map topic IDs to help topic HTML files. In a helpset, the map file is in 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 must coordinate your efforts with the help author.

Here's a sample map XML file:

<?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 would be displayed in. For more information about the elements used in the map file, see Section 12.3.2, "Contents of an OHJDK Release".

D.5.2 Creating Context-Sensitive Links to the Help System

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

When creating a link to OHW-UIX 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. You can also specify a locale in the URL destination.

D.5.2.1 Linking to the Front Page

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

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

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

http://www.yourcompany.com:7101/ohw-uix/help/

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

D.5.2.2 Linking to a Topic

To create the URL for linking to a topic, add a topic parameter to the URL of the OHW-UIX 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:7101/ohw-uix/help/?topic=topic_1

When implementing context-sensitive links to OHW-UIX, you may also want 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-UIX displays the file associated with the topic ID in a window page that does not include the OHW-UIX navigators (tabs). However, the topic page has a link to the front page of the help system should the user want to access the main help.

D.5.2.3 Specifying the Locale

When you link to any OHW-UIX page, including topic pages or front pages, you can include a locale in the URL of the OHW-UIX servlet with the locale query parameter.

The topic syntax is:

http://<server>:<port>/<servlet-mapping>/?topic=<topic-id>&locale=<ISO-code>

and the front page syntax is:

http://<server>:<port>/<servlet-mapping>/help?locale=<ISO-code>

If you specify the locale, OHW-UIX switches to the localized helpset if it is available, and keeps using the specified locale until it is overridden or removed. If the specified localized helpset is not available, the parameter is ignored.

For example:

http://www.yourcompany.com:7101/ohw-uix/help/?topic=topic_1&locale=sp

For more information about locale, see Chapter 8, "Oracle Help for the Web Configuration File".

D.5.3 Implementing Context-Sensitive Help in Oracle UIX-based Applications

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

Note:

UIX is not shipped with current release of JDeveloper, but if you want to use UIX, download JDeveloper 10.1.2 or any earlier release from OTN archives. More information about the uix-config.xml file is available in the JDeveloper online help.

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

To use the OracleHelpProvider, you must register OHW-UIX with the application, then specify the context-sensitive help links through databinding.

D.5.3.1 Registering OHW-UIX in the OracleHelpProvider

The first step in using the OracleHelpProvider is to register your OracleHelpProvider instance (i.e., OHW-UIX) 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 do not require to declare it in your UIX page, it is available in all pages once you register your HelpProvider with the Configuration object.

In UIX, 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.

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

Here is a 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:7101/ohw-uix</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-UIX. Once you've set this property, all uiXML and UIX Java pages have access to two data providers: ui:helpTopics and ui:helpSystem.

In UIX, if you want 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 UIX, see the following sample code.

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:7101/ohw-uix/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).

D.5.3.2 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-UIX 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"/>

When a user requests help for a user interface control that is linked to the front page, OHW-UIX is displayed in the user's browser, showing the first page of the help system.

Note:

The first page of the help system is defined as the first navigator declared in the .hs file and the first book defined in the OHW-UIX configuration file (ohwconfig.xml or another name specified by the configFileName initialization parameter for the servlet). Typically the first navigator of the first book is a table of contents.

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 want to access the main help.

D.6 Upgrading OHW-UIX Help System to OHW Help System

When upgrading from OHW-UIX to OHW, the helpsets contents may remain unchanged, however, there are two things you must do to use OHW:

  • Copy the OHW jar files into the WEB-INF/lib directory.

  • Modify the web.xml file under the WEB-INF/ directory. The best way to do this is to get the web.xml from the OHW demo bundle and copy the servlet and resource definitions and mappings.

There are three major parts required in a web.xml for OHW:

  • Basic configuration for JSF Trinidad and ADF RC (Faces Servlet, Trinidad Servlet and Filter, and so on):

    <context-param>
      <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
      <param-value>client</param-value>
    </context-param>
     
    <filter>
      <filter-name>trinidad</filter-name>
      <filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
    </filter>
     
    <filter-mapping>
      <filter-name>trinidad</filter-name>
      <servlet-name>Faces Servlet</servlet-name>
    </filter-mapping>
     
    <servlet>
      <servlet-name>Faces Servlet</servlet-name>
      <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
      <load-on-startup>1</load-on-startup>
    </servlet>
     
    <servlet-mapping>
      <servlet-name>Faces Servlet</servlet-name>
      <url-pattern>/faces/*</url-pattern>
    </servlet-mapping>
     
    <servlet>
      <servlet-name>resources</servlet-name>
      <servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-class>
    </servlet>
     
    <servlet-mapping>
      <servlet-name>resources</servlet-name>
      <url-pattern>/adf/*</url-pattern>
    </servlet-mapping>
     
    <servlet-mapping>
      <servlet-name>resources</servlet-name>
      <url-pattern>/afr/*</url-pattern>
    </servlet-mapping>
    
    <servlet-mapping>
      <servlet-name>resources</servlet-name>
      <url-pattern>/ohr/*</url-pattern>
    </servlet-mapping> 
    
  • Basic configuration for OHW:

    You must define an OHW Filter and map it to the Faces servlet.

    <filter>
      <filter-name>OHWRCFRequestFilter</filter-name>
      <filter-class>oracle.help.web.rich.OHWFilter</filter-class>
    </filter>
     
    <filter-mapping>
      <filter-name>OHWRCFRequestFilter</filter-name>
      <servlet-name>Faces Servlet</servlet-name>
    </filter-mapping>
    
  • OHW-UIX Servlet definition and servlet mapping:

    The existing OHW-UIX servlet definitions must be changed to use the OHW class oracle.help.web.rich.OHWServlet. The following steps describe how to change existing OHW servlet definitions:

    1. To specify the location of the ohw-config.xml for a OHW-UIX servlet instance, define OHW_UIX servlets with <init-param> named ohwConfigFileURL.

    2. Define the URL mapping for OHW-UIX servlets. You do not have to change the existing servlet mappings.

    3. Specify the <load-on-startup> parameter.

    OHW supports multiple OHW instances in one Web application. Here is an example which deploys two OHW instances in a web.xml:

    <!-- configuration for product1 help front servlet -->
    <servlet>
      <servlet-name>product1</servlet-name>
      <servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
      <init-param>
        <param-name>ohwConfigFileURL</param-name>
        <param-value>/helpsets/product1/ohwconfig.xml</param-value>
      </init-param>
      <load-on-startup>2</load-on-startup>
    </servlet>
    
    <servlet-mapping>
      <servlet-name>resources</servlet-name>
      <url-pattern>/ohr/*</url-pattern>
    </servlet-mapping> 
     
    <!-- configuration for product1 help front servlet -->
    <servlet>
      <servlet-name>product2</servlet-name>
      <servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
      <init-param>
        <param-name>ohwConfigFileURL</param-name>
        <param-value>/helpsets/product2/ohwconfig.xml</param-value>
      </init-param>
      <load-on-startup>3</load-on-startup>
    </servlet>
     
    <servlet-mapping>
      <servlet-name>product1</servlet-name>
      <url-pattern>/product1/*</url-pattern>
    </servlet-mapping>
     
    <servlet-mapping>
      <servlet-name>product2</servlet-name>
      <url-pattern>/product2/*</url-pattern>
    </servlet-mapping>