Documentation/DevGuide/Scripting Framework

An LibreOffice macro is a short program used to automate a number of steps. The Scripting Framework is a new feature in LibreOffice. It allows users to write and run macros for LibreOffice in a number of programming and scripting languages including:

The framework is designed so that developers can add support for new languages.
 * BeanShell (https://www.beanshell.org/)
 * JavaScript (https://www.mozilla.org/rhino/)
 * Java (https://www.java.com)
 * Python (Python as a macro language)
 * LibreOffice Basic (LibreOffice Basic)

Structure of this Chapter
This chapter is organized into the following sections:


 * Section Using the Scripting Framework describes the user interface features of the Scripting Framework
 * Describes how to run a macro using the Run Macro dialog.
 * Describes how to use the Organizer dialogs to create, edit and manage macros.
 * Section Writing Macros provides a guide on how to get started with writing Scripting Framework macros
 * Describes how to write a simple HelloWorld macro.
 * Describes how Scripting Framework macros interact with LibreOffice and the LibreOffice API.
 * Describes how to create a dialog from a Scripting Framework macro.
 * Describes how to compile and deploy a Java macro.
 * Section How the Scripting Framework Works describes how the plug-able architecture of the Scripting Framework allows support for new scripting languages to be added easily.
 * Section Writing a LanguageScriptProvider UNO Component using the Java Helper Classes describes how to use the Scripting Framework Java helper classes to add support for a new scripting language
 * Describes how to use the ScriptProvider abstract base class.
 * Describes how to add editor and management support.
 * Describes how to build and register a ScriptProvider.
 * Section Writing a LanguageScriptProvider UNO Component From Scratch describes how to write a LanguageScriptProvider UNO component.

Who Should Read this Chapter
If you are interested in automating LibreOffice using BeanShell, JavaScript, Java, Python or LibreOffice Basic then you should read sections Using the Scripting Framework and Writing Macros.

If you are interested in adding support to run and write macros in a language with a Java based interpreter then you should read section Writing a LanguageScriptProvider UNO Component using the Java Helper Classes.

If you are interested in adding support for a scripting language from scratch then you should read section Writing a LanguageScriptProvider UNO Component From Scratch.

Using the Scripting Framework
This section describes how to run and organize macros using the submenu:





Running Macros
To run a macro use the menu item Tools > Macros > Run Macro… This opens the Macro Selector dialog:



The Library list box contains a tree representation of all macro libraries. At the top level, there are three entries:

Each of these entries can be expanded to show any macro libraries they contain. When a library has been selected, the macros contained in that library are displayed in the Macro name list box. When a macro is selected its description, if one exists, is displayed at the bottom of the dialog. Selecting a macro and clicking Run will close the dialog and run the macro. Clicking Cancel will close the dialog without running a macro.
 * My Macros (macros belonging to the current user)
 * OpenOffice Macros (macros available to all users of the installation)
 * DocumentName Macros (macros contained in the currently active document)

Macros can also be run directly from the Macro Organizer Editing, Creating and Managing Macros and from some macro editors.

Editing, Creating and Managing Macros
The Scripting Framework provides support for editing, creating and managing macros via the Tools > Macro > Organize Macros menu. From there you can open a macro management dialog for BeanShell, JavaScript or LibreOffice Basic macros.

The Tools > Macro > Organize Macros menu of LibreOffice can only execute existing Python macros. Facilities for creating, editing, deleting, are not yet implemented.

The Organizer dialogs for BeanShell and JavaScript
The Organizer dialogs for BeanShell and JavaScript dialogs work in the same way. The dialog allows you to run macros and edit macros, and create, delete and rename macros and macro libraries.



The dialog displays the complete hierarchy of macro libraries and macros that are available for the language. The buttons in the dialog are enabled or disabled depending on which item is selected, so for example, if a read only library is selected the Create button is disabled. The buttons in the dialog are used as follows:


 * Run
 * Closes the dialog and runs the selected macro.


 * Create
 * Pops up a dialog prompting the user for a name for the new library (if a top-level entry is selected) or macro (if a library is selected). The dialog will suggest a name which the user can change if they wish. When the button is clicked, the new library or macro should appear in the Organizer.


 * Edit
 * Opens an Editor window for the selected macro.


 * Rename
 * Opens a dialog prompting the user for a new name for the selected library or macro. By default the dialog will contain the current name, which the user can then change. If the user presses OK the library or macro is renamed in the Organizer.


 * Delete
 * Deletes the currently selected entry.

BeanShell Editor


The macro source is listed in the main window with line numbers in the left-hand sidebar. The editor supports simple editing functions (Ctrl-X to cut, Ctrl-C to copy, Ctrl-V to paste, double click to select a word, triple click to select a line). The Run button executes the source code as displayed in the Editor window.

JavaScript Editor
Clicking the Edit button in the JavaScript Organizer will open the Rhino JavaScript Debugger:



The source of the JavaScript macro is displayed in the main window. The line numbers are shown in the left-hand sidebar. Clicking in the sidebar will set and remove breakpoints in the macro. There is currently a bug in the debugger which is not clearing the symbol in the sidebar when breakpoints are removed.

The contents of the text window can be saved by selecting the File > Save menu item. The macro can be run by selecting the File > Run menu item. This activates the four buttons above the main text window:


 * Break
 * Sets a breakpoint at the line where the cursor is.


 * Go
 * Runs the macro, stopping at the next breakpoint (if one is set).


 * Step Into
 * Runs a single line of code, stepping into functions if they exist and then stop.


 * Step Over
 * Runs a single line of code, without stepping into functions and then stop.


 * Step Out
 * Continues the execution of the macro until it exits the current function.

There are two other panes in the debugger which are hidden by default. These allow the developer to view the stack and watch variables:



For more information on the Rhino JavaScript Debugger see https://www.mozilla.org/rhino/debugger.html.

Basic and Dialogs
The LibreOffice Basic and Dialog Organizers are described in the LibreOffice Basic chapter.

Macro Recording
Macro Recording is only supported for LibreOffice Basic in Writer and Calc modules and is accessible via the Tools > Macro > Record Macro menu item.

The Macro Recorder is intended for simple, sequential tasks. It generates dispatch commands. Use instead the API resources for elaborate programming.

The HelloWorld macro
Here is a comparison of HelloWorld macros in the different script languages available in LibreOffice.

Basic
Basic interprets pairs of get and set methods at UNO objects as object properties if they follow this pattern:

Using these facilities some lines can be simplified:

Service properties can be directly accessed in Basic, it is not necessary to use  or   methods.

BeanShell
As BeanShell accepts typeless variables, the code is simplified compared to Java.

BeanShell interprets pairs of get and set methods at UNO objects as object properties if they follow this pattern:

Using these facilities some lines can be simplified:

Service properties are only accessed with  or.

JavaScript
As JavaScript accepts typeless variables, the code is simplified compared to Java.

JavaScript does not accept the simplifications seen in Basic and BeanShell.

Setting an integer value to a property requires to use a java class.

Java
Other sections of this document provide numerous Java examples. Here is the HelloWorld provided in LibreOffice

Compiling and Deploying Java macros
Because Java is a compiled language it is not possible to execute Java source code as a macro directly from within LibreOffice. The code must first be compiled and then deployed within a LibreOffice installation or document. The following steps show how to create a Java macro using the HelloWorld example code:


 * Create a HelloWorld directory for your macro
 * Create a HelloWorld.java file using the HelloWorld source code
 * Compile the HelloWorld.java file. The following jar files from the program/classes directory of a LibreOffice installation must be in the classpath: ridl.jar, unoil.jar, jurt.jar
 * Create a HelloWorld.jar file containing the HelloWorld.class file
 * Create a parcel-descriptor.xml file for your macro

The parcel-descriptor.xml file is used by the Scripting Framework to find macros. The functionname element indicates the name of the Java method which should be executed as a macro. The classpath element can be used to indicate any jar or class files which are used by the macro. If the classpath element is not included, then the directory in which the parcel-desciptor.xml file is found and any jar files in that directory will be used as the classpath. The necessary Java UNO classes are available automatically.


 * Copy the HelloWorld directory into the share/Scripts/java (or basis/share/Scripts/java) directory of a LibreOffice installation or into the user/Scripts/java directory of a user installation. If you want to deploy the macro to a document you need to place it in a Scripts/java directory within the document zip file.
 * If LibreOffice is running, you will need to restart it in order for the macro to appear in the Macro Selector dialog.

If these files are embedded in document file, they have to be registered in META-INF/manifest.xml:

Python
A Python module may contain several scripts.

Python interprets pairs of get and set methods at UNO objects as object properties if they follow this pattern:

Using these facilities some lines can be simplified:

Service properties can be directly accessed in Python, no need to use  or.

Using the LibreOffice API from macros
BeanShell, JavaScript, Java, Python macros are supplied with a variable of type com.sun.star.script.provider.XScriptContext which can be used to access the LibreOffice API. This interface has three methods:


 * com.sun.star.frame.XModel
 * Returns the  interface of the document for which the macro was invoked (see Using the Component Framework)


 * com.sun.star.frame.XDesktop
 * Returns the  interface for the application which can be used to access open document, and load documents (see Using the Desktop)


 * com.sun.star.uno.XComponentContext
 * Returns the  interface which is used to create instances of services (see Service Manager and Component Context)

Depending on the language the macro accesses  in different ways:

oDoc = XSCRIPTCONTEXT.getDocument;
 * BeanShell: Using the global variable

oDoc = XSCRIPTCONTEXT.getDocument;
 * JavaScript: Using the global variable

Xmodel xDocModel = xScriptContext.getDocument;
 * Java: The first parameter passed to the macro method is always of type

oDoc = XSCRIPTCONTEXT.getDocument
 * Python: Using the global variable

Handling arguments passed to macros
In certain cases arguments may be passed to macros, for example, when a macro is assigned to a button in a document. In this case the arguments are passed to the macro as follows:

event = (ActionEvent) ARGUMENTS[0];
 * BeanShell: In the global  variable

event = ARGUMENTS[0];
 * JavaScript: In the global  variable

public void handleButtonPress(     XScriptContext xScriptContext, Object[] args)
 * Java: The arguments are passed as an  in the second parameter to the macro method

Each of the arguments in the  are of the UNO type Any. For more information on how the Any type is used in Java see Type Mappings.

The ButtonPressHandler macros in the Highlight library of a LibreOffice installation show how a macro can handle arguments.


 * Python: The arguments are passed as parameters of the called function.

Creating dialogs from macros
Dialogs which have been built in the Dialog Editor can be loaded by macros using the com.sun.star.awt.XDialogProvider API. The method  from interface   uses a string as a parameter. This string is the URL to the dialog. It is formed as follows:

vnd.sun.star.script:DIALOGREF?location=[application|document]

where  is the name of the dialog that you want to create, and location is either application or document depending on where the dialog is stored.

For example if you wanted to load dialog called MyDialog, which is in a Dialog Library called MyDialogLibrary in the LibreOffice dialogs area of your installation then the URL would be:

vnd.sun.star.script:MyDialogLibrary.MyDialog?location=application

If you wanted to load a dialog called MyDocumentDialog which in a library called MyDocumentLibrary which is located in a document then the URL would be:

vnd.sun.star.script:MyDocumentLibrary.MyDocumentDialog?location=document

The following code shows how to create a dialog from a Java macro:

Calling a macro with the Scripting Framework
The service com.sun.star.script.provider.ScriptProvider exports interface com.sun.star.script.provider.XScriptProvider which offers method. This method returns an interface com.sun.star.script.provider.XScript which offers the method  which will call the script with parameters if necessary.

The identity and location of the called script is contained in an URI, which follows a particular syntax.

How the Scripting Framework works
The goals of the ScriptingFramework are to provide plug-able support for new scripting languages and allow macros written in supported languages to be:


 * Executed
 * Displayed
 * Organized
 * Assigned to LibreOffice events, key combinations, menu and toolbar items

This is achieved by enabling new language support to be added by deploying an UNO component that satisfies the service definition specified by com.sun.star.script.provider.LanguageScriptProvider. The ScriptingFramework detects supported languages by discovering the available components that satisfy the service specification and obey the naming convention " "

LibreOffice comes with a number of reference LanguageScriptProviders installed by default.

For more details on naming conventions, interfaces and implementation of a LanguageScriptProvider please see Writing a LanguageScriptProvider UNO Component From Scratch and Writing a LanguageScriptProvider UNO Component using the Java Helper Classes.



The illustration above shows the simplified interaction between the Office Process and the ScriptingFramework when invoking a macro. Macros are identified by a URI and are represented by objects implementing the com.sun.star.script.provider.XScript interface. When the  method is called the ScriptingFramework uses the URI to determine the correct LanguageScriptProvider to call   on. The LanguageScriptProvider translates a URI into a object that implements. Office can then invoke the macro by calling invoke on that object.

Writing a LanguageScriptProvider UNO Component Using the Java Helper Classes
The Scripting Framework provides a set of Java Helper classes which make it easier to add support for scripting languages for which a Java interpreter exists. This set of classes will handle all of the UNO plumbing required to implement a LanguageScriptProvider, leaving the developer to focus on writing the code to execute their scripting language macros. The steps to add a new LanguageScriptProvider using Java are:


 * 1) Create a new ScriptProviderForYourLanguage by inheriting from the abstract ScriptProvider Java base class
 * 2) Implement the com.sun.star.script.provider.XScript UNO interface with code to run your scripting language interpreter from Java
 * 3) Optionally, add support for editing your scripting language macros by implementing the ScriptEditor Java interface
 * 4) Build and register your ScriptProvider

