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 by this specification defines, amongst other things, the means to:
feature
element have successfully loaded.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.
Widget
Interface
viewMode
Attributelocale
Attributeidentifier
AttributeauthorName
AttributeauthorEmail
AttributeauthorHref
Attributename
Attributedescription
Attributeversion
Attributewidth
Attributeheight
Attributepreferences
attributeonmodechange
CallbackhasFeature()
MethodopenURL()
MethodgetAttention()
MethodshowNotification()
MethodThis 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].
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 attempts to implement 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
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
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 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);
}
viewMode
AttributeThe 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).
locale
AttributeThe 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).
identifier
AttributeThe 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).
authorName
AttributeThe 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).
authorEmail
AttributeThe 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).
authorHref
AttributeThe 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).
name
AttributeThe 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).
description
AttributeThe 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).
version
AttributeThe 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).
width
Attribute
The width
attribute MUST return the width of the widget's view port, in [CSS21] pixels.
height
AttributeThe height
attribute MUST return the height of the widget's view port, in [CSS21] pixels.
preferences
attributeThe 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.
onmodechange
CallbackThe 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.
hasFeature()
MethodThe 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?
openURL()
MethodThe 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.
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()
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.
This section will be completed as the document matures.
This section will be completed as the document matures.
This section will be completed as the document matures.