Extensions best practices

From Apache OpenOffice Wiki
Jump to: navigation, search

How to write OpenOffice GUI Extensions today

The Extension Infrastructure Enhancement Project had the goal to introduce missing functionality in this area step-by-step with the next OO.o updates. The respective tasks had high priority for Sun's OpenOffice.org Development Team. Anyhow, some important functionality is currently missing completely, but many things can be even implemented in a more or less clean way already. In most cases you should be able to implement a 'clean' extension even today.

So, what are your choices today?

Programming Language & Environment

  1. Generally, you have the freedom of choice among the programming languages which have a UNO language binding.
  2. We recommend to use a programming platform that generates platform-independent executable files (like Java). This makes an extension binary usable for a maximum of users without the cost of recompilation, packaging, testing, ... for every single platform that shall be supported.
  3. If you want to use Java, try out the Netbeans OpenOffice API Plugin that was designed especially to ease OO extension development.

Compatibility

  1. Use the OO.o SDK to develop and build your extension. This prevents you from using types that are not guaranteed to stay compatible.
  2. Avoid usage of unpublished UNO types.

GUI Design and Implementation

  1. Never use VCL, because VCL API is not guaranteed to stay compatible, not even over micro OO.o updates. Use UNO AWT instead. If something is missing/broken in UNO AWT, don't close your eyes! File a bug and insist that it gets implemented/fixed quickly. Improving UNO AWT has very high priority.
  2. The OO.o Dialog Editor can be used for dialog design. You can put the XML dialog descriptions into your extension's package. The Extension Manager is able to deploy XML dialog descriptions. There is a UNO Service available that creates an UNO AWT dialog from an XML dialog description.
  3. For binding events (code) to controls you currently have the following choices:
    1. Since OO.o 2.0.4: Use the dialog editor to design the dialogs. Implement the event logic using a language supported by UNO. Assign UNO events to the controls. Put both the dialog XML and the event logics into your extension. (Feature Specification)
    2. Use the dialog editor to design the dialogs. Assign no events to the controls. At runtime, after creating the UNO AWT dialog, attach the needed event listeners to the controls.
    3. Use the dialog editor to design the dialogs. Write some BASIC code that implements event handlers for your dialog controls. Those handlers might be very small, in the most simple approach they would just call one of your UNO event handling objects. The BASIC library containing your glue code can easily put into the package for your extension. The OO.o Extension Manager already supports deployment of BASIC libraries.
    4. Use the dialog editor to design the dialogs. Write a macro in a language supported by AOO Scripting Framework (Java, Beanshell, ...) that implements event handlers for your dialog controls. The Dialog Editor already supports binding events to Scripting Framework macros. The macro containing your code can easily put into the package for your extension. The OO.o Extension Manager already supports deployment of Scripting Framework macros.

GUI Localization

  1. Since OO.o 2.2: The OO.o Dialog Editor supports creation and editing of multi language dialogs. Feature Specification)
  2. Obtain the right locale-dependent strings at runtime and to set it at the respective UNO AWT controls.
  3. Recently the UNO service com.sun.star.resource.OfficeResourceLoader was introduced that is able to access arbitrary resource strings that are accessible by the OO.o ResMgr class. This service can be of help if you just want to use an already existing OO.o resource string.
  4. A good approach is to use the localization features of the UNO Configuration service. The UNO Configuration Service allows to define locale-dependend strings. The Configuration service returns values of those string configuration items according to the locale set upon initialization of the Configuration service.

Extension Features

Dependencies

  1. Since OO.o 2.0.4: It is possible to define dependencies for packages. (Feature Specification) An extension can specify that it needs a minimal OO.o version. Formally, the dependency is an empty XML element whose name consists of the namespace name "http://openoffice.org/extensions/description/2006" and the local part "OpenOffice.org-minimal-version". It shall have two attributes, namely the "name" attribute required for every dependency and an attribute with unprefixed name "value" whose value is the string representation of an OOo version starting with OOo 2.1 (in which case the value is the string "2.1"). The dependency is fulfilled if and only if the value of the current OOo version is (element-by-element lexicographically) greater than or equal to the specified value. It is not possible to define that an extension requires an OO.o version 2.0.3 or older. However, if you want that yor extension can only be installed in OOo 2.0.4 or newer, use the OXT Extension Package format for your extension. OXT cannot be installed prior to OOo 2.0.4.
  2. Prior to OO.o 2.0.4, it is not possible to specify runtime dependencies for packages.

Versions

  1. Since OO.o 2.1: It is possible to specify version information for extensions. (Feature Specification)
  2. Prior to OO.o 2.1 it is not possible to specify version information for packages. However this is not a big issue until you want to provide the first update for your component. Packages without explicit version information will be considered to be “version 1”. However, package versioning must be available latest when the first official package update needs to be released.

Licenses

  1. Since OO.o 2.0.4: It is possible to include a license text in the extension package. The text will be displayed while installing the extension. Installation will be aborted in case the user declines the license. (Feature Specification)
  2. Prior to OO.o 2.0.4, no licensing features are available.

Product Registration

This feature is not yet available.

Digital Signatures

This feature is not yet available.

Common User Interface for Extension Preferences

  1. Since OO.o 2.3: Extensions can have own Preferences pages that are part of the Extension package. These pages appear in OO.o's common Options dialog (Tools/Options...) as well as in the Extension Manager (Feature Specification). OO.o Dialog Editor now can be used to design the preferences pages and to export single dialogs (Feature Specification).

Help Content

  1. Since OO.o 2.4, an extension can come with a set of own help files (XHP files). These help files will be integrated seamlessly into the OO.o Help System (OO.o Help Viewer, Tool Tips, ...). User Interface elements (dialogs, dialog controls, ...) can be associated with own help pages. (Feature Specification).
  2. You could put an HTML (or other format supported by Writer) file into your extension package. When the user requests help for your extension (for instance by pressing a help button you designed), you could load your help file into Writer. Not a very cool solution, though. Note: Currently it is very inconvenient to figure out the root directory of your package installation. How to do this is explained here: http://api.openoffice.org/docs/DevelopersGuide/Components/Components.xhtml#1_9_1_UNO_Package_Installation_Using_unopkg , in section Package Bundle Structure => Arbitrary Files. (To address this problem, we will design and implement an API that allows to directly obtain the package installation root.)
  3. A even more primitive approach is to use a simple message box for displaying the help text of your extension.

Package File Format

Since OO.o 2.0.4, a new Package file format is available – OXT (OO.o eXTension). OXT files have basically the same structure as UNO packages. They are ZIP files containing the parts building the extension. OXT packages cannot be installed in OO.o version prior to 2.0.4. For detailed information see the Extensions chapter of the Developers Guide. See also UNO component packaging.

Online Update

  1. Since OO.o 2.2, online update of extensions is supported by the Extension Manager. (Feature Specification)
  2. Since OO.o 2.3, the Extension Manager dialog contains a link control, that opens a web browser with the Official OpenOffice.org Extension Web-site. (Feature Specification). Extension developers can create entries for their extensions in this repository, gaining a maximum of visibility for their product.

Extension Meta Data

  1. Since OO.o 2.4, an extension can have a display name. The display name can be localized. In versions prior to 2.4, the name of the oxt file was used as display name, for example in the list of installed extensions.
Personal tools