| |
April, 2000: Using Dynamic Linking
This column was originally published in April,
2000 and written for RoboHELP Office Version 8.
by Char James-Tanny
Dynamic linking is a way of using keywords to
design hyperlinks in your Help projects that are resolved at
runtime. This means that when the user clicks the hotspot in the
compiled Help file, the appropriate Help engine looks for the
specified Help files with topics that match the criteria. "Regular"
hyperlinks are resolved at compile-time, which means that the
compiler verifies that the target topic actually exists and
displays an error message if it doesn't.
The concepts are identical for WinHelp and HTML Help. (Dynamic
linking only works with compiled Help files, which means that it
doesn't work with WebHelp.) The names, however, are slightly
different. WinHelp uses K-Keywords, KLinks, A-Keywords, and ALinks,
while HTML Help uses Keywords, Keyword Links, ALink Names, and
ALink Controls.
Understanding
the Concepts in WinHelp and HTML Help
What is Modular Help?
Considering Your
Options
Designing for Your
Users
Creating
Dynamic Links in RoboHELP 2000 for WinHelp
Working with the Contents
File
Creating ALink and KLink
Macros
Squashing the Bugs
Comparing Dynamic Linking in
WinHelp and HTML Help
Considering Your Design
Options
Creating Dynamic Links in
RoboHELP 2000 for HTML Help
Scripting Hidden
Controls
Avoiding the "Gotchas"
In regular hyperlinks (jumps or popups), there is
a one-to-one relationship between the link and the target topic.
The topic ID or keyword must exist or an error results. The Help
file must exist or an error results. And you don't have the
flexibility of searching across multiple Help files. In any one
link, you can specify only one external Help file.
What about the cross-help WinHelp macros, such as JumpId,
JumpContents, and JumpKeyword? With the exception of JumpKeyword
(which displays a Topics Found dialog box if more than one topic is
found with the specified keyword), these commands all work the
same. The WinHelp engine locates the Help file (if it's not the
current one) and then displays the topic that matches the specified
parameter (either the Topic ID, the Contents topic, or the
Keyword).
However, if the WinHelp engine can't find the Help file, it
displays an error message. And if the Help file is located but the
information in the parameter isn't, the WinHelp engine displays an
error message, along with the default topic for the specified Help
file. There isn't any "real" error handling (other than assigning a
We're sorry topic as the Contents topic, which is a "one
size fits all" fix).
This is where dynamic linking can help. You can design your links
to have the results you want: one-to-one or one-to-many. You
aren't limited to specifying just one keyword. You can search
across as many Help files as desired. As an added benefit, you
don't have to remember the topic ID, because you use keywords to
create the links.
Dynamic links work with individual Help files, but their power lies
in their ability to work across multiple Help systems. Typically,
we refer to them as modular Help systems.
Modular Help systems combine several independent
Help files into one oohesive system. Unless you code your projects
to indicate that several Help files have been combined, users will
never know that they are navigating through more than one Help
file. (OK, there's one exception: if you use identical A- or
K-Keywords in your merged WinHelp projects, they display with the
name of the WinHelp file in the Topics Found dialog box.)
Modular WinHelp systems are created with commands in the Contents
(.cnt) file. Modular HTML Help systems are created with commands in
the Contents (.hhc) and project (.hhp) files. Both Help systems
allow you to display as much or as little information as
desired.
Consider using modular WinHelp or HTML Help when:
Why would you select dynamic linking instead of regular hyperlinks? One consideration is the type of Help system you are developing: modular or independent.
Planning your modular Help system lets you verify
the results of your links and the accuracy of your plan. Since
dynamic links use keywords (either K-Keywords, which comprise the
index, or A-Keywords or ALink Names, which are only used for these
links), you can decide the results of the links before you start
entering project information.
Why is planning so important? A Topics Found dialog box is only
effective if it presents a reasonable list of topics for the user
to choose from. If you've ever clicked a link that displayed a
Topics Found dialog box that contained 10, 20, or 40 topics, you
have probably experienced the frustration of "Are all these topics
really related?" By limiting your Topics Found lists, you
provide useful functionality while not overwhelming the user.
Possible planning methods include:
It's harder to map K-Keywords ahead of time, since good indexes aren't done on the fly but after the content has been developed. However, if you're using existing Help files, you can use the Index and See Also reports in RoboHELP and RoboHTML to list your existing entries.
Dynamic link hotspots in WinHelp can appear in one of several ways:
To create dynamic links, use the following procedure:
For more information on using macros in RoboHELP, see the February Help Corner.
Modular Help uses commands in the Contents file,
which is nothing more than an ASCII (text) file with a .cnt
extension. The three commands that produce modular Help systems are
built into two different RoboHELP dialog boxes: New External CNT in
the TOC Composer and the Contents tab in Project Settings.
| Note | The Windows 95 Help system (back when Microsoft still distributed .hlp files and not .chm files) had the best Contents file for learning how these commands work. While it did contain some actual references to the Windows Help file, it mostly contained these commands to other Help files that may or may not be on your system. This enabled Microsoft to distribute small Help files that displayed as one large Help system, depending on the software you had installed. |
One feature of the commands in the Contents file
is that no errors result if the specified Help file doesn't exist
on the user's system. For example, if a user purchases General
Ledger but not Accounts Payable, and the Accounts Payable
information is included in the Contents file, nothing is displayed.
The user never realizes that something isn't being displayed.
| Note | This can also be a hindrance. If the file name is typed incorrectly, the file isn't displayed-but neither is an error message. |
For a complete modular help system, you would
include all three commands in the Contents file. However, each
command is independent, allowing you to access only the piece(s)
you want. For example, you could include only the Table of
Contents, or only the Index and Find tab information, or both.
To use the :Index and :Link commands in RoboHELP, select the
Contents tab in the Project Settings dialog box.
| Note | If you want to specify a Help file that hasn't been created yet, type the name in the input box. When you click OK, a message is displayed, stating that the file doesn't exist. To include it, click Yes. |
Typically, the names of the Help and Contents
files are the same. However, they don't have to be, as long as the
Help file "knows" the name of the Contents file it is to use. This
allows us to create Master Contents files, linking multiple help
systems into one. I'll cover modular Help in more detail in June's
Help Corner.
To be safe, you should always install your Help files into the same
folder. However, if the referenced file isn't found in the current
folder, the WinHelp engine searches the following folders:
In February's
Help Corner, I discussed the Macro Wizard, which you can use to
enter ALinks and KLinks. This month, I'll discuss the syntax and
parameters of these macros, so that you understand what the Wizard
is doing. To enter ALinks or KLinks, select Linking (under
Category) and then select the macro. Each parameter (explained
below) is displayed on its own line and, where possible, includes
either a drop-down box or button where you can select the desired
information.
Syntax:
ALink(A-Keyword[; A-Keyword] [,type[,topic-ID[,window-name]]])
KLink(K-Keyword[; K-Keyword] [,type[,topic-ID[,window-name]]])
ALink(A-Keyword)
KLink(K-Keyword)
| Note | Before creating macros in RoboHELP, enter the keywords first by using the appropriate index entry (A-Keyword or K-Keyword). |
| Parameter | Description | ||||||||
| A-Keyword, K-Keyword |
Specifies the keywords to
look for. The keywords must be entered in at least one topic and must match exactly, including punctuation. Duplicate keywords (the same keyword in more than one topic) must match case-wise, but keywords are not case-sensitive. (The compiler notifies you of identical keywords that don't match case-wise and corrects the necessary entries so that all keywords match.) When using the Macro Wizard, the following keyword combinations are inserted with the correct syntax as you select keywords. This description explains the syntax that is used.
Specify multi-level K-Keywords by separating them with colons. There aren't any multi-level A-Keywords. KLink(copying:bibliography) Specify multiple keywords (A or K) by separating them with semi-colons. KLink(copying:bibliography;bibliography) ALink(biblio;tour) If a keyword contains spaces or commas, you must enclose it in double-quotes. KLink("alias file") ALink("context-sensitive help") If you have a keyword that uses an apostrophe, type a backslash (\) before the apostrophe so that it is interpreted correctly). KLink("What\'s This Help") ALink("What\'s This Help") |
||||||||
| Type | Specifies how to handle
the results of the macros.
WinHelp 4 allows you to enter either the numerical or string (name) version of this parameter if you're only specifying one value. To use multiple values (for example, Jump and Title), add the numerical values together and enter that value in the macro. For Default, Jump, and Title, therefore, type 3. (Don't try to enter the string names separated by spaces, as compilation errors result.) When using the Macro Wizard for multiple values, replace the text selection with the number. |
||||||||
| topic-ID | Lets you add
error-handling to ALink and KLink macros. If, by some chance, there
aren't any hits when the user clicks the macro, the default error
message is No additional information available. To make this a little more user-friendly, you can design a "Sorry" topic that displays as a popup instead of the standard error message. This topic can contain a brief explanation of what might have happened or your contact information. While you can enter the Topic ID, making sure to type it exactly as it's found in the # footnote, it's easier to use the Select Topic ID button (to the right of the field) to select a topic from your project. |
||||||||
| window-name | Specifies the window in
which to display selected topics. This value overrides any other
settings. By default, topics found display in the window specified by their > footnote (as found on the Advanced tab in the Topic Properties dialog box). If no window has been specified, the topic displays in the currently active window or, if no window is open, the topic displays in the default window. You must be sure that the window-name exists in the project containing the topic. For example, if the user clicks a link for a macro in HelpFile A that can jump to HelpFile B, and you specify a window-name of Second, then the Second window definition must exist in HelpFile B. When using the Macro Wizard, click the drop-down arrow next to Window and select a window from your Help project. |
Typically, once you understand what the
parameters are and how to use them, you can start developing
macros. The bad news is that there are a number of WinHelp bugs in
the ALink and KLink macros. The good news is that most of them have
workarounds.
| Bug | Description | Workaround |
| Can't use multiple keywords in the KLink macro | If you code your KLink macro to search for more than one keyword, it ignores all but the first. The ALink macro works fine. | Use either the :Link or
:Index Contents command. The specified help file doesn't have to
exist. However, this method has been known to corrupt the Find tab
(think of it as a bug in a bug). The only effective workarounds are to include a "real" Contents or Help file or to use the ALink macro. In RoboHELP, use the Contents tab in the Project Settings dialog box to add a "dummy" help file. I usually only select the A- and K-Link checkbox. |
| Default action for the KLink macro doesn't match the default for the ALink macro when there's only one hit | The KLink macro immediately displays the topic if there's only one hit, while the ALink macro displays a Topics Found dialog box. (By the way, there are conflicting opinions as to which is best.) | Use either the :Link or
:Index command (even to a non-existent help file). The KLink and
ALink macros then work the same. If you don't want the Topics Found dialog box to be displayed for just one hit, use the "Jump" Type parameter. |
| Window specified in KLink macro is ignored (i=reported to Don Lammers for inclusion in the WinHelp 4 Bug List) | If you code the window parameter in the KLink macro, the target topic displays in the window specified in the > footnote (or in the default window, if there isn't one). The ALink macro works fine. | Use either the :Link or :Index command (even to a non-existent help file). The topic then displays in the specified window. |
| Topics Found dialog box displays multiple topic titles. | When either the ALink or KLink macro is coded for multiple keywords, and some combination of those keywords exists in the same topic, the Topics Found dialog box displays the topic title for each keyword. | There isn't one. You may have to use ALinks coded specifically for the results. |
| If specifying a topic ID, also specify a window name. | If entering a topic ID for error handling, you must enter a window name. | This is listed on the WinHelp 4 Bug List, but both macros work with or without both parameters. |
| Note | These bugs were taken from the WinHelp 4 Unofficial Bug and Anomaly List, now maintained by Don Lammers of Shadow Mountain. Clicking the link downloads a zipped version of the file, which includes known workarounds. |
Actually, everything's the same...but different.
The following chart compares linking between WinHelp and HTML
Help.
| Concept | WinHelp | HTML Help |
| Name | Dynamic Linking (ALinks and KLinks), which are resolved at runtime. Multiple hits display in a Topics Found dialog box. | Associative Linking (ALinks) and keyword links (KLinks), which are resolved at run-time. You determine if multiple hits display in a Topics Found dialog box or a popup. ALinks are only available with compiled HTML Help files. |
| Related Topics | Hard-coded list of author-determined links, which must be entered. You determine the format: you can list links in a topic or design a hyperlink to display a popup of jumps by creating a topic to display the links. | You can produce the list in the same way as WinHelp, but a better design implementation is to use the Related Topics Wizard to produce the list (entering all related topics in the Wizard). You can display results in a Topics Found dialog box or in a popup. You can edit the resulting control to change the results. Related Topics can be used with compiled HTML Help or uncompiled HTML files. |
| "Standard" hyperlinks | Individually coded and resolved at compilation. | Individually coded and resolved at compilation. |
| Finished help | *.hlp; uses the WinHelp 4 engine (WINHLP32.EXE) to display the content and run the commands. | *.chm; uses the HTML Help engine (HH.EXE) to display the content in browser window; however, all commands are stored in the HTML Help API. |
| Table of Contents | An ASCII file with a .cnt extension. | An HTML file with a .hhc extension. |
| Index | Produced during compilation; uses K-Keywords for content. | Two choices (not mutually exclusive): either an ASCII file with a .hhk extension or a binary index produced during compilation using all keywords (from the .hhk file and those entered in individual .htm files). |
| Modular Help | .hlp files linked through .cnt. | .chm files linked through .hhc. |
As in WinHelp, you must still determine:
HTML Help offers some different choices for the
final design of your linking hotspots:
(you have to remember to add the descriptive
text)
All commands are created with the HTML Help
ActiveX Control (hhctrl.ocx). For uncompiled HTML files, hhctrl.ocx
uses Internet Explorer. For compiled HTML Help files, hhctrl.ocx
uses an Internet Explorer .dll (shdocvw.dll) and the HTML Help
Compiler.
To add HTML Help controls to topics, use the HTML Help Control
Wizards. Click Insert HTML Help Control and select a control from
the list that appears. (You can also select a control from the
Insert menu.) Select your options on the dialog boxes that appear,
and then click Finish. The HTML Help control is added to your
topic.
When you insert an ALink or Keyword Link control, four dialog boxes
are displayed. The first is the Display Options dialog box, where
you enter your options for the button display. In the second dialog
box, you need to select the keywords for the search. (The dialog
boxes for ALink and Keyword Link are identical except for the
column names.) In the third dialog box, select how you want the
results to be displayed for the user. The last dialog box let you
choose a font for the button.
You can only test ALinks and Keyword Links from the .chm file. (In
other words, you can't use the View option to test the
functionality.)
Instead of using buttons, you can create a text
link. Create the control, selecting Hidden on the first
screen of the wizard. Then, create the link that calls the control.
The link is a scripted hyperlink that uses this format:
<A
HREF="JavaScript:id.Click()">hotspot</A>
where id is the control identifier in the wizard.
When scripting hidden links, you must remember the following:
| Note | Hidden links don't get converted correctly when generating WebHelp. If you plan on generating WebHelp, use the default button, which converts without problems. |
Actually, there's only one gotcha to worry about
and it concerns secondary windows. Since regular HTML hyperlinks
don't accommodate secondary windows, most developers use the
Related Topics control. Unfortunately, this functionality broke in
Microsoft's HTML Help Workshop several versions ago, but there is a
workaround.
First, create your Related Topics control by selecting Related
Topics from the control list. Four dialog boxes display. The first
dialog box is the Display Options screen, where you enter your
options for the button display. Select the related topics in the
second dialog box. In the third dialog box, select how you want the
results to display, including the window specification. The last
screen is the Font Selection screen for the button.
| Tip | If you want to mimic a WinHelp hyperlink with this method, select only one topic and script the link as explained in Scripting Hidden Controls |
Then, to correct the secondary window display
problem, open the TrueCode Editor and locate the Related Topics
object.
<OBJECT
CLASSID="clsid:ADB880A6-D8FF-11CF-9377-00AA003B7A11"
ID="RelatedTopics"
ALIGN=BOTTOM
BORDER="0"
VSPACE="0"
HSPACE="0"><PARAM
NAME="Command" VALUE="Related Topics"><PARAM
NAME="Window" VALUE="WindowName"><PARAM
NAME="Button" VALUE="Text:Related Topics"><PARAM
NAME="Font" VALUE="MS Sans Serif,8,0,,"><PARAM
NAME="Item1" VALUE="Get Colors;Get
Colors.htm"></OBJECT>
The number of items equals the number of topics that you added to
the control. For each item, position your cursor after the
semi-colon (before the HTML file name) and type
filename.chm::/ (if you are using HHW 1.2, type
ms-its:filename.chm::/ instead).
The new code looks like this:
<OBJECT
CLASSID="clsid:ADB880A6-D8FF-11CF-9377-00AA003B7A11"
ID="RelatedTopics"
ALIGN=BOTTOM
BORDER="0"
VSPACE="0"
HSPACE="0"><PARAM
NAME="Command" VALUE="Related Topics"><PARAM
NAME="Window" VALUE="WindowName"><PARAM>
NAME="Button" VALUE="Text:Related Topics"><PARAM
NAME="Font" VALUE="MS Sans Serif,8,0,,"><PARAM
NAME="Item1" VALUE="Get Colors;paint.chm::/Get
Colors.htm"></OBJECT>
| Note | Robert Chandler of The Helpware Group originally posted this solution. |
Portions of the material in
this column were originally presented as a conference session at
the Seventh Annual WinWriters Conference in February 1999. Portions
of the WinHelp section have been taken from Advanced RoboHELP
2000 for WinHelp, a training seminar provided by SOLUTIONS,
Inc. and taught by Char James-Tanny. Portions of the HTML Help
section have been taken from Sams Teach Yourself RoboHELP 2000
for HTML Help in 24 Hours by Char James-Tanny, ISBN
0-672-31625-0. Used with permission from Macmillan Computer
Publishing USA.
Copyright © 2000 Char James-Tanny.