Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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 as part of the Widget interface by this specification provide, amongst other things, the means to:
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-appformats@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.
Widget Interface
viewMode Attributelocale Attributeid Attributeauthor AttributeauthorEmail AttributeauthorHref Attributename Attributedescription Attributeversion Attributewidth Attributeheight Attributepreferences attributeonmodechange CallbackopenURL() MethodgetAttention() MethodshowNotification() MethodThis specification defines a set of application programming interfaces (APIs) and events for widgets that enable baseline functionality such as exposing widget metadata and runtime information.
This specification defines defines APIs using [WebIDL].
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].
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.
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.
A user agent supports a specification if it implements that specification.
A user agent must support:
Storage interface, with the exclusion of the Database interface. 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 is presented to the user. When a user agent instantiates a start file, the content of the
start file is said to be running in a widget context.Widget InterfaceThe 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 execution context [Widgets-Access], the Widget interface provides the following attributes and methods.
interface Widget {
readonly attribute DOMString viewMode;
readonly attribute DOMString locale;
readonly attribute DOMString id;
readonly attribute DOMString author;
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;
void openURL(in DOMString url);
void getAttention();
void showNotification(in DOMString title, in DOMString message, in Function onclick);
}
viewMode AttributeThe viewMode attribute contains a representation of one valid window mode, as defined in [Widgets-WM].
Editorial note: this is a computed value.
locale AttributeThe locale attribute represents the current locale for the start file. This attribute must be set to the value of user agent locales, which is derived from processing the configuration document in the [Widgets-Packaging] specification (Step 7).
id AttributeThe id attribute represents the value of widget element's id attribute, if one was used in the configuration document. This attribute must be set to the value of widget id, which is derived from processing the configuration document in the [Widgets-Packaging] specification (Step 7).
author AttributeThe author attribute represents people or an organization attributed with the creation of the widget. This attribute must be set to the value of author name, which is derived from processing the configuration document in the [Widgets-Packaging] specification (Step 7).
authorEmail AttributeThe authorEmail attribute represents an e-mail address associated with the author of a
widget. This attribute must be set to the value of author email, which is derived from processing the configuration document in the [Widgets-Packaging] specification (Step 7).
authorHref AttributeThe authorHref attribute represents a URI associated with the author of a
widget. This attribute must be set to the value of author href, which is derived from processing the configuration document in the [Widgets-Packaging] specification (Step 7).
name AttributeThe name attribute
represents the name of the widget. This attribute must be set to the value of widget name, which is derived from processing the configuration document in the [Widgets-Packaging] specification (Step 7).
description AttributeThe description represents the description given to the widget.
This attribute must be set to the value
of widget description, which is derived from processing the configuration document in the [Widgets-Packaging] specification (Step 7).
version AttributeThe version attribute represents the version element assigned to
the widget. This attribute must be
set to the value of widget version, which is derived from processing the configuration document in the [Widgets-Packaging] specification (Step 7).
width Attribute The width attribute must return the width of the widget's viewport, in [CSS21] pixels.
height AttributeThe height attribute must return the height of the widget's viewport, in [CSS21] pixels.
preferences attributeThe purpose of the preferences attribute is to store key-value
preference data for the widget.
The preferences attribute provides a Storage object for a widget. The Storage interface is defined in the [WebStorage] specification.
User agents must have a set of preference storage areas, one for each widget instance.
On the first instantiation after installation of the widget, the preferences instance must be populated with the objects held by widget preferences, which is derived from processing the configuration document in the [Widgets-Packaging] specification (Step 7).
The values stored in preferences SHOULD be preserved across instantiations of the widget.
If setItem() or removeItem() are invoked with a preference key whose value is defined as
read-only, then the user agent must throw a NO_MODIFICATION_ALLOWED_ERR exception.
onmodechange CallbackThe onmodechange attribute MAY holds a function that is to
be executed when a widget's view mode changes, meaning that the value of the viewMode 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 viewMode attribute to the
new view mode prior to invoking the function.
openURL() MethodThe openURL() method takes a valid URI as an argument (relative URI references must not be resolved). When invoked, the provided url should be opened with the appropriate handler for the given URI scheme. If there is no such scheme handler, or it is otherwise rejected by the user agent (e.g., because of security policy or user prompting), or url is not a valid URI, then the user agent must act as if the method had not been invoked. The user agent should however inform the user that the request to open the URL has failed.
getAttention() MethodWhen 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.
showNotification() MethodTHIS FEATURE IS AT RISK OF BEING REMOVED.
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.