Re: synchronizing the toc in HTML Help (.chm) file that uses a frameset -- Workaround Solution

["David Geddes" <david -dot- geddes -at- visualinsights -dot- com>]

I found a reasonably simple workaround to the problem of synchronizing the
TOC in a compiled HTML Help file when using a frameset in the topic pane of
the chm's tripane viewer. The solution is outlined at the end of this
message.

Overview:

I have a compiled HTML Help (.chm) file with the standard three-pane viewer
(navigation pane, toolbar pane and topic pane). The topic pane has a 2-frame
frameset . One frame (named secondary) has navigation buttons and the other
frame (named main) contains help information. I use javascript to make the
TOC in the navigation pane work with the frameset.

The Problem:
Everything works fine except that when topics are replaced in the frameset
either by using the navigation buttons or by clicking links in the main
frame, the toc does not synchronize with the new topic. If I do not use the
frameset, synchronization works fine.

Potential Solution?
I'm thinking that if I can programmatically tell the toc to synchronize to a
specific (named topic) using javascript then my problem would be solved. I'm
wondering if either the HTML Help API command "HH_SYNC" or the HTML Help
ActiveX control command "syncURL" would work. The problem I have with either
of these commands is that I do not know how to address the .chm's toc from a
topic page within that same .chm. All of the HTML Help API documentation
assumes that the
.chm is being manipulated from another program or that an embedded HTML
Help
ActiveX control is being manipulated.

Workaround Solution Overview:

The frameset in the navigation pane of the standard tripane viewer is built
dynamically with javascript that is executed from each .html topic file. For
instance, when you select the a toc entry, the loaded topic .html file then
executes javascript code to build a two-frame frameset and then place the
topic file inside the lower frame (called main). The upper frame (called
secondary) is also created with javascript and has navigation buttons for
the next and previous topics (in topic sequence) and a tab for accessing
various components of the help file. All this works fine except that the
toc, which is in the standard navigation of the tripane viewer, will not
synchronize with the current topic when you select a topic using a hyperlink
or the navigation buttons in the upper frame.


Solution:

Although many javascript solutions should work for this problem, the .chm
viewer does not execute this code properly (likely because the frameset is
causing the viewer to get confused). Additionally, there is no way to
address the API of a .chm viewer from a topic inside the currently open
viewer, thus the activeX HTML Help method SyncURL and the API command
HH_Sync cannot be used.
The solution involves two parts: First, make every hyperlink use the syntax
normally reserved for accessing topics in other .chm files. This syntax
starts with the "mk:@MSIT:" text string. Second, use a target of
target="_top" so that whenever a topic is opened, the existing frameset is
swept away and the selected topic is loaded in an empty topic window. In
other words, the frameset is removed and replaced with a single topic file
which then builds a new frameset thus repeating the cycle described
previously in Workaround Solution Overview.

For example:

A link, whether it be in a standard href or image map, looks like this:
<href="mk:@MSITStore:D:\directory\blah\blah\MyHelpFile.chm::/htm/ATopic.html
target="_top">

The special syntax shown above is described in HTML Help Workshop's help
file if you need more info.

If the link is being written dynamically using javascript, as was the case
for links in my upper frame, you need to include extra backslashes as escape
characters so as not to confuse javascript, for example;

d.writeln('<a href =
"mailto:mk:@MSITStore:D:\\directory\\blah\\blah\\MyHelpFile.chm::/htm";
target="_top">');

If you're still reading this, you are a glutten for punishment and you're
likely thinking that this is way too much effort. But in fact it wasn't,
because all of the links that go in my upper frame are generated
automatically using a DocToHelp boilerplate .txt file which you can easily
customize -- I'm sure Robohelp has a similar convenience feature. Look up
"boilerplate" in D2H for details.

As for the links in my topics, I didn't have to add the extra info because I
set up a base tag which appends the extra info to each link. My base tag
looks like:

<base target="_top"
href="mk:@MSITStore:D:\directory\blah\blah\MyHelpFile.chm::/htm/">

This tag must be placed before the </head> tag in each topic file. Again, I
added this to my boilerplate .txt file. Unfortunately, the base tag didn't
work for the generated upper frame so I made sure my boilerplate added the
extra info to each link in the generated upper file explicitly.

Miscellaneous points:

- A DocToHelp-specific item: D2H glossary popups had to have the
target="main" attribute in each popup href link. In this case, "main" is the
name of the bottom frame in the frameset.

- Because there is a two frame frameset, users have to click the Back button
twice to view the previous topic because the generated upper frame is
replaced with a placeholder topic when the Back button is first clicked. I
didn't have time to find a decent solution so I added an animated .gif to
the placeholder topic that loops once only so that after 1 second of
nothing, text appears telling the user to click the Back button again to
view the previous topic -- goofy but better than nothing I suppose.

David Geddes

Visual Insights Canada,  http://www.VisualInsights.com
david -dot- geddes -at- visualinsights -dot- com