RoboHelp 10 introduced a new feature for scripts: events. An event is a specific action that is executed in the RoboHelp application. For example, saving a topic or opening a project are events. With scripting events, you can set scripts to run automatically whenever a certain event occurs.

So why is this great news? Because these events enable you to make the most out of RoboHelp automation. Consider an example: many users have customized WebHelp output. This means that they made thier output files. Whenever WebHelp is generated, they need to paste the modified output files into their output.

Enter events: When WebHelp is generated, RoboHelp automatically runs a script. This script finds the correct output folder and pastes the modified output files into the output.

To illustrate this article, I have created a simple script for this scenario. You can add the script to RoboHelp, and register the script to run whenever a WebHelp output is generated. The script will automatically copy any custom-modified output files into the WebHelp output. Download the script and follow the instructions in this article to set it up.

In this article I will how you how you can register scripts to run when specific events occur and which events are available. I will also show you how you register a script to an event using scripting and which arguments are passed by RoboHelp for each event.

Setting up the example script

Before you can use the example script, you need to tell the script where your custom-modified output files are stored.

  1. Go to the Script Explorer pod. If you don't see it, select View > Pods > Script Explorer.
  2. Click in the empty space inside the pod, and then click the Import button to import the script.
  3. In the import dialog box, choose the script file and click Open.
  4. In the Script Explorer pod, select the script and click the Edit Selected Item button. The script is opened in the ExtendScript Toolkit.
  5. Go to line 14, and add the full path of the location where your modified files are stored between the brackets. Ensure you replace all backslashes in the path by forward slashes. Example:

    this.skinDirectory="C:/temp/SkinFiles"

  6. Save your changes and close the script.

The script is now set up and ready to run.

Note: This example script is very simple and therefore runs on all  WebHelp outputs you create for all your projects. You cannot choose for which projects it should run.

Making script run when event occurs

Before script can work, you need to register script with the correct event. And to register the script, you need to know which function in the script you want to run. Ask the developer of the script about which function RoboHelp must run. For the example script provided, you need the function copySkinFiles.
To register script with event:

  1. Go to the Script Explorer pod.
  2. Right-click the script, and select Register for Event from the context menu. RoboHelp opens the Register Event dialog box.
  3. In the Function Name field, enter the function name that RoboHelp should run.
    Note: Add only the name of the function, and do not add parentheses or arguments to the function name.
  4. In the Eventfield, select the event on which RoboHelp must run the script. For the example script, choose PostSSLGenerate.
  1. Click OK.

The script is now registered with the event and will run every time after you generate a single source layout. The script will automatically determine whether you’ve generated a WebHelp output. Try generating a WebHelp layout to see how the script works.

Stopping script from running when an event occurs

If you don’t want the script to run when an event occurs, you must unregister the script from the event.

  1. Go to the Script Explorer pod. If you don't see the pod, select View > Pods > Script Explorer.
  2. Click the View Registered Items button. The All Registered Events dialog box appears. It lists all registered scripts.
  1. Select the script that you want to unregister.
  2. Click Unregister.
  3. Click OK.

The script will no longer run when the specific event occurs.

Available events

The events supported by RoboHelp are listed in the table below:

Event Event occurs
closeTopic

When a topic is closed

openTopic When a topic is opened
preImport Before a file is imported
postImport After a file is imported
postSSLGenerate After an SSL is generated
Note: When you have an SSL with multiple content categories, this event is fired for every category.
preSSLGenerate Before an SSL is generated
Note: When you have an SSL with multiple content categories, this event is fired for every category.
preWordDocUpdate Before a linked Word document is updated
postWordDocUpdate After a linked Word document is updated
preFrameMakerDocUpdate Before a linked FrameMaker document is updated
postFrameMakerDocUpdate After a linked FrameMaker document is updated
SaveAll When the Save All button is clicked
postTopicUpdate After a topic is updated
preImportPDFComments Before importing PDF review comments
postImportPDFComments After importing PDF review comments
preCreateReviewPDF Before creating a PDF review document
postCreateReviewPDF After creating a PDF review document
openProject When a project is opened
preCloseProject Before a project is closed
postSOpenProject After a project is closed

Scripting for events

(This section is only for users who want to create scripts.)

You can also register and unregister scripts to events using scripts themselves. For this, the RoboHelp object supports the following three methods:

RoboHelp.registerEvent(eventname:string, filename:string, function to run:string); RoboHelp.isEventRegistered(eventname:string, filename:string, function to run:string); RoboHelp.unregisterEvent(eventname:string, filename:string, function to run:string);

The method registerEvent registers a script to an event, while the method unregisterEvent unregisters the script. Both the methods return a Boolean value to indicate whether the script was successfully registered or unregistered.

The method isEventRegistered checks whether a script is already registered to an event. This method returns true when the script is registered and false when the script is not registered.
The first and third parameters of the new methods are easy to understand: the name of the event you want to register the script with and the name of the function you want to run when the event occurs.

For the second parameter, you need to know the full path of the file that contains the script you want to register. Luckily, ExtendScript provides a method for getting the file name of the current script: $.fileName.

Therefore, to register the function copySkinFiles in the current script file to the event PostSSLGenerate, you can use the following command:

RoboHelp.registerEvent('PostSSLGenerate', $.fileName, 'copySkinFiles');

Available arguments for scripting

Most scripting events supply an argument when the script is run. The argument provides details of the event occurred.

The table below lists the arguments that are available when a specific event occurs:

Event Argument passed to the function
closeTopic The full file path of the topic closed from the WYSIWYG editor
openTopic The full file path of the topic opened in the WYSIWYG editor
preImport The full path of the file being imported
postImport The full path of the file that was imported
preSSLGenerate The name of the SSL being generated
postSSLGenerate The name of the SSL that was generated
preWordDocUpdate The full file path of the Word document that is being updated
postWordDocUpdate The full file path of the Word document that was updated
preFrameMakerDocUpdate The full file path of the FrameMaker document that is being updated
postFrameMakerDocUpdate The full file path of the FrameMaker document that was updated
SaveAll None
postTopicUpdate None
preImportPDFComments The full file path of the topic in which the comments are being imported
postImportPDFComments The full file path of the topic in which the comments were imported
preCreateReviewPDF The full path of the topic being added to the review PDF
postCreateReviewPDF The full path of the topic that was added to the review PDF
openProject The full path of the project XPJ file
preCloseProject The full path of the project XPJ file
postOpenProject The full path of the project XPJ file

Where to go from here

Be sure to read my previous article on Getting started with ExtendScript in RoboHelp. Here are some more scripting resources: