Difference between revisions of "Non-code extensions"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (Localization of templates and template categories)
(Extensions containing UNO services (code))
Line 26: Line 26:
 
== Extensions containing UNO services (code) ==
 
== Extensions containing UNO services (code) ==
  
If an OOo extension 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.
+
If an OOo extension 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.  
 
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 extensions 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.  
+
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 extensions 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.
  
 
== Extension support in the Configuration Manager ==
 
== Extension support in the Configuration Manager ==

Revision as of 21:03, 25 October 2006

OOo Extensions project

Please view the wiki usage guidelines
before contributing.

Categories:

Pages:

Extensions on the main site

Extensions in other languages:
ES - FR - IT - JA - NL - OC -

OOo Extensions: Basic Principles

OpenOffice.org was designed to be extendable from its very beginning. At first every extension was something that contained code (e.g. written in Java or OOo Basic). It was integrated into OOo by our component technology called UNO, so the file containing such an extension was called a "UNO package". Meanwhile OOo extension have reached the world of end users and so we thought that it's time to change our terminology a bit. The following documentation takes this into account. It tries to avoid the more technical term "UNO package" where possible as 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.

The OpenOffice.org extension concept is not limited to code, it also allows to install other things like templates, autotexts etc. in handy single files. Here's a short explanation how this basically works. It is targeted to advanced end users, administrators and development newbies. 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.

If you are not interested in development at all you might want to skip the section about code extensions.

The section about the Configuration Manager gives you some ideas how you can use OOo extensions for customization purposes.

If you are only interested in knowing how to create non-code extensions without really knowing how this works you can go right to the section about "Path Settings". You should read at least this introducing section though.

Please send feedback to Ooo-email.PNG. In case you have an account for this wiki you can of course also use the "Discussion" tab at the top of this page.

OOo Extensions are more or less zip containers with some additional data and meta data describing its content. They can be deployed by the built-in Extension Manager GUI (“Tools – Package Manager”, it will become renamed to "Tools-Extension Manager" in 2.0.5). It installs the extension 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 an extension not only for a single user but for all of them by using the “--shared” parameter.

When extensions 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 extension installation (whole installation or single user). "Private" means: don't write any code that relies on the particular structure of an unpacked extension, 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 OOo extensions still need to be registered in xlc-files in one of the "basic" directories.

OOo extensions 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 extension 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 an extension) 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 extensions can be installed whenever wanted, but gallery extensions should be installed before the gallery is used the first time.

Extensions containing UNO services (code)

If an OOo extension 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 extensions 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.

Extension 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 and puts them all together. The list of folders is extendable itself (through configmanager.ini) so that the Config Manager can get additional "layers". It even has the ability to use other backends than the file system for additional layers but I leave this out here.

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 does. 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 OOo extensions 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 an extension can extend or change the OpenOffice.org configuration by providing xcu files that overwrite or extend (merge) configuration settings of OpenOffice.org. It can also have its own configuration settings if it provides schema (xcs) files for them.

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 an extension 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 OOo extensions.

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 as extensions, so the access to these files must have a layering concept that allows extensions to meddle in the access to the files. 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

      Dialog Tools Options 204.png

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 an extension. 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

      Dialog Tools Options Edit 204.png

Templates Extensions

An extension 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 extension in the set of document templates folders. This file contains the URL of the folder where the templates in the extension will be unpacked to. As this is something that isn't known the creation time of the extension a variable is used in the URL that is replaced by the extension 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 templates extension so there is no need for the creator of such an extension 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>

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

Here is an "empty extension" 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 extension 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 zip container. 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 templates extensions

Multi language templates extensions 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 extension 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 extension.

AutoText Extensions

Everything told about templates extensions also applies to extensions 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 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 extension. And also creating extensions 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. As distinct from the template path the autotext path doesn't need to contain "$(vlang)" for multi language extensions as the autotext management component implements the language dependent access internally.

There is a tricky part here when you deploy autotext extensions: 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 an extension will get lost when the extension is deinstalled. Extension content is not meant to be changed directly!

Gallery Extensions

Everything told about templates extensions also applies to extensions 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 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 it is not recommended to use gallery extensions until the issue about these problems is fixed.

Extensions for dictionaries and user wordbooks

This is work in progress as we have to redesign the file access of the linguistic tools. So stay tuned. You can refer to the issue that covers this.

Personal tools