Working with ActiveX Controls in RoboHelp

This month, a trouble free way to create and work with HTML Help controls using RoboHelp. In addition, you learn how to add the Microsoft HTML Help Workshop to your HTML Editors.

If you have ever added an HTML Help ActiveX control, such as a Shortcut or Related Topics button, to a RoboHelp topic and then attempted to change the parameters, you may have discovered that all or some of your changes mysteriously disappear. It is frustrating and difficult to predict when RoboHelp will strip out parameters added to ActiveX controls. In fact, you may be better off deleting and recreating a button if you forgot to add a parameter, than to attempt to add it later on.

The reason RoboHelp strips parameters from HTML Help controls is due to how RoboHelp creates the buttons. If you create a Shortcut control, for example, RoboHelp actually adds two sets of <OBJECT> tags to TrueCode. RoboHelp creates the first set of green object tags so the button can function within the RoboHelp environment, and to produce working buttons in HTML Help, WebHelp, JavaHelp, and/or Oracle Help. The second set of gray object tags is the actual Microsoft HTML Help ActiveX control created specifically for HTML Help. For example, Microsoft's version of a Related Topic control technically should not work in other Help platforms, but eHelp tweaked the code to make it work in WebHelp, JavaHelp, and Oracle Help. This feature is terrific and is really quite an accomplishment by the developers at eHelp.

Unfortunately, the extra code is also its undoing when an HTML Help control button is copied from one location to another, or the button is opened and modified in the WYSIWYG Editor. RoboHelp does not automatically synchronize new changes throughout the two sets of <OBJECT> tags, so you can end up with mismatched parameters in your code. Consequently, the buttons may not work properly if you copy/paste them and then change the parameters.

A closer look at the problem

A Microsoft HTML Help Shortcut control uses the gray-colored parameters displayed below to launch programs in HTML Help. The code may look like the following:

As RoboHelp inserts the gray-colored code, RoboHelp then adds the following green code above your code.

Note the circled parameters. These parameters (and others) may often become mismatched when an ActiveX Control is edited in WYSIWYG mode.

If you modify the code in WYSIWYG mode (especially one with several parameters), or if you copy the button and paste it to another topic and attempt to change a parameters in WYSIWYG mode, everything starts to go haywire.
This image is a preview of a future tip I am working on to add user notes to HTML Help using WinHelp topics!!!
If you double-click an ActiveX Control (in WYSIWYG, as above) and attempt to modify the parameters, many of the parameters change back to their original settings or lost all together. It is difficult to predict which parameters you lost  until you stumble upon it in the CHM file.

The reason the code disappears -- it appears to be a synchronization bug. RoboHelp does not correctly synchronize all parameters inside its own green <OBJECT> tags with the changes made in the gray Microsoft <OBJECT> tags. Therefore, the button may revert to its original settings.

The Solution

There is a rather easy solution: use the Edit With: RoboHelp TrueCode command (this is not the same as clicking the TrueCode tab for reasons I don't fully understand). This command performs magic on Shortcut controls. It can also identify mismatched green and gray code.

When you right-click and choose Edit With: RoboHelp TrueCode, a properly synchronized Shortcut control will only show the gray Microsoft object code -- RoboHelp's green chunk of code does not display. If you see a combination of green and gray code after using Edit With: RoboHelp TrueCode, you probably have mismatched code.

To successfully alter a Shortcut control in a topic:

  1. Right click the topic under HTML Files and choose Edit With: RoboHelp TrueCode.

  2. Make sure only gray code is visible (if you see green and gray code, see how to fix mismatched object code below).

  3. Manually change the parameters in TrueCode.

  4. Save and switch topics.
     

You can check to see if green and gray code is synchronized by clicking TrueCode from the WYSIWYG tab.

To fix mismatched object code

  1. Right click the offending topic.

  2. Choose Edit With: RoboHelp TrueCode.

  3. Delete the entire green object tag and click Save.
    The next time you open the topic, RoboHelp automatically recreates the green code.

  4. Switch to another topic and then edit the topic again using Edit With: RoboHelp TrueCode.
    You should only see the gray Microsoft HTML Help code.

  5. Gray code means you have synchronized code in your Shortcut.

  6. Green and gray code in Shortcuts usually means you have mismatched code; by deleting all the green code, RoboHelp automatically regenerates the code and resynchronizes it to match the settings in the gray code.

NOTE:
I offer no guarantees on this technique, nor is it an approved method by eHelp, but I have discovered that it works.

Next, Adding HTML Help Workshop as an Editor