You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 19 Next »

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 need to implement a plugin - don't worry, it's pretty easy and we're here to help.

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.

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. API Keys are generated from Wookie's administration interface.

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

The Java connector framework is used within Wookie itself and is therefore considered the reference implementation. Other connector frameworks include PHP, C#, Ruby and Python.

See http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/ for the latest available code.

To use the frmework you will need to do the following:

  • get a WookieConnectorService
  • set the current user
  • get or create a widget instance
  • provide the instance URL to the hosting environment and display it

Using the Java connector frameowrk you would do something like:

// Get the wookie service connector
StringBuilder sbUrl = new StringBuilder(request.getScheme());
sbUrl.append("://");
sbUrl.append(request.getServerName());
sbUrl.append(":");
sbUrl.append(request.getServerPort());
sbUrl.append(request.getContextPath());
serverURL = "http://foo.org/wookie";
apiKey = "TEST";
sharedDataKey = "myshareddata";
connectorService = new WookieConnectorService(serverURL, apiKey, sharedDataKey);


// Set the current user
connectorService.setCurrentUser("testuser");


// get or create a widget
instance = connectorService.getOrCreateInstance(guid);


// show widget
showWidget(instance.getUrl());

uilding 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.

Wookie provides the widgets interface for accessing metadata about currently installed widgets. There are two approaches that can be taken:

/wookie/widgets?all=true returns all the current widgets available. This is the method that most plugins will want to use.

/wookie/widgets with no parameters returns only the widgets set as defaults for the currently set widget services. This is mostly used for some advanced plugins for authoring tools.

Each method returns metadata including widget icons, titles, categories, and descriptions. This should be sufficient for creating a gallery user interface where a user can select a widget, and your application can use the identifier of the widget to create an instance, as covered in the next section.

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 Wookie REST API documentation, however the main points to bear in mind are how to construct the request parameters:

user_id: the user id is an identifier associated with the current viewer, and not the owner of the view. This doesn't need to be a "real" identifier, and can be a hashcode or other opaque value; you just need to be consistent.

shareddatakey: this value is used by Wookie to identify "sibling" widget instances that can share state information where appropriate (for example, in a chat widget). To do this an application needs to have a consistent process for generating this value. Typically this is an identifier already used in the application for identifying areas of pages; for example a combination of page identifier and a block or (native) widget identifier.

Note that subsequent requests for a widget instance will always return the same instance for the same given parameters - this means that if your application does not persist the instance data you can request it with each page view. Note that an exception to this rule is locale parameters - subsequent requests for an instance using the same user id and shared data key but with a different locale will always return the same instance rather than a new instance.

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.

However, if you are careful about how each plugin issues its SharedDataKey it is possible to operate with shared widgets.

For example, it is possible to have a single shared widget state for the same group of users in two different applications if they issue a matching SharedDataKey for the context, matching UserIds for users, and use the same API Key.

Obviously this is something that needs careful attention in configuring the plugins for the applications.

Using IMS Basic LTI to embed Wookie Widgets in educational systems

For education applications it is possible to also use Wookie with the IMS Basic LTI specification, which is a specification for connecting e-learning applications with tools. To do this you can use the BasicLTI4Wookie plugin . There is IMS Basic LTI support in popular education platforms such as Blackboard, Sakai, Desire2Learn and WebCT.

  • No labels