Non-code extensions
| OOo Extensions project
Please view the wiki usage guidelines
|
|---|
|
Categories: Pages: |
| Extensions on the main site |
|
Extensions in other languages: |
Contents
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 are 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. 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.
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". They are identified and accessed by their service names. A component implementing such services must tell the world how they are named. Nowadays all components export a function that unopkg can call that forces the component to write the necessary information into a service registry file that is created and maintained inside a „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.
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.
Package support in the Configuration Manager
The Configuration Manager of OpenOffice.org has the same ability to scan an extendable set of folders as the Service Manager. If it finds several configuration files in these folders that contain data for the same elements in the tree of configuration entries it either merges them or replaces data in lower layers by data in higher layers, depending on the type of configuration data. This is well known from the fact that configuration data users have created always get the highest priority, preinstalled data in the "share" layer has the lowest. Configuration data in the UNO packages layers lie in between: configuration data in shared UNO packages has a higher priority than in the preinstalled share layer, but lower than data in user specific UNO packages that again have lower priority as the user layer.
But which data is merged, which is replaced when at least two configuration layers are put together?
The Configuration Manager usually gets its data from xml files (extension xcu) with typed elements. It supports some basic types, structured types that needs to be defined in schema files (extension xcs) and lists of all these types. They are not extendable. If the configuration finds different values for them in different layers the higher layer "wins". Merging configuration items and so extending functionality that relies on them needs the "set" type. Please look at the configuration schema mentioned in the "Path Settings" section to understand how this works.
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 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!
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, 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>
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="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.
