Using the new RoboHelp 10 scripting events
Created
29 October 2012
Requirements
User level
Intermediate
Required products
- RoboHelp (Download trial)
Sample files
- copySkinFiles.zip (3 KB)
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.
Before you can use the example script, you need to tell the script where your custom-modified output files are stored.
- Go to the Script Explorer pod. If you don't see it, select View > Pods > Script Explorer.
- Click in the empty space inside the pod, and then click the Import button to import the script.
- In the import dialog box, choose the script file and click Open.
- In the Script Explorer pod, select the script and click the Edit Selected Item button. The script is opened in the ExtendScript Toolkit.
- 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" - 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.
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:
- Go to the Script Explorer pod.
- Right-click the script, and select Register for Event from the context menu. RoboHelp opens the Register Event dialog box.
- 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. - In the Eventfield, select the event on which RoboHelp must run the script. For the example script, choose PostSSLGenerate.
- 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.
If you don’t want the script to run when an event occurs, you must unregister the script from the event.
- Go to the Script Explorer pod. If you don't see the pod, select View > Pods > Script Explorer.
- Click the View Registered Items button. The All Registered Events dialog box appears. It lists all registered scripts.
- Select the script that you want to unregister.
- Click Unregister.
- Click OK.
The script will no longer run when the specific event occurs.
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 |
(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:
