Revision as of 17:21, 13 October 2006

UNO Packages: Basic Principles

The OpenOffice.org extension deployment concept based on UNO packages is not limited to code, it also allows to install other things like templates, autotexts etc. in handy packages. Here's a short explanation how this basically works. It is targeted to advanced end users and administrators. Most of the things explained here are discussed more detailed and comprehensive elsewhere. The purpose of this documentation is to provide an overview and an explanation of the basic concepts. If you want to learn more about UNO you can check our UNO wiki or the web pages of the UDK project.

All information provided here describes what is found in OpenOffice.org 2.0.4. Differences to older versions are not explained though it is explicitly mentioned when something has been added in 2.0.4 first.

UNO packages are more or less zip containers with some additional data and meta data describing its content. They can be deployed by the built-in Package Manager GUI (“Tools – Package Manager”). This installs the package for the current user using OpenOffice.org. The same can be done by using the command line tool “unopkg” that is located in the OOo program folder. This tool also allows to deploy a package not only for a single user but for all of them by using the “--shared” parameter.

When packages are installed their content is copied to some well defined though private places below “share/uno_packages” or “user/uno_packages”, depending on the scope of the package installation (whole installation or single user). "Private" means: don't write any code that relies on the particular structure of an unpacked UNO component, access to unpacked files must use a defined API that handles the details for the caller. Files outside the "uno_packages" folders are not touched at all, with a single exception that can be seen as a bug: Basic macros in UNO packages still need to be registered in xlc-files in one of the "basic" directories.

UNO packages also support "Live deployment". This is different to e.g. Firefox where you always have to restart the application to make the extension available. In OpenOffice.org you can basically use the extension right after its installation. There is a restriction though: it is possible that the OpenOffice.org code using whatever is installed by the package might "cache" what it finds when it is executed the first time and does not update this cached information when external influences (like the installation of a package) actually would make it invalid. So at least either opening a new window or document or restarting the application can be necessary. In most cases this can be seen as a bug. As an example, in OpenOffice.org 2.0.4 templates packages can be installed whenever wanted, but gallery packages should be installed before the gallery is used the first time.

Extensions containing UNO services (code)

If a UNO package contains a UNO component written in Java, C++ or Python this component must publish its functionality to become usable for OpenOffice.org. In UNO based development a defined set of functionality is called a "service". A service is identified and accessed by its service name. So A component implementing such services must tell the world how they are named. Nowadays all components export a function that unopkg can call to force the component to write the necessary information into a service registry file that is created and maintained inside the „uno_packages“ folder. When OpenOffice.org uses its Service Manager to look for available UNO services it will scan not only the service registry (services.rdb) in its program directory (containing information about all "internal" services) but also all registry files inside the “uno_packages” folders.

Of course OOo can only instantiate UNO services by their names if it knows them. This is easy for services that replace already existing "internal" ones as OOo surely knows them and uses them, but as most components provide new services there must be something else that enables OOo to use them though they are not known at its compile time. So in these cases UNO components must provide additional data about when a particular service they implement should be loaded. The „additional component data“ is provided in OOo configuration files.

An example for this is a document filter component where the additional data that needs to be provided is (amongst other things) the file type that the filter can load. A particular filter component might register itself for being able to load Word Perfect files. So if a user selected this filter to load a file OOo would find the registered data by searching for any data containing the desired file type (wps), instantiate the filter component by its service name found in this data and use it to load the file. Each built-in filter has its own configuration data and document filters in UNO packages provide their own configuration data that extends the preinstalled data. So the Configuration Manager must be able to locate them and integrate their content in the suitable way.

Package support in the Configuration Manager

The Configuration Manager has a similar ability as the UNO Service Manager, it can scan a set of folders for data. The list of folders is even extendable itself (through configmanager.ini) so that the Config Manager can get additional "layers". It can even use the possibility to add other backends than the file system but I leave this out here. How does the Configuration Manager handle layers?

The configuration data is arranged in a tree structure, data can be filled into this structure in every layer. The Configuration Manager scans the layers (folders) in a way that the data in "higher" layers either replaces or extends the data in "lower" layers, pretty much like the Windows registry. Wether data is replaced or extended depends on the type of the data and is explained in the discussion of the configuration schema for our path settings.

