Difference between revisions of "Non-code extensions"
m (→Localization of templates and template categories) |
m (→Multi language templates extensions) |
||
| (96 intermediate revisions by 10 users not shown) | |||
| Line 1: | Line 1: | ||
| + | {{Extensions}} | ||
| + | [[Category:Extensions]] | ||
__TOC__ | __TOC__ | ||
| − | = | + | = 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 [https://wiki.openoffice.org/wiki/Uno UNO wiki] or the web pages of the [https://www.openoffice.org/udk/ 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 {{AOo}} 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. | |
| − | The | + | Please send feedback to [[Image: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. | ||
| + | |||
| + | {{AOo}} Extensions are more or less zip containers with some additional data and metadata describing its content. They can be deployed by the built-in Extension Manager GUI (“Tools – Package Manager”, it is renamed to "Tools-Extension Manager" in 2.0.5). It installs the extension for the current user using {{AOo}}. The same can be done by using the command line tool “unopkg” that is located in the {{AOo}} 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 [http://www.openoffice.org/issues/show_bug.cgi?id=70283 bug]: Basic macros in {{AOo}} extensions still need to be registered in xlc-files in one of the "basic" directories. | ||
| + | |||
| + | {{AOo}} 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 {{AOo}} you can basically use the extension right after its installation. There is a restriction though: it is possible that the {{AOo}} 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 {{AOo}} 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 {{AOo}} 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 {{AOo}} can only instantiate UNO services by their names if it knows them. This is easy for services that replace already existing "internal" ones as {{AOo}} surely knows them and uses them, but as most components provide new services there must be something else that enables {{AOo}} 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 {{AOo}} 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 {{AOo}} 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. Whether data is replaced or extended depends on the type of the data and is explained in the discussion of the [[Configuration_schema_path_settings|configuration schema for our path settings.]] | ||
| + | |||
| + | By default {{AOo}} 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 {{AOo}} 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 {{AOo}} configuration by providing xcu files that overwrite or extend (merge) configuration settings of {{AOo}}. 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 {{AOo}} 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 {{AOo}}. No need to edit the xcu files in "share/registry" by hand! | ||
| + | [[File:Configuration.oxt]] is an example for such configuration file. It sets "Load printer settings with the document" (found in Tools-Options-Load/Save) to "false". It contains a Common.xcu file with just this setting. It's important that this Common.xcu file is referenced in the manifest.xml. | ||
| + | |||
| + | The layering concept of the service registry and the configuration are the basic principles that create the power of {{AOo}} extensions. | ||
= Path Settings = | = Path Settings = | ||
| + | Some data in {{AOo}} 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 {{AOo}} 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 [[Configuration_schema_path_settings|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 [http://specs.openoffice.org/appwide/options_settings/OOoPaths.odt 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 {{AOo}} you usually could see the two "templates" folders in the "share" and "user" trees of {{AOo}}. 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 OpenOffice.org 2.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 [[Configuration_schema_path_settings|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''' | |
| + | [[Image: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 {{AOo}} 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 {{AOo}} 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 {{AOo}} whould choose. In most cases it was the last one of the list, but now everything is unmistakable. | |
| − | + | '''Dialog Tools - Options - Paths - Edit''' | |
| + | [[Image:Dialog_Tools_Options_Edit_204.png]] | ||
| − | The zip container has a folder called “templates”. Any sub folder of it you create will appear as a template category in the | + | = 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''' | ||
| + | <syntaxhighlight lang="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> | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | If you compare this data with the data in [[Configuration_schema_path_settings#Data_based_on_new_schema|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 == | ||
| + | [http://framework.openoffice.org/files/documents/25/3702/TemplatePackage.oxt 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 {{AOo}} 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 == | == 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 | + | 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 metadata (Document Properties) so they don't create a problem here. |
| − | The localization file is called "groupuinames.xml" and it is placed in the "templates" | + | The localization file is called "groupuinames.xml" and it is placed in the "templates" subdirectory 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''' |
| + | <syntaxhighlight lang="xml"> | ||
<?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | ||
<groupuinames:template-group-list xmlns:groupuinames="http://openoffice.org/2006/groupuinames"> | <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="educate" |
| − | <groupuinames:template-group groupuinames:name="layout" groupuinames:default-ui-name=" | + | groupuinames:default-ui-name="Bildung" /> |
| − | <groupuinames:template-group groupuinames:name="misc" groupuinames:default-ui-name="Diverses" /> | + | <groupuinames:template-group groupuinames:name="layout" |
| − | <groupuinames:template-group groupuinames:name="officorr" groupuinames:default-ui-name=" | + | groupuinames:default-ui-name="Präsentationshintergründe" /> |
| − | <groupuinames:template-group groupuinames:name="offimisc" groupuinames:default-ui-name="Sonstige | + | <groupuinames:template-group groupuinames:name="misc" |
| − | <groupuinames:template-group groupuinames:name="personal" groupuinames:default-ui-name="Private Korrespondenz und Dokumente" /> | + | groupuinames:default-ui-name="Diverses" /> |
| − | <groupuinames:template-group groupuinames:name="presnt" groupuinames:default-ui-name=" | + | <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> | </groupuinames:template-group-list> | ||
| − | </ | + | </syntaxhighlight> |
| + | |||
| + | == 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''' | ||
| + | <syntaxhighlight lang="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> | ||
| + | |||
| + | </syntaxhighlight> | ||
| + | |||
| + | and additional directories need to be created be the "templates" folder that have the ISO language codes supported by the {{AOo}} language packs as their names. I have created a [http://framework.openoffice.org/files/documents/25/3706/MultiLanguageTemplatePackage.oxt 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. | ||
| + | |||
| + | If you create an extension this way you can always only use the templates of the current GUI language. This is caused by the "$(vlang)" variable in the path. A solution that allows to switch the template language independently is [https://bz.apache.org/ooo/show_bug.cgi?id=72005 still missing]. | ||
| + | |||
| + | = AutoText Extensions = | ||
| + | |||
| + | Everything said about extensions for templates 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 [http://framework.openoffice.org/files/documents/25/3710/AutoTextPackage.oxt here] is an example that can be filled with autotext files. Since there is currently no exporter you can manually copy any ".bau" files you have created into the extension. 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. Unlike 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 [https://bz.apache.org/ooo/show_bug.cgi?id=70410 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 [http://framework.openoffice.org/files/documents/25/3711/GalleryPackage.oxt 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 [https://bz.apache.org/ooo/show_bug.cgi?id=70412 issue] about these problems is fixed. | ||
| + | |||
| + | = Extensions for dictionaries = | ||
| + | |||
| + | The linguistic tools and dictionaries configuration has been reworked and now dictionaries as extensions are possible. In the upcoming OpenOffice.org 3.0 beta both ways (dictionaries as extensions, dictionaries as single files installed by dictionary.lst) are supported but support for dictionary.lst will be dropped in OpenOffice.org 3.0 final. More can be found [[Extension_Dictionaries | here]]. | ||
Latest revision as of 15:02, 2 February 2021
| OOo Extensions project
Please view the wiki usage guidelines
|
|---|
|
Categories: Pages: |
| Extensions on the main site |
|
Extensions in other languages: |
Contents
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 Apache OpenOffice 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 
.
In case you have an account for this wiki you can of course also use the "Discussion" tab at the top of this page.
Apache OpenOffice Extensions are more or less zip containers with some additional data and metadata describing its content. They can be deployed by the built-in Extension Manager GUI (“Tools – Package Manager”, it is renamed to "Tools-Extension Manager" in 2.0.5). It installs the extension for the current user using Apache OpenOffice. The same can be done by using the command line tool “unopkg” that is located in the Apache OpenOffice 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 Apache OpenOffice extensions still need to be registered in xlc-files in one of the "basic" directories.
Apache OpenOffice 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 Apache OpenOffice you can basically use the extension right after its installation. There is a restriction though: it is possible that the Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice can only instantiate UNO services by their names if it knows them. This is easy for services that replace already existing "internal" ones as Apache OpenOffice surely knows them and uses them, but as most components provide new services there must be something else that enables Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice 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. Whether 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 Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice configuration by providing xcu files that overwrite or extend (merge) configuration settings of Apache OpenOffice. 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 Apache OpenOffice 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 Apache OpenOffice. No need to edit the xcu files in "share/registry" by hand! File:Configuration.oxt is an example for such configuration file. It sets "Load printer settings with the document" (found in Tools-Options-Load/Save) to "false". It contains a Common.xcu file with just this setting. It's important that this Common.xcu file is referenced in the manifest.xml.
The layering concept of the service registry and the configuration are the basic principles that create the power of Apache OpenOffice extensions.
Path Settings
Some data in Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice you usually could see the two "templates" folders in the "share" and "user" trees of Apache OpenOffice. 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 OpenOffice.org 2.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 Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice whould choose. In most cases it was the last one of the list, but now everything is unmistakable.
Dialog Tools - Options - Paths - Edit
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 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 Apache OpenOffice 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 metadata (Document Properties) so they don't create a problem here.
The localization file is called "groupuinames.xml" and it is placed in the "templates" subdirectory 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 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 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 Apache OpenOffice 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.
If you create an extension this way you can always only use the templates of the current GUI language. This is caused by the "$(vlang)" variable in the path. A solution that allows to switch the template language independently is still missing.
AutoText Extensions
Everything said about extensions for templates 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. Since there is currently no exporter you can manually copy any ".bau" files you have created into the extension. 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. Unlike 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
The linguistic tools and dictionaries configuration has been reworked and now dictionaries as extensions are possible. In the upcoming OpenOffice.org 3.0 beta both ways (dictionaries as extensions, dictionaries as single files installed by dictionary.lst) are supported but support for dictionary.lst will be dropped in OpenOffice.org 3.0 final. More can be found here.