The ScriptProvider Abstract Base Class
The ScriptProvider class is an abstract Java class with three abstract methods:

The most important method is the  method which must be implemented in order for LibreOffice to execute macros in your scripting language. Fortunately this is made easy by a set of helper methods in the ScriptProvider class, and by a set of helper classes which implement the BrowseNode API described in Writing a LanguageScriptProvider UNO Component From Scratch.

Here is an example of a ScriptProvider implementation for a new ScriptProviderForYourLanguage:

The  and   methods, make the implementation of the   method easy.

The  and   methods are standard LibreOffice methods for registering UNO components. The only thing you need to change in them is the name of your ScriptProvider.

Implementing the XScript interface
The next step is to provide the  implementation which will execute the macro code. The following example shows the code for the  class:

If the interpreter for  supports Java class loading, then the   helper class can be used to load any class or jar files associated with a macro. The  uses the parcel-descriptor.xml file (see Compiling and Deploying Java macros) to discover what class and jar files need to be loaded by the script.

The  class will load the source code of the macro which can then be passed to the   interpreter.

Implementing the ScriptEditor interface
If you want to add support for editing scripts you need to implement the  interface:

The  method is called when a user presses the Edit button in the Macro Organizer. The  implementation can use the   object to obtain the source code for the macro and display it.

