Widget Cookbook

From Stellar Deliverable 6.3

Jump to: navigation, search

1 Widgets for Wookie & Elgg

1.1 Screencast: How to build a widget and to use the Wookie Server

The following two links lead you to tutorials about

How to build a widget [[1]]
How to run them on the Wookie widget server [[2]]

1.2 Creating widgets

The Wookie Widget Developer’s Guide is a comprehensive introduction of the Wookie widget development process.

See http://svn.apache.org/repos/asf/incubator/wookie/trunk/docs/

The documentation of Wookie is work in progress. New documentation is in development. For the actual state of these look here: http://incubator.apache.org/wookie/.

1.3 Installation of the Wookie Server and Elgg

In case you want to install Wookie and Elgg, follow these installation steps. However, for the development of widgets this is not necessary. You can develop them without the Wookie server.

First you have to set up the Wookie engine. You will find a step by step installation here: http://incubator.apache.org/wookie/downloading-and-installing-wookie.html.

The same applies for Elgg. Go to http://elgg.org/downloads.php and download the latest release. Find the installation instructions here: http://docs.elgg.org/wiki/Installation.

Elgg can use Wookie widgets through the Elgg plugin system. First install the Wookie Widget Plugin (http://community.elgg.org/pg/plugins/hoisl/read/323321/wookie-widgets-21). Rename the base folder “wookie” to a name reflecting your plugin. You can modify the languages/en.php the array values, to brand your widget and add further languages files for internationalisation (see http://docs.elgg.org/wiki/Engine/Internationalisation#Adding_language_files_to_plugins_.28and_best_practices.29).

For general plugin configuration information, see http://docs.elgg.org/wiki/Configuration/Plugins.

Set at the beginning of the view.php in the view folders the URL to the Wookie engine, your API key, and the type of widget (see the following section).

For the development process of widgets within Elgg turn off the simple cache and the view filepath cache, to avoid that changes become not instantly visible. Set the options in the Adminstration menu under the “Site Administration” submenu.

To enable the Wookie plugin, go to the Administration page to the submenu “Tool Administration” and enable your plugin. The name of the plugin is the name of your plugin folder, e.g. “wookie”. Further descriptions of the plugin can be set in the manifest.xml of your plugin.

1.4 Wookie

1.4.1 Wookie Engine

The Wookie Server allows delivering widgets, which follow the W3C widget specification. The Wookie server administration interface provides functionalities to add widgets and to remove them, to set a white list for accessing data (both in a restricted are), to request an API for the widget, and to instantiate a widget.

1.4.2 Getting an API key

Through the public administration interface of the Wookie server everyone can request an API key entering an email address (the latest version of Wookie seems to have a bug. It says that there is a problem to create the API key. Nevertheless you can find the API key in the database).

1.4.3 Accessing data

White lists for remote content could be set in the administration interface of Wookie. If the widget wants to access for example a data feed from a remote server, the white list has to be set in the Wookie engine. This is due to the restriction of many browsers to allow communication only from the server from where the widget is coming from (same server restriction).

An example for a white list entry is: http://news.kmi.open.ac.uk/rostra/rss2.php?r=11

1.4.4 Instantiate a Widget

You don’t have to worry about how to instantiate your widget. The Elgg Wookie plugin described earlier sends a proper request to the Wookie engine to instantiate the widget. Nevertheless the details for the call to the Wookie engine and the response could be useful to extend the Elgg Wookie plugin to your needs.

The API call “getwidget” instantiates a new widget or returns the previously used instance. The administration interface helps to generate an example call. Five parameters could be specified:

?requestid=getwidget

&userid={userid} (unique string for a user)

&shareddatakey={ shared data key} (any string)

&api_key={API key} (string retrieved from the administration interface)

&servicetype={service type} (string, e.g. ‘chat’, ‘forum’ or ‘vote’)

1.4.5 Example:

http://localhost:8080/wookie/WidgetServiceServlet?requestid=getwidget&userid=thomas&shareddatakey={mysharedkey}&api_key={key}&servicetype={socialGraph}

The shareddatakey parameter allows users to share the same instance of the widget. If another user wants to share the same instance of the widget the call has to include the same shareddatakey string of the first user.

1.4.6 Example:

http://localhost:8080/wookie/WidgetServiceServlet?requestid=getwidget&userid=fridolin&shareddatakey={mysharedkey}&api_key={key}&servicetype={socialGraph}

1.4.7 Return values

The call returns and XML fragment with information how to display the widget:

<url> url of the widget instance

<height> height of widget

<width> width of widget

<maximize> {true, false} to flag if the widget can be maximized to full screen or if it should be fixed to the default height & width in the client application.

1.4.8 Example

<url>

http://localhost:8080/wookie/wservices/www.tencompetence.org/widgets/default/chat/index.htm?idkey=N9xrPyhLWZUC7UXnWsjVKYbr8bE.eq.&proxy=http://localhost:8080/wookie/proxy&st=wookie%3AyoGtWfi05DhnluULQ1B3i48C8iJcSP70A%2F06HUrQ4SJuQx%2FVnZdM84Yhrz1CZjd6VbckJRGM6yNPW1nqtoOn0SS1YJ6iq15VFAoo%2Bzn37w29xYMCq%2Bdi%2BOEYoV7kHd%2F9ZkFhSR9r514b9o9O36Ir4FMkQ1bht6Gg2wOnXCshIBmjfAzEWCpDWUmoUIOaVF8LLX2C9g%3D%3D

</url>

<title>Default chat widget</title>

<maximize>false</maximize>

</widgetdata>

This information could be used for the <iFrame> of the target container (e.g. Elgg). Wookie loads the start.html of the widget package into this iFrame.

For more information, look into the Wookie Widget Server API specification: http://tencompetence.cvs.sourceforge.net/viewvc/*checkout*/tencompetence/wp6/org.tencompetence.widgetservice/docs/widget_web_api_09.doc.

A Wookie REST API draft is listed here: http://cwiki.apache.org/WOOKIE/wookie-rest-api.html.

2 Style Guide

One of the cornerstones of our Stellar infrastructure is "[Identity Management]". One important part of Identity Management is a corporate Stellar look-and-feel. Consider the Stellar Brand Guidelines for your development of Widgets and Tools:

You can use this icons to represent your widgets as Stellar widgets:

or create your own one (according to the Stellar Brand Guidelines)

3 Further Resources

IBM articles about (wookie) widgets [[3]]
Slideshare of Scott Willson [[4]]
Tutorial of Ross Gardler [[5]]
Tutorial of David from TenCompetence [[6]] bear in mind that this tutorial works with an old version of the wookie server. Do not use the config.xml described there as well as the way how to upload the widgets to the wookie server. Nevertheless it shows quite good how to use javascript and css and html in wookie widgets.
Showcase of what is possible with wookie widgets and google wave: [[7]]
Material from the Wookie training day: [[8]]

Navigation

SEARCH

TOOLBOX

LANGUAGES

Create a book