April 2000: Using Dynamic Linking

This Help Corner column was originally published in April, 2000, and written for RoboHELP Office Version 8.

by Char James-Tanny

In this section...

January 2000: Setting the Tool Options

February 2000: Macros and Scripting

March 2000: Formatting Topics

May 2000: Modular Help

June 2000: Context-sensitive Help

August 2000: Using the Single-Source Wizards in RoboHelp Office

September 2000: RoboHelp Version 9 is here!

October 2000: Generating WebHelp

November 2000: Creating Glossaries

December 2000: Using Browse Sequences

Using Dynamic Linking

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

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.

What is Modular Help?

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:

You are developing Help for an application that can easily be divided into sections (for example, an Accounting application that includes General Ledger, Accounts Payable, Accounts Receivable, and so on) that users don't have to purchase at one time, if ever.
You have one (or more) sections that are common to several applications (for example, a Glossary).
You are part of a multi-authoring development team, with each developer responsible for a portion of the Help system.

In addition, consider using modular WinHelp when:

Your project contains large RTF and/or graphic files, which take a long time to compile. It is easier to work with multiple Help files; individually, they compile more quickly. You can also divide your project conceptually, making it easier to work with the individual files.
You want to include links to future Help files.

Considering Your Options

Why would you select dynamic linking instead of regular hyperlinks? One consideration is the type of Help system you are developing: modular or independent.

In a modular Help system, you must be sure to include the appropriate external Contents file. In an independent WinHelp system, bugs can prevent the desired results unless you include an external Contents file (even if it doesn't exist). I'll discuss this in more detail in Squashing the Bugs.
Modular Help systems usually require more work when combining indexes to guarantee that index terms merge correctly. If there is a problem with the keywords that make up the index, the macros (in WinHelp) or commands in HTML Help that use the keywords could be affected.

There are two dynamic link macros, ALink (using A- Keywords or ALink Names) and KLink (using index Keywords). Which will you use?

If your Help file will be translated, you'll want to use ALinks. Users never see A-Keywords or ALink Names, because their only purpose is to provide a term for dynamic linking, so they don't have to be translated. On the other hand, K-Keywords also provide the index, so they have to be translated in both the index and in the commands.
The benefit of using dynamic links is that they resolve at runtime. However, this can provide unexpected results when using K-Keywords. If the index of an included file is updated, the results of any KLinks or Keyword Links will also be updated the next time the user clicks the hotspot. You could possibly produce a much longer Topics Found dialog box than originally planned. This tends to be more of an issue when multiple Help authors work on the same modular system.

How will you use dynamic links?

If you implement Related (or See Also) Topics in WinHelp, you can have one-to-one or one-to-many relationships, depending on the assigned keyword. This is slightly different in HTML Help, where you use a wizard to create a static Related Topics link that displays specific topics.
You can use ALinks as a replacement for standard hyperlinks. In a multi-developer system, this can make planning easier, especially for cross-file links.

How will you define your Related Topics? In Developing Online Help for Windows 95, Boggan et al describe four types of Related Topics:

Closely associated tasks (topics for all dialog box tabs could be related topics for the individual tabs)
Reversals or opposites (how to log off could be a related topic for logging on)
Near misses (WebHelp could be a related topic for JavaHelp)
Other kinds of Help information (a list of Cascading Style Sheet bugs could be a related topic for creating style sheets)

Designing for Your Users

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 make up 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:

Storyboarding the Help system (colored stickies, a bulletin board, tacks, and string help you visualize it)
Using a Topic Map, drawing the topics and their corresponding links
Customizing a Topic List with a column for A- and K-Keywords

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.

Creating Dynamic Links in RoboHELP 2000 for WinHelp

Dynamic link hotspots in WinHelp can appear in one of several ways:

With the look of a standard hyperlink (green, single- underlined text). Turn off the green by preceding the hidden text with %. For example:
As a small (12x12 pixel) button with descriptive text
As a labeled button (the length of the description determines the width of the button)

To create dynamic links, use the following procedure:

Create the macro in one topic.
Test and debug.
Enhance and modify.
Test and debug.
Copy to other topics as listed in your design. (Once it's working, you don't have to test it again unless you make changes to either the keywords or the macro code.)

For more information on using macros in RoboHELP, see February 2000: Macros and Scripting.

Working with the Contents File

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.

:Include inserts all the commands in another Contents file in the current Table of Contents. RoboHELP inserts this command when you add an external CNT file in the TOC Composer.
:Index merges the K-Keywords of the specified file with the current Index in alphabetical order. RoboHELP enters the command as :Index Help File Name=filename.hlp (which displays Help File name instead of just filename.hlp). This command also merges the Find tab information.
:Link gives you access to the A- and K-Keywords of the specified file for use with dynamic linking (ALinks and KLinks). It doesn't update the Index or the Find tab information.

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.

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.

Then, click the Add button under Files Included in Index.

Select the Help File by clicking the Open Folder icon to display the File Open dialog box. Navigate to the correct folder and select the Help file. If you're merging the Indexes, type a title in the input box. Then, click OK.

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:

Windows
Windows/System
The system PATH
The Windows Registry

Creating ALink and KLink Macros

In , 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]]])

