W3C

Widgets 1.0

W3C Working Draft 9 November 2006

This Version:
http://www.w3.org/TR/2006/WD-widgets-20061109/
Latest Version:
http://www.w3.org/TR/widgets/
Editors:
Anne van Kesteren (Opera Software ASA) <annevk@opera.com>
Marcos Caceres, (Queensland University of Technology) <m.caceres@qut.edu.au>

Copyright © 2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This document describes widgets. It covers the packaging format, the manifest file config.xml, and scripting interfaces for working with widgets.

The type of widgets that are addressed by this document are usually small client-side applications for displaying and updating remote data, packaged in a way to allow a single download and installation on a client machine. The widget may execute outside of the typical web browser interface. Examples include clocks, stock tickers, news casters, games and weather forecasters. Some existing industry solutions go by the names "widgets", "gadgets" or "modules".

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the First Public Working Draft of the Widgets 1.0 specification. This document is produced by the Web Application Formats Working Group, part of the Rich Web Clients Activity in the W3C Interaction Domain.

Web content and browser developers are encouraged to review this draft. Please send comments to public-appformats@w3.org, the W3C's public email list for issues related to Web Application Formats. Archives of the list are available.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

1. Introduction

Widgets are web applications which use the browser as an environment to run in, but which do not have the usual browser chrome. They are installed on a local client, and have several features that are not available to regular web applications, such as a more explicit security model to allow them to perform a wider range of tasks easily, and a persistent information store apart from cookies.

This specification is not complete. Besides things that are obviously missing there may well be inconsistencies in writing and editorial choices.

They are installed by a user agent, for re-use. This specification does not define the storage method, nor limit the ways the user agent can find a widget (such as downloading, installing from a local file, having widgets pushed to a client, etc).

Eventually this document will attempt to address all requirements of the [WIDGET-REQ] document.

1.1. Conformance Requirements

As well as sections marked as non-normative, all diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, shall, shall not, should, should not, recommended, may and optional in this document shall be interpreted as described in [RFC2119].

Need to define classes of products.

2. Widget Packaging

2.1. File Format

Widgets are a bundled archive of files, as specified by the [ZIP] file format specification, with exception that the "Deflate64" compression method for the [ZIP] file format is not supported.

I think this last sentence means "conforming to level 2.0 zip". Need to check.

A future revision of this draft will address digital signing of widgets. Need to figure out how.

It has been suggested that the widget should have some means of preventing access to the content of it.

2.2. Widget Files

Every widget must contain the following two files:

config.xml

A manifest file containing information necessary to initialize the widget. This file always contains information about the widget's name and geometry, and may optionally contain more information about the widget:

index.html
The main document for the actual widget, and is displayed in a viewport whose main properties are established by the config.xml file. This HTML document can reference external content, including, but not limited to scripts, CSS files and images the same way regular web pages can.

Need to address other formats, such as SVG and XHTML, as well. Probably in a way by making this a whole lot more abstract, so that you can use any language you want.

2.3. Widget Folder Structure

Need to look into how ZIP actually handles folders and define some useful terminology around that.

The config.xml and index.html should be at the root of the .zip file, with any associated resources, such as scripts and images, in the same directory or subdirectories.

In some user agents the config.xml and index.html files may be placed in a directory inside the zip file, with all the widget's files and folders located inside this subfolder. This folder should bear the same name as the compressed zip file. User agents may not support this structure, so authors should not use it.

When a widget is run a virtual root path for a file system is established based on the location of the config.xml, where this root path is in the same folder where config.xml exists.

2.4. Content-Type

When widgets are served from web servers, they must be served with the content-type application/widget.

Need to register this.

2.5. File Extension

When not served over HTTP widgets should have the file extension .widget

3. Widget Configuration File: config.xml

This is an XML file, do we need a namespace? Advantages either way: input solicited.

Need to address licensing and copyright information. Also per file or just for the whole widget?

Some necessary information to run a widget is stored in a file named config.xml. This file contains information about the widget's size which is neccesary to establish the initial view for the widget file. The config.xml file is an XML document [XML].

A minimal config.xml looks like the following, giving the widget a name, and an initial viewport the size of 300×300 pixels: 

<widget>
  <widgetname>
    Hello World!
  </widgetname>
  <width>
    300
  </width>
  <height>
    300
  </height>
</widget>

3.1. White Space

Element content presented to the user must be styled as if the value normal for the white-space property in [CSS21] is applied.

3.2. The widget Element

Contexts in which this element may be used:
As the root element of a document.
Content model:
In any order, exactly one of each widgetname, width and height element and optionally one of each author, description, icon, security and id element.

The widget element is the root element of the config.xml file and must be present.

3.3. The widgetname Element

Contexts in which this element may be used:
In a widget element.
Content model:
Text.

The widgetname element must be present in config.xml as a child of the widget element. It should contain a string whose purpose is to provide a human-readable title for the widget that can be used for example in application menus and similar contexts.

