Overview and core concepts

To embed a Wookie widget in a host application you need to install (or create) an appropriate plugin for your host environment. This will provide the bridge between your host platform and the Wookie server. Before we get into the details lets looks at some key terminology.

Plugin
A plugin is an extension to an existing web application that enables it to show widgets that are being served by Wookie. A plugin implements the Wookie REST API to discover which widgets are available, to request instances for particular users, and to set participant information.

Plugins are usually written in the programming language of the host web application and may make use of an existing "widget" or "plugin" system, extending it to support additional widgets made available by Wookie.

Connector Framework

Wookie provides a connector framework that provides most of the code you need to build a plugin. We hope to provide these frameworks in as many languages as possible. If you intend to write a plugin for your favourite host application please check with the Wookie developers list about what frameworks and plugins are already available. We would prefer to work together in order build as large a set of connector frameworks and plugins as possible.

Viewer
The viewer is the current user who is viewing a widget in the browser. Typically an application uses session information to know who the current user is, and this is used to request a particular widget instance. It is up to the plugin to determine how to identify the viewer; for example the user's real id is one possibility; another is an opaque hashcode using the id.

...

Shared Data Key
The shared data key is an arbitrary identifier that marks widget instances as being sibling instances that can share state information. It is up to the plugin to determine this value; typically there is a persistent identifier available for whichever view is being used as the container for a widget.

Building Plugins with the Connector Framework

At the time of writing (Feb 2010) there is a partial implementation of a Java connector framework see http://svn.apache.org/repos/asf/incubator/wookie/trunk/src/org/apache/wookie/connector/framework/^{Image Added}

In order to build a plugin for a Java application you simple need to implement IWookieConnectorService by extending and implementing AbstractWookieConnectorService.

Building Plugins without a Connector Framework

We strongly discourage you from building a plugin from scratch without first building a connector framework for your chosen language. By building a connector framework, or even partially implementing one, in your chosen programming language you will be helping others build more plugins as well as being able to share resources with others using the same connector framework.

The best way to build a new connector framework is to copy the Java one (see above). The rest of this document describes what is going on in this framework.

Creating a widget gallery

To make it easier for users to add widgets to parts of an application, you may want to provide users with a gallery of widgets.

...

You can also obtain localized information about widgets by adding a locale parameter to the request. If appropriately localized information about widgets (including localizd icons, titles, descriptions, and license information) will be returned rather than the default content.

Widget instance lifecycle

Requesting an instance

Whenever a user - the viewer - is to be shown a widget, your application needs to make sure you have a widget instance to show the user. To do this you should request a widget instance at /wookie/widgetinstances. The format of the request can be found in the REST API docuumentation, however the main points to bear in mind are how to construct the request parameters:

...

The response to a widget instance request contains a URL; typically you would use this information to construct an iframe tag with the correct height and width. Generally this is all that is needed to include a widget served by Wookie.

Adding Participants

Initial state information

Advanced functionality

Cloning widget instances

Stopping and resuming instances

Sharing widgets across applications

The assumption in the documentation above is that each application will want to maintain widget states in isolation from other applications - for example, that it is not desirable to potentially mix up the states of widgets run by users in different contexts.

...