The  method should return a template of a macro in your language, for example the code to write   into a document. The  method should return the filename extension used for macros written in your language. These methods are called when the Create button is pressed in the Macro Organizer.

The  and   methods are not called by the Macro Organizer and so they do not have to do anything. They are used by the implementation of the  to execute the source code that is displayed in the , and to open the   at the line for which an error has occurred. The developer may wish to do the same when writing their  and.

The following code shows an example ScriptEditorForYourLanguage.java file:

Building and registering your ScriptProvider
In order to compile these classes you need to include the UNO and Scripting Framework jar files in your classpath. You can find these in the program/classes directory of your LibreOffice installation. The jar files that you need to include are: ridl.jar, unoil.jar, jurt.jar and ScriptFramework.jar.

To compile :

Built-By: Yours Truly RegistrationClassName: ScriptProviderForYourLanguage
 * 1) Compile the ScriptProviderForYourLanguage.java, ScriptEditorForYourLanguage.java and YourLanguageScript.java files
 * 2) Create a jar file for   with the following in the manifest file. (Use the   switch to the jar command to add the manifest data)
 * 1) Register the   jar file using the Extension Manager.

Now you should see an entry for  in the Tools - Macros - Organize Macros… menu.

Writing a LanguageScriptProvider UNO Component From Scratch
To provide support for a new scripting language a new  for that language needs to be created. The new, an UNO component, must be written in a language from which there is an existing UNO bridge. Details about UNO bridges can be found at UNO C++ Bridges.

