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:
Section D.5, "Implementing Context-Sensitive Help in a Web Application"
Section D.6, "Upgrading OHW-UIX Help System to OHW Help System"
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.
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 numbered callouts identify the following user interface components:
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.
Helpset switcher: If you have more than one helpset, you can specify whether to merge them or to enlist them separately in this dropdown.
Tab bar: The default tabs are Contents, Index, Search, and View Topic.
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:
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
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.
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-6 Advanced Search Navigator in OHW-UIX
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
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.
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:
Section D.3.2, "Installing the OHW-UIX Demo EAR File on Oracle WebLogic Server"
Section D.3.3, "Installing the OHW-UIX Demo EAR File using Oracle JDeveloper"
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.
Directory Location | Description |
---|---|
|
Java EE application: a simple OHW-UIX application. The file is available in |
|
A web module containing three helpsets: The helpsets directory exists in the |
|
The UIX installable resource files. The |
|
Contains configuration and deployment information that affects OHW-UIX. The file ise available in |
|
OHW-UIX configuration file. The file is available in |
Installing the demo EAR file is a very simple process:
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.
Start the Oracle WebLogic Administration Console and navigate to Deployments page.
In the Deployments page, click Install to start the deployment wizard.
In the Path field, enter the location where you saved the ohw-uix-demo.ear
file, and click Next.
In the Choose targeting style page, select Install this deployment as an application, and click Next.
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.
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.
To install the demo file on Oracle JDeveloper, follow these steps:
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.
Start JDeveloper.
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.
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.
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.
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.
In the Applications window, open the project and edit desired files.
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.
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.
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".
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:
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. |
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.
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:
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
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.
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:
Modify the <books></books>
section to direct it to your helpset. For example:
<books> <helpSet id="myModule" location="my_ModuleHelpset/my_ModuleHelpset.hs" /> </books>
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.
Update the <brandings></brandings>
section to display your own brand. For example:
<brandings> <branding text="My Module" /></brandings>
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.
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.
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:
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>
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.
Compress the <OHW-UIX_deployment_name>
directory into a WAR file.
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".
Compress the <OHW-UIX_HOME>
directory into a EAR file.
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.
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.
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:
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>
To change the access URL for your application, edit the <context-root>
element entry under <web>
element in application.xm
l, 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>
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.
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:
Section D.5.2, "Creating Context-Sensitive Links to the Help System"
Section D.5.3, "Implementing Context-Sensitive Help in Oracle UIX-based Applications"
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".
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.
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).
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.
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".
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.
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).
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.
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:
To specify the location of the ohw-config.xml
for a OHW-UIX servlet instance, define OHW_UIX servlets with <init-param>
named ohwConfigFileURL
.
Define the URL mapping for OHW-UIX servlets. You do not have to change the existing servlet mappings.
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>