This chapter describes how to enable context-sensitive help in your web application and how to map topic IDs with the help topics.
This chapter includes the following sections:
Section 18.1, "About Implementing Context-Sensitive Help In a Web Application"
Section 18.3, "Creating Context-Sensitive Links to the Help System"
Oracle Help for the Web (OHW) 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 clicking 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.
OHW 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 saved in XML file format as map.xml.
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 will have to coordinate your efforts with the help author.
Here is a sample map file in XML format:
<?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 target attribute specifies a unique ID for the associated HTML file within a helpset. The url attribute 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 will be displayed in. For more information about the elements used in the map file, see Section 5.3, "Map Files".
Applications that rely on OHW for context-sensitive help request the context-sensitive topics via specially formulated URLs to the OHW servlet. Any user interface control with a URL destination (links, images, etc.) can be associated with a context-sensitive topic.
When creating a link to OHW for context-sensitive help, you can either use the URL destination for the front main page, which is a tripane-layout UI with the Contents, Index, and Search navigators on the left side, or you can create a URL destination for displaying a topic in tripane-layout UI using the topic ID. You can also specify a locale and a group in the URL destination.
The URL to the front main page is simply the URL to the OHW 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 servlet (oracle.help.web.rich.OHWServlet).
For example, in the web.xml, it has the following servlet definition and servlet mapping:
<!-- 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>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>product1</servlet-name>
<url-pattern>/product1/*</url-pattern>
</servlet-mapping>
In this example, the URL to the front main page is:
http://www.myhelpserver.com:8888/docs/product1/
When a user requests help for a user interface control that is linked to the front main page, the OHW tripane-layout main page will be displayed in the user's browser, showing the Contents, Index, and Search navigators on the left side.
To create the URL for linking to a topic, add a topic parameter to the URL of the OHW 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.myhelpserver.com:8888/docs/product1/?topic=topic_1
When implementing context-sensitive links to OHW, you may also wish 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 displays the tripane-layout UI with the topic file shown in the Topic Navigator (the right side), and Contents Navigator is shown in the left side with the topic highlighted in the TOC tree.
When you link to any OHW page, including topic pages or front pages, you can include a locale and a group in the URL of the OHW servlet with the locale and group query parameter.
The topic syntax is:
http://<server>:<port>/<servlet-mapping>/?topic=<topic-id>&locale=<ISO-code> http://<server>:<port>/<servlet-mapping>/?topic=<topic-id>&locale=<ISO-code>&group=<aGroup>
and the front page syntax is:
http://<server>:<port>/<servlet-mapping>/?locale=<ISO-code> http://<server>:<port>/<servlet-mapping>/?locale=<ISO-code>&group=<aGroup>
If you specify the locale, OHW switches to the localized helpset if it is available, and will keep 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.myhelpserver.com:7101/docs/product1/?topic=topic_1&locale=sp
For more information about locale and group, see Chapter 8, "Oracle Help for the Web Configuration File".