W3C

Widgets 1.0: APIs and Events

W3C Working Draft 23 April 2009

This Version:
http://www.w3.org/TR/2009/WD-widgets-apis-20090423/
Latest Version:
http://www.w3.org/TR/widgets-apis/
Previous Version:
http://www.w3.org/TR/2009/WD-widgets-apis-20090205/
Latest Editor's draft:
http://dev.w3.org/2006/waf/widgets-api/
Version history:
Twitter messages (non-editorial changes only): http://twitter.com/widgetspecs (RSS)
Editors:
Arve Bersvendsen, Opera Software ASA
Marcos Caceres, Opera Software ASA

Abstract

This specification defines a set of APIs and events for the Widgets 1.0 family of specifications that enable baseline functionality for widgets. The APIs and Events defined by this specification defines, amongst other things, the means to:

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 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.

This document is produced by the Web Applications WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. 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.

You can find the latest Editor's Draft of this document in the W3C's CVS repository, which is updated on a very regular basis. Please send comments to public-webapps@w3.org, the W3C's public email list for issues related to Web Application Formats. Archives of the list are available. A detailed list of changes from the previous version is also available from the W3C's CVS server.

Interested parties should be aware that this document is not stable and should not be implemented. Interested parties who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. If you are interested in implementing this document before it eventually reaches the Candidate Recommendation stage, join the aforementioned mailing lists and take part in the discussions.

User agents that wish to extend this specification in any way are encouraged to discuss their extensions on a public forum, such as public-webapps so their extensions can be considered for standardization.

Table of Contents

  1. 1 Introduction
    1. 1.1 The Widget Family of Specifications
  2. 2 Conformance
  3. 3 User Agents
    1. 3.1 Support of Other Specifications
  4. 4 Definitions
  5. 5 The Widget Interface
    1. 5.1 The viewMode Attribute
    2. 5.2 The locale Attribute
    3. 5.3 The identifier Attribute
    4. 5.4 The authorName Attribute
    5. 5.5 The authorEmail Attribute
    6. 5.6 The authorHref Attribute
    7. 5.7 The name Attribute
    8. 5.8 The description Attribute
    9. 5.9 The version Attribute
    10. 5.10 The width Attribute
    11. 5.11 The height Attribute
    12. 5.12 The preferences attribute
    13. 5.13 The onmodechange Callback
    14. 5.14 The hasFeature() Method
    15. 5.15 The openURL() Method
    16. 5.16 The getAttention() Method
    17. 5.17 The showNotification() Method
  6. Acknowledgements
  7. Normative References
  8. Informative References

1 Introduction

This specification defines a set of application programming interfaces (APIs) and events for widgets that enable baseline functionality for widgets.

This specification defines defines APIs using [WebIDL].

1.1 The Widget Family of Specifications

This section is non-normative.

Widgets are full-fledged client-side applications that are authored using Web standards. They are typically downloaded and installed on a client machine or device where they typically run as stand-alone applications outside of a Web browser. Examples range from simple clocks, stock tickers, news casters, games and weather forecasters, to complex applications that pull data from multiple sources to be "mashed-up" and presented to a user in some interesting and useful way (see [Widgets-Landscape] for more information). The runtime environment in which a widget runs is referred to as a user agent.

This specification is part of the Widgets 1.0 family of specifications, which together standardize widgets as a whole. The Widgets 1.0: Packaging and Configuration [Widgets-Packaging] standardizes a Zip-based packaging format, an XML-based configuration document format and a series of steps that user agents follow when processing and verifying various aspects of widgets. The Widgets 1.0: Digital Signature [Widgets-DigSig] specification defines a means for widgets to be digitally signed using a custom profile of the XML-Signature Syntax and Processing Specification. The Widgets: 1.0: Automatic Updates [Widgets-Updates] specification defines a version control model that allows widgets to be kept up-to-date over [HTTP].

2 Conformance

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, should, should not, recommended, may and optional in this specification are to be interpreted as described in [RFC2119].

This specification describes the conformance criteria for user agents (relevant to implementers).

There is only one class of product that can claim conformance to this specification: a user agent.

3 User Agents

