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