2007-02-01T13:42:04Z

Kso:

{{Extensions}}
Developing extensions is an efficient way to bring value to OpenOffice.org without diving into core sources. Obviously all developers willing to [[Main_Page|develop at OpenOffice.org sources level]] are welcomed.

OpenOffice.org enables third party tools creation through UNO bridges, allowing using many languages.

The principle is to create UNO packages that can be listed in the OpenOffice.org [[Extensions_repository|Extensions repository]] and installed by end-users easily.

This section wants to give newcomers as well as experienced developers some hints to develop Extensions in their desired languages and provide them with tools and frameworks that ease and homogenize the development.

Finally, popular Extensions may be integrated into OpenOffice.org so it is important to follow common policies from beginning to ease this merging.

==== Starting in a language ====
Addons can be written in various languages. Each section is here to give starting informations that let you create your addons. Each section is dedicated to a language. It deals with specific points concerning the Extensions aspect. Resources regarding the OpenOffice.org API can be found on the [http://api.openoffice.org API project] and UNO bridges languages issues on the [http://udk.openoffice.org UDK project]

The translations of these pages are welcomed and [[Extensions#Translating_these_pages|guidelines are available]].

* [[Extensions_development_python|Starting in Python]]
* [[Extensions_development_basic|Starting in Basic]]
* [[Extensions_development_java|Starting in Java]]
* [[Using_Cpp_with_the_OOo_SDK|Starting in C++]]
* [[Non-code_extensions|Non programmatic Extensions]]
* [[Extensions_packaging|Extensions packaging]]
* [[Extensions_Integration_into_Installation_Set|Extensions Integration into Installation Set]]

==== Tools & Frameworks ====

* [http://codesnippets.services.openoffice.org Code snippets available in many languages]
* [[Extensions_development_translation|Translation framework]]
* [[Extensions_Packager|Extensions Packager]]
* Predefined wizards
* [[Extensions_introspection|Introspection Tools]]: discover the API

==== Best Practices ====
* [[Best Practices|How to write OO.o GUI Extensions today]]

==== Project: Enhancing Extensions Infrastructure of OpenOffice.org 2.0.3 ====
* [[Proposal_for_improvements|Project Proposal (agreed by the Community June 2006)]]
* [[Improvements_plan_and_status|Project Status]]

==== Improving the Extension Manager ====
* [[Extensions_feature_ideas|Feature ideas]]

[[Category:Extensions]]

Extensions development

2007-02-01T13:40:17Z

Kso:

{{Extensions}}
Developing extensions is an efficient way to bring value to OpenOffice.org without diving into core sources. Obviously all developers willing to [[Main_Page|develop at OpenOffice.org sources level]] are welcomed.

OpenOffice.org enables third party tools creation through UNO bridges, allowing using many languages.

The principle is to create UNO packages that can be listed in the OpenOffice.org [[Extensions_repository|Extensions repository]] and installed by end-users easily.

This section wants to give newcomers as well as experienced developers some hints to develop Extensions in their desired languages and provide them with tools and frameworks that ease and homogenize the development.

Finally, popular Extensions may be integrated into OpenOffice.org so it is important to follow common policies from beginning to ease this merging.

==== Starting in a language ====
Addons can be written in various languages. Each section is here to give starting informations that let you create your addons. Each section is dedicated to a language. It deals with specific points concerning the Extensions aspect. Resources regarding the OpenOffice.org API can be found on the [http://api.openoffice.org API project] and UNO bridges languages issues on the [http://udk.openoffice.org UDK project]

The translations of these pages are welcomed and [[Extensions#Translating_these_pages|guidelines are available]].

* [[Extensions_development_python|Starting in Python]]
* [[Extensions_development_basic|Starting in Basic]]
* [[Extensions_development_java|Starting in Java]]
* [[Using_Cpp_with_the_OOo_SDK|Starting in C++]]
* [[Non-code_extensions|Non programmatic Extensions]]
* [[Extensions_packaging|Extensions packaging]]
* [[Extensions_Integration_into_Installation_Set|Extensions Integration into Installation Set]]

==== Tools & Frameworks ====

* [http://codesnippets.services.openoffice.org Code snippets available in many languages]
* [[Extensions_development_translation|Translation framework]]
* [[Extensions_Packager|Extensions Packager]]
* Predefined wizards
* [[Extensions_introspection|Introspection Tools]]: discover the API

==== Best Practices ====
* [Best Practices|How to write OO.o GUI Extensions today]]

==== Project: Enhancing Extensions Infrastructure of OpenOffice.org 2.0.3 ====
* [Proposal_for_improvements|Project Proposal (agreed by the Community June 2006)]]
* [Improvements_plan_and_status|Project Status]]

==== Improving the Extension Manager ====
* [[Extensions_feature_ideas|Feature ideas]]

[[Category:Extensions]]

Extensions improvements proposal

2007-02-01T13:29:54Z

Kso:

Extensions improvements proposal

2007-02-01T13:27:01Z

Kso:

== Abstract ==
This document discusses the possibilities for development and deployment of GUI Extensions for '''OpenOffice.org 2.0.3'''. It shows gaps in the existing functionality and proposes a number of possible improvements in that area.

Especially for GUI Extension development this document often has really proposal character. There may always be valid and working exceptions from the tools pointed out here. For instance it can make sense to use another Windowing Toolkit than the one proposed here for implementing the GUI of a certain component.

Although this document focuses on OO.o Extensions with a Graphical User Interface, many of the topics discussed apply also to OO.o Extensions without a Graphical User Interface.

== Motivation ==
Currently, it's not always an easy task to implement a GUI Extension for OpenOffice.org. First, there is very little documentation how to do this. In the OO.o Developers Guide, there is only a Java example showing a simple dialog and a Basic library example showing the implementation of different controls (e.g. progress bar). Thus, people trying to find their own way to solve problems. This leads not always to optimal solutions. The same standard problems need to be solved again and again, many times with different solutions. The quality of these solutions varies. Even worse, currently OO.o totally misses some important features that are essential for high-quality GUI Extensions. The OO.o Help system that cannot be extended with additional content after OO.o has been installed is a prominent example for this. At the moment of this writing a developer has no chance to integrate own help content into OO.o. Some other needed functionality is present, but must be extended to enable development and deployment of high-quality and state-of-the-art extensions. The OO.o Extension Manager comes to mind here.

The goal of this document is to close the gaps just mentioned and to propose a common way how to develop and deploy OO.o GUI extensions.

== Project Constraints ==
The goal of the project is to deliver missing features and functionality
* step by step with the next OO.o minor updates, starting with OO.o 2.0.4
* without having to do major rewrites of OO.o code. Development resources are restricted and there already is much functionality that can be polished up in a relative short time frame without the risk to break important functional areas.

== Development of OpenOffice.org GUI Extensions ==
=== Requirements ===
# Extensions must be packaged and distributed in a format supported by the OO.o Extension Manager .
# It must be possible to implement Extensions that are usable with more than one specific version of OO.o.
# Extensions must be able to come with own GUI elements, like dialogs, menu items, toolbars. It must be possible to integrate those own items with existing OO.o user interface.
# All GUI elements that come with an extension must be accessible and recognize the system color scheme and GUI fonts. People with disabilities must be able to use the extension.
# Extensions must be able to extend and (up to a certain point) modify certain aspects of the existing OO.o user interface. An example is to remove certain OO.o menu items.
# Extensions GUI Look & Feel must match OO.o Look & Feel.
# Extensions must be localizable.
# Extensions must be able to integrate own help content with OO.o Help System.
# The functionality of extensions must be fully automatically testable.

=== Proposed Solutions ===
==== Extension Package File Format ====
The OO.o Extension Manager supports a number of file formats. The most important one is the so called UNO package (extension uno.pkg), which is basically a ZIP file containing other items that can be managed by the Extension Manager.

“UNO” in the format name is misleading; a package can contain even content that is not related to UNO at all, for instance a configuration item, which is just an XML file. The name should be changed to reflect the actual purpose.

==== Compatibility ====
Generally, the design goal for an extension should be that it should work with as much different OO.o versions as possible, starting with a certain minimal required version. For instance, an extension introduced for OO.o 2.0.4 should work for all upcoming OO.o 2.x.y. Moreover, the concept must allow to write extensions, that work even across major OO.o versions without the need to recompile it.

Rules to achieve maximum compatibility for extensions:

* Use OO.o SDK as build environment for your extension. All published types (C++, Java, ...) accessible from the SDK build environment are guaranteed to be “stable” and therefore guaranteed to keep binary compatibility of your extension code. Currently there are no plans to change the SDK in an incompatible way, not even for OO.o 3.0. Exception from this rule are unpublished types that are part of the SDK, but not guaranteed to stay compatible, not even for next micro update! Never use unpublished UNO types or types not available in the OO.o SDK, if you want your extension to be compatible with more than just the OO.o micro version it was initially developed for!
* Extension code logics needs to be implemented as a UNO component (or as a Scripting Framework Parcel or an OO.o BASIC library). No other formats containing executable code are supported by the Extension Manager. SDK-built UNO components minimize the risk of introducing incompatibilities. Actually, they are the only way to guarantee a certain amount of compatibility.
* To produce binaries, only use compiler suites that are officially supported by the OO.o SDK. This includes not just the compiler suite product itself, but also the correct version of that product.

==== GUI Design and Implementation ====
The Windowing Toolkit to use for all Graphical User Interface elements is the U NO AWT. Many users reported, that the UNO AWT currently lacks several must-have functionality. Other functional areas are not really convenient to use. Both issues need to be addressed in order to build a solid platform for the development of OO.o GUI Extensions.

In case a developer of a GUI extension stumbles over missing UNO AWT functionality it is generally no option to use Non-SDK types (e.g. VCL classes) for the implementation. Instead, the missing UNO AWT functionality must be implemented and used by the extension.

To provide more convenience for GUI designers, the existing OO.o Dialog Editor will be extended to support binding UNO objects/methods to GUI control events. Extension developers then can use the Dialog Editor to design own dialogs. Dialogs are made persistent using a special XML format (some similarities to XUL here). The OO.o Extension Manager already supports deployment of those XML dialog descriptions. Extension developers can use a UNO service to create a UNO AWT dialog object from XML dialog descriptions.

Obviously, the Dialog Editor should be extended to support the new UNO AWT features, like completely new controls.

At the end, a standalone dlgedit binary could be extracted from the existing OO.o Dialog Editor sources. This binary would become part of the OO.o SDK. Best would be to integrate this tool into Netbeans, as part of our upcoming Netbeans OO.o Development Package (just a new menu item that starts the SDK Dialog Editor). It must be possible to add dialog description files to an OO.o Extension project. Building the distribution package for the extension must put the dialog description files into the package.

For non-dialog related GUI functionality (e.g. enabling a certain toolbar item) the respective UNO API must be used. Is is a goal of this project to implement easy-to-use UNO APIs for those tasks, if not already available.
Using the UNO AWT also ensures that the Look (& Feel) of the extension is the same like in OpenOffice.org.

Additional menu items and toolbars can be introduced easily using Configuration Snippets (XCU files) that become part of the extension package.
OO.o GUI must be usable by people with disabilities. Thus, they must meet Accessibility requirements. It must be possible to assign mnemonics and keyboard accelerators to UNO AWT dialog controls and menu items.

'''Comments on other Toolkits'''

Using Java Windowing Toolkits like SWING was also discussed. SWING functionality and tooling is very good. The look of the GUI elements would be very like the same as for OO.o GUI elements. SWING already has good localization and accessibility support. However, most of the OO.o core developers are C++ programmers and the OO.o community has stressed many times, that they do not like to much Java dependencies in OO.o, especially in core components. This does not mean that we generally want to prohibit usage of Java Windowing Toolkits. There are certainly cases were it makes sense to use them.

Another option is to use non-OO.o native Windowing Toolkits, like MFC, GTK or QT. Although tooling and functionality is great, some are not available for all OO.o platforms (MFC). It might be okay to have extensions only for some of the platforms supported by OO.o, but this should be the exception. Another problem can be that the toolkit libraries are not always present on every target machine. Again, it can make sense to use even those Toolkits for the implementation of OO.o Extensions. This depends on the kind of extension and its purpose.

Using XUL/Gecko to describe/render the user interface of OO.o Extensions comes also to mind. We already did some prototyping in that area. Although this seems to be very interesting, both from the technical and strategic stand point, we have no chance to implement this in the given time frame. There are to many known and unknown problems. For instance, we would get highly dependent on 3rd party software components and have no idea how good the cooperation with the Mozilla project would work. The risk is very high and there is very much work to be done to get XUL/Gecko usable for OO.o GUI development. Therefore, this is not an option at this time.

A big disadvantage when using other toolkits than UNO AWT is that automatic GUI testing using the OO.o Testtool will not work.

==== GUI Localization ====
It must be possible to localize the User Interface of extensions.

The plan is to have a new UNO service that implements a Resource Management System that can deal with different locales.

In a first step we need localization support for
* strings and
* dialogs

Localization support for dialogs is more than just access to translated strings, it also includes for instance localized control positions and sizes. The latter is rather high effort and implementation is not a must for this project.

An extension developer would use the new Resource Management UNO Service in order to access localized resources. Resource loader method(s) will return either a string or an UNO AWT dialog instance, depending on the actual resource referenced by the given resource identifier. Is is important to design an extensible UNO interface here, in order to be able to add support for more resource types in the future. For instance, just having one single loadResource() method that returns an UNO ANY would be fine.

An important point to take into account is persistence of the resource descriptions. To keep things simple, resource description files should be in a format that can easily be edited without additional special tools. Using a normal text editor is desirable. This is not the case for the resource system (src files that need to be compiled into binary res files) currently used by OO.o. Using something simple like Java properties files seems to be a good idea. Strings in XML dialog descriptions should be just references to strings located in a properties file.

However, it makes sense to add support for the “traditional” binary resource format to the new Resource Management UNO service, for instance, in order to reuse existing error messages.

To provide some convenience, the OO.o Dialog Editor will be extended to support localized dialogs. The idea is to be able to switch the locale to use for the dialogs in the Editor User Interface. The Editor will always display dialogs according to the locale chosen. For the first step, just translated strings will be supported. In a second step, support for localized controls (position size, ...) will be added.

==== Help Content ====
OO.o GUI Extensions must be able to come with their own customized help content. This help content must integrate seamlessly with the OO.o help system. This means that the extension's help content must
* appear in the usual OO.o Help Viewer window upon requesting help for the extension (by pressing F1 or pushing a help button in a dialog supplied by the extension)
* appear in the table of contents of the Help Viewer
* appear in the index of the OO.o Help Viewer
* be searchable using OO.o Help Viewer

Additionally, it must be possible to define and integrate 'Help Tips' (toolbar items) and 'Extended Tips' (toolbar items, menu items, dialog controls) for own GUI elements and own content 'Help Agent'.

The OO.o Help System will be extended to support all the requirements above.
There will be new OO.o SDK tools – at least a help compiler-- to support the extension developer with creating the files that need to be packaged with his extension in order to supply help content for the extension. It must be possible to use standard tools (a normal text editor) to produce the input file(s) needed by the help compiler.

In the end, the help compiler will be integrated into the OO.o Netbeans Development Package. It must be possible to add help source files to an OO.o Extension project, then. Building the project will include compiling help source files and creating the distribution package for the extension must put the compiled help files into the package.

The OO.o Extension Manager needs to be extended with a new backend for help content.

==== Testing ====
The functionality of an extension should be testable fully automatically. The GUI can be tested using the OO.o Testtool. The rest should be covered by testcases for the OO.o Testing Framework.

== Deployment of OpenOffice.org GUI Extensions ==
All OO.o Extensions will be managed by the OO.o Extension Manager. The Extension Manager already fulfills some of the requirements we have:
* Installation of packages
* Deinstallation of packages
* Enabling/Disabling of packages without need to (re-)install the package
* Visualization of installed packages
* Installation of packages for both single user and all users. (The latter is achieved using the command line tool unopkg, which comes with every OO.o installation.)

Additional requirements, that are not yet implemented in the OO.o Extension Manager, are:
* '''Update''' of installed packages. This feature involves and includes the following:
** '''Package versioning''': A package must be able to specify a version number in a standardized way. This enables the Extension Manager to compare versions and to react accordingly, for instance when requested to replace an older version with a newer version of the same package.
** '''Package Dependencies''': A package must be able to specify its runtime dependencies in a standardized way. In a first implementation step, a package would be able to specify coarse grained dependencies, for instance that it needs “OO.o 2.0.4 or higher” to run properly. Later on, support for more fine grained dependencies will be implemented. The Extension Manager must do a dependency check upon package installation/update and allow or prohibit the installation/update of the package according to the result of the check.
** '''Online updates''': This means that a package can be updated over the (inter)net. The Extension Manager will be extended to support online updates. This includes checking for updates, downloading and installation of updates. Checking for updates should be possible automatically, for instance at startup of OO.o, and additionally every X minutes or so. User must be able to customize this feature to meet its personal preferences. Generally, the online update functionality (and internals) of '''Firefox/Thunderbird''' is considered to be very good and is definitely worth a deeper look when thinking about the details for the OO.o Extension Manager online update feature.
Note: Like for the OO.o base product itself it is important to define a backend (UNO) API that enables implementation and usage of different server-side software update technologies. Thus, StarOffice could use a different mechanism than OO.o.
* '''Product Configuration''': A package must have the possibility to provide its own configuration user interface (e.g. a configuration dialog). The Extension Manager UI must be extended with the functionality to be able to activate the configuration interface of a package. The package will need to implement a certain UNO API that gets called be the Extension Manager. This API does not yet exist and will be very simple – just one 'configure' method returning void. It's completely up to the package to handle its configuration items. Additionally, we will implement the framework needed to be able to integrate extensions configuration dialogs into OpenOffice.org's standard configuration dialog (Tools/Options).
* '''Package Signing''': It must be possible to digitally sign a package. This is important especially for commercial packages in order to provide the possibility to ensure that the package has not been altered by 3rd party. The Extension Manager will check the validity of a package signature before installing a package. In case of an invalid signature the user gets informed and can decide whether the package shall be installed anyway.
* '''License Acknowledgement and Management''' upon package installation/update: A package must be able to implement its own license management. This will basically be done by providing a licensing API that can be implemented by the package provider and that will be called by the Extension Manager. The Extension Manager will react according to the return value(s) of the licensing hook functions.
* '''Product registration''' upon package installation/update: It must be possible to register packages upon installation/update. Most similar to licensing, an idea is to provide a registration API that can be implemented by the package and that will be called by the Extension Manager.
* '''New''' easy to use Extension Manager '''User Interface''': Current Extension Manager user interface is powerful, but rather 'technical'. Extensions are not just for power users. Thus it should be as easy as possible to install, maintain and deinstall extensions. That's why we want to implement a new, more simple and user-friendly graphical user interface for the OO.o Extension Manager. The user interface for Firefox Extensions looks pretty good and should be evaluated closely while designing the new user interface for the OO.o Extension Manager. It is not yet decided whether we keep and extend the old user interface in parallel to the new one.