19  Scripting Framework

A OpenOffice.org macro is a short program used to automate a number of steps. The Scripting Framework is a new feature in OpenOffice.org [VERSION]. It allows users to write and run macros for OpenOffice.org in a number of programming and scripting languages including: 

This chapter is organized into the following sections: 

This section describes how to run and organize macros using the Tools-Macros submenu:

Illustration 19.1Tools-Macros submenu

To run a macro use the menu item Tools – Macros - Run Macro... This opens the Macro Selector dialog:

Illustration 19.2Macro Selector dialog

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

• My Macros (macros belonging to the current user) 

• OpenOffice.org Macros (macros available to all users of the installation) 

• DocumentName Macros (macros contained in the currently active document) 

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.

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 OpenOffice.org Basic macros.

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. 

Illustration 19.3BeanShell Organizer

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

Illustration 19.4BeanShell 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. 

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

Illustration 19.5JavaScript 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: 

Illustration 19.6JavaScript Debugger with Stack and Watch tabs displayed

Macro Recording is only supported for OpenOffice.org Basic and is accessible via the Tools-Macro-Record Macro menu item.

When the user creates a new macro in BeanShell or JavaScript, the default content of the macro is the HelloWorld. Here is what the code looks like for BeanShell: 

import com.sun.star.uno.UnoRuntime; 

import com.sun.star.text.XTextDocument; 

import com.sun.star.text.XText; 

import com.sun.star.text.XTextRange; 

oDoc = context.getDocument(); 

xTextDoc = (XTextDocument) UnoRuntime.queryInterface(XTextDocument.class,oDoc); 

xText = xTextDoc.getText(); 

xTextRange = xText.getEnd(); 

xTextRange.setString( "Hello World (in BeanShell)" ); 

// BeanShell OpenOffice.org scripts should always return 0 

return 0; 

Here is the same code in JavaScript: 

importClass(Packages.com.sun.star.uno.UnoRuntime); 

importClass(Packages.com.sun.star.text.XTextDocument); 

importClass(Packages.com.sun.star.text.XText); 

importClass(Packages.com.sun.star.text.XTextRange); 

oDoc = XSCRIPTCONTEXT.getDocument(); 

xTextDoc = UnoRuntime.queryInterface(XTextDocument,oDoc); 

xText = xTextDoc.getText(); 

xTextRange = xText.getEnd(); 

xTextRange.setString( "Hello World (in JavaScript)" ); 

Here is the code for HelloWorld in Java: 

import com.sun.star.uno.UnoRuntime; 

import com.sun.star.frame.XModel; 

import com.sun.star.text.XTextDocument; 

import com.sun.star.text.XTextRange; 

import com.sun.star.text.XText; 

import com.sun.star.script.provider.XScriptContext; 

public class HelloWorld { 

    public static void printHW(XScriptContext xScriptContext)

    {

        Xmodel xDocModel = xScriptContext.getDocument()

        // getting the text document object

        XTextDocument xtextdocument = (XTextDocument) UnoRuntime.queryInterface(

            XTextDocument.class, xDocModel);

        XText xText = xtextdocument.getText();

        XTextRange xTextRange = xText.getEnd();

        xTextRange.setString( "Hello World (in Java)" );

    }

} 

The table below outlines some of the features of macro development in the different languages: 

Instructions on compiling and deploying Java macros can be found later in this chapter.

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: 

• BeanShell: In the global Object[] variable ARGUMENTS

event = (ActionEvent) ARGUMENTS[0];

• JavaScript: In the global Object[] variable ARGUMENTS

event = ARGUMENTS[0];

• Java: The arguments are passed as an Object[] in the second parameter to the macro method

public void handleButtonPress(

    XScriptContext xScriptContext, Object[] args)

Because Java is a compiled language it is not possible to execute Java source code as a macro directly from within OpenOffice.org. The code must first be compiled and then deployed within a OpenOffice.org 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 OpenOffice.org 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 

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

<parcel language="Java" xmlns:parcel="scripting.dtd"> 

    <script language="Java">

        <locale lang="en">

            <displayname value="HelloWorld"/>

            <description>

                Prints "Hello World".

            </description>

        </locale>

        <functionname value="HelloWorld.printHW"/>

        <languagedepprops>

            <prop name="classpath" value="HelloWorld.jar"/>

        </languagedepprops>

    </script>

</parcel> 

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. All of the jar files in the  program/classes directory are automatically placed in the classpath.