By default OpenOffice.org has two layers you already know: "share" and "user". The former contains preinstalled data, the latter takes all settings a particular users created by himself. Configuration files in UNO packages create two new layers, "share/uno_packages" and "user/uno_packages". They lie in between the default layers, in the obvious order of priority "share" - "share/uno_packages" - "user/uno_packages" - "user".

So a component can extend or change the OpenOffice.org configuration by providing xcu files in its package that overwrite or extend (merge) configuration settings of OpenOffice.org. It can also have its own configuration settings if it provides a schema (xcs) files in its package.

There is another (pretty obvious) use case for the layering concept of the Configuration Manager: overwriting the preinstalled OpenOffice.org configuration settings on the "all users" level. An administrator can customize the OpenOffice.org installation in his own account, take the created xcu files containing these customizations and bundle them in a package that he installs with "unopkg add --shared" each time he installs, reinstalls or updates OpenOffice.org. No need to edit the xcu files in "share/registry" by hand!

The layering concept of the service registry and the configuration are the basic principles that create the power of UNO packages.

Path Settings

Some data in OpenOffice.org is not stored in xcu configuration files but somewhere else in the file system, e.g. document templates, autotexts, gallery content etc. Of course this content also should be deployable in packages, so the access to these files must have a layering concept. OpenOffice.org has some components that manage the access to the files. We could have extended these components in the same way as we have extended the Configuration Manager or the Service Manager (by enabling them to use layers explicitly), but we decided to reuse the already available capability of the Configuration Manager.

The place where these files are looked for is defined in the configuration, in our path settings. Each "path" in any OOo version prior to 2.0.4 either was a single string describing a folder or a list of strings describing a list of folders ("multipath"). Unfortunately such a list can only be overwritten in upper layers, but not extended, so we needed a new configuration schema for paths that uses "sets" of strings instead of "string lists" as sets are extendable. We use this new schema for path settings starting with OpenOffice.org 2.0.4. We kept the old schema and its data for compatibility reasons and migrate its settings to the new data. The old schema will be removed in OpenOffice.org 3.0.

In earlier versions of OOo you usually could see the two "templates" folders in the "share" and "user" trees of OpenOffice.org. You also could see any additional folders that either the user of the administrator might have added.

If you look on the “Paths” settings in the “Options” Dialog in OOo2.0.4 you will notice that not all parts of the multipaths are shown here, only the folders from the "UserPaths" and "WritePath" elements from the new configuration schema. As the former is empty in a default installation usually only one folder is visible per path setting.

Dialog Tools - Options - Paths

Have a look on the path for templates. You can see "user/template" as this is the "WritePath" element and another folder ("g:\Departement Templates") that has been added as part of the "UserPaths" element, either by an administrator or by the user himself. You don't see the "share/templates" folder here as it is part of the "InternalPaths" element whose content intentionally isn't shown in the dialog. This element is the extendable part of the path setting and it contains all folders that are added either by the OOo installation itself or by the installation of a package. As they have been added by deployement they shouldn't be controlled by the user, removing them is a task for those who have added them.

An improvement for the users as well as for the OpenOffice.org code is that now the folder that a user can put own data in is selected explicitly by marking it with a radio button. In older versions it was always a little bit unclear which folder OpenOffice.org whould choose. In most cases it was the last one of the list but now everything is unmistakable.

Dialog Tools - Options - Paths - Edit

Template Packages

A UNO package for document templates is quite simple. It mainly contains just the templates, organized in directories that define template categories for the Document Templates Manager. Additionally a Paths.xcu file has to be provided that registers the package in the set of document templates folders. This file contains the URL of the folder where the templates in the package will be unpacked to. As this is something that isn't known at package creation time a variable is used in the URL that is replaced by the package manager when he copies the xcu file to the final location. The good thing is that this variable will always be the same for each template package so there is no need for the creator of such a package to create by himself:

Paths.xcu [xml] <?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"

   oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation" 
   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:component-data>

