|Oracle® Fusion Middleware Developer's Guide for Oracle Help
11g Release 1 (5.1)
Part Number E14149-02
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 need 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 21.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 will 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:
Table 22-1 OHW-UIX Deployment Minimum Requirements
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.
OHW-UIX is supported on Microsoft Internet Explorer 7, Microsoft Internet Explorer 8, Mozilla FireFox 2, Mozilla FireFox 3, Apple Safari, and Google Chrome.
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 need to be modified to configure OHW-UIX correctly. The following information will help 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
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
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
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 9, "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
The instructions in this section will help 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 Chapter 21, "Deploying 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
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, etc.). 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.
Create the configuration file. In an editor, create an XML file and save it as
ohwconfig.xml, in the
<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\helpsets directory. You may also copy the
ohwconfig.xml from demo EAR file and edit it to your requirement. The file is available in
If you are creating a new
ohwconfig.xml file, see Chapter 9, "Oracle Help for the Web Configuration File" for more information about behaviors you can configure.
If you are editing the demo EAR file's
ohwconfig.xml, follow these instructions:
<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 wish 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.
<brandings></brandings> section to display your own brand. For example:
<brandings> <branding text="My Module" /></brandings>
Download the cabo and OHW-UIX library files from OTN. Copy the cabo files in
<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\cabo and library files in
You may also copy the library files from demo EAR file. The files are available in
Create the UIX configuration file
You may also copy the
uix-config.xml from demo EAR file and edit it to your requirements. The file is available in
web.xml to set the initialization parameters in
You may also copy the
web.xml from demo EAR file and edit it to your requirements. The file is available in
If you are editing the demo EAR file's
web.xml, follow these instructions:
<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 wish 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 .
<OHW-UIX_deployment_name> directory into a WAR file.
<OHW-UIX_HOME>\META-INF directory. In this file, you will provide the web module name of each product that you will deploy.
You may also copy the
application.xml from demo EAR file and edit it to your requirements. The file is available in
ohw-uix-demo\META-INF directory. Specify the WAR file name, created in step 7, in
<web-uri></web-uri> element. If you wish to change the access URL of the application, update the
<context-root><context-root> element. For more information, see Section 22.4.2, "Changing the access URL to another name".
<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 will be available.
Direct the browser to
<hostname> is the name of the machine 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 will search only for items in the selected helpset.
You can change this URL in the following ways:
To change the help at the end of the URL, edit
<url-pattern> specifies the URL used to access OHW-UIX. For example, if you change
<url-pattern> from the default
/onlinereference/*, the URL used to access OHW-UIX would become
<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.xml, located in
<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>
To upgrade OHW-UIX to a newer version, you need to replace the OHW-UIX JAR file located in the
To upgrade UIX to a newer version, you need to 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
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.