Documentation/DevGuide/Extensions/File Format

OpenOffice.org Developer's Guide

Extensions

< Previous Section

Next Section >

• Extension Manager

• Extension Repositories
• The Active Extension
• Updating Extensions
• Processing Extensions
• Packaging Notes For Bundled Extensions
• Deployment Items
• Installing Extensions for All or a Single User
• Extension Manager in OpenOffice.org
• unopkg
• Location of Installed Extensions
• Extension Layers

• Checklist for Writing Extensions
• File Format
• description.xml

• Description of XML Elements
• Localized XML Elements
• Example

• Display Name
• Icon
• Extension Description
• Extension Identifiers
• Extension Versions
• Target Platform
• Simple License
• Dependencies
• Publisher Information
• System Integration
• Online Update of Extensions

• Running Online - Update
• Concept
• Example Scenario for Providing Updates
• Migration of Update Information
• Description of the Update Information
• Description of Atom Feed
• Examples

• Options Dialog

• Creating the GUI of the Options Page
• Saving and Reading Data for the Options Page
• Defining the Usage of Options Pages

• Adding a Leaf to an Existing Node
• Adding Several Leaves
• Grouping of Leaves
• Adding Nodes
• Adding Several Nodes
• Absolute Position of Leaves
• Grouping of Nodes
• Assigning Nodes to Modules
• Defining a Module
• Absolute Position of Nodes

• The Options Dialog of the Extension Manager

• Help Content

< Previous Page

Next Page >

An extension is a zip file having a name that ends on .oxt (formerly .uno.pkg or .zip). The file extension .oxt is associated with the MIME / media type vnd.openofficeorg.extension. An extension can contain UNO components, type libraries, configuration files, dialog or basic libraries, etc.

An extension should also contain a description.xml (see description.xml) and must contain a directory META-INF (all uppercase). The META-INF directory contains a manifest.xml which lists all items and their media-type.

Depending on the media-type the respective file needs to be treated particularly. For example a UNO component needs to be registered before it can be used. All media types which does not require a particular handling of the file are ignored currently (and actually need not be contained in the manifest.xml).

Runtime Libraries

The extensions need to bring their own runtime libraries, such as C or C++, when it is not guaranteed that these libraries are shipped with OOo or are installed on the users' systems. They typically need to reside in the same directory as the libraries containing the UNO components.

Please note that there is a peculiarity of libraries build with MS Visual Studio 2008. The runtime libraries (C, C++) need either be installed in the system or must reside next to the library in order to be found. It does not matter if the runtime libraries are contained in the OOo installation (<office>/OpenOffice.org/Basis/program). As a consequence extensions need always contain the runtime libraries which they use.

The runtime libraries must not be referenced by the manifest.xml.

Shared Library UNO Components

The media-type for a shared library UNO component is application/vnd.sun.star.uno-component;type=native, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=native" 
                       manifest:full-path="myComponent.uno.so"/>

Shared Library UNO Components for particular Platforms

When you implement a UNO native component, for example, a .dll or .so file, then this file is only deployable on that specific platform. It is often convenient to package a bundle for different platforms. For instance, you compile your component for x86 Linux, Solaris SPARC and Windows. You have to tell the Extension Manager which version of your component file corresponds to which platform via a platform attribute supplied with the media-type, for example,

  <manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Windows"
                      manifest:full-path="windows/mycomp.uno.dll"/>
  <manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Linux_x86"
                       manifest:full-path="linux/myComp.uno.so"/>
  <manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Solaris_SPARC"
                       manifest:full-path="solsparc/myComp.uno.so"/>

RDB Type Library

The media-type for a UNO RDB type library is application/vnd.sun.star.uno-typelibrary;type=RDB, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=RDB"
                       manifest:full-path="myTypes.uno.rdb"/>

Jar Type Library

The media-type for a UNO Jar typelibrary is application/vnd.sun.star.uno-typelibrary;type=Java, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=Java" 
                       manifest:full-path="myTypes.uno.jar"/>