The  is an UNO component that provides the environment to execute a macro for a specific language. For example when LibreOffice encounters a Scripting Framework URI (see Scripting Framework URI Specification) the  finds the appropriate   to execute the script. A  has the following responsibilities:


 * It must support the com.sun.star.script.provider.LanguageScriptProvider service.
 * It is responsible for creating the environment necessary to run a script.
 * It is responsible for implementing the com.sun.star.script.browse.BrowseNode service to allow macros to be organized and browsed.
 * Given a script URI it is responsible for returning a command like object that implements the com.sun.star.script.provider.XScript interface that can execute the macro indicated by the URI.
 * The name of the any  service must be of the form " ", where Language is the language name as it appears in a script URI.

General syntax
The URI is a case-sensitive string. It is composed of fixed terms and three parameters:

where:
 * identifies the script.
 * identifies the  needed to execute the script as described. Current language values : Basic, BeanShell, Java, JavaScript, Python
 * identifies the container of the script, i.e. My Macros, or OpenOffice Macros, or within the current document, or in an extension.

As the syntax of these parameters depends on each  they are described hereafter for each implemented language. Terms like,   are placeholders that stand for the names used in a real case.

Basic script
A Basic script is usually called : a macro. It may be a Sub or a Function.

The Basic script is supposed to be created through the user interface, see section Editing, Creating and Managing Macros.

