February, 2000: Macros and Scripting

Help Corner

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

by Char James-Tanny

Macros and Scripting

Both WinHelp and HTML Help let you extend the functionality of your Help files. In WinHelp, you use one of the 88+ included WinHelp macros. In HTML Help, you use one of the scripting languages. This month, I'll discuss the Macro Wizard in RoboHELP and provide an overview to scripting in HTML Help.

Using Macros in RoboHELP 2000 for WinHelp

Using Scripts in RoboHELP 2000 for HTML Help

Using Macros in RoboHELP 2000 for WinHelp

Macros provide extra functionality for your help files. They are commonly used to close open windows, change window colors, and run programs. The following table lists WinHelp macros according to when they run.

This macro type... Runs when...
Startup The help file is opened. Enter startup macros in RoboHELP Explorer (File | New | Startup Macro).
Topic-entry The topic is opened. Enter topic-entry macros when you create or edit a topic (Advanced Tab | Entry Macro).
Window-entry The secondary window is opened (Main window macros are entered as startup macros). Enter window-entry macros in the Window Properties dialog box.
Index keyword The user selects the keyword on the Index tab. Enter keyword macros in Project Settings under the Index Macros tab.
Contents The user selects the entry in the Contents Tab. Enter Contents macros in RoboHELP Explorer in the TOC Composer (New Page, select Macro radio button).
Text/graphic hotspot The user selects it (when they click a hotspot in the topic). Enter text/graphic macros in Word (Help Macro Hotspot, Help Authorable Button, and Help Graphical Button).
Hypergraphics (SHG) The user selects it (when they click a hotspot in the graphic). Enter macros in SHED files using the Shed Editor when inserting graphics.


The following table lists WinHelp macros according to what they do (their functionality). Note that some macros fit into more than one functional group.

This macro type... Is used to...
Button Add, modify, delete, and or disable window buttons.
HTML Run Internet macros.
Keyboard Add or remove accelerator keys.
Linking Add hypertext, typically across Help files.
Menu Add,modify, delete, or disable menu items.
Program Run external applications.
RoboHELP Extensions Add functionality with RoboHELP. Requires additional files.
Text-Marker Add bookmark and conditional macros.
Window Focus, position, and close windows.


Some of the most commonly used WinHelp macros are:



Macro Syntax

Syntax is extremely important. If it's not correct, the macro doesn't work. Macros have two main components: Macro Name and Parameters. The syntax is:

MacroName(parameter1, parameter2, ..., parameterX)



Macro Name. Most macros have both a long name (ExecProgram) and a short name (EP). Some only have a long name (Exit). Most of the time, either name can be used. However, when adding macros to the Contents tab or a SHED file, the short name must be used. Macro names are not case-sensitive.

Parameters. Most macros have specific parameters that must be entered. For example:

CloseWindow(main)

If the macro doesn't require specific parameters, you must still include the parentheses. For example:

CloseSecondarys()



Some macros require several parameters. Depending on the macro, you may use another macro as a parameter. For example:

CreateButton(BTN_EXIT, E&xit, Exit())



When required, quotes enclose individual parameters. They are typically not required if the macro is in a topic or project file. You can use double quotes or the single open quote (under the tilde) and single close quote. Within a set of parameters, you must use the same type of quotes (either all doubles or all singles). If you get an error message about a macro when compiling, it's likely you have either used the wrong open quote or you have Smart Quotes turned on. Check your syntax and verify that you typed the single open quote under the tilde, not the single close quote under the double quote.

RoboHELP makes entering basic macro information fairly easy. The RoboHELP Help file includes a Macro section that describes all possible WinHelp macros. (On the Contents tab, select WinHelp Reference | WinHelp Macro Reference.) When you choose to enter a macro in your project, RoboHELP displays the Insert Help Hotspot dialog box. At the bottom of this dialog box is a Wizard button. When you click this button, the Macro Wizard dialog box displays.

The Macro Wizard displays a list of all WinHelp macros, organized by functionality.



