W3C widget configuration and packaging

Learn about the candidate specification for W3C widgets

The World Wide Web Consortium (W3C) "Widget Packaging and Configuration" specification is currently in candidate recommendation status. The widgets, which can be used to provide rich Web application elements for mobile devices and Web sites, are an emerging technology to be used with Hypertext Markup Language (HTML). They are packaged as compressed (.zip) files and can be deployed in HTML files with a Multipurpose Internet Mail Extensions (MIME) type of application or widget. This article dives deeper into the specification, exploring how Web application developers can use it and what the benefits are.


Nathan A. Good, Senior Consultant and Freelance Developer, Enterprise Frameworks

Nathan GoodNathan A. Good lives in the Twin Cities area of Minnesota. Professionally, he does software development, software architecture, and systems administration. When he's not writing software, he enjoys building PCs and servers, reading about and working with new technologies, and trying to get his friends to make the move to open source software. He's written and co-written many books and articles, including Professional Red Hat Enterprise Linux 3, Regular Expression Recipes: A Problem-Solution Approach, and Foundations of PEAR: Rapid PHP Development.

16 March 2010

Also available in Chinese Russian Japanese Portuguese

W3C widgets overview

The W3C "Widget Packaging and Configuration" specification is an emerging specification for configuring, packaging, and deploying widgets. W3C widgets are components that are made up of HTML, cascading style sheets (CSS), JavaScript files, and other resources such as images. You can use widgets in devices for small applications such as calendars, weather reports, chats, and more.

One advantage of using widgets rather than normal Web applications is that they can be downloaded once and used many times after that, just like non-Web applications that are installed on a device. This allows users to save on bandwidth because the only data they transfer is the data used by the widget and not the widget files themselves.

Widgets often provide a rich user experience, such as interactive calendars and even games. You can use widgets in mobile devices, where the advantage of downloading the widget once and using it over and over can save on data transfer costs.

As of January 2010, the W3C "Widget Packaging and Configuration" specification (see Resources for a link to the full specification) is in candidate recommendation state. This means that the W3C believes the specification is in a stable state and encourages developers to create implementations of the specification.

The goal of the W3C widget specification is to propose a standard method for building and packaging widgets. There are currently many different vendors that have widgets (see Resources), and almost all of them implement their own proprietary application program interface (API) and packaging format.

This article introduces the W3C Packaging and Configuration specification, showing you how you can package HTML, CSS, and JavaScript files into a widget that can be deployed to a device that implements the W3C widget specification. Because this is an emerging specification, the implementation choices for devices that render the widgets are limited. If you want to see the widgets in action, you need to download some extra applications if you don't already have them installed.

To view the W3C widget package in action, you need:

  • Software that implements the W3C widget specification. This article uses Apache Wookie, an Apache Incubator project that is aimed at serving W3C widget content and allowing users to deploy W3C widgets.
  • A utility to create the widget's compressed file archive.
  • The Subversion (SVN) client if you want to download and install Apache Wookie.

Related technology: Other widgets and servers

There are many different versions of widgets and gadgets currently on the market, so it's sometimes difficult to understand how the different technologies compare. The fragmentation of the widget technologies can make creating reusable rich user Web components difficult.

You say widget, I say gadget

For the purposes of this article, the terms widget and gadget mean the same thing—small components that can be installed and run locally as if they're applications. This article refers to the widget or gadget in a manner consistent with the item's vendor. For example, W3C calls them widgets, and Google calls them gadgets.

In addition to Microsoft® Windows® Vista gadgets and Apple® widgets, similar technologies include Google Wave gadgets, OpenSocial, and OpenAjax. These technologies have their own APIs and specifications (see Resources).

Google Wave gadgets

Google Wave gadgets are similar in concept to W3C widgets but are targeted for use in Google's Wave Web application. By contrast, W3C widgets are published as a specification by the W3C and are intended to be non-proprietary and used by different vendors.

Google Wave is a Web application that is currently in limited preview for developers and early adopters who want to learn more about the technology. Google Wave is primarily a collaboration tool, providing different abilities in the form of Google Wave gadgets to users. Developers can build gadgets that provide special abilities for Wave users to include in each "wave."


OpenSocial is an API that allows you to build gadgets that work well in social networking Web applications. The OpenSocial 1.0 specification is currently under review, but versions 0.9 and 0.8.1 are used in containers (Web applications that use the gadgets) such as iGoogle, MySpace, Yahoo, and LinkedIn.

OpenSocial gadgets are based on the Google gadgets framework. The OpenSocial framework includes prewritten JavaScript APIs that you can use to work with people, activities, and persistence.

The adoption for OpenSocial makes it a compelling alternative for building gadgets.


OpenAjax is "an organization of leading vendors, open source projects, and companies using Asynchronous JavaScript + XML (Ajax) that are dedicated to the successful adoption of open and interoperable Ajax-based Web technologies" (see Resources).

