Difference between revisions of "Documentation/DevGuide/Extensions/File Format"

From Apache OpenOffice Wiki
Jump to: navigation, search
m
(19 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 
{{Documentation/DevGuide/ExtensionsTOC
 
{{Documentation/DevGuide/ExtensionsTOC
 
|ShowPrevNext=block
 
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Location of Installed Extensions
+
|PrevPage=Documentation/DevGuide/Extensions/Checklist for Writing Extensions
|NextPage=Documentation/DevGuide/Extensions/Display Name
+
|NextPage=Documentation/DevGuide/Extensions/description.xml
 
}}
 
}}
 +
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
 
{{DISPLAYTITLE:File Format}}
 
{{DISPLAYTITLE:File Format}}
__NOTOC__
+
An extension is a zip file having a name that ends in ''.oxt'' (formerly ''.uno.pkg'' or ''.zip''). The file extension ''.oxt'' is associated with the MIME / media type ''vnd.openofficeorg.extension''. The ''.oxt'' file serves as a wrapper for all the items of an extension, and contains files which list and describe those items. An extension can contain UNO components, type libraries, configuration files, dialog or basic libraries, etc.  
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 [[Documentation/DevGuide/Extensions/description.xml|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.
+
An extension should contain a ''description.xml'' (see [[Documentation/DevGuide/Extensions/description.xml|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.
  
{{Documentation/Note|For backward compatibility, legacy bundles (extension ''.uno.pkg'', ''.zip'') that have been formerly deployed using ''pkgchk'' are deployable, too. Migrate legacy bundles to the current ''.oxt'' format. This can easily be done using the GUI, exporting a legacy bundle as an ''.oxt'' file. When a legacy bundle is exported, a ''manifest.xml'' file is generated, enumerating the detected items of the bundle.}}
+
{{Note|For backward compatibility, legacy bundles (extension ''.uno.pkg'', ''.zip'') that have been formerly deployed using ''pkgchk'' are deployable, too. Migrate legacy bundles to the current ''.oxt'' format. This can easily be done using the GUI, exporting a legacy bundle as an ''.oxt'' file. When a legacy bundle is exported, a ''manifest.xml'' file is generated, enumerating the detected items of the bundle.
 +
'''Note''': Legacy bundles will be deprecated in OpenOffice 4.0, and support for them could be dropped in a future release; please convert them to ''.oxt''.}}
  
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'').
+
Depending on its 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 do 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 ===
 
=== Shared Library UNO Components ===
Line 33: Line 41:
 
                       manifest:full-path="solsparc/myComp.uno.so"/>
 
                       manifest:full-path="solsparc/myComp.uno.so"/>
 
  </source>
 
  </source>
 +
 +
=== Uno Jar Components===
 +
 +
The media-type for a UNO Jar component is ''application/vnd.sun.star.uno-component;type=Java'', for example,
 +
<source lang="xml">
 +
  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Java"
 +
                      manifest:full-path="myComponent.uno.jar"/>
 +
</source>
 +
 +
=== UNO Python Components===
 +
 +
''unopkg'' now supports registration of Python components (''.py'' files). Those files are registered using the <code>com.sun.star.loader.Python</code> loader. For details concerning Python-UNO, please refer to [http://udk.openoffice.org/python/python-bridge.html 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,
 +
<source lang="xml">
 +
  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Python"
 +
                      manifest:full-path="myComponent.uno.py"/>
 +
</source>
 +
 +
=== Passively Registered UNO Components ===
 +
 +
Beginning with {{PRODUCTNAME}}&nbsp;3.4, UNO components can use passive registration, see [[Passive_Component_Registration]]. Components written that way are no longer individually listed in the <code>manifest.xml</code> file. Instead, one or more XML files (with root element <code>&lt;components&gt;</code>) containing the relevant information are registered in the <code>manifest.xml</code> file with media type <code>application/vnd.sun.star.uno_components</code>, optionally giving a <code>platform</code> attribute. For an example extension containing passively registered UNO components, see [http://hg.services.openoffice.org/OOO340/file/c904c1944462/desktop/test/deployment/passive <code>desktop/test/deployment/passive/</code>].
  
 
===  RDB Type Library===  
 
===  RDB Type Library===  
Line 50: Line 78:
 
  </source>
 
  </source>
 
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.
 
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,
 
<source lang="xml">
 
  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Java"
 
                      manifest:full-path="myComponent.uno.jar"/>
 
</source>
 
 
=== UNO Python Components===
 
 
''unopkg'' now supports registration of Python components (''.py'' files). Those files are registered using the <code>com.sun.star.loader.Python</code> loader. For details concerning Python-UNO, please refer to [http://udk.openoffice.org/python/python-bridge.html 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,
 
<source lang="xml">
 
  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Python"
 
                      manifest:full-path="myComponent.uno.py"/>
 
</source>
 
  
 
=== {{PRODUCTNAME}} Basic Libraries===  
 
=== {{PRODUCTNAME}} Basic Libraries===  
  
{{PRODUCTNAME}} Basic libraries are linked to the basic library container files. Refer to [[Documentation/DevGuide/Basic/OpenOffice.org Basic and Dialogs|OpenOffice.org Basic and Dialogs]] for additional information.The media-type for a {{PRODUCTNAME}} Basic Library is "application/vnd.sun.star.basic-library", for example,
+
{{PRODUCTNAME}} Basic libraries are linked to the basic library container files. Refer to [[Documentation/DevGuide/Basic/OpenOffice.org Basic|OpenOffice.org Basic]] for additional information.The media-type for a {{PRODUCTNAME}} Basic Library is "application/vnd.sun.star.basic-library", for example,
 
  <source lang="xml">
 
  <source lang="xml">
 
   <manifest:file-entry manifest:media-type="application/vnd.sun.star.basic-library"  
 
   <manifest:file-entry manifest:media-type="application/vnd.sun.star.basic-library"  
 
                       manifest:full-path="myBasicLib/"/>
 
                       manifest:full-path="myBasicLib/"/>
 
  </source>
 
  </source>
 +
 
=== Dialog Libraries===  
 
=== Dialog Libraries===  
  
Dialog libraries are linked to the basic dialog library container files. Refer to [[Documentation/DevGuide/Basic/OpenOffice.org Basic and Dialogs|OpenOffice.org Basic and Dialogs]] for additional information.The media-type for a dialog library is ''application/vnd.sun.star.dialog-library'', for example,
+
Dialog libraries are linked to the basic dialog library container files. Refer to [[Documentation/DevGuide/Basic/OpenOffice.org Basic|OpenOffice.org Basic]] for additional information.The media-type for a dialog library is ''application/vnd.sun.star.dialog-library'', for example,
 
  <source lang="xml">
 
  <source lang="xml">
 
   <manifest:file-entry manifest:media-type="application/vnd.sun.star.dialog-library"  
 
   <manifest:file-entry manifest:media-type="application/vnd.sun.star.dialog-library"  
 
                       manifest:full-path="myDialog/"/>
 
                       manifest:full-path="myDialog/"/>
 
  </source>
 
  </source>
 +
 
=== Configuration Data Files===  
 
=== Configuration Data Files===  
  
Line 99: Line 113:
  
 
=== Extension Tooltip Description===  
 
=== Extension Tooltip Description===  
 +
 +
'''Deprecated as of OOo 3.1.'''  See [[Documentation/DevGuide/Extensions/Extension Description|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,
 
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,
Line 113: Line 129:
 
=== Executable Files ===
 
=== 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 [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|OpenOffice.org-minimal-version]] set to 2.4.
+
The media type for an executable is ''application/vnd.sun.star.executable''. This media type is new in OOo 2.4. If an extension uses it then it should also use the dependency [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|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.
 
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:
 
Example:
Line 124: Line 140:
  
 
{{PDL1}}
 
{{PDL1}}
[[Category: Extensions]]
+
 
 +
[[Category:Documentation/Developer's Guide/Extensions]]

Revision as of 19:56, 3 July 2018



An extension is a zip file having a name that ends in .oxt (formerly .uno.pkg or .zip). The file extension .oxt is associated with the MIME / media type vnd.openofficeorg.extension. The .oxt file serves as a wrapper for all the items of an extension, and contains files which list and describe those items. An extension can contain UNO components, type libraries, configuration files, dialog or basic libraries, etc.

An extension should 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.

Documentation note.png For backward compatibility, legacy bundles (extension .uno.pkg, .zip) that have been formerly deployed using pkgchk are deployable, too. Migrate legacy bundles to the current .oxt format. This can easily be done using the GUI, exporting a legacy bundle as an .oxt file. When a legacy bundle is exported, a manifest.xml file is generated, enumerating the detected items of the bundle.

Note: Legacy bundles will be deprecated in OpenOffice 4.0, and support for them could be dropped in a future release; please convert them to .oxt.

Depending on its 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 do 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"/>

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"/>

Passively Registered UNO Components

Beginning with OpenOffice.org 3.4, UNO components can use passive registration, see Passive_Component_Registration. Components written that way are no longer individually listed in the manifest.xml file. Instead, one or more XML files (with root element <components>) containing the relevant information are registered in the manifest.xml file with media type application/vnd.sun.star.uno_components, optionally giving a platform attribute. For an example extension containing passively registered UNO components, see desktop/test/deployment/passive/.

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.

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.executable. 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).
Personal tools
In other languages