LANGPARAM
 

LOCPARAM

 * macro in a library of My Macros :  
 * macro in a library of OpenOffice Macros :  
 * macro in an extension installed for the current user :  
 * macro in an extension installed for all users :  
 * macro in a library of the document that calls the macro :  

MACROPARAM
The Basic macro  is stored in module   itself stored in library.
 * General case : the value of MACROPARAM is :  
 * Basic script in an extension : same as above. The directory  containing the files constituting the Basic library must be stored in the extension package (see description in section Basic / Application Library Container).

Remember that, unlike usual calls in Basic, you must respect the majuscules and minuscules of library, module, macro names.

BeanShell script
The BeanShell script is supposed to be created through the user interface, see section Editing, Creating and Managing Macros.

LANGPARAM
 

LOCPARAM

 * script in a library of My Macros :  
 * script in a library of OpenOffice Macros :  
 * script in an extension installed for the current user :   where myExtension.oxt is the file name of the extension package.
 * script in an extension installed for all users :  
 * script in a library of the document that calls the script :  

MACROPARAM
The BeanShell script  is stored in library.
 * General case : the value of MACROPARAM is :  
 * BeanShell script in an extension : same as above. The directory   containing the BeanShell script file and  parcel-descriptor.xml file must be stored in the extension package.

Java script
Java scripts are macros in compiled Java. This is different from language JavaScript. See section Scripting / Writing Macros / Compiling and Deploying Java macros.

LANGPARAM
 

LOCPARAM

 * script in a library of My Macros :  
 * script in a library of OpenOffice Macros :  
 * script in an extension installed for the current user :   where myExtension.oxt is the file name of the extension package.
 * script in an extension installed for all users :  
 * script in a library of the document that calls the script :  

MACROPARAM
The Java script file  is stored in directory. The Java method to be executed is  (this is the value of   element of the parcel-descriptor.xml file).
 * General case : the value of MACROPARAM is :  
 * Java compiled script in an extension : same as above. The directory  must be stored in the extension package.

JavaScript script
The JavaScript script is supposed to be created through the user interface, see section Editing, Creating and Managing Macros.

LANGPARAM
 

LOCPARAM

 * script in a library of My Macros :  
 * script in a library of OpenOffice Macros :  
 * script in an extension installed for the current user :   where myExtension.oxt is the file name of the extension package.
 * script in an extension installed for all users :  
 * script in a library of the document that calls the script :  

MACROPARAM
The JavaScript file  is stored in library.
 * General case : the value of MACROPARAM is :  
 * JavaScript script in an extension : same as above. The directory   containing the JavaScript file and  parcel-descriptor.xml file must be stored in the extension package.

Python script
The location of a Python script is described in Python as a macro language.

LANGPARAM
 

LOCPARAM

 * script in a library of My Macros :  
 * script in a library of OpenOffice Macros :  
 * script in an extension installed for the current user :  
 * script in an extension installed for all users :  
 * script in a library of the document that calls the script :  