The OpenAjax Hub provides publication and subscribing (pub/sub) technologies that are used in OpenSocial gadgets.

Because widgets built according to the W3C packaging and configuration specifications can use Ajax, OpenAjax can be a good technology to use for building widgets that can have improved interoperability. You can create widgets that use OpenAjax but conform to the W3C widget specification.

Apache Wookie

Apache Wookie is an Apache Software Foundation incubator project that is capable of serving both Google Wave gadgets and W3C widget packages. Apache Wookie is a server application that you can download and install as a Web application or run as a stand-alone server.

Getting the Apache Wookie source is also a good way to view samples of W3C widget source code.

There are no prebuilt Apache Wookie binary distributions available on the official site (see Resources), so to download and run Apache Wookie you need to have SVN installed. To download Apache Wookie, simply use the commands shown in Listing 1.

Listing 1. Downloading Apache Wookie
$ svn co http://svn.apache.org/repos/asf/incubator/wookie/trunk

After downloading Apache Wookie, you can run it as a stand-alone server by typing the commands shown in Listing 2.

Listing 2. Running Apache Wookie in stand-alone mode
$ ant run

The ant command starts the Apache Wookie server in stand-alone mode. After you start the server, you can access the widgets at http://localhost:8080/wookie/.

The widget configuration

To start building a widget, first create an empty directory with the widget name, such as myWidget. (For operating systems that allow dots in file names, use myWidget.wgt.) You will put the new widget files in this directory. If you want to create and test new HTML, CSS, and JavaScript files, create this directory in your Web server's document root so you can see how the HTML file works in your browser before packaging the widget.

Each widget package must have a configuration file called config.xml (case-sensitive) directly inside the empty directory that you just created, which is the base directory of the package. The configuration file contains vital information about the widget, such as the name, author, description, license, and more.

An example configuration file is shown in Listing 3.

Listing 3. A sample config.xml file
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
version="0.1" width="300" height="200">
  <description>A very basic widget that says, "Hello"</description>
  <content src="index.html" />
  <icon src="images/icon.png" />
  <access network="false" />
  <author>Nathan A. Good</author>
  <license>This is my license</license>

The XML file should be UTF-8 encoded, as shown in the example.

The widget parent element has attributes that specify information about the widget, as shown in Table 1.

Table 1. Attributes for the widget parent element
Attribute nameDescription
idThe unique URI that is an identifier for the widget
versionThe widget's version
width, heightThe width and height of the widget, respectively, in pixels
viewmodesThe view mode for the widget (see Resources)

The XML elements that are used in the configuration are shown in Table 2.

Table 2. Widget configuration elements
Element nameDescription
nameThe short name of the widget is given in the short attribute, and the long name is given in the text of the XML element
descriptionThe description of the widget
authorInformation about the widget's author
licenseThe license for the widget
iconThe relative path of an icon file

With a sample configuration file created, you are now ready to create the start file.

The start file

Aside from the config.xml configuration file, the only other file that is required for a valid W3C widget package is at least one start file. If the start file is not specified, the default file is the file that has a name starting with index—usually with an .html, .htm, or .xhtml extension. Other extensions are allowed for different types of widgets, but this article focuses on the standard HTML example.

An example file is shown in Listing 4.

Listing 4. A sample start file
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
<html xmlns="http://www.w3.org/1999/xhtml">
  <meta http-equiv="pragma" content="no-cache" />
  <meta http-equiv="Content-Type" content=
  "text/html; charset=us-ascii" />
  <link rel="stylesheet" href="style/common.css" type="text/css" />
<h1>Hello World...</h1>

The HTML file shown in Listing 4 is like any other well-formed HTML file that can be displayed in a browser. This does allow widgets to be easily designed—you can create them as normal HTML pages. This HTML start file is the file used to render the widget.

Because the widgets are simply HTML that is rendered by a browser, they can include JavaScript files. The use of JavaScript functions allows the widgets to have rich, dynamic content. You can use Ajax to display data dynamically in widgets to users. (See Resources for information about Ajax.)

JavaScript files referenced in the widget's HTML start file should be included in the packaged widget archive.

The sample HTML file for this widget also uses CSS for styling. Similar to the JavaScript files, the CSS files should be included in the compressed file archive that is deployed as a packaged widget.

The W3C specification provides guidelines for localization (l10n). The locale support is folder-based, so you create a directory called locales inside your widget's directory. Inside the locales folder, you can create folders with the locale names (for example, en, fr, de) that include different resources that are appropriate for the locales.

Packaging the widget

Widgets are packaged in standard compressed archive files that have the .wgt extension. You should create the compressed file archive for a widget package using the DEFLATE method. The compressed file archive must include the configuration file, the start file, and any resource used by the files, such as JavaScript files, CSS, and images.