Short names: AL and KL (required when creating macros in the Table of Contents or in a SHEG file)

The optional parameters, indicated by brackets, can be omitted. The only required parameter for both macros is one keyword:

ALink(A-Keyword)

KLink(K-Keyword)

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.

When selecting keywords, be sure that a check mark is displayed in the selection box. Highlighting a keyword doesn't select it for the macro.

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.

0 or blank	Default. For the ALink macro, displays a Topics Found dialog box, no matter how many hits. For the KLink macro, jumps to the topic if there's only one hit and displays a Topics Found dialog box if there's more than one.
1 or Jump	Displays the topic if there's only one hit.
2 or Title	Displays the Help file title in the Topics Found dialog box. Usually used when developing modular help systems and you want the user to know which Help file they are jumping to.
4 or Test	Returns a value of 1 if there's a hit. This actually runs the TestALink or TestKLink macro to check for the existence of the desired keyword and must be included within a marker macro (IfThen, IfThenElse, and so on).

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.

Squashing the Bugs

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.

These bugs were taken from the WinHelp 4 Unofficial Bug and Anomaly List, now maintained by Don Lammers of Shadow Mountain. Clicking the link at his site downloads a zipped version of the file, which includes known workarounds.

Comparing Dynamic Linking in WinHelp and HTML Help

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:

Standard hyperlinks vs. associative linking
One-to-one or one-to-many results
Paths the user is allowed to take through the finished Help file

Considering Your Design Options

HTML Help offers some different choices for the final design of your linking hotspots:

You can use a:
- Hotspot
- Text button
- Small button (you have to remember to add the descriptive text)
- Bitmap image (using a .bmp file)
- Icon image (using a .ico file)
If there are no hits, you can display either a:
- Grayed-out button
- "No topics found" message
Multiple results can display as a:
- Popup
- Topics Found dialog box

Creating Dynamic Links in RoboHELP 2000 for HTML Help

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.)

Scripting Hidden Controls

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:

The control identifier is case-sensitive and cannot contain spaces.
Click() must be entered with an initial cap.

The default control identifiers for the various HTML Help controls are:

ALink: See Also (which must be changed if scripted)
Close Window: CloseWindow
HHCTRL Version: HHCtrlVersion
Index: Index
Keyword Link: KeywordSearch
Related Topics: RelatedTopics
Shortcut: Shortcut
Splash Screen: SplashScreen
Table of Contents: TOC
WinHelp Topic: WinHelp

To modify any values in a control, right-click the control and select ActiveX Properties, or click the control to select it, and then choose Edit | ActiveX Properties.

Hidden links don't get converted correctly when generating WebHelp. If you plan on generating WebHelp, use the default button, which converts without problems.

Avoiding the "Gotchas"

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.

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>

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.