Using Topic Identifiers for Creating Context-Sensitive Help

Version	Date	Changes
	2009-04-17	Click Discussion link above for a sample TopicAlias link customization for context-sensitive help.
1.1	2007-07-09	Added images. Updated defined terms.
1.0	2007-07-07	Initial version.

Description

This article describes how to use topic identifiers in your source content so that your published WebWorks Help output can easily support context-sensitive help and other HTML remoting applications.

Contents

Using Topic Identifiers for Creating Context-Sensitive Help

Definitions

WebWorks Help Helpset

A helpset is the result of a single ePublisher project conversion and can be generated by either of the components: Pro, Express, or AutoMap. Most of the time, it is generated by Express or AutoMap as a reproducible publication update. It is made up of a combined set of HTML, graphic, and javascript files. All files working together to create a robust and full-featured set of web-based content. It may include among other features: (1) a table of contents, representing the structure of all the output content, (2) an Index, representing the indexable terms of the output, (3) a client-side full-text search engine, and (4) a mechanism for storing user favorites.

A helpset can be broken down into one or more help modules.

Help Module

A help module combines all the source content or documents that occur underneath a top level group of an ePublisher project or job. When there is more than one help module in a helpset, then these modules must be merged in order to create a unified helpset (one module does not need merging because it is already unified). Any ePublisher project or job will automatically perform this merge operation during a "generate all" operation.

Context Identifier

Each help module is assigned a context identifier; by default that value is the same as the corresponding top-level group name, except when white space characters are used, in which case these are replaced with underscore characters. Context identifiers can be reassigned to specific values using the Merge Settings of an ePublisher project or job. This is important when you need exact control of the context identifiers and your help module labels are not locked down. Consider that in your applications that use published helpsets; they will have the value of the context identifiers hard-coded into the WebWorks Help API calls. So these values are need to be tracked for use later if you reconfigure your ePublisher projects or jobs.

Topic Identifier

A topic identifier equates a well defined "name" with a specific location in the source content that is to be published into WebWorks Help helpset. In cases where FrameMaker or Word documents are used for the source content, it is quite common to use custom markers called "TopicAlias" markers to contain these names in instances located within a specific region of the containing document. Many "TopicAlias" markers can be used to identify any paragraph of the original source content. In addition, multiple "TopicAlias" markers can be applied to a single paragraph, allowing for multiple aliases to the same location.

Source Content

Source content generically describes any kind of electronic information that can be read into ePublisher by one of its input adapters. Currently ePublisher can process FrameMaker (Structured and Unstructured) documents, Word documents, and XML DITA files of all types. In the future, ePublisher will be open and established enough to read any file format that has a non-proprietary interface.

Goals

Define an efficient process for:
1. adding topic identifiers to source content
2. updating published content as source content evolves without re-doing existing topic identifiers
3. examining help module groupings to see what topic identifiers currently exist in a helpset
Understand the basics for using an API to load a specific HTML location, within a specific help module, from a given WebWorks Help helpset.

Stationery Configuration Requirement(s)

Your stationery must be made aware of the topic alias marker type behavior. You will need to use ePublisher Pro, in order to configure your marker style options and then re-deploy your stationery.

Authoring Steps

The steps for authoring content with topic identifiers is not difficult. They are as follows:

Create a custom marker (if not already in template file) called: TopicAlias.
- Note: another name can be used if necessary and only requires that it be defined in the ePublisher Pro master project that creates the stationery.
Insert a TopicAlias marker with a unique value consisting of alphanumeric characters and the underscore character (do not use spaces). Each marker instance should be inserted on or after the heading paragraph that names the topic. There are no limits on the number of TopicAlias markers. Just be sure to name them carefully because they will be used by other applications and/or HTML files that point to your helpset.
Test each implementation of TopicAlias markers by creating a Topics Report in ePublisher Express or Pro. The report will list all TopicAlias markers for the selected top-level grouping or help module. After a full conversion, a Topics Report will be available to display all the topic identifiers, listing their name and providing a means to link back to the source content and forward to the generated output. Simply right click on the report item and make a menu choice. Topics Report list only those topics within that help module or grouping.

Publishing Steps

The steps for publishing content is as follows:

Make sure that the ePublisher master project has defined a topic alias behavior for the TopicAlias marker (and other custom marker names if others were used).
Make sure that the ePublisher projects or jobs (AutoMap) used for publications have properly defined their Merge Settings, located in the Formats Menu. This is where the context identifiers are set for each help module. The context and topic identifiers together, along with the location of the helpset, are what create the

necessary pieces of information to enable HTML or application remoting of WebWorks Help.

Generate the project or job. Multiple help modules will be merged to create a unified helpset.

What Do My Developers Need From Me?

Before starting the authoring phase of a context-sensitive project, you can meet with your developers and compile a list of topic identifiers, group context identifiers, and the topics or application controls to which they will correspond. If you prefer instead to create the content first, you can deliver your published helpset to your developers with an auto-generated list containing all the information they need to connect their application to your documentation.

After output is generated, navigate to the output or deployment directory. Each top-level group in your project will have its own folder within that output directory. For each group, navigate to the following file:

\wwhdata\xml\files.xml

Your developers can reference this file when coding the calls from their application to ensure they are using the appropriate identifiers. Open the file in a text editor, such as NotePad. At the top, you'll see a reference to the group's context. Then, at the bottom, you will find a <TopicMap> section listing all of the group's topic identifiers alongside the files they represent (like in the Topics Report).

So, with this file, the developer now knows the context ID and the topic ID (which is all they need to implement context-sensitive help), and they can also view the associated HTML content to confirm that their application control references the relevant topic.

WebWorks Help Remoting Steps

You can enable WebWorks Help remoting from any HTML file or web-based application (non-web based applications will also work, but they in discussed in the WebWorksHelpSDK).

The following illustrates the construction of a simple HTML file that will perform WebWorks Help remoting using the javascript API provided for WebWorks Help.

Parts

wwhapi.js
- This javascript file includes the definition of the WWHAPI_Object, which is used to control a single browser window instance.
wwhbaseurl.js
- This javascript file simply calculates the base url to find one or more helpsets. It is optional, but useful when working with multiple helpsets.
HTML using Javascript API for WebWorks Help
- This HTML file includes the above javascript files and creates an instance of the WWHAPI_Object. Then this object is used to perform remoting operations on the specified WebWorks Help output.

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
        "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
  <title>WebWorks Help 5.0 Javascript Example</title>

  <script type="text/javascript" src="../wwhapi.js"></script>
  <script type="text/javascript" src="wwhbaseurl.js"></script>
  <script type="text/javascript">
   <!--
    var  GlobalHelpsetA;

    GlobalHelpsetA = new WWHAPI_Object(BaseHelpURL() + "helpsets/HelpsetA" , "help_window");
   // -->
  </script>
 </head>

 <body>
  <h2 class="title">context identifier = 'module1' and topic identifier = 'Topic1'</h2>

   <div>
    <a href="javascript:GlobalHelpsetA.fDisplayHelp('module1','Topic1');">Click Here!</a>
   </div>

 </body>
</html>

DevCenter/Projects/WebWorksHelp/UsingTopicIdentifiers (last edited 2009-04-17 20:11:09 by JoanThomas)