MACROPARAM

 * General case : the Python module  is stored in directory   of the user or share directory of the installation, or of the document. The name of the Python function to be executed is  . The value of MACROPARAM is :  
 * Python script in an extension : myExtension.oxt is the file name of the extension package. The Python module is stored in directory  in this package. The value of MACROPARAM is :  

Complete URI examples
These URI's call a script stored in My Macros vnd.sun.star.script:myLibrary.myModule.myMacro?language=Basic&location=application vnd.sun.star.script:myLibrary.myMacro.bsh?language=BeanShell&location=user vnd.sun.star.script:myLibrary.myMethod?language=Java&location=user vnd.sun.star.script:myLibrary.myMacro.js?language=JavaScript&location=user vnd.sun.star.script:myModule.py$myFunction?language=Python&location=user

These URI's call a script stored in an extension installed for all users vnd.sun.star.script:myLibrary.myModule.myMacro?language=Basic&location=application vnd.sun.star.script:myLibrary.myMacro.bsh?language=BeanShell&location=share:uno_packages/myExtension.oxt vnd.sun.star.script:myLibrary.myMethod?language=Java&location=share:uno_packages/myExtension.oxt vnd.sun.star.script:myLibrary.myMacro.js?language=JavaScript&location=share:uno_packages/myExtension.oxt vnd.sun.star.script:myExtension.oxt|myScript|myModule.py$myFunction?language=Python&location=share:uno_packages

.

Storage of Scripts
A  is responsible for knowing about how its own macros are stored: where, what format and what kind of directory structure is used. The Scripting Framework attempts to standardize how to store and discover macros by defining:


 * A default directory structure.
 * Macros can only be stored under a directory with the language name ( as it appears in the script URI ) in lowercase under a directory called Scripts, which is located in either the user or share directories of a LibreOffice installation or a LibreOffice document.
 * Example for a  for the “JavaScript” macro library. It is located in /share/Scripts/JavaScript/Highlight


 * A generic mechanism for enabling discovery of macros in macro libraries and associating meta-data with scripts located in this libraries. See parcel-descriptor.xml in Compiling and Deploying Java Macros. Example the parcel-descriptor for the JavaScript Highlight macro library is located in /share/Scripts/JavaScript/Highlight/parcel-descriptor.xml

Implementation
A  implementation must follow the service definition com.sun.star.script.provider.LanguageScriptProvider

Since a  is an UNO component, it must additionally contain the component operations needed by a UNO service manager. These operations are certain static methods in Java or export functions in C++. It also has to implement the core interfaces used to enable communication with UNO and the application environment. For more information on the component operations and core interfaces, please see Component Architecture and Core Interfaces to Implement.



The interface Initialization supports method:

void initialize( [in] sequence arguments )

The  is responsible for organizing and execution of macros written in a specific language for a certain location. The possible locations for macros are within a document or either the user or share directories in a LibreOffice installation. The  is initialized for given location context which is passed as the first argument to the   method. The location context is a string with the following possible values

The com.sun.star.script.browse.XBrowseNode interface supported by a  service is the initial point of contact for the [AOo] application. In order for the  to process and display macros it needs to be able to list those macros. Additionally the  dialogs use the com.sun.star.script.browse.BrowseNode service to create/delete new macros and macro libraries.

The interface com.sun.star.script.browse.XBrowseNode supports the following methods:

The method  returns the name of the node.

The method  method should return the nodes which represent the next level in the hierarchy of macros and macro Libraries the   is managing.

The method  returns the type of the node.

Nodes can be of three types represented by the constants com.sun.star.script.browse.BrowseNodeTypes

The objects implementing  can must also implement com.sun.star.beans.XPropertySet.

Note that a node that has the,  ,   or   properties set to true is expected to implement the com.sun.star.script.XInvocation interface.

The interface com.sun.star.script.XInvocation supports the following methods:

The  function is passed as an argument the property keys of the com.sun.star.script.browse.BrowseNode service

Access to a macro if provided for by the com.sun.star.script.provider.XScriptProvider interface which supports the following method:

The  method is passed a script URI   and the LanguageScriptProvider implementation needs to parse this URI so it can interpret the details and validate them. As the  is responsible for exporting and generating the URI associated with a macro it is also responsible for performing the reverse translation for a give n URI and returning an object implementing com.sun.star.script.provider.XScript interface which will allow the macro to be invoked.

