The Free and Open Productivity Suite
Follow us on Twitter: @ApacheOO

User Guide for the Office Scripting Framework

Contents

Pre-requisites

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

Binding Office Scripts

The execution of Office scripts can be bound to menu and key items and also to application or document events. These bindings can be defined via a set of Assign dialogs which can be started from the Tools/Scripting Add-on's menu

Assigning scripts to Menu and Key items

The dialog shown below is the Assign Script to Menu dialog. This dialog is similar in design and function to the Assign Script to Key dialog and the instructions below should be seen to apply also to the Assign Script to Key dialog.

Note: Unlike StarBasic it will not be possible to setup a key binding that applies for the whole Office suite – key bindings can only be setup for an application or a document of that application type.

Assigning scripts to events

Other Scripting-Add'ons Menu Items

Two other menu items are available under the Tools/Scripting Add-on's submenu:

Top

Running the example Office Scripts

There are two examples scripts supplied with the Scripting Framework, Highlight and MemoryUsage. Highlight is an 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 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 examples are available for both Java and BeanShell in the language directories created under <Office Installation>/user/Scripts by the installer.

Running the Highlight example

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

Running the MemoryUsage example

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

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

Top

Leveraging StarBasic Security

As part of the Early Developer Release v0.2 of the Scripting Framework, we have attempted to mimic the Security settings for StarBasic.  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 StarBasic macros. The settings in this dialog now apply to both StarBasic macros and Scripting Framework 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 never run. No warning displayed.

According to path list

No

No

No

Macros never run. No warning displayed.

According to path list

No

No

Yes

Macros run. No warning displayed.

According to path list

No

Yes

No

Macros 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 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 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 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 will run, otherwise they will not.

Always

N/A

No

N/A

Macros run. No warning displayed.

Always

N/A

Yes

N/A

Warning displayed on document load. If "Run" button clicked macros will run, otherwise they will not.



Top

Different behaviour in the Scripting Framework

The Script Security has one significant difference in behaviour to the StarBasic security. In the Scripting Framework the security warning dialogs are displayed only upon the first script invocation on a document containing scripts, unlike StarBasic where the dialogs are displayed on loading a document containing macros.
If the settings are "Always", and "Show Warning Before Running", when loading a document containing macros the StarBasic dialog display is incorrect (the dialog displayed is more appropriate to the "According To Path List" setting). This has been logged as Issue 11822, the fix for which is not in the OpenOffice.org 1.1 beta release. Under the Scripting framework the correct dialog is displayed.

Top

Troubleshooting

See the Release Notes page.


Last Modified: Tue Mar 12 11:40:28 GMT 2003

Apache Software Foundation

Copyright & License | Privacy | Website Feedback | Contact Us | Donate | Thanks

Apache, the Apache feather logo, and OpenOffice are trademarks of The Apache Software Foundation. OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.