Author: rgardler
Date: Thu May 12 14:10:37 2011
New Revision: 1102318
URL: http://svn.apache.org/viewvc?rev=1102318&view=rev
Log:
Documentation for the connector framework
Added:
incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext (with
props)
Added: incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext
URL:
http://svn.apache.org/viewvc/incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext?rev=1102318&view=auto
==============================================================================
--- incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext (added)
+++ incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext Thu May 12
14:10:37 2011
@@ -0,0 +1,144 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+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:
+
+<ul>
+ <li><a
href="http://community.elgg.org/pg/plugins/hoisl/read/385029/wookie-widgets";
class="external-link" rel="nofollow">Elgg</a></li>
+ <li><a
href="http://code.google.com/p/foogen/source/browse/#svn/trunk/drupal/module/didget";
class="external-link" rel="nofollow">Drupal</a></li>
+ <li><a
href="http://wiki.lamsfoundation.org/display/lamsdocs/Wookie+Widgets";
class="external-link" rel="nofollow">LAMS</a></li>
+ <li><a href="http://moodle.org/mod/data/view.php?rid=3319";
class="external-link" rel="nofollow">Moodle</a></li>
+ <li><a href="http://code.google.com/p/wookiewordpressplugin/";
class="external-link" rel="nofollow">Wordpress</a></li>
+
+</ul>
+
+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 intend to write a plugin for your favourite host application please
check
+the latest version of our [connector frameworks in
Subversion](http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/)
+for the latest available connector code.
+
+Naturally, 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.
+
+### 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. However, even the Java framwork is incomplete and some
+activities are accessed directly through the REST API (see next section). We
welcome your help in expanding the framework code (in any language) so that all
features can be accessed through it.
+
+See
[Subversion](http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/)
for
+the latest available code.
+
+All code examples in this page are in Java, but other languages will use the
same method names and parameters.
+
+### 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:
+
+<ul>
+ <li>get a WookieConnectorService</li>
+ <li>set the current user</li>
+ <li>get or create a widget instance</li>
+ <li>provide the instance URL to the hosting environment and display
it</li>
+</ul>
+
+### 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
+
Propchange: incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
