Extensions best practices
How to write OpenOffice.org GUI Extensions today
The Extension Infrastructure Enhancement Project has the goal to introduce missing functionality in this area step-by-step with the next OO.o updates. The respective tasks have 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?
- Use the OO.o SDK to develop and build your extension. This prevents you from using types that are not guaranteed to stay compatible.
- Avoid usage of unpublished UNO types.
GUI Design and Implementation
- 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.
- The OO.o Dialog Editor can be used even today for dialog design. You can put the XML dialog descriptions into your extension's package. The Extension Manager is already able to deploy XML dialog descriptions. There is a UNO Service available that creates an UNO AWT dialog from an XML dialog description. For event binding you currently have basically two choices:
- Since OOo 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)
- 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.
- 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.
- Use the dialog editor to design the dialogs. Write a macro in a language supported by OO.o 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.
- Since OOo 2.2: The OO.o Dialog Editor supports creation and editing of multi language dialogs. Feature Specification)
- Obtain the right locale-dependent strings at runtime and to set it at the respective UNO AWT controls.
- 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.
- 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.
- Currently there is no known way to integrate own help content with the OO.o help system.
- 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.)
- A even more primitive approach is to use a simple message box for displaying the help text of your extension.
- Package dependencies
- 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.
- Prior to OO.o 2.0.4, it is not possible to specify runtime dependencies for packages.
- Package versions
- Since OO.o 2.1: It is possible to specify version information for extensions. (Feature Specification)
- 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.
- Package licensing
- 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)
- Prior to OO.o 2.0.4, no licesing features are available.
- Package product registration: This feature is not yet available.
- Package signing: This feature is not yet available.
- Common extension preferences user interface: This feature is not yet available.
- 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.