If you compare this data with the data in the installation you can see that both files contain something in the "InternalPaths" that the configuration merges into its name container representing this element. Merging is caused by the "fuse" keyword that defines the operation "add me to the container or create a new container if it doesn't exist".

Example Package

Here is an empty package for document templates that is ready to be filled with templates.

The zip container has a folder called “templates”. Any sub folder of it you create will appear as a template category in the OOo templates dialogs. Templates can be put into those sub folders. The title of the template will be taken from the document metadata (document properties) or from the file name if the title in the metadata is not set. If one of your sub folders has the same name as an existing template category the templates in the package will be merged into this category by the OpenOffice.org templates component. Just try it out, it's simpler to do it than to explain it.

Localization of templates and template categories

The titles of the categories and templates can be taken from the file and folder names. These names can be localized and use any characters that the zip container and the target file systems(s) allow. It is possible that templates are installed on file systems that have problems with localized category (=folder) names so the Document Templates component allows to provide these localized names in a different file. The localized document template names can be stored in the document meta data (Document Properties) so they don't create a problem here.

The localization file is called "groupuinames.xml" and it is placed in the "templates" sub directory of the package. Its content is pretty straightforward. Here's an example for a german localization of some folders that use english file names:

groupuinames.xml [xml] <?xml version="1.0" encoding="UTF-8"?> <groupuinames:template-group-list xmlns:groupuinames="http://openoffice.org/2006/groupuinames">

       <groupuinames:template-group groupuinames:name="educate" 
               groupuinames:default-ui-name="Bildung" />
       <groupuinames:template-group groupuinames:name="layout" 
               groupuinames:default-ui-name="Präsentationshintergründe" />
       <groupuinames:template-group groupuinames:name="misc" 
               groupuinames:default-ui-name="Diverses" />
       <groupuinames:template-group groupuinames:name="officorr" 
               groupuinames:default-ui-name="Geschäftliche Korrespondenz" />
       <groupuinames:template-group groupuinames:name="offimisc" 
               groupuinames:default-ui-name="Sonstige geschäftliche Dokumente" />
       <groupuinames:template-group groupuinames:name="personal" 
               groupuinames:default-ui-name="Private Korrespondenz und Dokumente" />
       <groupuinames:template-group groupuinames:name="presnt" 
               groupuinames:default-ui-name="Präsentationen" />

</groupuinames:template-group-list>

Multi language template packages

Multi language template packages are also possible, they need a small modification in line no. 13 of the Paths.xcu file:

Paths.xcu [xml] <?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office" oor:name="Paths"

   xmlns:install="http://openoffice.org/2004/installation" 
   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="%origin%/template/$(vlang)" oor:op="fuse"/>

and additional directories need to be created be the "templates" folder that have the ISO language codes supported by the OOo language packs as their names. I have created a second empty package file that provides the infrastructure. Take it and put german templates into the "de" folder, english ones into "en-US", french ones into "fr" etc. Empty folders are not a problem. The localization files (groupuinames.xml) now need to be placed into the language specific folders, not directly into the "templates" folder as in the single language package.

AutoText Packages

Everything told about template packages also applies to packages for autotexts. The Paths.xcu of course now doesn't contain a value for the "Template" path but for the "AutoText" path. Again here is an example package that can be filled with autotext files. As currently there is no exporter you can manually copy any ".bau" files you have created into the package. And also creating packages with localized autotexts works the same way: put the files into sub folders with names created from ISO language codes like you can see in the "share/autotext" folder.

There is a tricky part here when you deploy autotext packages: currently the autotext GUI allows to save autotexts to arbitrary locations. This is a bug that needs to be fixed. Any changes applied to autotexts in a package will get lost when the package is deinstalled. Package content is not meant to be changed!

Gallery Packages

Everything told about template packages also applies to packages for gallery items. The Paths.xcu of course now doesn't contain a value for the "Template" path but for the "Gallery" path. Again here is an example package that can be filled with gallery themes you have created by yourself. As this is a little bit tricky and the gallery code currently is prone to name clashes of the theme files. So it is not recommended to use gallery packages until the issue about these problems is fixed.