Extension Deployment

First considerations

Extension deployment should not be considered as an independent task.

Indeed, when you need to deploy extensions on a number of workstations, you'll need also to deploy templates, autotexts, gallery themes, and so on, because you'll need to preserve a relative homogeneity. In fact, you'll often need to deploy extensions in the same time you need to deploy templates, autotexts and gallery themes.

This is the reason why it is suggested here to consider the following approach:

1 - to define the structure of a package which aims to deploy in one operation extensions, including macro and toolbars, templates, autotexts and gallery themes;

2 - to define the user interface of an administration tool whose goal is to create such a package;

3 - to define the user interface of a user tool which would enable the end user to install the package on her workstation, or the administrator to install it in the shared installation tree.

Technical context

Before specifying the content of the package, we must keep in mind some technical constraints induced by the implementations of the configuration objects, and the rules for specifying their location.

The OOo registry

Apache OpenOffice comes with its own registry system.

The registry is implemented in a directory named "registry", as well in the shared installation directory as in the user .openoffice.org2/user directory.

When the user modifies its Apache OpenOffice environment, sometimes its registry is changed, sometimes not. The installation process should not alter directly the user Apache OpenOffice directory if this change cause alteration in the registry. In this case, the work should be taken in charge by Apache OpenOffice, thus the installation process should invoke Apache OpenOffice API.

Default locations

Default locations of the objects seem to be specified in the file

$(insturl)/share/registry/schema/org/openoffice/Office/Common.xcs

In most configuration files, some frequently used locations are referenced via variables:

$(insturl) represents the installation directory, eg. /opt/openoffice.org2.0

$(userurl) represents the user configuration directory, eg. /home/smith/.openoffice.org2/user

$(work) stands for the user work directory.

Templates

The default locations of templates are specified in the following XML part:

<prop oor:name="Template" oor:type="oor:string-list">

<info>

<desc>Specifies the templates originate from these folders and sub-folders.</desc>

</info>

<value oor:separator=":">$(insturl)/share/template/$(vlang):$(userurl)/template</value>

</prop>

Templates are objects very similar to other objects produced with the suite. The only differences stand in the 't' in place of 'd' in the second place of the suffix, and in the virtual tree for accessing to them, built from the set of paths declared in the configuration files.

From the time the user changes something in the paths, they are stored in the file

$(userurl)/registry/data/org/openoffice/Office/Common.xcu

Autotexts

The default location of autotexts is specified in the following XML part:

<prop oor:name="AutoText" oor:type="oor:string-list">

<info>

<desc>Contains the directory which contains the AutoText modules.</desc>

</info>

<value oor:separator=":">$(insturl)/share/autotext/$(vlang):$(userurl)/autotext</value>

</prop>

Autotexts are organized in categories. The user can create as many categories as she wants, and ask for storing them in one of the directories declared in the configuration file, provided that she has write access. Each category is implemented in a file named <category_name>.bau which is in fact a zip archive.

Nevertheless, if the category name contains special characters, they are silently dropped from the file name. Thus, it is more robust to search the category name in the file BlockList.xml included in the archive.

Databases

The databases are described in .odb files which may be stored anywhere. this ones are standard OOo archive. The content.xml file describe the data source and some attributes of the database.

The databases are declared in the registry directory, in the file:

$(userurl)/registry/data/org/openoffice/Office/DataAccess.xcu

The database name must appear in the "RegisteredNames" node.

<node oor:name="RegisteredNames">

...

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

<prop oor:name="Location" oor:type="xs:string">

<value>file://the/location/of/the/database.odb</value>

</prop>

<prop oor:name="Name" oor:type="xs:string">

<value>the_database_name</value>

</prop>

</node>

...

</node>

Gallery's themes

At the moment, managment of themes in OOo seems a little bit twisted.

Themes are stored in three binary files, those format are inherited from StarOffice.

This files are suffixed with .sdg, .sdv and .thm.

The .thm file contains, among binary data, the name of the theme, as given by the user.

