Documentation/DevGuide/Scripting/Integration with Extension Manager

OpenOffice.org Developer's Guide

Scripting Framework

< Previous Section

Next Section >

• Using the Scripting Framework

• Running Macros
• Editing, Creating and Managing Macros

• The Organizer dialogs for BeanShell and JavaScript
• BeanShell Editor
• JavaScript Editor
• Basic and Dialogs
• Macro Recording

• Writing Macros
• How the Scripting Framework Works
• Writing a LanguageScriptProvider UNO Component using the Java Helper Classes

• The ScriptProvider Abstract Base Class
• Implementing the XScript Interface
• Implementing the ScriptEditor Interface
• Building and Registering Your ScriptProvider

• Writing a LanguageScriptProvider UNO Component From Scratch

• Scripting Framework URI Specification
• Storage of Scripts
• Implementation
• Integration with Extension Manager

< Previous Page

Next Page >

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 "application/vnd.sun.star.framework-script" are supported. Macros deployed in extensions of this media type must use the ScriptingFramework 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 "application/vnd.sun.star.framework-script" with the Extension Manager.

Overview of how ScriptingFramework integrates with the Extension Manager API

Registration of macro library using Package Manager

Registration

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

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.

Implementation of LanguageScriptProvider with support for Package Manager

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.

Location context
"user:uno_packages"	String. Denotes the user installation deployment context.
"share:uno_packages"	String. Denotes the share installation deployment context.

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

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 additionally needs to support the com.sun.star.container.XNameContainer interface which supports the following methods.

  void insertByName( [in] string aName, 
                     [in] any aElement ) 
  void removeByName( [in] string Name )

On registration of an extension containing scripts the LanguageScriptProvider's insertByName() method is called with aName containing the URI to a macro library contained in the extension and aElement 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 LanguageScriptProvider's removeByName() method is called with aName 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

  boolean hasByName( [in] string aName )

To determine whether the macro library in an extension is already registered the LanguageScriptProvider's hasByName() is called with aName 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 LanguageScriptProvider. A Developer however still must implement these methods.

Implementation of the BrowseNode service

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.

Example of creating a 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 <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.

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.

Content on this page is licensed under the Public Documentation License (PDL).