The macro description (at the bottom of the dialog box) includes all parameters. Required parameters are shown in parentheses (and the parentheses must be included). Optional parameters are shown in square brackets. If you include an optional parameter, you must omit the square brackets.

If you aren't using the parameters at the end of the macro, they can be omitted. However, if you omit a parameter but include any other that follows it, you must include all the comma delimiters so that the compiler correctly interprets the macro. For example, the ALink macro only requires one keyword. If you want to also include a window name, the format of the macro would be ALink(keyword,,,winname). The Macro Wizard takes care of the syntax for you when you select the desired parameters.

Using the Macro Wizard

To enter macros using the Wizard:

  1. Select the appropriate category. If you aren't sure which category you need, select All Macros.
  2. Select the desired macro. If the macro uses parameters, they display in the middle of the dialog box.
  3. If required, add the necessary parameters. Some parameters (for example, window name and keyword) use drop-down boxes that present valid options you can select from.
  4. Click OK.


Make sure you test your macro before distributing your Help file!

Material in this section is taken from Using RoboHELP 2000 for WinHelp a training seminar provided by SOLUTIONS, Inc. and taught by Char James-Tanny.

Using Scripts in RoboHELP 2000 for Microsoft HTML Help

Scripting allows you to extend and enhance the functionality of your HTML Help or HTML-based Help (WebHelp) file. It also makes development easier by allowing you to create script files that you can call as needed or as desired. A word of caution: scripting is programming. As such, it has a syntax that must be followed or the script just won't run.

Scripting allows you to:



You use external script files when you have consistent information that you want repeated throughout your help file. For example, you could enter copyright information in a .js file. If your copyright changes, you only have to change it once (in the .js file) and then recompile for your changes to take effect.

The various scripting languages, combined with the latest browser versions, are considered low security. In other words, you can't retrieve any user information without them being aware of it. For example, it used to be possible to create a script that would email the user's email address to you so that you knew who hit your site. Now, the browser interrupts the transmission and notifies the user that they are sending an email.

The only exception to this is cookies. Cookies are pieces of user-specific information saved on a user's hard drive (in cookies.txt) when they hit sites scripted to save this information. However, as a developer, you cannot read cookies.txt. You can check the file for your cookie, but no others.

What Scripting Language Should You Use?

Three scripting languages are currently available:



If you really want to learn scripting (not just cut and paste someone else's scripts), you can get more information from the web or one of the many available books. Both Microsoft and Netscape's sites include script information, from documentation to tutorials to sample scripts.

If you prefer to copy and paste tested scripts, the best resource is the web. Several sites include hundreds of scripts that you can demo first. Usually, the only requirement is that you leave the author's copyright information in the comments. Sites with sample scripts usually work in one of three ways:



Script site developers are constantly adding new scripts to their sites. And new sites themselves are also added frequently. Use your search engines if you're interested in getting more scripts.

Inserting and Modifying Scripts

Once you've retrieved a script, you can insert it in RoboHTML in either editor. Make sure you follow any special instructions provided with the script. Inserting scripts can involve one, two, or three steps:



You enter script information in the <HEAD> when you are scripting functions (global pieces of information that can be used repeatedly by a script). Information placed in the <HEAD> tags is interpreted while the page loads, thus making the script immediately available to the user. On traditional web pages, if the script is entered anyplace else, a user could get an error message by requesting information from the script before it has been loaded.

RoboHTML doesn't allow you to enter information in the <HEAD> of a topic. In the WYSIWYG editor, the script is placed at the cursor position. If you use the True Code editor to enter the script in the <HEAD>, RoboHTML parses the information and places it so that it follows the </HEAD> tag. This tends to affect your formatting. You might want to place scripts normally placed in the <HEAD> at the bottom of the topic instead. This way, your formatting isn't affected.

If you are creating compiled help, the script should be available immediately without any problems (even if the scripts aren't located in the <HEAD> tags).

Scripting in the WYSIWYG Editor

Note The information in this section applies to RoboHELP HTML Edition Version 2000 (also known as Version 8). The new Scripting Wizard in RoboHELP HTML Version 9 works differently.


To add a script to a topic in the WYSIWYG Editor:

  1. Position your cursor where you want the script and select Insert | Script. The Edit Script dialog box displays.
  2. Click the down arrow next to Script language and select either JavaScript (default) or VBScript. (Select JavaScript for JScript.)
  3. Enter your script text in the window. When you're finished, click OK.
  4. You can test your scripts without compiling by using the View icon.
  5. Scripts display in the WYSIWYG editor as <S>. You can edit scripts by selecting and double-clicking the <S>.

Scripting in the True Code Editor

Note The information in this section applies to RoboHELP HTML Edition Version 2000 (also known as Version 8), but should work as described with RoboHELP HTML Version 9. However, the enhancements in Version 9 mean that you probably won't have to add scripts in the TrueCode Editor, because the new Scripting Wizard lets you specify an external JavaScript file.


To add a script to a topic, click the TrueCode tab, position your cursor where you want the script, and type it. RoboHTML displays an <S> in the WYSIWYG editor after you have entered the script.

You have to enter some scripts in the True Code editor because the Script Editor in the WYSIWYG editor doesn't have the necessary functionality. For example, if you're using a .js file, the script line is <SCRIPT LANGUAGE="JavaScript" SRC="filename.js"></SCRIPT>. You have to enter this in the True Code editor because the Script Editor doesn't allow you to modify the opening SCRIPT tag.

Modifying Scripts

While the ability to retrieve fully-functional scripts from books and the web is a bonus (since you don't have to learn the entire scripting language), the chances are very good that you'll have to modify the script. In providing scripts, developers reach for the widest possible audience. As a result, you'll rarely find a script that does exactly what you want.

Editing existing scripts is easy. The hard part is maintaining the correct syntax and debugging any errors that might result. Because JavaScript is the most widely used language today (and has the most samples on the web), the following example uses it to demonstrate how to make modifications. This script loads a simple function into memory. You can then access the function through a button or other user interaction.

JavaScript is case-sensitive. However, the spacing is used to make it easier to read the script, but isn't required.

<SCRIPT LANGUAGE="JavaScript">
<!--Allows script to be ignored by browsers that don't understand scripting
// creates sayHello function for button
function sayHello() {
  alert("Hello")}
// -->
</SCRIPT>

This code... Means this...
<SCRIPT LANGUAGE="JavaScript"> Tells the browser this is a script and the language it is written in. (The only other choice is "VBScript".)
<!-- Ignored by browsers that don't understand scripting. Since some users might use older browsers that don't know how to interpret scripts, this tag in effect "comments out" the following lines. The browser will ignore all lines until //-->.

Even though this isn't an issue with HTML Help (since the Help file uses the IE engine to display the results), it is good scripting practice to include it.
// creates sayHello function for button Two slashes (//) indicate a comment to JavaScript. Use this method to put informational messages in your script to explain what something is doing or why you wrote it the way you did. Scripts retrieved from the web may have several comment lines for the original developer's copyright.
function sayHello() { function is a reserved word in JavaScript. A function is similar to a macro: it is a group of statements that run when requested.

sayHello() is the name given to the function by the developer. Unless you have a real issue with a function name, you're better off leaving it alone. If you really do need to change the name, just be sure to also change it in the script line that requests it later on the page (it can be found in the code for a button or other user interaction). Developers usually use mixed case when naming functions, and function names are case-sensitive.

The empty parentheses indicate that there aren't any parameters with this function. You must always include the parentheses when referring to a function.

{ indicates that the script for the function follows.
alert("Hello")} alert is a reserved word in JavaScript. It tells the browser to display the information, when requested, in a message box on the user's screen.

Hello is the information that displays. You can change this to anything you like.
// --> The // indicate a comment to JavaScript, and the --> indicates the end of a comment to the browser. Those browsers that can't interpret scripts would now start reading the file again.
</SCRIPT> This tells the browser that the script is finished.


In this script, you can change two things: the name of the function and the text that displays when the function is called. For most downloadable scripts, you will probably have to change any information that displays to the user.

Material in this section is 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.