User Guide for the OpenOffice.org Scripting Framework

Pre-requisites
Configuring display of OpenOffice.org Scripts
Assiging OpenOffice.org Scripts
Running the example OpenOffice.org Scripts
OpenOffice.org Security

Pre-requisites

Before you install the Scripting Framework, be aware of the following:

This is an Early Developer Release of the OpenOffice.org Scripting Framework provided for users and developers of OpenOffice.org to try out and provide feedback. Future releases of the Framework may change.
The Scripting Framework is currently available in English only.

Configuring display of OpenOffice.org scripts

As the Scripting Framework project is still in development, display of OpenOffice.org scripts is switched off by default in your OpenOffice.org installation. To enable the Scripting Framework download one of the following UNO packages:

EnableSF.zip simply enables the display of Scripting Framework scripts in parallel with the existing method for listing Basic macros. Note that the Basic macros will also be listed under the Scripting Framework scripts.
EnableSF2.zip simply enables the display of Scripting Framework scripts instead of the existing method for listing Basic macros.

The UNO package is then installed using the pkgchk executable found in the OpenOffice.org program directory.
pkgchk EnableSF.zip

Assigning OpenOffice.org Scripts

The execution of OpenOffice.org scripts can be assigned to menu and key items and also to application, document, object and dialog events.

To assign a script to a new menu item:

Select the Tools/Configure menu item, and go to the Menu tab.
In the Category section of the Menu tab, scroll to the bottom of the list and expand the item OpenOffice.org Scripts
You should see entries for share (scripts in the share directory of your OpenOffice.org installation), user (scripts in the user directory of your OpenOffice.org installation), and the current document. Expand one of these entries to see the languages for which scripts are available
Under the language entries you will see entries for script that are available. Select one of these entries.
A list of the script functions available for assignment will appear in the Function list. Select one of the functions.
Now click the New button to create a new menu assignment. The new menu item will appear in the Menu Entries section of the tab. You can rename the new menu item by clicking on it.

To assign a script to a key combination:

Select the Tools/Configure menu item, and go to the Keyboard tab.
To select an OpenOffice.org script to assign, follow steps 2 to 5 for creating menu items.
Now select a key combination from the Shortcut Keys section and click the Modify button to create a new menu assignment.

To assign a script to an event:

Select the Tools/Configure menu item, and go to the Events tab.
To select an OpenOffice.org script, follow steps 2 to 5 for creating menu items.
Now select an event from the list and click the Assign button to assign the selected script to the selected event.

To assign a script to an event for an embedded Object (eg. a chart):

Select the embedded Object in your document and then select the Format/Object... menu item.
In the Object dialog that appears select the Macro tab.
You should be able to select an OpenOffice.org script and assign it to an Object event as in the assign script to event steps above.

To assign a script to a Hyperlink:

Select the Insert/Hyperlink menu item.
In the Hyperlink dialog clicking on the Events button will allow you to assign an OpenOffice.org script to a hyperlink event.

To assign a script to a Graphic:

Select the Format/Graphics... menu item.
In the Graphics dialog you can assign an OpenOffice.org script to an event in the Macro tab.

To assign a script to a Form control:

Insert a Form control (eg. a button) into your document by clicking on the form functions button on the left hand toolbar, selecting a control and then selecting an area in your document to create the control.
Select the control and then select the Format/Control... menu item to bring up a Properties dialog for the control.
Select the Events tab of the Properties dialog and click on one of the buttons labelled "..." beside the event to which you want to assign an OpenOffice.org script.
An Assign Macro dialog will pop up in which you can select an OpenOffice.org script and assign it to the selected event.

To assign a script to a control in an OpenOffice.org Basic dialog:

Open the OpenOffice.org Basic dialog editor and create a dialog with a control on it (eg. a button)
Right click on the control and select Properties... on the popup menu.
Select the Events tab of the Properties dialog and click on one of the buttons labelled "..." beside the event to which you want to assign an OpenOffice.org script.
An Assign Macro dialog will pop up in which you can select an OpenOffice.org script and assign it to the selected event.

Running the example OpenOffice.org Scripts

There are three example scripts supplied with the Scripting Framework, Highlight, MemoryUsage, and ExportSheetsToHTML.

Highlight is a BeanShell application level script for Writer that allows the user to search for a word or phrase. It will highlight all instances in red and give a count of the number of instances.

