OpenOffice.org Scripting Framework Specification

OpenOffice.org 2.0

Document - ID	Specification Owner	Last Change	Status
	Tomas O'Connor	April 8, 2004	Draft
Conforms to	
Applies to	All OOo modules
Task ID(s)	i21173, i21174, i21176, i21179
Category	Feature

Abstract

The Scripting Framework allow OpenOffice.org users to write macros in a number of languages and execute them in OpenOffice.org. Users can assign these macros to menu items, keyboard combinations, application and document events, form controls within documents and various objects within documents.

i-Team Members

	Name	E-mail Address
User Experience		
Development	Tomas O'Connor (TOC)	tomas.oconnor@sun.com
Quality Assurance	Joerg Skottke (JSK)	joerg.skottke@sun.com
Documentation		

Approved for Implementation

	Approved by	Date
User Experience		
Development		
Quality Assurance		
Documentation		
String Review		

Document Change History

Rev. Level	Change	Initials	Date
0.1	First Draft	TOC	08/04/04
0.2	Second Draft from initial feedback	NP	04/21/03
0.3	Added chapter 6.1: Configuring the Scripting Framework / Updated tables and changed figure descriptions to be object captions.	JSK	04/26/04
0.4	Updated Figure 3. and some rewording.	NP	04/26/04

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Goals	1

4	Requirements and Dependencies	1

4.1	Requirements	1

5	Competitive Analyses	1

6	Detailed Specification	2

6.1	Configuring the Scripting Framework	3

7	Technical overview of Architecture	4

7.1	MasterScriptProvider service	4

Lifecycle	5

7.2	LanguageScriptProvider service	5

Xinitialization Method initialize()	6

XScriptProvider Method getScript()	6

XScript invoke() method.	6

XScriptContext methods	7

7.3	Discovery of Scripts using XBrowseNodeAPI	7

XBrowseNode method getName()	7

XBrowseNode method getChildNodes()	7

XBrowseNode method hasChildNodes()	7

XBrowseNode method getType()	7

7.4	Scripting Framework URI specification	8

7.5	Storage of Scripts	8

8	Future Tasks	9

9	Notes	10

10	References	10

Glossary

Term	Description
Script	A code fragment which can be executed by the scripting framework. A script may be either compiled or interpreted
Macro	Same as Script

Motivation

Enhance the programmability of OpenOffice.org by making it possible to write execute and manage macros written in multiple languages, including OpenOffice.org Basic, Java, JavaScript and BeanShell.

Scalability – provide mechanisms for additing new langauges to the framework.

User Scenarios

Goals

The goals of the Scripting Framework is to make automation of OpenOffice.org easier by allowing users and developers to write macros in a language of their choice.

Requirements and Dependencies

Requirements

The Scripting Framework must fulfill the following requirements:

It must be pluggable, ie. it must be possible to add support for additional languages via a UNO component which implements a well defined SPI

Existing assignments to OpenOffice.org Basic macros must not be broken

Be able to detect and display macros from supported languages.

Enhance current language support which facilitates binding of OpenOffice.org Basic macros to specific events to include macros from supported languages from ScriptingFramework

Provide built-in support for compiled Java and interpreted Java scripting languages JavaScript and BeanShell. Note BeanShell is interpreted Java.

It must be possible to switch off display of Scripting Framework macros in the OpenOffice.org UI

Must be possible to deploy scripts using unopkg.

Competitive Analyses

No suitable products available for analyses.

Detailed Specification

The ScriptingFramework will provide the means by which new scripting langauges can be supported by OpenOffice.org. The is achieved by providing a framework whereby support for a new language can be deployed as an UNO package. The new language support component ( LanguageScriptProvider ) will be automatically detected by OpenOffice.org. Any macros that are deployed for that language will be displayed in the new MacroSelector dialog ( see specification here )

The ScriptingFramework also provides the means whereby macros written in those languages can be organized/managed. LanguageScriptProvider developers may reuse the MacroOrganization dialog support for the reference langauges Beanshell and JavaScript ( see specification here ) or can provide their own implementation.

The MacroSelector dialog will be used to allow users to associate not only macros written in OpenOffice.org Basic but also written in any of the langauges for which there is an installed LanguageScriptProvider. This allows macros written in any supported language to be associated with

menus

keyboard events

application and document events

controls in forms

controls in dialogs

Hyperlinks

Graphics etc.

