...
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. Currently available plugins include:
If your environment is not listed above then you need to implement a plugin - don't worry, it's pretty easy, especially if we have a connector framework available for you (see below) and we're here to help.
Before we get into the details lets looks at some key terminology.
...
Wookie provides a connector framework for many languages. This 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. for your platform.
If you intend to write a plugin for your favourite host application please check http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/ for the latest available conenctor code.
Naturally, we with the Wookie developers list about what frameworks and plugins are already available. We would prefer to work together in order to build as large a set of connector frameworks and plugins as possible, so please help us improve and expand this set of connector frameworks.
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.
...
In general to use the framework you will need to:
- get a WookieConnectorService
- set the current user
- get or create a widget instance
- provide the instance URL to the hosting environment and display it
Getting a connection to a Wookie server
...
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
Participants are added to a Widget Instance using the Participants REST API. The format of the request can be found in the Wookie REST API documentation, however the main points to bear in mind are how to construct the request parameters. As well as the usual parameters (API key, shared data key, widget id, user id) this method requires:
participant_id: An identifier for the participant in the application. This doesn't need to be a "real" identifier, and can be a hashcode or other opaque value; you just need to be consistent.
participant_display_name: A name to display for the participant; typically a nickname or any other name commonly displayed in the application for this participant.
participant_thumbnail_url: A URL pointing to the participant's icon or avatar, if they have one. This should be an absolute URL.
Initial state information
You can populate the preferences and shared state information of a Widget Instance using the REST API. The format of the request can be found in the Wookie REST API documentation, however the main points to bear in mind are how to construct the request parameters. As well as the usual parameters (API key, shared data key, widget id, user id) this method requires parameters for the key and value being set. If you set is_public=true then the property set is in the shared state for the Widget Instance and its sibling instances, otherwise its a private preference just for the current Widget Instance.
Advanced functionality
Cloning widget instances
It is possible to clone a Widget Instance; this creates a copy of the Instance but with a new SharedDataKey (which you supply). You can use this to support moving widget instances from one space into another while keeping all their state information. The format of the request can be found in the Wookie REST API documentation.
Stopping and resuming instances
It is possible to Stop and Resume a Widget Instance; the effect of this is to prevent any further storage events for the Widget Instance (e.g. preference setting, or shared state changes). The format of the request can be found in the Wookie REST API documentation.
Sharing widgets across applications
...