Oracle Help for the Web – UIX (OHW-UIX) 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 selecting 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.
The following sections describe how to implement context-sensitive help using OHW-UIX:
Section 23.2, "Creating Context-Sensitive Links to the Help System"
Section 23.3, "Implementing Context-Sensitive Help in Oracle UIX-based Applications"
OHW-UIX 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 in XML file format.
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's a sample map XML file:
<?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 attribute target specifies a unique ID for the associated HTML file within a helpset. The attribute url 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 13.2.2, "Contents of an OHJDK Release".
Applications that rely on OHW-UIX for context-sensitive help request the context-sensitive topics via specially formulated URLs to the OHW-UIX 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-UIX for context-sensitive help, you can either use the URL destination for the front page (with the Contents, Index, and Search navigators), or you can create a URL destination for a topic using the topic ID. You can also specify a locale in the URL destination.
The URL to the front page is simply the URL to the OHW-UIX 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-UIX servlet (by default this is ohw-uix/help/). For example:
http://www.yourcompany.com:7101/ohw-uix/help/
When a user requests help for a user interface control that is linked to the front page, OHW-UIX will be displayed in the user's browser, showing the first page of the help system (usually a table of contents).
To create the URL for linking to a topic, add a topic parameter to the URL of the OHW-UIX 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.yourcompany.com:7101/ohw-uix/help/?topic=topic_1
When implementing context-sensitive links to OHW-UIX, 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-UIX displays the file associated with the topic ID in a window page that does not include the OHW-UIX navigators (tabs). However, the topic page has a link to the front page of the help system should the user wish to access the main help.
When you link to any OHW-UIX page, including topic pages or front pages, you can include a locale in the URL of the OHW-UIX servlet with the locale query parameter.
The topic syntax is:
http://<server>:<port>/<servlet-mapping>/?topic=<topic-id>&locale=<ISO-code>
and the front page syntax is:
http://<server>:<port>/<servlet-mapping>/help?locale=<ISO-code>
If you specify the locale, OHW-UIX switches to the localized helpset if it is available, and will keep using the specified locale until it is overidden or removed. If the specified localized helpset is not available, the parameter is ignored.
For example:
http://www.yourcompany.com:7101/ohw-uix/help/?topic=topic_1&locale=sp
For more information about locale, see Chapter 9, "Oracle Help for the Web Configuration File".
UIX is an Oracle technology for creating web applications. UIX provides mechanisms that make it easy to provide context-sensitive help via OHW-UIX. With UIX, you can implement context-sensitive help programmatically using the UIX Java API, or declaratively using the UIX language (an XML language).
Note:
UIX is not shipped with current release of JDeveloper, but if you wish to use UIX, download JDeveloper 10.1.2 or any earlier release from OTN archives. More information about theuix-config.xml file is available in the JDeveloper online help.The HelpProvider architecture in UIX provides a generic context-sensitive help mechanism. OHW-UIX provides context-sensitive help for UIX applications through a specific implementation of HelpProvider called the OracleHelpProvider.
To use the OracleHelpProvider, you have to register OHW-UIX with the application, then specify the context-sensitive help links via databinding.
The first step in using the OracleHelpProvider is to register your OracleHelpProvider instance (i.e., OHW-UIX) with the UIX Configuration object. In UIX, the HelpProvider appears as a special UIX DataProvider that can be used for databinding. It is special in that you don't need to declare it in your UIX page, it is available in all pages once you register your HelpProvider with the Configuration object.
In UIX, you can use the uix-config.xml file and ApplicationConfiguration API to create a set of configuration objects without writing a line of code, and update configuration properties in the field without recompiling code.
To register OHW-UIX with your application, modify the uix-config.xml file to point UIX to an instance of the OHW-UIX servlet.
Here is a sample uix-config.xml file:
<?xml version="1.0" encoding="ISO-8859-1"?>
<configurations xmlns="http://xmlns.oracle.com/uix/config">
...
<default-configuration>
<help-provider>
<ohw-servlet-url>http://www.yourcompany.com:7101/ohw-uix</ohw-servlet-url>
</help-provider>
</default-configuration>
...
</configurations>
The <help-provider> element allows configuration of a help provider. The only supported syntax at this time is a contained <ohw-servlet-url> element. The ohw-servlet-url must contain an URL that points to an installation of OHW-UIX. Once you've set this property, all uiXML and UIX Java pages have access to two data providers: ui:helpTopics and ui:helpSystem.
In UIX, if you still need to use Java code to create your Configuration object but want to use the default properties defined in the uix-config.xml file, you would use the following code:
ApplicationConfiguration appConfig =
ApplicationConfiguration.getInstance(servletContext);
configurationImpl impl =
new ConfigurationImpl ("someName", appConfig.getDefault());
impl.register(servletContext);
To register OHW with your application programmatically in UIX, see the following sample code.
protected ConfigurationImpl createDefaultConfiguration()
{
ConfigurationImpl cfg = super.createDefaultConfiguration();
//For your application you'd likely pull the location of the
//OHW servlet out of a servlet init parameter
OracleHelpProvider provider = new OracleHelpProvider("http://www.yourcompany.com:7101/ohw-uix/help/")
cfg.setProperty(Configuration.HELP_PROVIDER, provider);
return cfg;
}
The HelpProvider sets up two special data objects (helpTopics and helpSystem in the UIX UI Components namespace).
The HelpProvider sets up two data providers—ui:helpTopics and ui:helpSystem. Here, ui is used as the prefix for the UIX UI namespace. They are used for databinding the destination attribute of links or buttons (or any control that has a destination) from which you want to connect to the help system.
After registering OHW-UIX with your UIX-based application, you can then specify context-sensitive help declaratively using the data objects ui:helpTopics and ui:helpSystem.
Databinding a Destination to the Front Page
Using declarative UIX, a destination can be created for the front page by using the special frontPage key for the ui:helpSystem data object. For example:
<globalButton icon="globalhelp.gif" text="Help" data:destination="frontPage@ui:helpSystem"/>
When a user requests help for a user interface control that is linked to the front page, OHW-UIX will be displayed in the user's browser, showing the first page of the help system.
Note:
The first page of the help system is defined as the first navigator declared in the.hs file and the first book defined in the OHW-UIX configuration file (ohwconfig.xml or another name specified by the configFileName initialization parameter for the servlet). Typically the first navigator of the first book is a table of contents.Databinding a Destination to a Topic
To show a topic, use the unique topic ID as the key for the ui:helpTopics data object. For example:
<button text="Button To Help" data:destination="myTopicID@ui:helpTopics" /> <link text="Link To Help" data:destination="someOtherTopicID@ui:helpTopics" />
At runtime, UIX uses the OracleHelpProvider instance to resolve the value of these destinations. The OracleHelpProvider automatically returns a destination that includes JavaScript to launch help in a separate, smaller browser window. This window has a link to the front page of the help system should the user wish to access the main help.