This specification defines an application programming interface (API)
for widgets that provides, amongst other things, functionality for
accessing a widget's metadata and persistently storing data.
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 17 November 2009 Last Call Working Draft version of the
"Widgets 1.0: The widget Interface" specification.
The Last Call period ends on 8 December 2009. The requirements, which are
listed in the specification, were addressed and specified through
extensive research, and via consultation with W3C members and the public
via the Working Group's mailing lists (WAF
archive, WebApps
archive). The purpose of this Last Call is to give external interested
parties a final opportunity to publicly comment on how the API should work
within widgets before the Working Group issues a call for implementations.
The Working Group's goal is to make sure that vendor's requirements for an
API for widgets have been effectively addressed and
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.
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.
Handle an IRI through an appropriate scheme handler.
Retrieve the name and value of preferences, which may have been
declared in a widget's configuration document.
1.1 The Widget Family of Specifications
This section is non-normative.
This specification is part of the Widgets 1.0 family of
specifications, which together standardize widgets as a whole. The
list of
specifications that make up the Widgets 1.0 Family of Specifications
can be found on the Working Group's wiki.
1.2
Design Goals and Requirements
This section is non-normative.
The design goals and requirements for this specification are documented
in the Widgets 1.0 Requirements [Widgets-Reqs] document.
This document addresses some of the requirements relating to
Application Programming Interfaces of the 30 April 2009 Working Draft
of the Widgets 1.0: Requirements Document:
All examples and notes in this specification are non-normative, as are
all sections explicitly marked as non-normative. Everything else in this
specification is normative.
The key words must, must not,
should, recommended, may and optional in the normative
parts of this specification are to be interpreted as described in [RFC2119].
Only user agents can claim conformance to this
specification. Conformance requirements phrased as algorithms or specific
steps can be implemented in any manner, so long as the end result is
equivalent to what would be achieved when following the specification.
Note: Implementers can
partially check their level of conformance to this specification by
successfully passing the test cases of the
[A&E-Test-Suite]. Passing all the tests in the test suite
does not imply conformance to this specification; It only implies that the
implementation conforms to aspects tested by the test suite.
3 Definitions
The following definitions are used throughout this specification. Please
note that the following list is not exhaustive; other terms are defined
throughout this specification.
Author script
Some code running within a widget
instance (e.g., some ECMAScript).
Configuration document
A configuration document is reserved file called
"config.xml" at the root of the widget package as
specified in the [Widgets-Packaging]
specification.
Feature
A runtime component (e.g. a device API, video decoder, etc.) that is
made available by the user agent to the widget instance as a direct result of an
author requesting its availability via a feature element in the widget's configuration document.
Getting
A DOM attribute is said to be getting when its value is being
retrieved (e.g. by an author script).
A persistently stored name-value pair that is associated with the
widget the first time the widget is initiated.
Start file
A file in the widget package to be loaded by the user agent when it
instantiates the widget, as specified in the [Widgets-Packaging] specification.
Supports
A user agent implements a
mentioned specification or conformance clause.
Valid IRI
A string that matches the IRI
token of the [IRI] specification.
Viewport
A CSS viewport. For a start
file rendered on continuous media, as
defined in the [CSS21] specification, a viewport is
the area on which the Document of the start file is rendered by the user agent. The
dimensions of a viewport excludes scrollbars, toolbars, and other user
interface "chrome".
Widget Instance
A browsing context that comes into
existence after initialization. The
concept of a browsing context is
defined in [HTML5]. Multiple widget instances can
be instantiated from a single widget package. Every widget instance is
universally unique, meaning it does not share any DOM attribute values
or storage areas with
any other widget instance.
4 User Agents
A user agent is a software implementation of
this specification that also supports the [Widgets-Packaging] specification.
Note: The user agent described in this specification does
not denote a "widget 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 in this specification is only
concerned with the behavior of programming interfaces. A user agent needs
to impose implementation-specific limits on otherwise unconstrained
inputs, e.g. to prevent denial of service attacks, to guard against
running out of memory, or to work around platform-specific limitations.
5 The Widget Interface
This specification uses [WebIDL] to define the
application programming interfaces.
A user agent
whose start file
implements [HTML5]‘s Window interface must
implement the Widget interface as the widget
attribute of the window object in the
manner defined by the WindowWidget interface.
Note: A user agent can support the Storage interface on DOM attributes other than
the preferences attribute (e.g., a user agent can to support
the [WebStorage] specification’s
localStorage attribute of the window object in conjunction to
the preferences attribute. For the sake of interoperability
across widget user agents, and where it makes sense, authors can use the
preferences attribute over other APIs that provide a Storage interface.
Most of the attributes of the widget interface correspond
to the metadata derived from the initialization process.
When an object implementing the Widget interface is
instantiated, a user agent
sets the attributes identified in the left column of the configuration attributes table
to the values that correspond to values in table of configuration defaults
as defined in [Widgets-Packaging]
(identified by the values in the right hand column).
Upon getting any of the attributes
from the attributes column of the configuration attributes
table, a user agentmust return the corresponding value from the ‘Values in Table of Configuration Defaults’
column.
Configuration
Attributes Table
Attributes
Values in Table of Configuration Defaults
author
author name
authorEmail
author email
authorHref
author href
description
widget description
id
widget id
name
widget name
version
widget version
shortName
widget short name
5.1.1
Usage Example
This section is non-normative.
// Hypothetical example that emails a bug to an Author
function emailBug(bug){
var subject = widget.name + " (" + widget.version + ")";
var to = widget.authorEmail;
var emailURI = "mailto:" + to
+ "?subject=" + escape(subject)
+ "&body=" + escape(bug);
//use email client to send email
widget.openURL(emailURI);
}
// Hypothetical example that generates an about box
// using metadata from a widget's configuration document.
function makeAboutBox(){
var title = "<h1>" + widget.name + "</h1>";
var version = "<h2>Version: " + widget.version + "</h2>";
var id = "<p><small>" + widget.id +"</small></p> <hr/>";
var auth = "<p>Created by: " + widget.author + "</p>";
var homepage = "<p>My Site: " +widget.authorHref + "</p>"
var desc = "<h3>About this Widget</h3><p>"
+ widget.description + "</p>";
var box = "<div id='aboutBox'>"
+ title + version + id + auth + desc +
"</div>";
document.getElementById("console").innerHTML = box;
}
Upon invocation of the setItem() or
removeItem() method by an author
script on an item that is not a read-only
item, a user agentmustqueue a task to fire an
event with the name storage, which
does not bubble and is not cancelable, and which uses the StorageEvent interface, at each Window object whose Widget object
has a Storage object that is
affected. The concept of ‘queue a task’ is defined in [HTML5]. Storage
event and the StorageEvent
interface is defined in [Storage].
Upon invocation of the preferences attribute's
clear() method, a user agentmust not remove read-only items and
corresponding values from a storage area. A
user agent must, however, remove other items from the
storage area in the manner described in the [WebStorage] specification without throwing a
NO_MODIFICATION_ALLOWED_ERR
exception for items that the user agent cannot remove.
The steps to perform the preference-origin security
check are given by the following algorithm:
If the Document‘s effective script origin is not the
same origin as the
Document’s origin, then throw a
SECURITY_ERR exception and abort these steps. The concept
of effective script origin and
same origin are defined in [HTML5].
If the pref-key already exists in the storage area, stop processing this
preference: go back to step 2 in
this algorithm, and process the next preference (if any).
Directly write pref-key and pref-value to the
storage area (i.e., don't use the Storage interface to avoid firing storage
events):
If the user agent cannot write to the storage area (e.g., because it ran out of
disk space, or the space quota was exceeded, etc.), terminate all
processing of this widget. It is recommended
that the user agent inform the end-user of the error.
<!doctype html>
...
<fieldset id="prefs-form">
<legend>Game Options</legend>
<label>Volume: <input type="range" min="0" max="100" name="volume"/> </label>
<label>Difficulty: <input type="range" min="0" max="100" name="difficulty"/> </label>
<input type="button" value="Save" onclick="savePrefs()"/>
<input type="button" value="load" onclick="loadPrefs()"/>
</fieldset>
...
<script>
var form = document.getElementById("prefs-form");
var fields = form.querySelectorAll("input[type='range']");
function loadPrefs () {
for(i in fields){
var field = fields[i];
if (typeof widget.preferences[field.name] != "undefined") {
field.value = widget.preferences[field.name];
}
}
}
function savePrefs () {
for(var i = 0; i < fields.length; i++){
var field = fields[i];
widget.preferences[field.name] = field.value;
}
}
</script>
5.5 The openURL() Method
The openURL() method provides a means to defer the handling
of [IRI]s, to an appropriate scheme handler for the
given IRI scheme (if one is available). The openURL() method
takes a valid IRI as an argument.
When the method is invoked, a user agentmust behave in one
of the following two ways: One, either handle the IRI passed as an
argument with a supported handler for the given URI scheme; or two, if
there is no such scheme handler, or the scheme is unsupported or otherwise
rejected by the user agent (e.g., because of security policy or user
prompting), then the user agent must act as if the
method had not been invoked (i.e., return void and continue
executing the author script as normal).
For security reasons, a user agentmust notnavigate the browsing context of a widget instance through the
openURL() method. The concept of navigate is defined in [HTML5].
The user agent may inform the end-user when a
request to handle the IRI via the openURL() method has
failed.
It is optional for a user agent to support any URI scheme via the openURL()
method.
If the argument passed to the openURL() method is not a valid IRI, the user agentshould inform the
end-user that the request to handle the IRI method has failed.
If a relative URI reference is used as an
argument for openURL(), a user agentmust act as if the
openURL() method had not been invoked (i.e., return
void and continue executing the author script as normal).
5.5.1
Usage Example
This section is non-normative.
//open email
openURL("mailto:jsmith@example.org?subject=A%20Hello&body=hi");
//make a phone call
openURL("tel:+1234567678");
//open a web page
openURL("http://example.org");
//send and sms
openURL("sms:+41796431851,+4116321035;?body=hello%20there");
//SSH
openURL("ssh://user@host.example.com:2222");
6 Storage Areas
A storage area is a data-store that is
unique for the widget instance, which a
user agent uses to store key-value pairs that pertain to the
preferences attribute. An author
script interacts with the storage area via
the [WebStorage] specification's Storage interface. To facilitate the storage of
preferences during the initialization of the preferences
attribute, a user agent needs to have the ability to directly read and
write to a storage area without invoking the
methods of the [WebStorage] specification's
Storage interface.
A user agentmust preserve the values stored in a storage area when a widget is re-instantiated
(i.e., if the widget is closed, the data is saved; when the device is
rebooted and the widget is reopened, the save data is made available to
the storage area).
A user agent may expire data from a storage area for security reasons, or when
requested to do so by the end user, or if the user agent detects that it
has limited storage space.
6.1 Read-only Items
As an extension to the [WebStorage]
specification, this specification allows certain key-value pairs (items)
in a storage area to be read-only: a read-only item is an item in a storage area that cannot be modified or deleted
by an author script. A
read-only item always represents a preference
that author explicitly flagged as "read-only" in the widget's
configuration document (denoted by the preference having a readonly
attribute value set to true). A user agent creates read-only
items when the preferences
attribute is initialized.
Acknowledgements
Max Froumentin, Rune F. Halvorsen, Scott
Wilson, Addison Phillips, Alexander Dreiling, Arun Ranganathan, Arthur
Barstow, Bárbara Barbosa Neves, Brian Wilson, Bjoern Hoehrmann, Benoit
Suzanne, Bert Bos, Boris Zbarsky, Bradford Lassey, Cameron McCormack,
Cliff Schmidt, Claudio Venezia, Coach Wei, Corin Edwards, Dan Brickley,
David Clarke, Dean Jackson, David Pollington, Doug Schepers, Ed Voas,
Felix Sasaki, Francois Daoust, Gautam Chandna, Geir Pedersen, Gene
Vayngrib, Gorm Haug Eriksen, Guido Grassel, Hari Kumar G, Ian Hickson, Jay
Sweeney, Jere Käpyaho, Jim Ley, Jon Ferraiolo, Jose Manuel Cantera
Fonseca, Josh Soref, Jouni Hakala, Joey Bacalhau, Kevin Lawver, Kai
Hendry, Krzysztof Maczyński, Lachlan Hunt, Marc Silbey, Marcin
Hanclik, Mark Baker, Mikko Pohja, Mohamed Zergaoui, Olli Immonen, Philipp
Heltewig, Philip Taylor, Scott Wilson, Stephen Paul Weber.