To create a widget package, use a command-line compressed file utility to create the compressed file archive as shown in Listing 5.

Listing 5. Creating the compressed file archive
$ cd myWidget
$ zip myWidget.wgt *

You can also use a graphical user interface (GUI) method for creating a compressed file archive of the widget files. After you create the archive, change the extension from .zip to .wgt.

You can organize widget packages in directories to make it easier to work with the package. For instance, consider Figure 1, which displays folders such as images, style, and scripts that you can use to organize the widget package.

Figure 1. The W3C widget package folder structure
A screen shot of the widget package folder structure. There are folders for images, legal, lib, scripts, and style, respectively.

When referencing the resources in the start file, use relative paths as though the files are deployed to a Web server. For instance, use style/common.css to refer to the common.css file in the style folder, even though they're both included in a compressed file archive as the widget package.

You can digitally sign the widget package files for security. See Resources for more information about the W3C specification for digitally signing widget packages.

Deploying the widget

Limited implementations

Because the W3C widget specification is emerging and there are so many different proprietary widget specifications, it is difficult to find an implementation for the W3C widget specification that is production quality. Apache Wookie is an example of a W3C widget specification that is in active development. Because it is in active development, it may be unstable. When I was running my tests, there were some updates to the code in SVN that caused Apache Wookie to break for a while, but they were resolved in later updates.

You can deploy the widget using Apache Wookie's Administrative menu. To access Apache Wookie's menu, make sure Wookie is running (type ant run on the command line) and type the location for Apache Wookie in your browser. By default, that location is http://localhost:8080/wookie. Click the Administrative menu link (see Figure 2).

Figure 2. The Administrative menu link
A screen shot of the Wookie menu, showing options for Main menu, Options, View Widget Gallery, and Administration menu.

You are prompted for a username and password. If you haven't changed them from the defaults, the username and password are both java.

Click Add new widget as shown in Figure 3.

Figure 3. Adding a new widget
A screen shot of a widget menu, showing options to View existing widgets, Add new widget, Add new Google Gadget/OpenSocial app, and Remove widget from system.

Click Choose File and browse to your widget archive file. After you select the file, click Publish (see Figure 4).

Figure 4. Choosing the widget archive file
A screen shot of a window entitled 'Select a widget archive (zip) to uplaod.' Then a button to 'Choose file' and a 'Publish' and 'Clear' button underneath.

Apache Wookie then processes your widget archive. When it is finished processing the archive, you can see the widget in the list of widgets and in the widget gallery.

Alternatively, you can use Apache Wookie to deploy the widget without using the administrative utility. To do so, simply copy the widget package to the deployment directory configured in the build.properties file with the key widget.deploy.dir.

The specification for deploying and configuring W3C widgets includes recommendations for how implementations should handle widget archive files. When an implementation such as a browser downloads a package, it treats the widget package as a potential widget package. The browser verifies the integrity of the package, making sure that it is correctly built and that the configuration is complete. If the widget package conforms to the standard, it is treated as a valid widget package.

Viewing the sample

Apache Wookie allows you to view widgets in any browser, so you don't need to search for a browser that implements the W3C specification (similar to the Opera browser's implementation of widgets). Ideally, browsers will implement the W3C widget specification so users can take advantage of the benefits of downloading their widgets once and using them over and over.

To view your new widget, make sure Apache Wookie is running and access it from your browser. Click View Widget Gallery and you will see the widget that you deployed listed in the gallery (see Figure 5).

Figure 5. Viewing the widget gallery
A screen shot of the Wookie gallery, showing the current widgets available

Click Demo to see your widget in action.

You can also create a test file that has an iframe element that includes your new widget. Create a simple HTML file as shown in Listing 6.

Listing 6. A simple HTML file to launch the widget
<head><title>Widget sample</title>
<iframe src=
TuJip8BQ9i6ZXRH9193FT%2F7Ijjz0o1vdR91ofzcFA%3D%3D" width="500" height="400">

You will see your widget inside the Web page. I took the URL of the widget from the result of the Instantiate a widget action in Wookie's main menu.

You can view other sample packages that include more complex JavaScript files, CSS, and images in the source that comes with Apache Wookie. After downloading the Apache Wookie source code, look in the widgets subfolder to find the source code for other widgets.


The W3C "Widget Packaging and Configuration" specification is an emerging W3C specification for building widgets that can offer rich user interfaces to users and save on bandwidth.

The W3C widget specification uses open, non-proprietary standards such as HTML, CSS, JavaScript code, and compressed file archive. Because the specification is emerging, there are few implementations for it, but it is a promising specification that could allow standardization of widgets.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Web development on developerWorks

Zone=Web development, Open source
ArticleTitle=W3C widget configuration and packaging