com.sun.star.script.provider.XScript which supports the following methods:

In addition to the parameters that may be passed to an object implementing com.sun.star.script.provider.XScript it is up to the that object to decide what extra information to pass to a running macro. It makes sense to pass information to the macro which makes the macro writer's job easier. Information such as a reference to the document (context), a reference to the service manager (available from the component context passed into the  component's constructor by UNO), and a reference to the desktop (available from UNO using this service manager).

All the Java based reference  provided with LibreOffice make this information available to the running macro in the form of an object implementing the interface com.sun.star.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 macros 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 the first argument to the macro.

Integration with Extension Manager
The Extension Manager is a tool for deploying components, configuration data and macro libraries (see chapter Extensions). It provides a convenient mechanism for macro developers to distribute their macros.

The scripting framework supports deployment of macros in extensions. Currently only extensions for the media type " " are supported. Macros deployed in extensions of this media type must use the  storage scheme and parcel-descriptor.xml to function correctly. An implementation of the com.sun.star.deployment.PackageRegistryBackend service is provided which supports deployment of macro libraries of media type " " with the Extension Manager.

Registration
Macro libraries contained in extensions are registered by the Extensions Manager. It informs the  by calling its   method. The  persists in the registration of the macro library in order to be aware of registered libraries when LibreOffice is restarted at a future time.

Deregistration
Deregistration of a macro library contained in an extension is similar to the registration process described above, the Extension Manager informs the  that a macro library has been removed by calling its   method. The  removes the macro library from its persisted store of registered macro libraries.

Implementation of LanguageScriptProvider with support for Package Manager


In order for the  to handle macro libraries contained in UNO packages with media type " " it's   method must be able to accept a special location context that indicates to the   that it is dealing with extensions.

On initialization the  needs to determine what macro libraries are already deployed by examining its persistent store.

A  that does not use the Java abstract helper class   will need to persist in the extensions deployed for the supported language themselves.

The  additionally needs to support the com.sun.star.container.XNameContainer interface which supports the following methods.

On registration of an extension containing scripts the 's   method is called with   containing the URI to a macro library contained in the extension and   contains an object implementing com.sun.star.deployment.XPackage Note that the URI contains the full path to the macro library contained in the extension. For example, if the library is named my macros then the path includes the MyMacros directory.

On deregistration of an extension containing scripts the 's   method is called with   containing the URL to a macro library to be de-registered.

com.sun.star.container.XNameContainer interface itself inherits from com.sun.star.container.XNameAccess which supports the following method

To determine whether the macro library in an extension is already registered the 's   is called with   containing the URL to the script library. The other methods of the interfaces inherited by com.sun.star.container.XNameContainer are omitted for brevity and because they are not used in the interaction between the Extension Manager and the. A Developer however still must implement these methods.

Implementation of the BrowseNode service
The  created for an installation deployment context needs to expose the macro and macro libraries that it is managing. How this is achieved is up to the developer. A  created by extending the Java abstract helper class   creates nodes for each extension that contain macro libraries for the supported language. Each extension node contains the macro library nodes for the supported language and those nodes in turn contain macro nodes.

An alternative implementation could merge the macro libraries into the existing tree for macro libraries and not distinguish whether the macros are located in an extension or not. This is loosely the approach taken for LibreOffice Basic.

Example of creating an extension containing a macro library suitable for deploying with Extension Manager. The following example shows how to create an UNO package from the Beanshell macro library Capitalize. This macro library is located in the /share/beanshell/Capitalize directory of a LibreOffice installation. The extension created will be deployable using the Extension Manager.

First create a scratch directory for example called temp. Copy the macro library directory and its contents into temp. In temp create a sub-directory called META-INF and within this directory create a file called manifest.xml.

 Temp | |- Capitalise | | | |--parcel-desc.xml | |--capitalise.bsh | |- META-INF | |--manifest.xml

The contents of the manifest.xml file for the Capitalize macro library are as follows

Next create a zip file containing the contents (but not including ) the temp directory. The name of the file should have the extension ".oxt" e.g. Capitalise.oxt.

Deploying a macro library contained in an extension.To deploy the extension you need to use the Extension Manager (see chapter Extensions). Once the extension has been deployed successfully the macro will be available for assignment or execution.