The second example, MemoryUsage, is a Java script stored in a Calc spreadsheet that checks the current memory usage in the Java Virtual Machine and updates cells in the spreadsheet with the usage values. The spreadsheet also contains a graph which will update when the cell values are changed.

The ExportSheetsToHTML example is a JavaScript application level script for Calc which will save each individual sheet in a Calc spreadsheet as a separate html file.

Running the Highlight example

To run this example you first need to create a menu item from which you can execute the script.

Start OpenOffice.org and open an existing Writer document or create a new one.
Follow the steps for creating a menu item in the Assigning OpenOffice.org Scripts section. The Highlight example is available at OpenOffice.org Scripts/share/BeanShell/Highlight
Your new menu item will now be available and clicking on it will invoke the script.
You should see a Highlight Text dialog appear which you can use to highlight various text strings you are looking for in the document.

Running the MemoryUsage example

The Java version of the MemoryUsage example is already deployed inside an OpenOffice.org document, ExampleSpreadSheet.sxc. To run the Java example, just open:

<OpenOffice.org Installation>/user/Scripts/java/ExampleSpreadSheet.sxc.

You can then execute the MemoryUsage script by pressing CTRL+Shift+M with the ExampleSpreadSheet.sxc window focused. You should see the memory usage values being updated, and the graph should change to reflect the new values. You can also find the MemoryUsage example under OpenOffice.org Scripts/share/Java/MemoryUsage in the Tools/Configure dialog.

Running the ExportSheetsToHTML example

To run this example you first need to create or open an existing spreadsheet document. If you have created a new document save it (eg. c:\temp\mycalcdoc.sxc)

Follow the instructions in the Assigning OpenOffice.org Scripts section to create a key assignment for the script. You can find the ExportSheetsToHTML example at OpenOffice.org Scripts/share/JavaScript/ExportSheetsToHTML.

This will have created a key binding to the ExportSheetsToHTML script. Pressing your key binding will now save each sheet in HTML format in the same directory as the original document (eg. c:\temp\mycalcdoc_sheet1.html, c:\temp\mycalcdoc_sheet2.html, ...)

Top

OpenOffice.org Security

The Scripting Framework currently uses the same Security settings as OpenOffice.org Basic. The settings allow the user to control the execution of macros present in OpenOffice.org documents. Found in the Tools->Options dialog under OpenOffice.org->Security, these settings allow the user to specify the conditions under which it is permissable to execute document based OpenOffice.org Basic macros and OpenOffice.org scripts.

A full description of how these settings work can be found by clicking the "Help" button in the dialog, and then clicking "OpenOffice.org", and "Security" in the left-hand pane of the Help dialog. The possible scenarios associated with the security settings are summarised in the table below.

"Run Macro"	"Confirm in the case of other document sources"	"Show Warning before Running"	Document path in "Path List"	Behaviour
Never	N/A	N/A	N/A	Macros/Scripts never run. No warning displayed.
According to path list	No	No	No	Macros/Scripts never run. No warning displayed.
According to path list	No	No	Yes	Macros/Scripts run. No warning displayed.
According to path list	No	Yes	No	Macros/Scripts never run. No warning displayed.
According to path list	No	Yes	Yes	Warning displayed on document load. If "Run" button clicked macros will run, otherwise they will not.
According to path list	Yes	No	No	Warning with checkbox to add path to path list is displayed on document load. If "Run" button clicked macros/scripts will run, otherwise they will not. Regardless of which button is clicked, if checkbox is ticked document path is added to "Path List".
According to path list	Yes	No	Yes	Macros/Scripts run. No warning displayed.
According to path list	Yes	Yes	No	Warning with checkbox to add path to path list is displayed on document load. If "Run" button clicked macros/scripts will run, otherwise they will not. Regardless of which button is clicked, if checkbox is ticked document path is added to "Path List".
According to path list	Yes	Yes	Yes	Warning displayed on document load. If "Run" button clicked macros/scripts will run, otherwise they will not.
Always	N/A	No	N/A	Macros/Scripts run. No warning displayed.
Always	N/A	Yes	N/A	Warning displayed on document load. If "Run" button clicked macros/scripts will run, otherwise they will not

Top

Last Modified: Nov 19 2003