The Widget Jones Library

What is the Widget Jones Library?

The Widget Jones Library is a lightweight, flexible, template driven widget build system. It is intended to simplify creating portable widgets. Write your code once, build it with WJL, then run it on several widget platforms like

Should you have any remarks, observations, recommendations or even patches, don't hesitate to either to create a new ticket, or drop us a mail at info@euedge.com.

Philosophy and Design

There are several widget platforms out there, mostly sharing the basic design of using HTML/CSS/JavaScript, with asynchronous HTTP communication and some type of preferences management. Naturally, there are efforts to standardize these (see W3C Widget 1.0 spec) or to provide a common denominator (such as Netvibes Universal Widget API).

We needed a simple and pragmatic solution that fulfills the following criteria:

  • Full access to the underlying platforms: you should be able to take advantage of platform-specific capabilities.
  • Be transparent: do not layer in too many abstractions and indirections, so you know what's actually happening when debugging issues.
  • No vendor lock-in: avoid inventing proprietary APIs and languages. Do not impose hosting or distribution requirements.
  • Open source: this stuff should be free, and freely usable. New platform integrations should be contributed by community.

We felt that no existing approach fulfilled these, thus the Widget Jones Library was born. Its architecture is simple (simplistic even :), and defines three things:

  • Patterns: Define a consistent way of building new components and platform integrations.
  • Build system: Provide an extensible, template-based build system, with useful starting points.
  • Runtime library: Provide a minimal JavaScript runtime library that abstracts the most common operations: asynchronous HTTP communication and preferences management. This is currently much less than 100 lines of code.

Getting the Widget Jones Library

The Widget Jones Library is available from the EU Edge Open Source site, http://oss.euedge.com/ .

You can download released versions from the EU Edge OSS download area.

Alternatively, you can check out the latest sources from the EU Edge OSS subversion repository: 

svn checkout https://svn.oss.euedge.com/wjl/trunk

Requirements to build widgets

Note: the widgets built run on their own.

To build widgets, you need ruby and some related tools.

To obtain ruby please visit http://www.ruby-lang.org/en/downloads/ You will also need the rubygems package manager, see http://rubygems.org/

Furthermore you'll need two 'gems' (software packages written in ruby language and maintained by rubygems):

  • rake (like make utility)
  • yaml
  • builder (Markup builder)

Install them with 'gem install <package name>' command via command line interface: 

gem install rake
gem install yaml
gem install builder

How do I start my first project?

Make sure to download and extract the WJL package. The templates and the build environment are contained in the 'wjl' folder inside the archive.

A WJL project has the same directory structure as the 'wjl' directory, and is in essence an overlay on 'wjl'. You only need to create the files you wish to customize for your project. All other files will be taken from the 'wjl' supplied defaults.

Let's start with a basic example. Consider you already have WJL in a local folder. 

 .
 `-- wjl

Create your HelloWorld project beside WJL by first creating an empty folder 'helloworld'. This directory could be anywhere you find convenient. 

 .
 |-- wjl
 `-- helloworld

Now copy content.html and config.yml from WJL to their place as shown above. 

 .
 |-- wjl
 `-- helloworld
     |-- common
     |   `-- content.html
     `-- config.yml

Now start coding and fill in the config file. Open content.html and write the following code: 

<center>Hello Widget World</center>

Edit config.yml with a text editor, and fill it in. The fields are pretty self-explanatory: 

width: 320
height: 120
name: HelloWidgetWorld
title: Hello Widget World
description: "This is my first widget project!"
author: John Doe
author_email: john@doe.com
website: http://doe.com
website_text: "The Does"
namespace: com.doe.john.hellowidgetworld

In a console, navigate to your project and issue the following command-line command: 

  <wjl path>/build (Linux / Mac)
  <wjl path>\build.bat (Windows)

WJL builds the all widgets in 'dist' folder within your project directory: 

 .
 `-- helloworld
     `-- dist
         |-- dashboard  - Apple Dashboard widget
         |-- igoogle    - iGoogle widget
         `-- sidebar    - Windows Vista Sidebar widget

Congratulations, you completed your first WJL widget project. Now you can try out your widgets in their run-time environment. The simplest way to upload the generated dist/igoogle/main.xml (iGoogle) to http://google.com/ig and give it a try.

How can I override templates?

It's easier than you may think. Your project structure is a 'shadow' of WJL. If you want to override a WJL template just copy it to the same place in your project folder where it can be found in WJL.

What is the WJL JavaScript library good for?

WJL JavaScript library is automatically included to widget content and provides the following services:

  • fetch XML and text contents from remote site
  • simple preferences management

For developers