A user agent is software that implements the application programming interfaces defined in this specification. A user agent must behave as described by this specification in order to claim conformance.

Note: The user agent described in this specification does not denote a "user agent" at large. That is, a user agent that implements all the specifications, and dependencies, defined in the Widgets 1.0: Family of Specifications. The user agent described is this specification is only concerned with the behavior of programming interfaces and what causes events to be fired.

3.1 Support of Other Specifications

A user agent supports a specification if it attempts to implement that specification.

A user agent MUST support:

4 Definitions

The following definitions are used globally throughout this specification. Please note that other terms are given throughout this document and defined where they are used.

Widget context
A environment in which a Widget interface is presented to the user. When a user agent instantiates a start file, as defined by [Widgets-Packaging], the content of the start file is said to be running in a widget context.
Widget view mode
A distinct means of presenting a widget in a user agent. Such modes may include rendering the widget without any user interface constructs (default), fullscreen, or as any other application on the operating system on which the user agent runs, with native user interface controls for maximizing, minimizing, restoring and closing windows (application).
Valid URI
A valid URI is one that matches the URI token of [URI] or the IRI token of [RFC3987].

5 The Widget Interface

The Widget interface primarily provides access to metadata derived from processing the widget's configuration document. It also provides an interface for persistently storing, modifying, and deleting preferences.

A conformant user agent MUST implement the Widget interface as a widget attribute in the global object context.

Within the widget context, the Widget interface provides the following attributes and methods.

interface Widget {
  readonly attribute DOMString viewMode;
  readonly attribute DOMString locale;
  readonly attribute DOMString identifier;
  readonly attribute DOMString authorName;
  readonly attribute DOMString authorEmail;
  readonly attribute DOMString authorHref;
  readonly attribute DOMString name;
  readonly attribute DOMString description;
  readonly attribute DOMString version;
  readonly attribute unsigned short width;
  readonly attribute unsigned short height;
           attribute Storage        preferences;
           attribute Function       onmodechange;

  boolean hasFeature(in DOMString url);

  void openURL(DOMString url);

  void getAttention();

  void showNotification(in DOMString title, in DOMString message, in Function onclick);

}

5.1 The viewMode Attribute

The viewMode attribute contains a representation of one valid window mode, as defined in [Widgets-Packaging]. Upon instantiation, this attribute MUST be set to the value of widget window mode, which is derived from the configuration defaults from processing the configuration document in the [Widgets-Packaging] specification (Step 8).

5.2 The locale Attribute

The locale attribute represents the current locale for the running widget. Upon instantiation, this attribute MUST be set to the value of widget locale, which is derived from the configuration defaults from processing the configuration document in the [Widgets-Packaging] specification (Step 8).

5.3 The identifier Attribute

The identifier attribute represents the value of widget element's id attribute, if one was used in the configuration document. Upon instantiation, this attribute MUST be set to the value of widget id, which is derived from the configuration defaults from processing the configuration document in the [Widgets-Packaging] specification (Step 8).

5.4 The authorName Attribute

The authorName attribute represents the name of the person who authored the widget. Upon instantiation, this attribute MUST be set to the value of author name, which is derived from the configuration defaults from processing the configuration document in the [Widgets-Packaging] specification (Step 8).

5.5 The authorEmail Attribute

The authorEmail attribute represents an e-mail address associated with the author of a widget. Upon instantiation, this attribute MUST be set to the value of author email, which is derived from the configuration defaults from processing the configuration document in the [Widgets-Packaging] specification (Step 8).

5.6 The authorHref Attribute

The authorHref attribute represents a URI associated with the author of a widget. Upon instantiation, this attribute MUST be set to the value of author href, which is derived from the configuration defaults from processing the configuration document in the [Widgets-Packaging] specification (Step 8).

5.7 The name Attribute

The name attribute represents the name of the widget. Upon instantiation, this attribute MUST be set to the value of widget name, which is derived from the configuration defaults from processing the configuration document in the [Widgets-Packaging] specification (Step 8).

5.8 The description Attribute

The description represents the description given to the widget. Upon instantiation, this attribute MUST be set to the value of widget description, which is derived from the configuration defaults from processing the configuration document in the [Widgets-Packaging] specification (Step 8).

