2016/04/10 - Apache Wookie has been retired.

For more information, please explore the Attic.

This page contains some notes and guidance on how to build widgets that can be hosted in the Wookie Server.

Tutorials

You will probably want to look at the tutorial found in http://svn.apache.org/repos/asf/wookie/trunk/tutorials/

These include presentations on creating a Hello World widget and on basic widget features, but take a look there are other materials in there too..

Widget source directory

For ease of development you will probably want to build widgets using the src version of Wookie as this provides a number of tools for working with Widgets. This is not required, but this document assumes this to be the case.

Working directory

You can get started right away from within the Wookie source directory. However, if you are not planning on submitting your widget code to the Apache Wookie project then you might want to work in your own directory. The following two sections describe how to work with either of these scenarios.

Wookie widget directories

There are two widget directories for you to work in within the Wookie source. The first is intended for widgets that will go into production and is located at "/widgets". The second is for experimental or in-development widgets and can be found in "/scratchpad/widgets".

Own project directories

If you want to work within your own widgets directory you must first setup your environment as follows.

  1. Create your chosen widget directory
  2. Copy "/widgets/build_template.xml" to your widget directory as "build.xml"
  3. Edit the value of the "wookie.root.dir" property so that it reflects the location of your wookie source directory

In the examples below we use "$WIDGETS_HOME" to indicate the directory you are using and $WOOKIE_HOME to indicate the root directory of your Wookie sources. There is no requirement to set these environment variables, but you might find it useful to do so.

Create a widget

To create a widget:

cd $WIDGETS_HOME
ant seed-widget

This is an interactive target that will ask you a number of questions about the widget you wish to create. The first question asks for a short name for your widget. This short name is used as the name of the widget directory and other key widget. For the rest of this document WIDGET_SHORTNAME will refer to your response to this question.

Once the target has completed your widget skeleton will be available in a directory called WIDGET_SHORTNAME.

The default widget will provide a very basic widget with default style resource and javascript files.

Build a Widget

ant build-widget

You will be asked the name of the widget to buildunless you set it with the -Dwidget.shortname property as described below.

After a succesful build your widget package will be created in the /build/widgets directory.

Deploy a widget

ant deploy-widget

You will be asked the name of the widget to deploy unless you set it with the -Dwidget.shortname property as described below.

Your widget will be hot deployed and you can use it immediately (note the server must have hot deploy turned on for it to see the new widget).

Supplying the widget name

It can become tiresome having to enter the widget name repeatedly during the development cycle. For this reason you can supply it in the command, for example;

ant deploy-widget -Dwidget.shortname=FooWidget

Automatically deploying at build time

Widgets will automatically be deployed at build time by default. That is, any widgets found in the widgets directory will be deployed to the webapp when it is rebuilt. you can configure which widgets will be deployed in your local.build.properties files.

Platform independent widgets

Wookie is capable of serving the widget as a HTML application for embedding in your third party environments such as CMSs, LMSs and blogs. What about serving the packaged widget for deployment to widget clients such as Opera Mobile?

Through the Flatpack API Wookie will serve a widget as a packaged wgt file. This allows it to be hosted in any suitable container. However, there are a few things you need to be careful of when buidling widgets that are intended to be managed by other containers. The sections below discuss some of the issues you may face.

Wookie specific features

Widgets intended for use outside of Wookie should not use any Wookie-specific features or internal calls. The syntax analyzer outputs warnings about this when you deploy the widget, so its worth paying attention to the log output to see if there is anything that needs fixing.

It is also recommended that you test widgets by opening the .wgt using Opera Mobile, and by putting it through a PhoneGap Build and opening the generated application in the Android Emulator that comes with the Android SDK for Eclipse.

Platform compatibility

There are quite a few qotchas generally, mostly around things like differences in HTML5 support across different environments. For example the Android browser has poor Canvas support and Opera Widgets doesn't handle referenced audio files. The only realistic way to deal with this is to do a lot of testing, and where possible check for feature availability in scripts before making calls.

Development for browser and mobile applications

The following is a development and test cycle that has been found to work for some developers.

  1. develop the widget for in-browser use only, and test in a range of browsers including the Android browser, IOS Safari, and Opera Mobile
  2. test for existence of window.widget and if available enable widget features like preferences and metadata
  3. add features needed in config.xml, but make them optional, and test for availability in scripts before enabling them in the widget UI
  4. create .wgt package
  5. upload to PhoneGap build to create mobile apps

Its not exactly foolproof and automatic, and there are still problems, but if you are "serious" about widget development this basic approach can be used to get widgets working correctly across most platforms.

Please help us improve on this documented process.

Third Party Materials

This section links to third party materials about building Wookie Widgets.

Thomas Ullmann

Thomas has created some screencasts you can follow:

Cool Widgets

This section links to widgets hosted outside Apache that you may want to deploy.