User Guide for the Office Scripting Framework
Contents
Pre-requisites
Before you install the Scripting Framework, be aware of the following:
This is an Early Developer Release of the Office Scripting Framework provided for users and developers of OpenOffice.org to try out and provide feedback. Future releases of the Framework may change.
This release of the Scripting Framework runs only on OpenOffice.org 644 and above.
The Scripting Framework is currently available in English only.
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.
Location
The location combo box will be populated with “User”,”Share” or “Document” the default value will be “User” which will display all scripts (with the selected language type) in the “User” area.
Language
The language combox is populated with the list of supported languages. The default language is set to java.
Script ListBox
Only necessary information will be displayed, logicalname will always be displayed, if the “Detailed view” check box is selected the scripts will be displayed as follows “logicalname [functionname]”
New
This button will not be selectable unless a script from the script ListBox and a menu name is entered in the new menu text box (opposite New button), clicking [New] creates a binding between two.
Delete
This button will not be selectable unless a sub menu with a script binding is selected, clicking [Delete] removes the binding.
OK
Clicking [OK] commits all of the changes the user has made
Cancel
Disposes the dialog without committing any changes.
Help
Will display a dialog describing how to use each of the “Assign Script” dialogs.
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
Event ListBox
The ListBox will be populated with the list all event types, if a script has already been assigned to an event the existing binding is displayed as follows
Event [ script URI ]
example:
Start Application [script://Highlighter.BeanShell?language=BeanShell&function=highlighter.bsh&location=user]
Radio Buttons
By default the “Document” radio button is selected, if selected the event binding is for this document only. If “All Applications” is selected then the event binding is for all documents of all application types ( writer, calc etc. )
Assign
This button will not be selectable unless a script from the script ListBox and event from the event ListBox are highlighted (selected), clicking [Assign] creates a binding between two.
Delete
This button will not be selectable unless an event with a script binding from the event ListBox is selected, clicking [Delete] removes the binding.
OK
Clicking [OK] commits all of the changes the user has made
Cancel
Disposes the dialog without committing any changes.
Help
Will display a dialog describing how to use each of the “Assign Script” dialogs.
Other Scripting-Add'ons Menu Items
Two other menu items are available under the Tools/Scripting Add-on's submenu:
Interactive BeanShell Scripting - This pops up a window in which the user can experiment with writing and executing BeanShell code against the current document. See Writing Scripts in BeanShell and Java for more information on using this window.
Refresh All Scripts - This is used to refresh the script lists that appear in the Assign dialogs after new scripts have been deployed into your OpenOffice.org installation or documents.
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.
Start OpenOffice.org and open an existing Writer document or create a new one.
Select the menu item Tools/Scripting Add-on's/Assign Scripts To Menu...
In the "Assign Scripts To Menu" dialog that pops up do the following:
Select location and language
Set the location to User and the language to Java in the drop down lists.
Select script
Select the script HighlightText.showForm from the list.
Choose the menu to insert the script menu after
Select the top level menu and submenu under which you want to place your new menu item.
Assign script to new menu
In the New Menu text field enter the label you want for your menu item (eg. Highlight)
Click New Script Menu to create the new script menu item.
Finally click on the OK button to save your new script menu item.
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 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.
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. |
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