5.9 The version Attribute

The version attribute represents the version tag assigned to the widget. Upon instantiation, this attribute MUST be set to the value of widget version, which is derived from the configuration defaults from processing the configuration document in the [Widgets-Packaging] specification (Step 8).

5.10 The width Attribute

The width attribute MUST return the width of the widget's view port, in [CSS21] pixels.

5.11 The height Attribute

The height attribute MUST return the height of the widget's view port, in [CSS21] pixels.

5.12 The preferences attribute

The purpose of the preferences attribute is to store key-value preference data for the widget.

The preferences attribute must be of type Storage. The Storage interface is defined in the [WebStorage] specification.

On the first invocation of the widget, the preferences instance MUST be populated with preferences items from the widget's configuration document as specified in [Widgets].

The values stored in preferences SHOULD be preserved across instantiations of the widget.

5.13 The onmodechange Callback

The onmodechange attribute MAY hold a a function that is to be executed when a widget's view mode changes, meaning that the value of the currentMode attribute changes. Its initial value is null.

When a valid function is assigned to the attribute, a user agent MUST invoke this function whenever the view mode has changed, without passing any arguments to the function. A conformant implementation MUST further first set the value of the currentMode attribute to the new view mode prior to invoking the function.

5.14 The hasFeature() Method

The hasFeature() method accepts a valid DOMString as argument. This argument represents a URI reference identifying an API. If this API is recognized and available to the widget, the user agent MUST return true. In all other cases, for example if the API not being recognized, or access has been prohibited, the user agent MUST return false.

ISSUE: do we need to do some kind of URI normalization to check for equivalency?

5.15 The openURL() Method

The openURL(url) method takes a valid URI as an argument. When invoked, the url should be opened with the appropriate protocol handler for the given URI. If there is no such protocol handler or url is not a valid URI, then the user agent must act as if the method was not invoked.

5.16 The getAttention() Method

When the getAttention() method is invoked, a user agent MAY use a system-specific method of alerting the user that the widget requires attention. The user agent SHOULD NOT focus the widget.

This specification does not impose requirements for the user interface for such a mechanism, but examples may include flashing a task-bar entry, highlighting or animating the application icon for the widget.

5.17 The showNotification() Method

The showNotification() method accepts three arguments:

The first argument is a DOMString containing an informative title for the message (the second argument) to be displayed to the end-user.

The second argument is a DOMString containing an informative message to be displayed to the end-user.

The third argument is an optional function that is to be invoked if the user acknowledges the notification message, for instance by clicking on it.

Acknowledgements

This section will be completed as the document matures.

Normative References

This section will be completed as the document matures.

[CSS21]
Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification, Bert Bos, Ian Hickson, Tantek Çelik, Håkon Wium Lie. W3C Candidate Recommendation 19 July 2007.
[DOM3Core]
Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors. World Wide Web Consortium, April 2004.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, RFC2119, S. Bradner. March 1997.
[RFC3987]
Internationalized Resource Identifiers (IRIs). RFC3987, M. Duerst, M. Suignard. January 2005.
[URI]
Uniform Resource Identifier (URI): Generic Syntax.RFC 3986, T. Berners-Lee, R. Fielding and L. Masinter. January 2005.
[Widgets-Packaging]
Widgets 1.0: Packaging and Configuration. M. Caceres, Ed. W3C Working Draft 31 January 2009. (Work in progress)
[WebIDL]
Web IDL. Cameron McCormack. W3C Working Draft, 19 December 2008.
[WebStorage]
Web Storage. I. Hickson. W3C Editor's Draft. (Unpublished Work in Progress).

Informative References

This section will be completed as the document matures.

[Widgets-Landscape]
Widgets 1.0: The Widget Landscape (Q1 2008). M. Caceres. W3C Working Draft. 14 April 2008.
[Widgets-DigSig]
Widgets 1.0: Digital Signature. M. Caceres, Ed. W3C, W3C Working Draft 14 April 2008.
[HTTP]
Hypertext Transfer Protocol -- HTTP/1.1. RFC 2616, R. Fielding, et al. June 1999.