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

For more information, please explore the Attic.

This document describes how to embed Wookie Widgets in third party applications.

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. Currently available plugins include:

If your environment is not listed above then you may 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 embarking on this though be sure to do a thorough search for a pre-existing plugin we are not aware of. Please let us know if you find one.

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 connector framework code in many languages. These frameworks provides most of the code you need to build a plugin for your platform.

If you need a connector for a platform not listed above you need to implement your own using our provided connector frameworks. The latest versions of the connector frameworks can be found in Subversion.

The documentation below refers to the Java connector. As far as possible we've kept to the names and method signatures the same in the connector framework for each language.

Implementing a Connector for your Platform

To implement the connector you simply need to create an implementation of the AbstractWookieConnectorFramework class. This class provides abstract methods for communicating with the host environment.

We provide a reference implementation of this AbstractClass that is used within Wookie itself.

Concepts

This section introduces the various concepts you need to understand in order to build a connector for your host application.

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.

Widget Instance

A widget instance is a persistent instance of a particular widget created for a user. Each widget instance has its own storage area in Wookie. Widget Instances are created by invoking the Wookie REST API using an API Key and supplying values for the viewer and the shared data key.

API Key

An API Key is used to access many of the features of the Wookie REST API. Each individual web application needs its own API key.

For information on creating and managing API keys, see the Server Administration documentation.

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.

Basic usage of the framework

In this section we document the most basic use of the connector framework. All example code is written in Java, but it should be the same in other languages (if not, help us bring them all up to date).

In general to use the framework you will need to:

Getting a connection to a Wookie server

/*
 * Get the wookie service connector
 */
public WookieConnectorService getWookieConnectorService(String serverURL, String apiKey, String sharedDataKey ) {
  if (connectorService == null) {
    connectorService = new WookieConnectorService(serverURL, apiKey, sharedDataKey);
  }
  return connectorService;
}

Working with users

Set the current user:

WookieConnectorService conn = getWookieConnectorService(url, apiKey, datakey);
conn.setCurrentUser("testuser");

Working with widgets

Get a widget instance.

String guid = ".....";
WidgetInstance instance = conn.getOrCreateInstance(guid);

Displaying widgets

Displaying the widgets is the job of the platform in which you wish to embed widgets. The easiest way to embed a widget is simply to place it in an iframe. To do this you will need an URL for retrieving the widget instance, for example:

String url = instance.getUrl(); // get the URL from the WidgetInstance
displayWidget(url); // a method you implement that displays the data at the URL

Working with preferences and shared data

The connector framework also provides access to preferences and shared data for specific widget instances; for example, you can pre-populate information in a widget instance, such as the video to show in video player widget, or the initial location to use for a local weather information widget. For example, the following sets the widget preference key "city" to "manchester" for a single viewer:

conn.setPropertyForInstance(instance, false, "city", "manchester");

To set a property for all widget instances in the same context, use "true" for the second parameter.

Using admin functions from a connector or plugin

The connector framework also supports (as of v0.10) calling the administrator APIs of a Wookie server, provided you supply the correct admin credentials. This includes the ability to manage API keys, access policies for the built-in proxy service, and even to add and remove widgets from the server. This means that you can use the connector framework to build a complete admin client for Wookie.