The ScriptingFramework will provide internal IDE functionality for the reference LanguageScriptProviders e.g. JavaScript & BeanShell. For BeanShell this is a simple editing window with the ability to modify, run and save scripts. For JavaScript the IDE is a modified version of the Rhino Debug IDE which in addition to the basic functionality offered by the BeanShell IDE provides more advanced debug functionality. The runtime behavior of the IDE's is similar to OpenOffice basic, in other words if a macro is being edited, has being modified but not saved, if that macro is invoked from an event binding it is the unsaved version in the IDE that is executed. Additionally the document context for a script executed in the IDE is the currently active component from the point of view of the Desktop UNO service ( com.sun.star.Desktop ), this is similar to the behavior of ThisComponent in OpenOffice.org Basic.

The ScriptingFramework will also support Dialogs created from the OpenOffice.org Basic Dialog editor. In addition to supporting binding of macros in the supported languages for the dialog additionally a new UNO service ( com.sun.star.awt.DialogProvider ) has been provided so that Dialogs can be created from any language that has an UNO binding.

Configuring the Scripting Framework

The Scripting Framework can be configured by editing the file

<office-dir>/share/registry/data/org/openoffice/scripting.xcu

Sample Scripting.xcu-file

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:name="Scripting" oor:package="org.openoffice.Office" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="ScriptRuntimes">

<node oor:name="BeanShell" oor:op="replace">

<prop oor:name="SupportedFileExtensions">

<value xml:lang="en-US">bsh</value>

</prop>

</node>

<node oor:name="JavaScript" oor:op="replace">

<prop oor:name="SupportedFileExtensions">

<value xml:lang="en-US">js</value>

</prop>

</node>

</node>

<node oor:name="ScriptDisplaySettings">

<prop oor:name="ShowBasic">

<value>false</value>

</prop>

<prop oor:name="ShowSF">

<value>true</value>

</prop>

</node>

</oor:component-data>

Enabling/disabling the Scripting Framework

The relevant switches can be found below <node oor:name="ScriptDisplaySettings">.

The item “ShowBasic” defines whether the old style BASIC entries are to be shown in the script selectorsor not. If this setting is “false” the BASIC macros will be listed below the scripts-tree of the scripting framework. This is the default

“ShowSF” defines whether the Scripting Framework is enabled or not. The default is “true”

Adding support for other languages

Below <node oor:name="ScriptRuntimes"> the supported scripting languages, including their localization data and extension are listed.

Technical overview of Architecture

MasterScriptProvider service

Figure 1: MasterScriptProvider ( name space ommited )

The MasterScriptProvider is an Office side UNO component which is an integral part of the framework. It implements a number of services and interfaces. See Figure 1. It is available and deployed as part of an Office installation .

The MasterScriptProvider is an Office side UNO component which is an integral part of the framework. It implements a number of services and interfaces. See Figure 1. It is available and deployed as part of an Office installation .

Responsibilites

Identifes the available LangaugeScriptProviders. LanguageScriptProviders must adhere to a specific naming scheme. “drafts.com.sun.star.script.provider.ScriptProviderForXXX” where “XXX” is the language name as it appears in a script framework URI. Additionally the LanguageScriptProvider must implement the following service definition.

drafts::com::sun::star::script::provider::LanguageScriptProvider ( see Figure 2.)

Is created with a context argument that determines its search path for macros its child ScriptProviders are responsible for and the execution context when dealing with documents:

“user” – refers to the user directory for an OpenOffice installation

“share” - refers to the share directory for an OpenOffice installation.

“vnd.sun.star.tdoc” URL - refers to an open document ( Universal Content Provider) that handles URL-schema of open documents. The specification can be found here.

XModel – refers to an open document.

This context is passed as an argument to any child language LanguageScriptProviders the MasterScriptProvider creates.

Supports drafts.com.sun.star.provider.XScriptProvider interface. Returns a drafts.com.sun.star.script.provider.XScript object for any script URI ( see Scripting Framework URI section ) passed to the getScript() method. The MasterScriptProvider will create instances ( or access previously created instances) of the appropriate LanguageScriptProviders for that URI.

Supports the drafts.com.sun.star.script.browe.XBrowseNode API ( see section on ..... ) so it provides a single point of contact for browsing and executing scripts by delegating to correct LanguageScriptProviders. When a client accesses the XBrowseNode API the MasterScriptProvider will create an instance ( or access a previously created instance ) of each LanguageScriptProvider. It will access the XBrowseNode API for each LanguageScriptProvider and collate the information available from each provider to present this information back to the caller.

Lifecycle

