February 2000: Macros and Scripting

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

by Char James-Tanny

In this section...

January 2000: Setting the Tool Options

March 2000: Formatting Topics

April 2000: Using Dynamic Linking

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

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

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:

ALink and KLink add dynamic linking functionality to your Help file. They can be used in a modular Help system.
CloseSecondarys closes all secondary windows but the one currently opened.
CloseWindow closes a specific window.
CreateButton creates a button on the window button bar.
JumpId creates a hyperlink to a specific topic (used with a button and across Help files).
PopupId creates a hyperlink to a specific topic (used with a button) that displays as a popup.
SetPopupColor changes the color of the popup window in your Help file.
Shortcut runs a program (you can include a data file).

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

Select the appropriate category. If you aren't sure which category you need, select All Macros.
Select the desired macro. If the macro uses parameters, they display in the middle of the dialog box.
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.
Click OK.

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

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:

Display a customized welcome message.
Display a copyright at the bottom of every page (and type the copyright information itself only once).
Create text links instead of buttons for HTML Help control objects.
Display custom functionality, such as calendars, in your topics.
Control user events, such as moving the mouse over an area of the window.
Display different objects, such as text and images, according to the date.

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:

JavaScript (sometimes called ECMAScript) is the language used most often by developers. Now an international standard (ECMA-262), JavaScript can be used with both Internet Explorer and Netscape Navigator. JavaScript has the greatest number of resources available over the Web, with numerous Web sites providing free scripts for your use.
JScript is Microsoft's implementation of JavaScript. It also conforms to ECMA-262 and can be used to script ActiveX controls. JScript is best interpreted by Internet Explorer (which is fully ECMA compliant), but can also be interpreted by Netscape Navigator.
VBScript is a subset of Visual Basic for Applications by Microsoft. VBScript can only be interpreted by Internet Explorer. If you already know Visual Basic, VBScript would probably be the easiest for you to use.

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:

The developer provides an explanation and the script. There may or may not be any demonstrations, so read the explanations carefully. If you decide that you want to use the script, copy and paste it into your HTML file. For example, http://www.javascript-page.com.
The developer provides a demo button and text box containing the script. If you decide that you want to use the script, copy and paste it from the text box into your HTML file. For example, http://javascript.internet.com.
The developer provides several buttons on the page. One demonstrates the script results. Another allows you to download a set of files related to the script (usually demo.htm, code.htm, and details.htm, plus any other necessary files like graphics). You want to be careful with this type of site because every download is called download.zip or index.zip. Be sure to rename the zip files before saving them to your system. For example, http://www.jsworld.com.

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:

A one-step script is inserted in the topic where you want it, and runs as soon as the user interacts with it (usually by viewing).
A two-step script needs one piece of code (called a function) inserted in the document and another piece, calling the function, inserted where desired in the topic.
A three-step script requires the creation of an external script file (a text file with a .js extension), plus the function, plus code in the topic to call the function.

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

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:

Position your cursor where you want the script and select Insert | Script. The Edit Script dialog box displays.
Click the down arrow next to Script language and select either JavaScript (default) or VBScript. (Select JavaScript for JScript.)
Enter your script text in the window. When you're finished, click OK.
You can test your scripts without compiling by using the View icon.
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

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.

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