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:
Verify all requirements and dependencies before beginning any deployment:
Table 22-1 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 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 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 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 <OHW-UIX_HOME>\<OHW-UIX_deployment_name> directory.
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
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, 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 ohw-uix-demo\ohw-uix-demo\helpsets directory.
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:
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 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.
Update the <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 <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF\lib directory.
You may also copy the library files from demo EAR file. The files are available in ohw-uix-demo\ohw-uix-demo\cabo and ohw-uix-demo\ohw-uix-demo\WEB-INF\lib directory.
Create the UIX configuration file uix-config.xml in <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF directory.
You may also copy the uix-config.xml from demo EAR file and edit it to your requirements. The file is available in ohw-uix-demo\ohw-uix-demo\WEB-INF directory.
Create web.xml to set the initialization parameters in <OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF directory.
You may also copy the web.xml from demo EAR file and edit it to your requirements. The file is available in ohw-uix-demo\ohw-uix-demo\WEB-INF directory.
If you are editing the demo EAR file's web.xml, follow these instructions:
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 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 .
Compress the <OHW-UIX_deployment_name> directory into a WAR file.
Create application.xml in <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".
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 will be available.
Direct the browser to http://<hostname>:<port>/<OHW-UIX_deployment_name>/help/, where <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.
The URL to access OHW-UIX is http://<hostname>:<port>/mymodule/help/, where <hostname> is the name of the machine 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.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>
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 need to replace the OHW-UIX JAR file located in the WEB-INF/lib directory.
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 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.