1 Introduction to Oracle Help

The Oracle Help technologies provide the means for developing and displaying HTML-based help systems for Java applications and for web applications. Authors can create a single help system that can be displayed—without modification—both in a Java environment, using Oracle Help for Java (OHJ); and in a web environment, using Oracle Help for the Web. Alternatively, you can just use Oracle Help for Java if you only need help in a Java environment, or you can just use Oracle Help for the Web if you only need help in a web environment. Oracle Help for the Web is available in two versions: Oracle Help for the Web – UIX(OHW-UIX) and Oracle Help for the Web – Rich Client (OHW-RC).

Throughout this Oracle Help Guide, Oracle Help is used when the comments apply to both Oracle Help for Java and Oracle Help for the Web. OHJ is used when the comments apply only to Oracle Help for Java. OHW-UIX is used when the comments apply only to Oracle Help for the Web – UIX and OHW-RC is used when the comments apply only to Oracle Help for the Web – Rich Client. OHW is used when the comments apply to OHW-UIX and OHW-RC both.

This chapter includes the following sections:

• Section 1.1, "Oracle Help for Java"

• Section 1.2, "Oracle Help for the Web – Rich Client"

• Section 1.3, "Oracle Help for the Web – UIX"

• Section 1.4, "Oracle Help in Oracle JDeveloper"

• Section 1.5, "Oracle Help Licensing and Support"

1.1 Oracle Help for Java

Oracle Help for Java is a set of Java components, a Java API, and a file formats specification for developing and displaying HTML-based help content in a Java environment. OHJ is designed primarily for displaying help for Java applications, although it can also be implemented as a stand-alone document viewer for use in a Java environment.

The Oracle Help for Java Developer's Kit (OHJDK) includes the OHJ technology plus tools and documentation for developing context-sensitive help for Java applets and applications. This includes the following:

• Java components: OHJ includes a set of default Java user interface components that together comprise a complete help system, with a table of contents, index, search, and topic windows

• API: The OHJ API includes features for implementing context-sensitive help, for programmatically controlling how help is displayed (size, position, etc.), and for customizing and extending the help system. For example, you can replace a default component with your own, create custom controls, or embed selected components in an application

• Documentation: Documentation includes this Guide, plus the API reference (provided as JavaDoc documentation).

• Helpset Authoring Wizard: The Helpset Authoring Wizard helps you create Oracle Help control files without using a third-party authoring tool.

For more information about OHJ features, see Chapter 2, "OHJ User Interface".

1.2 Oracle Help for the Web – Rich Client

Oracle Help for the Web – Rich Client (OHW-RC), delivers HTML-based Help content in a Web environment. It uses the Oracle Application Developer Framework (ADF), which is based on the Java Server Faces (JSF) technology, to build a user interface that follows Oracle's Browser Look And Feel Plus (BLAF+) behaviors and guidelines.

Both OHW-RC and OHW-UIX share the same model layer to provide Help content, build the table of contents, process indexes, and execute searches. Similar to OHW-UIX, many users can have access to a single instance of OHW-RC, because the Help contents are processed at the server side.

The OHW-RC can be used in many different situations:

• As a help system providing context-sensitive Help to a rich client application in a new browser window

• As a standalone document viewer of Help content on a public website

• When a user performs a search on any popular search engine and the results link to indexed OHW-RC content

• When an ADF Faces component's runtime implementation requires to retrieve Embedded Help information (Definition Text, Instructions Text, or Full Help) using the HelpProvider interface it defines

OHW-RC includes the following:

• The OHW-RC Front Servlet: This is installed on a Web server, which enables OHW-RC to support same URL syntax for context sensitive help requests that was used in OHW UIX. It also enables an easy configuration to support multiple OHW-RC helpsets in a single web application.

• The OHW-RC Servlet Filter: This is used to pre-process requests sent to the JSF servlet.

• Documentation: Documentation includes this Guide.

1.3 Oracle Help for the Web – UIX

Oracle Help for the Web – 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, via 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.

You should use OHW-UIX if you are building applications with Oracle's 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 4, "OHW-UIX User Interface".

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

1.4 Oracle Help in Oracle JDeveloper

Besides being used for the internal JDeveloper help system itself, JDeveloper includes the Oracle Help for Java runtime library, so if you are developing Java applications with JDeveloper, it is easy to include OHJ as the Java help system technology. For more information, see Chapter 13, "Introduction to Oracle Help for Java Developer's Kit".

JDeveloper does not include the Oracle Help for the Web. You can obtain it, as well as the complete Oracle Help for Java development kit, from the Oracle Technology Network (OTN).

1.5 Oracle Help Licensing and Support

As a service to our customers and the software community, Oracle provides Oracle Help software and support for free. This includes both Oracle Help for Java (OHJ) and Oracle Help for the Web.

Oracle Help is available for free and may be redistributed as the help system for your application. For full information, see the license distributed with the release.

Post your questions on the Oracle Help Technologies Forum on the Oracle Technology Network, or send e-mail to [e-mail].