By default MasterScriptProvider can be obtained from any open document ( document model supports com.sun.star.script.provider.XScriptProviderSupplier interface ). Its lifecycle will be tied to the life of the document that created it.

The MasterScriptProvider can also be created standalone, in which case it will exist as long as a reference to it is held by the client that creates it.

The MasterScriptProvider is a lightweight object. The LanguageScriptProviders themselves are also intended to be lightweight objects. The MasterScriptProvider hides the details of the construction and access of the LanguageScriptProviders from clients and users.

LanguageScriptProvider service

Figure 2: LanguageScriptProvider for language XXXX (namespace omitted)

The LanguageScriptProvider is an UNO component that provides the environment to execute a script for a specific language. For example when office encounters a scripting framework URI ( see Scripting Framework URI section ) in an event assignment it delegates to a MasterScriptProvider which in turn finds the appropriate LanguageScriptProvider to execute the script.

Responsibilites

Responsible for creating the environment necessary to run a script. Implementation specific.

It is intended that the LanguageScriptProvider service will maintain some static state that represents the registry of scripts known to it ( for the specific language of the provider ), including scripts in OFFICE_INSTALLATION_PATH/user, OFFICE_INSTALLATION_PATH/share and for each open document. Therefore this information is available to all instances of the LanguageScriptProvider.

Given a script URI it is responsible for returning a command like object that implements the drafts.com.sun.star.script.provider.XScript interface that can execute the script described by the URI.

Supports XBrowseNode API to allow enumeration for all scripts

The name of the new LanguageScriptProvider service must be of the form drafts.com.sun.star.script.provider.ScriptProviderFor[Language].

The new LanguageScriptProvider service must support the “drafts.com.sun.star.script.provider.LanguageScriptProvider” service.

Detail

As mentioned above the new LanguageScriptProvider service will be instantiated by the MasterScriptProvider. It will be passed a context as a parameter of the initialise() method .

Xinitialization Method initialize()

Parameter Types	Parameters	Description
[in] sequence< any >	aParams	An invocation context. Contains either reference to the XModel ( representing a document context ) or a string referring to the scope of the provider “user”, “share” or UCB vnd.sun.star.tdoc URL

A LanguageScriptProvider should

be aware of any scripts located in the context it is created with.

be aware of any scripts located in any other context for which a LanguageScriptProvider of the same type has been created. This implies that the LanguageScriptProviders should cache this data statically so that it can be shared amongst the different instances.

be able to locate a script based on a scripting URI and return an object implementing the XScript interface.

XScriptProvider Method getScript()

Parameter Types	Parameters	Description
[in] string	URL	URL to script.

ReturnType	Description
XScript	Instance of an object implementing the XScript interface that represents a script that will execute against the context of the LanguageScriptProvider that created it. This means that when the invoke() method of this object is called that script will act on the document from which the script was invoked.

Note: It is up to the LanguageScriptProvider to decide what information to pass to a running script. It makes sense to pass information to the script which makes the script writer's job easier, such as a reference to the current document ( context ), reference to the service manager (available from the component context passed into the LanguageScriptProvider component's constructor by UNO) and a reference to the desktop (available from UNO using this service manager).

All of the Java based reference LanguagesScriptProviders provided with Office make this information available to the running script in the form of an object implementing the interface drafts.com.sun.script.provider.XScriptContext. This provides accessor methods to get the current document, the desktop and the component context. Depending on the constraints of the language this information is passed to the scripts in different ways, for example in Beanshell and JavaScript this is available as an environment variable and in the case of Java it is passed as a parameter to the script.

XScript invoke() method.

Parameter Types	Parameters	Description
[in] string	scriptURI	Original URI passed to the framework
[in] sequence< any >	aParams	Input parameters
[out] sequence< short >	aOutParamIndex	Output parameter index
[out] sequence< any >	aOutParam	Output parameters

ReturnType	Description
Any	Return value of script.

XScriptContext methods

XscriptContext Method	Returns	Description
getDocument	XModel	Access to the current document.
getDesktop	XDesktop	Access to the current desktop.
getComponentContext	XComponentContext	Can be used by the script to get the default multi component factory to create other UNO services.

Discovery of Scripts using XBrowseNodeAPI

The Browse interfaces ( XBrowseNode ) exported by the new LanguageScriptProvider service are the initial point of contact for the office application. In order for the Office process to display all scripts it first needs to create all available LanguageScriptProviders, each LanguageScriptProvider is created with a context (see above). Depending on how the new LanguageScriptProvider is initialised it will enumerate the scripts stored in that context. It is expected that the LanguageScriptProvider implementation will return the language name as the name of the top-level CONTAINER node. It is up to the LanguageScriptProvider how to arrange the hierarchy of the scripts and how they are presented to the user.

