18 Understanding OHW-UIX Deployment

18.1 Verifying Requirements and Dependencies

Verify all requirements and dependencies before beginning any deployment:

18.2 Understanding OHW-UIX Configuration Files

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.

18.3 Configuring OHW-UIX to Display Custom Helpsets

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 17, "Deploying 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, 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.

3. 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:

   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 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.

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

      <brandings>  <branding text="My Module" /></brandings>
      

4. 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.

5. 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.

6. 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:

   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 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 .

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

8. 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 18.4.2, "Changing the access URL to another name".

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 will be available.

11. 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.

18.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 machine on which OHW-UIX and Oracle WebLogic Server are installed.

You can change this URL in the following ways:

• Changing the final URL element of the access URL

• Changing the access URL to another name

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

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

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

18.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 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.