• Copy the HelloWorld directory into the share/Scripts/java directory of a OpenOffice.org 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 OpenOffice.org is running, you will need to restart it in order for the macro to appear in the Macro Selector dialog. 

The parcel-descriptor.xml file is also used to detect BeanShell and JavaScript macros. It is created automatically when creating macros using the Organizer dialogs for BeanShell and JavaScript.

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 OpenOffice.org events, key combinations, menu and toolbar items 

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: 

The ScriptProvider class is an abstract Java class with three abstract methods: 

// this method is used to get a script for a script URI 

public abstract XScript getScript( String scriptURI ) 

    throws com.sun.star.uno.RuntimeException,

           com.sun.star.script.provider.ScriptFrameworkErrorException;

// This method is used to determine whether the ScriptProvider has a ScriptEditor 

public abstract boolean hasScriptEditor(); 

// This method is used to get the ScriptEditor for this ScriptProvider 

public abstract ScriptEditor getScriptEditor(); 

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

import com.sun.star.uno.Type; 

import com.sun.star.uno.Any; 

import com.sun.star.lang.IllegalArgumentException; 

import com.sun.star.lang.WrappedTargetException; 

import com.sun.star.reflection.InvocationTargetException; 

import com.sun.star.script.CannotConvertException; 

import com.sun.star.script.provider.XScriptContext; 

import com.sun.star.script.provider.XScript; 

import com.sun.star.script.provider.ScriptFrameworkErrorException; 

import com.sun.star.script.provider.ScriptFrameworkErrorType; 

import com.sun.star.script.framework.provider.ClassLoaderFactory; 

import com.sun.star.script.framework.container.ScriptMetaData; 

public class YourLanguageScript implements XScript 

{ 

    private XScriptContext xScriptContext;

    private ScriptMetaData scriptMetaData;

    public YourLanguageScript(XScriptContext xsc, ScriptMetaData smd)

    {

        this.xScriptContext = xsc;

        this.scriptMetaData = smd;

    }

    public Object invoke( Object[] aParams,

                          short[][] aOutParamIndex,

                          Object[][] aOutParam )

        throws com.sun.star.script.provider.ScriptFrameworkErrorException,

               com.sun.star.reflection.InvocationTargetException

    {

        // Initialise the out paramters - not used at the moment

        aOutParamIndex[0] = new short[0];

        aOutParam[0] = new Object[0];

        // Use the following code to set up a ClassLoader if you need one

        ClassLoader cl = null;

        try {

            cl = ClassLoaderFactory.getURLClassLoader( scriptMetaData );

        }

        catch ( java.lang.Exception e )

        {

            // Framework error

            throw new ScriptFrameworkErrorException(

                e.getMessage(), null,

                scriptMetaData.getLanguageName(), scriptMetaData.getLanguage(),

                ScriptFrameworkErrorType.UNKNOWN );

        }

        // Load the source of your script using the scriptMetaData object

        scriptMetaData.loadSource();

        String source = scriptMetaData.getSource();

        Any result = null;

        // This is where you add the code to execute your script

        // You should pass the xScriptContext variable to the script

        // so that it can access the application API

        result = yourlanguageinterpreter.run( source );

        // The invoke method should return a com.sun.star.uno.Any object

        // containing the result of the script. This can be created using

        // the com.sun.star.uno.AnyConverter helper class

        if (result == null)

        {

            return new Any(new Type(), null);

        }

        return result;

    }

} 

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

package com.sun.star.script.framework.provider; 

import com.sun.star.script.provider.XScriptContext; 

import com.sun.star.script.framework.container.ScriptMetaData; 

public interface ScriptEditor 

{ 

    public Object execute() throws Exception;

    public void indicateErrorLine( int lineNum );

    public void edit(XScriptContext context, ScriptMetaData entry);

    public String getTemplate();

    public String getExtension();

} 

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

The getTemplate() method should return a template of a macro in your language, for example the code to write HelloWorld into a document. The getExtension() 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 execute() and indicateErrorLine() 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 ScriptProviderForBeanShell to execute the source code that is displayed in the ScriptEditorForBeanShell, and to open the ScriptEditorForBeanShell at the line for which an error has occurred. The developer may wish to do the same when writing their ScriptProviderForYourLanguage and ScriptEditorForYourLanguage. 

The following code shows an example ScriptEditorForYourLanguage.java file: 