XBrowseNode method getName()

ReturnType	Description
string	Name of Node.

XBrowseNode method getChildNodes()

ReturnType	Description
Sequence <XBrowseNode>	Children of this node.

XBrowseNode method hasChildNodes()

ReturnType	Description
boolean	True if children exist, false otherwise

XBrowseNode method getType()

ReturnType	Description
short	Constant defined in BrowseNodeTypes.idl indicating that node is the root node ( Reserved for use by the MasterScriptProvider service ) a container of other nodes a script

XBrowseNode implementations of type BrowseNodeTypes.SCRIPT is treated by OpenOffice.org as a special node see Figure 3. below.

Figure 3: PropertySet 1. available from node of type SCRIPT

Key	Value type
URI	string
Editable	boolean
Createable	boolean
Deleteable	boolean
Runable	boolean

In order for Office to be able to assign a script it needs to be able to retrieve the scripting framework URI that describes the script. When a XBrowseNode implementation of type SCRIPT is selected it needs to export the URI as a property named URI. Similarly it is possible to integrate an IDE that is capable of editing the script by exporting a property named Editable. Additionally to support organization of scripts Createable and Deletable need to be also supported, to support “Run” MacroSelector dialog, the “Runable” property needs to be supported. The script XBrowseNode implementation object needs to also implement the com.sun.star.script.XInvocation interface. This allows the implementation object to receive a request to edit the script. It is up the implementation to call the IDE and pass it the information required for the IDE to be able to edit and invoke the script.

Scripting Framework URI specification

vnd.sun.star.script:<script_name>['?'<query_element>('&'<query_element>)*]]

script_name is something meaningful that the ScriptProvider can use to determine what script to run.

Parameter	Description
language	identifies identifies the language, or LanguageScriptProvider to be used to process the URI e.g. language=StarBasic, language=Java, language=JavaScript
location	identifies the container for the script, could be document, user, share e.g. A placeholder to allow relative addressing of the document, user and share areas, the current Scripting Framework URI scheme caters for this by allowing location to be “user”, “share” or “document” indicating the location of the script is located in “install_path/User/Scripts/<language>”, “install_path/Share/Scripts/<language>” or document identified by the invocation context. For backwards compatibility Basic scripts use a location of “application” note: location could be another URI e.g. “file://” or “vnd.sun.star.pkg://”. Currently only user/share/application & document are supported by the framework..

Storage of Scripts

A LanguageScriptProvider is responsible for knowing about how its own scripts are stored, where, what format and what kind of directory structure is used.

The scripting framework however attempts to standardise how to store and discover scripts by defining

a default directory structure which is used by the reference implementations available for Java, JavaScript & BeanShell

Directory Structure

At the top level in the uncompressed format of a document, OFFICE_INSTALL_PATH/user or OFFICE_INSTALL_PATH/share there exists a “Scripts” directory with the following structure below it.

Scripts/

|

+- java/

|

+- otherLanguage/

under the language specific directory exists directories defined by the user. Each of these directories can be loosely considered to be analogous to a library and can be used to organize scripts.

+- a_language_name/

|

+- "user named deployment directory"/

a generic mechanism for enabling discovery of scripts and associating meta data with those scripts. Is achieved by the presence a file called “parcel-descriptor.xml” in each “Library” directory DTD and example. ( note: This mechanism is used only for additional Scripting Framework languages and not OpenOffice.org Basic for ease of backwards compatibility )

Future Tasks

Enhanced for organising, editing and assigning Scripting Framework macros is being covered in other specifications:

Script Selector dialog:

http://specs.openoffice.org/scripting_framework/ScriptSelectorSpecification.sxw

Script Organizer dialog:

http://specs.openoffice.org/scripting_framework/ScriptOrganizerSpecification.sxw

Improvements to reference Interpreted LanguageScriptProviders e.g. ( JavaScript, Beanshell )

It is planned to

eliminate the need for queryInterface from both of these languages

support properties directly

handle Any type transparently

in so far as its technically possible. The goal is to provide a similar level of functionality and ease of programming as is provided by OpenOffice.org Basic.

Notes

References

Scripting Framework project page: http://framework.openoffice.org/scripting/index.html

Page 8

Christian Jansen

2003-09-15T13:45:24

Christian Jansen