Keep in mind that the RDB variant of that type library must be deployed also. This is currently necessary, because your Java UNO types may be referenced from native UNO code.

Uno Jar Components

The media-type for a UNO Jar component is application/vnd.sun.star.uno-component;type=Java, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Java" 
                       manifest:full-path="myComponent.uno.jar"/>

UNO Python Components

unopkg now supports registration of Python components (.py files). Those files are registered using the com.sun.star.loader.Python loader. For details concerning Python-UNO, please refer to http://udk.openoffice.org/python/python-bridge.html. The media-type for a UNO Python component is application/vnd.sun.star.uno-component;type=Python, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Python" 
                       manifest:full-path="myComponent.uno.py"/>

OpenOffice.org Basic Libraries

OpenOffice.org Basic libraries are linked to the basic library container files. Refer to OpenOffice.org Basic for additional information.The media-type for a OpenOffice.org Basic Library is "application/vnd.sun.star.basic-library", for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.basic-library" 
                       manifest:full-path="myBasicLib/"/>

Dialog Libraries

Dialog libraries are linked to the basic dialog library container files. Refer to OpenOffice.org Basic for additional information.The media-type for a dialog library is application/vnd.sun.star.dialog-library, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.dialog-library" 
                       manifest:full-path="myDialog/"/>

Configuration Data Files

The media-type for a configuration data file is application/vnd.sun.star.configuration-data, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-data" 
                       manifest:full-path="myData.xcu"/>

Configuration Schema Files

The media-type for a configuration schema file is application/vnd.sun.star.configuration-schema, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-schema" 
                       manifest:full-path="mySchema.xcs"/>

Be careful not to install schemata (.xcs files) which contain the same elements (oor:package, oor:name) but have different definitions.

Extension Tooltip Description

Deprecated as of OOo 3.1. See Extension Description for details.

If you want to add a tooltip description (which shows up in the balloon help of a bundle node in the Extension Manager dialog), then you can do so by specifying localized UTF-8 files, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.package-bundle-description;locale=en" 
                       manifest:full-path="readme.en" />
  <manifest:file-entry manifest:media-type="application/vnd.sun.star.package-bundle-description;locale=de" 
                       manifest:full-path="readme.de" />
  <manifest:file-entry manifest:media-type="application/vnd.sun.star.package-bundle-description" 
                       manifest:full-path="readme.txt" />

The best matching locale (against the current installation's locale) is taken. The locale is of the form locale=language-country-variant.

Executable Files

The media type for an executable is application/vnd.sun.star.configuration-schema. This media type is new in OOo 2.4. If an extension uses it then it should also use the dependency OpenOffice.org-minimal-version set to 2.4. This media type was introduced to work-around the problem that the executable attribute (Unix files, does not apply for Windows files) will not be preserved when OOo extracts a zipped extension. Also when an extension was zipped on Windows then the attribute is lost. Using the media type for an Windows executable does not have an effect since there is no such file attribute on Windows. On Unix the executable attribute is set when the extension is being installed. If it is installed for the current user then the user exectuable flag is set and if it is installed for all users, that is as shared extension, then the executable flag is set for user,group and other. Example:

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.executable" 
                       manifest:full-path="hello"/>

All other contents of the extension are simply copied into the Extension Manager cache. You can, for instance, deploy an image for add-on menus within a package, or any other file needed by your component. The OpenOffice.org configuration is used to find out in which path this file is located in a particular installation. When you define a package containing additional files, include an .xcu configuration data file, which points to your files. Use a variable %origin% as a placeholder for the exact path where the file will be copied by the Extension Manager. When unopkg installs the data, it replaces the path with an URL containing a macro and writes into the configuration. This URL has to be expanded before it is a valid file URL. This can be done using the com.sun.star.util.MacroExpander service. The %origin% variable is, for instance, used by the ImageIdentifier property of add-on menus and toolbar items, which is described in the Configuration section.

Content on this page is licensed under the Public Documentation License (PDL).