Difference between revisions of "Documentation/DevGuide/Extensions/File Format"
m (4 revision(s)) |
m |
||
| Line 17: | Line 17: | ||
The media-type for a shared library UNO component is ''application/vnd.sun.star.uno-component;type=native'', for example, | The media-type for a shared library UNO component is ''application/vnd.sun.star.uno-component;type=native'', for example, | ||
| − | + | <source lang="xml"> | |
<manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=native" | <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=native" | ||
manifest:full-path="myComponent.uno.so"/> | manifest:full-path="myComponent.uno.so"/> | ||
| − | + | </source> | |
=== Shared Library UNO Components for particular Platforms === | === 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, | 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, | ||
| − | + | <source lang="xml"> | |
<manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Windows" | <manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Windows" | ||
manifest:full-path="windows/mycomp.uno.dll"/> | manifest:full-path="windows/mycomp.uno.dll"/> | ||
| Line 32: | Line 32: | ||
<manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Solaris_SPARC" | <manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Solaris_SPARC" | ||
manifest:full-path="solsparc/myComp.uno.so"/> | manifest:full-path="solsparc/myComp.uno.so"/> | ||
| − | + | </source> | |
=== RDB Type Library=== | === RDB Type Library=== | ||
The media-type for a UNO RDB type library is ''application/vnd.sun.star.uno-typelibrary;type=RDB'', for example, | The media-type for a UNO RDB type library is ''application/vnd.sun.star.uno-typelibrary;type=RDB'', for example, | ||
| − | + | <source lang="xml"> | |
<manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=RDB" | <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=RDB" | ||
manifest:full-path="myTypes.uno.rdb"/> | manifest:full-path="myTypes.uno.rdb"/> | ||
| − | + | </source> | |
=== Jar Type Library=== | === Jar Type Library=== | ||
The media-type for a UNO Jar typelibrary is ''application/vnd.sun.star.uno-typelibrary;type=Java'', for example, | The media-type for a UNO Jar typelibrary is ''application/vnd.sun.star.uno-typelibrary;type=Java'', for example, | ||
| − | + | <source lang="xml"> | |
<manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=Java" | <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=Java" | ||
manifest:full-path="myTypes.uno.jar"/> | manifest:full-path="myTypes.uno.jar"/> | ||
| − | + | </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. | ||
| Line 54: | Line 54: | ||
The media-type for a UNO Jar component is ''application/vnd.sun.star.uno-component;type=Java'', for example, | 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:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Java" | ||
manifest:full-path="myComponent.uno.jar"/> | manifest:full-path="myComponent.uno.jar"/> | ||
| − | + | </source> | |
=== UNO Python Components=== | === 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, | ''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:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Python" | ||
manifest:full-path="myComponent.uno.py"/> | 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 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, | ||
| − | + | <source lang="xml"> </source> | |
<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/"/> | ||
| Line 77: | Line 77: | ||
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 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, | ||
| − | + | <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> | |
=== Configuration Data Files=== | === Configuration Data Files=== | ||
The media-type for a configuration data file is ''application/vnd.sun.star.configuration-data'', for example, | The media-type for a configuration data file is ''application/vnd.sun.star.configuration-data'', for example, | ||
| − | + | <source lang="xml"> | |
<manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-data" | <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-data" | ||
manifest:full-path="myData.xcu"/> | manifest:full-path="myData.xcu"/> | ||
| − | + | </source> | |
=== Configuration Schema Files=== | === Configuration Schema Files=== | ||
The media-type for a configuration schema file is ''application/vnd.sun.star.configuration-schema'', for example, | The media-type for a configuration schema file is ''application/vnd.sun.star.configuration-schema'', for example, | ||
| − | + | <source lang="xml"> | |
<manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-schema" | <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-schema" | ||
manifest:full-path="mySchema.xcs"/> | manifest:full-path="mySchema.xcs"/> | ||
| − | + | </source> | |
Be careful not to install schemata (''.xcs'' files) which contain the same elements (<code>oor:package</code>, <code>oor:name</code>) but have different definitions. | Be careful not to install schemata (''.xcs'' files) which contain the same elements (<code>oor:package</code>, <code>oor:name</code>) but have different definitions. | ||
| Line 101: | Line 101: | ||
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, | ||
| − | + | <source lang="xml"> | |
<manifest:file-entry manifest:media-type="application/vnd.sun.star.package-bundle-description;locale=en" | <manifest:file-entry manifest:media-type="application/vnd.sun.star.package-bundle-description;locale=en" | ||
manifest:full-path="readme.en" /> | manifest:full-path="readme.en" /> | ||
| Line 108: | Line 108: | ||
manifest:media-type="application/vnd.sun.star.package-bundle-description" | manifest:media-type="application/vnd.sun.star.package-bundle-description" | ||
manifest:full-path="readme.txt" /> | manifest:full-path="readme.txt" /> | ||
| − | + | </source> | |
The best matching locale (against the current installation's locale) is taken. The locale is of the form locale=language-country-variant. | The best matching locale (against the current installation's locale) is taken. The locale is of the form locale=language-country-variant. | ||
| Line 116: | Line 116: | ||
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: | ||
| − | + | <source lang="xml"> | |
<manifest:file-entry manifest:media-type="application/vnd.sun.star.executable" | <manifest:file-entry manifest:media-type="application/vnd.sun.star.executable" | ||
manifest:full-path="hello"/> | manifest:full-path="hello"/> | ||
| − | + | </source> | |
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 {{PRODUCTNAME}} 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 <idl>com.sun.star.util.MacroExpander</idl> service. The ''%origin%'' variable is, for instance, used by the <code>ImageIdentifier</code> property of add-on menus and toolbar items, which is described in the [[Documentation/DevGuide/WritingUNO/AddOns/Configuration|Configuration]] section. | 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 {{PRODUCTNAME}} 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 <idl>com.sun.star.util.MacroExpander</idl> service. The ''%origin%'' variable is, for instance, used by the <code>ImageIdentifier</code> property of add-on menus and toolbar items, which is described in the [[Documentation/DevGuide/WritingUNO/AddOns/Configuration|Configuration]] section. | ||
Revision as of 15:45, 23 March 2008
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).
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"/>
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 and Dialogs 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 and Dialogs 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
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: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). |