import com.sun.star.script.framework.provider.ScriptEditor; 

import com.sun.star.script.provider.XScriptContext; 

import com.sun.star.script.framework.container.ScriptMetaData; 

import javax.swing.*; 

public class ScriptEditorForYourLanguage implements ScriptEditor 

{ 

    public Object execute() throws Exception

    {

        return null;

    }

    public void indicateErrorLine( int lineNum )

    {

        return;

    }

    public void edit(XScriptContext context, ScriptMetaData entry)

    {

        JFrame frame = new JFrame();

        frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);

        JTextArea ta = new JTextArea();

        entry.loadSource();

        ta.setText(entry.getSource());

        frame.getContentPane().add(ta);

        frame.setSize(400, 400);

        frame.show();

    }

    public String getTemplate()

    {

        return "the code for a YourLanguage script";

    }

    public String getExtension()

    {

        return "yl";

    }

} 

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 OpenOffice.org installation. The jar files that you need to include are: ridl.jar, sandbox.jar, unoil.jar, jurt.jar and ScriptFramework.jar.

To compile ScriptProviderForYourLanuage: 

vnd.sun.star.script:MACROREF?language=Language&location=[user|share|document]

where: 

A LanguageScriptProvider 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 OpenOffice.org installation or a OpenOffice.org document.
  Example for a LanguageScriptProvider for the “JavaScript” macro library. It is located in
  
  <OfficePath>/share/Scripts/JavaScript/Highlight

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

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

Illustration 19.10: LanguageScriptProvider

In order for the LanguageScriptProvider to handle macro libraries contained in UNO packages with media type ”application/vnd.sun.star.framework-script” it's initialize() method must be able to accept a special location context that indicates to the LanguageScriptProvider that it is dealing with extensions.

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

LanguageScriptProviders created by implementing the abstract Java helper class  com.sun.star.script.framework.provider.ScriptProvider do not need to concern themselves with storing details of registered macro libraries in extensions. This support is provided automatically. An XML file called unopkg-desc.xml contains the details of deployed UNO script packages . This file located in either <OfficePath>/user/Scripts or <OfficePath>/share/Scripts depending on the installation deployment context. The DTD for unopkg-desc.xml follows <?xml version="1.0" encoding="UTF-8"?>  <!-- DTD for unopkg-desc for OpenOffice.org Scripting Framework Project -->    <!ELEMENT package EMPTY>  <!ELEMENT language (package+)>  <!ELEMENT unopackages (language+)>  <!ATTLIST language          value CDATA #REQUIRED >  <!ATTLIST package          value CDATA #REQUIRED >  An example of a sample an uno-desc.xml file is shown below.  <unopackages xmlns:unopackages="unopackages.dtd">    <language value="BeanShell">     <package value="vnd.sun.star.pkg://vnd.sun.star.expand:         $UNO_USER_PACKAGES_CACHE%2Funo_packages%2Flatest.uno.pkg/WordCount" />   </language>   <language value="JavaScript">     <package value="vnd.sun.star.pkg://vnd.sun.star.expand:         $UNO_USER_PACKAGES_CACHE%2Funo_packages%2Flatest.uno.pkg/ExportSheetsToHTML" />     <package value="vnd.sun.star.pkg://vnd.sun.star.expand:         $UNO_USER_PACKAGES_CACHE%2Funo_packages%2Flatest.uno.pkg/JSUtils" />   </language> </unopackages

A LanguageScriptProvider that does not use the Java abstract helper class  com.sun.star.script.framework.provider.ScriptProvider will need to persist the extensions deployed for the supported language themselves.

The LanguageScriptProvider 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  LanguageScriptProviders created by extending the Java abstract helper class  com.sun.star.script.framework.provider.ScriptProvider 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 OpenOffice.org Basic.  

The following example shows how to create an UNO package from the Beanshell macro library Capitalize. This macro library is located in the <OfficeDir>/share/beanshell/Capitalize directory of a OpenOffice.org 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.

<Dir> Temp 

| 

|-<Dir> Capitalise 

|  |

|  |--parcel-desc.xml

|  |--capitalise.bsh

| 

|-<Dir> META-INF 

   |

   |--manifest.xml

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

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

<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd"> 

<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest"> 

 <manifest:file-entry manifest:media-type="application/vnd.sun.star.framework-script" manifest:full-path="Capitalise/"/>

</manifest:manifest> 

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.