3.4. The width and height Elements

The width and height elements must be present in config.xml as children of the widget element. After stripping of any leading/trailing whitespace the value of this element must be interpretable as a string representation of an integer, containing only the characters [0-9].

These integers give the initial width and height of the viewport avilable to the widget, measured in CSS pixels, as per section 4.3.2 of [CSS21].

This should handle percentages or perhaps defer the whole thing to CSS? CSS should probably remain optional... Need default values as well (for when the elements are omitted). Perhaps make it clear that these give the initial height and width as you can use scripting to change that.

3.5. The author Element

Contexts in which this element may be used:
In the widget element.
Content model:
In any order, optionally one of each name, organization, email and link elements

The author element is an optional element of the widget element. If present, the purpose of the element is to provide information about the widget's author.

3.6. The name Element

Contexts in which this element may be used:
In the author element.
Content model:
Text.

If the author element is present in the document, this element should be present as well. If present, this element must be a child of the author element and its value must be a string that contains a human-readable representation of the widget author's name.

3.7. The organization Element

Contexts in which this element may be used:
In the author element.
Content model:
Text.

If this element is used present, it must be a child of the author element and its value should be a string that contains a human-readable name for an organization representing or represented by the widget author.

3.8. The email Element

Contexts in which this element may be used:
In the author element.
Content model:
Valid e-mail address.

When present, this element must contain a string, whose value should be a valid e-mail adress as specified by [RFC2822]. This e-mail address should be a live e-mail address widget users can use to contact the widget author.

Contexts in which this element may be used:
In the author element.
Content model:
IRI.

If the author element is present, the link element should be present as well and if it is it must be a child element of the author element and contain a string whose value is a syntactically valid IRI as specified by [RFC3987]. User agents should make this IRI available as a link the user can follow to find out more about the author.

3.10. The description Element

Contexts in which this element may be used:
In the widget element.
Content model:
Text.

If present, this element must be a child of the widget element and should contain a string that serves as a human-readable short plain-text description of the widget.

3.11. The icon Element

Contexts in which this element may be used:
In the widget element.
Content model:
IRI.

The icon element should be present as a child of the widget element. The purpose of this element is to provide a pointer to an icon file contained within the widget archive that the underlying operating system and widget player can display to the end user as appropriate. This may include as an icon in a toolbar, widget management interface or siimilar.

The element must contain a string that is a relative reference in accordance with [RFC3987], with the root path being the same as the location of the config.xml file.

When present, the IRI should resolve, and should reference an image, in either of the following formats: [PNG] or [GIF]. User agents may recognize other formats.

3.12. The id Element

The plan is for this element to define a universally unique identifier for the widget. Together with an element that defines a timestamp, like atom:updated, this creates a simple versioning mechanism.

Perhaps rename id to something else. Suggestions welcome!

3.13. The security Element

Specific details of this element are to be determined. This element might address things like:

4. Widget Scripting Interfaces

4.1. The Widget Object

The purpose of the widget object is to expose functionality specific to widgets that either should not or must not be available to scripts running on regular web pages. 

interface Widget {
  void       openURL(DOMString url);
  DOMString  preferenceForKey(DOMString key);
  void       setPreferenceForKey(DOMString value, DOMString key);
}
openURL(url), method

The openURL() method on the widget object takes a String as an argument. as defined by [RFC3987]. When this method is called with a valid URL as defined by [RFC3987], the URL should be opened in the system browser on the system on which the widget runs.

Note that restrictions to what URLs can be opened using openURL, as defined in the security section of this specification. Specifically this applies:

preferenceForKey(), method

The preferenceForKey() method takes a String argument, key. When called, this method shall return a string that has previously been stored with the setPreferenceForKey method, or undefined if the key key does not exist.

setPreferenceForKey(), method

The setPreferenceForKey() method takes two String arguments, preference and key. When called, this method shall store the string in the preference argument with the key named in the key argument for later retrieval using the preferenceForKey() method. If the setPreferenceForKey() method is called with the value null in the preference argument, the key identified in the key argument shall be deleted.

4.2. Widget Geometry

This should probably be defined in The Window Object specification.

A widget's initial dimensions are controlled by the width and height elements in the config.xml file. In addition to this, a widget can be resized or moved by scripting. If you change these settings for a widget, the settings are volatile. User agents may ignore changes when closing and reopening widgets. To make the widget a different size from the install-time default, store the widget size using setPreferenceForKey() and resize it on opening. 

interface Window {
  void resizeTo( in int w, in int h );
  void resizeBy( in int delta_w, in int delta_h );
  void moveTo( in int x, in int y );
  void moveBy( in int delta_x , in int delta_y );
};
resizeTo(w, h), method

This method takes two positive integers as arguments: a width w and height h. These sizes are the desired dimensions of the widgets in pixels, and correspond to the width height elements in a widget's configuration file. The method sets the window.outerWidth and window.outerHeight properties. Example:

// Resize the widget to 400x300 px
window.resizeTo( 400, 300 );

