Non-code extensions

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 end users and administrators. If you want to learn more about UNO you can check our UNO wiki or the web pages of the UDK project.

UNO packages are more or less zip containers with some additional data and meta data describing its content. If such a 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". So a component implementing such services must tell the world how they are named by providing a registry file (services.rdb) containing this information and probably another registry file (types.rdb) in case it uses and defines some new UNO types. Other components that don't implement such concrete services use extendable configuration entries to make their existence known to OpenOffice.org or to bind themselves to events that happen in the program.

The Configuration Manager of OpenOffice.org has the same ability to scan an extendable set of folders as the Service Manager. So a component can extend or change the OpenOffice.org configuration in the same way: by providing xcu files in its package that overwrite or extend configuration settings of OpenOffice.org. It is also possible to add new configuration settings by providing schema (xcs) files. Some configuration entries are used by OpenOffice.org to manage and access components (e.g. document filters or UI command dispatchers). So components in packages can integrate themselves by extending these entries in their package.

UNO packages can be deployed by the built-in Package Manager GUI (“Tools – Package Manager”) or by the command line tool “unopkg” that is located in the OOo program folder. The latter also allows to deploy a package not only for a single user but 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.

When now 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 but also all registry files inside the “uno_packages” folders. Installing and removing components is done by adding or removing packages with unopkg, the global registry files are not touched at all.

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

Path Settings

Besides the the mentioned component registrations e.g. for document filters there is another (pretty obvious) use case for the layering concept of the Configuration Manager: overwriting of 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!

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, but here usually you don't want to overwrite existing content, you want to add something. So the access to these files must have a layering concept also. 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, either as a single path or a list of paths ("multipath"). Unfortunately such a path list can only be overwritten in upper layers, but not extended, so we needed a new configuration schema for paths that uses "sets" instead of "lists" as they can be extended by packages. We use this new schema for paths 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.

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. In earlier versions of OOo you usually could see two folders e.g. for templates: $(share)/templates and $(user)/templates, where "$(share)" and "$(user) are variables for the share and user folders of the particular installation. You also could see any additional folders that either the user of the administrator might have added. In OOo2.0.4 you still will see $(user)/template and these additional folders (in case there are any), but you won't see $(share)/templates here. If any packages containing document templates are installed their folder won't be shown here also, this dialog now is only a tool for the user to customize the settings that under his own direct control.

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:name="Paths">

<node oor:name="Template" oor:op="fuse"> <node oor:name="InternalPaths"> <node oor:name="%origin%/template" oor:op="fuse"/> </node> </node>

</node> </oor:component-data>

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 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="Paths">

<node oor:name="Template" oor:op="fuse"> <node oor:name="InternalPaths">

                               <node oor:name="%origin%/template/$(vlang)" oor:op="fuse"/>

</node> </node>

</node>

</oor:component-data>

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.