Title: Building Widgets
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 page contains some notes and guidance on how to build widgets 
that can be hosted in the Wookie Server.

#Tutorials
You will probably want to look at the tutorial found in 
[http://svn.apache.org/repos/asf/wookie/trunk/tutorials/][1]

These include presentations on creating a [Hello World][2] widget and on
[basic widget features][8], but take a look there are other materials in there too..

#Widget source directory

For ease of development you will probably want to build widgets using the src
version of Wookie as this provides a number of tools for working with Widgets.
This is not required, but this document assumes this to be the case.

## Working directory

You can get started right away from within the Wookie source 
directory. However, if you are not planning on submitting
your widget code to the Apache Wookie project then you might
want to work in your own directory. The following two sections
describe how to work with either of these scenarios.

## Wookie widget directories

There are two widget directories for you to work in within the Wookie source. The
first is intended for widgets that will go into production 
and is located at "/widgets". The second is for
experimental or in-development widgets and can be found in 
"/scratchpad/widgets".

## Own project directories

If you want to work within your own widgets directory you 
must first setup your environment as follows.

 1. Create your chosen widget directory
 1. Copy "/widgets/build_template.xml" to your widget directory as "build.xml"
 1. Edit the value of the "wookie.root.dir" property so that it reflects the location of your wookie source directory
 
In the examples below we use "$WIDGETS_HOME" to indicate the directory you are
using and $WOOKIE_HOME to indicate the root directory of your 
Wookie sources. There is no requirement to set these environment variables, but you 
might find it useful to do so.

#Create a widget
To create a widget:

    cd $WIDGETS_HOME
    ant seed-widget

This is an interactive target that will ask you a number of questions 
about the widget you wish to create. The first question asks for a 
short name for your widget. This short name is used as the name of the 
widget directory and other key widget. For the rest of this document 
WIDGET_SHORTNAME will refer to your response to this question.

Once the target has completed your widget skeleton will be available in
a directory called WIDGET_SHORTNAME.

The default widget will provide a very basic widget with default style
resource and javascript files.

#Build a Widget

    ant build-widget

You will be asked the name of the widget to buildunless
you set it with the -Dwidget.shortname property as described
below.
 
After a succesful build your widget package will be 
created in the /build/widgets directory.

#Deploy a widget

    ant deploy-widget

You will be asked the name of the widget to deploy unless
you set it with the -Dwidget.shortname property as described
below.

Your widget will be hot deployed and you can use it immediately 
(note the server must have hot deploy turned on for it to see the new widget).

##Supplying the widget name

It can become tiresome having to enter the widget name repeatedly 
during the development cycle. For this reason you can supply it in the
command, for example;

    ant deploy-widget -Dwidget.shortname=FooWidget

#Automatically deploying at build time
Widgets will automatically be deployed at build time by default. That is, any widgets found in the widgets directory will be deployed to the webapp when it is rebuilt. you can configure which widgets will be deployed in your local.build.properties files.

# Platform independent widgets

Wookie is capable of serving the widget as a HTML 
application for embedding in your third party 
environments such as CMSs, LMSs and blogs. What about
serving the packaged widget for deployment to widget 
clients such as Opera Mobile?

Through the [Flatpack API][9] Wookie will serve a widget as 
a packaged wgt file. This allows it to be hosted in any 
suitable container. However, there are a few things you need 
to be careful of when buidling widgets that are intended to 
be managed by other containers. The sections below discuss 
some of the issues you may face.

## Wookie specific features

Widgets intended for use outside of Wookie should not use 
any Wookie-specific features or internal calls. The 
syntax analyzer outputs warnings about this when you 
deploy the widget, so its worth paying attention to 
the log output to see if there is anything that needs 
fixing.

It is also recommended that you test widgets by opening 
the .wgt using Opera Mobile, and by putting it through 
a PhoneGap Build and opening the generated application in 
the Android Emulator that comes with the Android SDK for 
Eclipse.

## Platform compatibility

There are quite a few qotchas generally, mostly around 
things like differences in HTML5 support across different 
environments. For example the Android browser has poor 
Canvas support and Opera Widgets doesn't handle referenced 
audio files. The only realistic way to deal 
with this is to do a lot of testing, and where possible 
check for feature availability in scripts before making
calls.

## Development for browser and mobile applications

The following is a development and test cycle that has been
found to work for some developers.

  1. develop the widget for in-browser use only, 
     and test in a range of browsers including the 
     Android browser, IOS Safari, and Opera Mobile
  2. test for existence of window.widget and if available enable widget features like preferences and metadata
  3. add features needed in config.xml, but make them optional, and test for availability in scripts before enabling them in the widget UI
  4. create .wgt package
  5. upload to PhoneGap build to create mobile apps

Its not exactly foolproof and automatic, and there are 
still problems, but if you are "serious" 
about widget development this basic 
approach can be used to get widgets working correctly 
across most platforms.

Please help us improve on this documented process.

#Third Party Materials
This section links to third party materials about building Wookie Widgets.

##Thomas Ullmann
Thomas has created some screencasts you can follow:

  - [Creating widgets][3] - Note that this screencast demonstrates how
    to build widgets manually, the presentation above describes how to
    use the templates to get started faster. 
  - [Uploading widgets][4]-
    Note that this is made against an older version of Wookie, whilst
    uploading is correctly documented, the method for previewing widgets
    is incorrect. To preview a widget click the "demo" link in the
    widget gallery.

#Cool Widgets
This section links to widgets hosted outside Apache that you may want to deploy.

 - [MultiXinha][5] is a collaborative real-time text editor (think EtherPad in a widget) by Mark Johnson
 - [Pacman][6] is a pacman widget adapted by Scott Wilson from a game by Dale Harvey
 - [WIDER][7] is a project that has a number of widgets aimed at digital inclusion and accessiblity.


  [1]: http://svn.apache.org/repos/asf/wookie/trunk/tutorials/
  [2]: http://svn.apache.org/repos/asf/wookie/trunk/tutorials/tutorial_1_hello_world.odp
  [3]: http://people.kmi.open.ac.uk/ullmann/tutorials/wookie/widget.htm
  [4]: http://people.kmi.open.ac.uk/ullmann/tutorials/wookie/widgetUploadWookie.htm
  [5]: http://marxjohnson.github.com/MultiXinha/
  [6]: https://github.com/scottbw/pacman
  [7]: http://arc.tees.ac.uk/wider/index.php?p=widgets&from=0&number=10
  [8]: http://svn.apache.org/repos/asf/wookie/trunk/tutorials/tutorial_2_basic_interactions.odp
  [9]: http://wookie.apache.org/docs/api.html