Need to define error handling and outerWidth and outerHeight propably. Well again, The Window Object specification should...

resizeBy(), method

This method takes two integers as arguments: A delta_w that is the desired change in width, measured in pixels, and a delta_h that is the desired change in height, again measured in pixels. The width and height of the widget is then recalculated to be equivalent to the following pseudocode:

window.resizeTo( window.outerWidth + delta_x, window.outerHeight + delta_y );

In all cases of window resizing, the resizing happens from the lower-right corner of the widget window, while the upper-left corner remains static.

// Grow the widget by 100px horizontally
window.resizeBy( 100, 0 );
moveTo(), method

The moveTo method takes two integers as arguments: An x that is the desired x coordinate for the upper-left corner of the widget, and an y that is the desired y coordinate for the upper-left corner of the widget, with both values mentioned in pixels.

// Move the widget to the upper-left corner of the screen
window.moveTo( 0, 0 )
moveBy(), method

The resizeBy method takes two integers as arguments: A delta_x that is the desired change in x position, measured in pixels, and a delta_y that is the desired change in y position, again measured in pixels. Both values can be negative. Example:

// Move the 50px left and 50px down
window.moveBy( -50, 50 )

5. Widget Autodiscovery

This section only applies to HTML user agents.

Widget autodiscovery enables a user agent to identify and install a widget that is associated with a web page. When a web page points to a related widget user agents should expose the presence of the widget to the user and allows the user to install the widget.

Widget autodiscovery uses the HTML link element, as defined in section 12.3. of [HTML4], with certain required attributes and values as defined below. As with other link elements, an autodiscovery element may appear in the head element of an HTML or XHTML document, but it must not appear inside the body element. An example in HTML would look like this: 

<link
 type="application/widget"
 rel="alternate"
 href="http://widgets.example.org/SimAquarium"
 title="An Example Widget">

A document may contain multiple autodiscovery elements. A User Agent should present an installation option for all autodiscovered widgets to the user, listed in the order of appearance in the source code.

Only when the following conditions are met a user agent should expose the available widget(s) for download:

We should probably have some author requirements as well: title attribute should have a meaningfull value. If multiple link elements are provided the title attributes should be clear. Not just "Widget 1", "Widget 2", etc. The href attribute should point to a location that actually has a widget served with the application/widget media type, etc.

6. Security Model

User agents may block access to resources according to internal security models. User agents should consider the following things when implementing a security model:

  1. Widgets do not have access to content residing on a user's file system, using the file: protocol
  2. Widgets can access content over http, regardless of the presence of a security section in config.xml. Widgets may not use any other protocol without prior declaration. Widgets may access content over https, ftp or other supported protocols (except file as previously noted), but only if the widget has declared this in the security section of config.xml
  3. Widgets may not contact non-default ports, except when pre-declared in config.xml. Further, widgets may not contact non-default ports equal to or below 1023.
  4. A widget that has contacted an intranet must not be able to contact addresses not defined as being intranets. Likewise, widgets interacting with hosts outside the IPv4 ranges specified below must not be allowed to interact with these IP ranges.

An intranet is defined based on the resolved IPv4 address of a host name. The following IPv4 ranges are defined as intranets:

All other IP ranges than these are defined as Internet addresses.

This section needs more details, including requirements on how to implement the security model, given that we keep signing and the security element.

Acknowledgements

The editors would like to thank the following people for their contributions to this specification:

Special thanks go to Arve Bersvendsen and Charles McCathieNevile who wrote the initial version of this document, "Opera Widgets 1.0."

The widget object was based on Apple's Dashboard [Dashboard] and Widget Autodiscovery is based on Atom Autodiscovery [AtomAutodiscovery].

References

[AtomAutodiscovery]
Atom Autodiscovery (draft), M. Pilgrim, P. Ringnalda. ATOMPUB Working Group, May 2005.
[CSS21]
Cascading Style Sheets, level 2 revision 1; CSS 2.1 Specification. Bert Bos, Ian Hickson, Tantek Çelik, Håkon Wium Lie. W3C, April 2006.
[Dashboard]
Dashboard Reference. Apple Computer, Inc, May 2006.
[DBI]
The Apple dashboard interfaces. Apple Comuter Inc, May 2006.
[HTML4]
HTML 4.01 Specification, Dave Raggett, Arnaud Le Hors, Ian Jacobs. W3C, December 1999.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.
[RFC3987]
Internationalized Resource Identifiers (IRIs) . M. Duerst, M. Suignard. IETF, January 2005.
[WIDGET-REQ]
Web Applications Packaging Format Requirements, M. Caceres, editor. W3C, August 2006.
[XHTML1]
XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition), S. Pemberton et al. W3C, January 2000.
[XML]
Extensible Markup Language (XML) 1.0 (Third Edition). Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, François Yergeau. W3C, February 2004.
[ZIP]
.ZIP File Format Specification. PKWare Inc., January 2006.