The name of each file is of the form sgNNN.xxx where NNN is a number (the same from the three files) and xxx the suffix.

Apparently, the only rule for choosing the number is to obtain unique file names in the target directory.

This implementation is adequate for a local managment of themes, but doesn't give satisfaction when exchanging themes between users. Indeed, the question is: how to detect duplicates during the installation?

using the file name?: as the file name is, in a way, randomly given during installation, the same theme may be given different names depending on the history of previous installations on different workstations. Furthermore, OOo may have given the same filename to different themes created on different workstations.

using the name stored in the .thm file?: if this name is too generic, as "people", "events" or "houses", the same name may be given to different themes created by different users.

Thus, at the installation time, it is pertinent to consider the following cases:

the number and the theme name doesn't exist: to install directly the theme;

the number already exists and the theme name doesn't exist: to search another discriminatory number;

the theme name already exists: to ask the user if the existing theme must be overwritten, or the new one renamed, or its installation aborted.

It is important to systematically search for the theme name in all already existing themes.

Macros

to be completed

Toolbars

to be completed

The package manager

At this stage, it is important to consider the package management provided by OpenOffice.org V2.

The package manager can import, enable, disable and export packages.

In the package you can store one module containing several libraries of macros.

You can describe additional main menu items, tools menu items and buttons for launching the macros. The buttons are grouped in one new toolbar.

At the moment, the package manager can't manage templates, autotexts nor gallery themes.

A package is a zip archive.

The root of this archive contains an addons.xcu file whose contains is described here

Background

This project should not start from zero. Some work has already been done, and here is some non-exhaustive reference to it.

Bernard Marcelly has written a document called "How to Distribute Macros with an Addon" containing macros making it very easy to create a package. This document is outdated. For OpenOffice.org 2.x see page Extensions_Packager

Didier Dorange-Pattoret has written a macro allowing easy installation of galleries.

Laurent Godard has written DicOOo which installs dictionaries on a workstation, and which is now distributed with OpenOffice.org V2.

Philippe Allart has written a simple bash script which complies to the structure proposed below, and which use the tool of Didier Dorange-Pattoret

Specification of a configuration package

Layout

To be consistent with the technological choices of the developers team of Apache OpenOffice, it is suggested that the package be implemented as a zip archive.

This archive should contain one directory for each type of object.

Perhaps, it would be a good idea to add a "goodies" directory, allowing to add objects not directly concerned by the configuration process, but which would be very useful for end users.

Thus, the suggested tree could be as follows:

/

- tools allowing installation of the package

- specifications for installation (location of templates, ...)

1. /autotexts/

1. - autotexts (.bau files) to be installed

1. /packages/

1. - packages (.zip files) to be installed

1. /databases/

1. - databases (.odb files) to be installed and possibly local data

1. /templates/

1. - templates to be installed

1. /autocorr/

1. - .dat files containing replacement rules and exceptions

1. /wordbooks/

1. - dictionaries to be installed

1. /fonts/

1. - fonts to be installed

1. /gallery/

1. - themes to be installed

1. /goodies/

Dependencies

The objects in the package are not fully independent of others. For instance, a macro may refer to styles coming with a template and be called when the document is created.

Furthermore, some objects in the package may depend on the previous installation of other objects.

Thus, it will be very useful to identify all types of dependencies, and how and where to express them.

Specifications for installation

At this stage, it is necessary to define what will be specified, and how it will be, for the installation process.

It is useless to re-invent the wheel, and it seems a good idea to reuse the structure of the addons.xcu file used by the package manager.

Indeed, this structure is very generic, in the sense that it doesn't contain specific tags. In fact, it's just a set of two columns tables containing properties/values pairs. These tables are organized in a tree where each node has a name as an attribute.

Formally, the XML Schema is as follows:

XML Schema to be described

Now, the work stands in:

to define the structure of the tree, and to give a name to each node;

for each node, to define the content of the table, i.e. the set of properties/values pairs.

Contributors

--Pallart 16:34, 6 April 2006 (CEST)