Виджеты: API и события

Widgets 1.0: APIs and Events

W3C Working Draft 5 February 2009

This Version:: http://www.w3.org/TR/2009/WD-widgets-apis-20090205/
Latest Version:: http://www.w3.org/TR/widgets-apis/
Previous Version:: none.
Editors:: Arve Bersvendsen, Opera Software ASA; Marcos Caceres, W3C Invited Expert

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:

access the metadata declared in a widget’s configuration document,
receive events related to changes in the view state of a widget,
determine the locale under which a widget is currently running,
be notified of events relating to the widget being updated,
invoke a widget to open a URL on the system’s default browser,
requests the user’s attention in a device independent manner,
and check if any additional APIs requested via the configuration document’s feature element have successfully loaded.

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

First Public Working Draft of the Widgets 1.0: APIs and Events specification.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.

Implementers should be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should 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.

1 Introduction

This specification defines a set of APIs and events for widgets that enable baseline functionality for widgets. 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 widget user agent.

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 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) and various resource types (relevant to authors and authoring tool 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 an implementation that attempts to support this 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 is this specification is only concerned with the behavior of programming interfaces and what causes events to be fired.

A user agent must behave as described by this specification in order to claim conformance.

3.1 Dependencies on Other Specifications

This specification relies on several other specifications. A specification is said to be supported by a user agent if the user agent attempts to implement that specification.

A user agent MUST support the [Widgets-Packaging] specification and [DOM3Core].

Need to clarify dependency of HTML5’s window object (or reference the Window spec). Need to talk to HTML-WG about having the spec moved outside of HTML5.

In addition to this specification, a user agent SHOULD support the following specifications:

4 Global 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 object 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 Resolving DOM Nodes

Need to define what URI scheme we are going to use for widgets.

6 The `WindowWidget` Interface

Objects implementing [HTML5]’s Window interface MUST also implement the WindowWidget interface. The WindowWidget interface provides access to [DOM3Core] Document objects in a widget context.

interface WindowWidget {
  readonly attribute Widget widget;
}

6.1 The `Widget` Attribute

The read only widget attribute MUST contain a Widget object.

7 The `Widget` Interface

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

interface Widget {

  readonly attribute dom::DOMString currentMode;
  readonly attribute dom::DOMString locale;
  readonly attribute dom::DOMString identifier;
  readonly attribute WidgetIcon     currentIcon;
  readonly attribute dom::DOMString authorName;
  readonly attribute dom::DOMString authorEmail;
  readonly attribute dom::DOMString authorURL;
  readonly attribute dom::DOMString name;
  readonly attribute dom::DOMString description;
  readonly attribute dom::DOMString version;
  readonly attribute unsigned short width;
  readonly attribute unsigned short height;

           attribute Array          preferences;
  DOMString setPreference(in DOMString name, in DOMString value);
       void getPreference(in DOMString name);

  void hide();
  void show();
           attribute Function onmodechange;

           attribute Function onbeforeupdate;
           attribute Function onafterupdate;

  boolean hasFeature(in DOMString url);

  readonly attribute Array          icons;
  void setIcon(in DOMString url);
  void setIcon(in WidgetIcon icon);

  void openURL(DOMString url);

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

7.1 The `currentMode` Attribute

The currentMode 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 Steps for Processing a Widget Resource in [Widgets-Packaging].

7.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 Steps for Processing a Widget Resource in [Widgets-Packaging].

7.3 The `identifier` Attribute

The identifier attribute represents a unique instance identifier for the widget. The instance identifier MUST be unique on for each widget instance on the device or machine it is installed.

Issue: how does an author access the widget’s id as declared in the config document? Also, what happens if this is not unique? How is uniqueness assured?

7.4 The `currentIcon` Attribute

The currentIcon attribute MUST contain a WidgetIcon object that represents the current icon for the widget.

Issue: need to define how this icon is initially derived. This was in the Packaging spec, but no more. The above definition seems incomplete, what does “current” mean in this context.

7.5 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 Steps for Processing a Widget Resource in [Widgets-Packaging].

7.6 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 Steps for Processing a Widget Resource in [Widgets-Packaging].

7.7 The `authorURL` Attribute

The authorURL 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 Steps for Processing a Widget Resource in [Widgets-Packaging].

7.8 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 Steps for Processing a Widget Resource in [Widgets-Packaging].

Wondering if we should rename this widgetname to avoid confusion with window.name.

7.9 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 Steps for Processing a Widget Resource in [Widgets-Packaging].

7.10 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 Steps for Processing a Widget Resource in [Widgets-Packaging].

7.11 The `width` Attribute

The width attribute represents the width of the widget measured in [CSS21] pixels. Upon instantiation, this attribute SHOULD be set to the value of widget width, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].

Issue: need to define cases where the has been implicitly resized by the user agent, or explicitly resized by other means.

7.12 The `height` Attribute

The height attribute MUST provide the height of the widget measured in [CSS21] pixels. Upon instantiation, this attribute SHOULD be set to the value of widget height, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].

Issue: need to define cases where the has been implicitly resized by the user agent, or explicitly resized by other means.

7.13 The `preferences` Attribute

The preferences attribute holds either no preferences, or any preferences that have previously been stored in the widget using the setPreference method.

The values held in preferences MUST be preserved across instantiations of the widget.

This feature is at Risk. We are still discussing if we should use HTML5’s Storage to achieve this. Please send us feedback.

7.14 The `setPreference()` Method

The setPreference() method accepts two arguments, both of which MUST be present. The first argument MUST be a DOMString providing the name of the preference to be stored. The second argument MUST be either a DOMString, or null.

When correctly invoked, the setPreference() method MUST store the value from the second argument, in a preference with the value from the first argument.

If setPreference() is invoked with null as the second argument, and a preference with the name from the first argument exists, the preference MUST be deleted.

If either argument to setPreference() is invalid, a user agent MUST throw an INVALID_ARGUMENT_ERR.

Issue: INVALID_ARGUMENT_ERR is not defined as extending DOM3Core’s DOMException interface. Need to define it here or throw a predefined exception type.

This feature is at risk. We are still discussing if we should use HTML5’s Storage to achieve this. Please send us feedback.

7.15 The `getPreference()` Method

The getPreference() method accepts one argument, a DOMString containing the name of a preference to be retrieved from the preference storage.

Upon invocation of the method, a user agent MUST attempt to retrieve the value of the preference with the name given from the first argument, and return the value as a DOMString. If a preference with the given name does not exist, the user agent MUST instead return null.

7.16 The `hide()` Method

If the widget is visible, a user agent MAY hide the widget from the user’s view. When a widget is hidden, it MUST stop accepting input events.

Issue: Does hiding change the window mode? Need to define “input event”.

7.17 The `show()` Method

Upon invocation of the method, the show() the widget is visible, a user agent SHOULD ensure that if the widget is invisible, should be made visible.

Issue: Does showing change the window mode or cause onmodechange to fire? This is under-defined. What happens if the widget is visible but off screen?

7.18 The `onmodechange` Callback

The onmodechange attribute MAY hold a reference to 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.

7.19 The `onbeforeupdate` Callback

The onbeforeupdate attribute MAY hold a reference to a function that is to be executed before a widget is updated, prior to the widget shutting down to prepare for the update. Its initial value is null.

When a user agent is about to update the widget update, the function assigned to this attribute is invoked prior to the widget instance shutting down, to allow the widget to perform a clean shutdown, and possibly prepare the widget for the next startup.

Should we add a checkForUpdate() method? which requests that the widget engine check if an update is available by using the Widget Update spec?

7.20 The `onafterupdate` Callback

The onafterupdate attribute MAY hold a reference to a function that is to be executed after a widget is updated. Its initial value is null.

On startup of a widget, the value of this attribute will always be null. If the widget then assigns a function to this attribute, a user agent MUST immediately invoke the function after it has been assigned.

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

7.22 The `icons` Attribute

The icons MUST hold an array of icon objects, each icon representing an icon from the widget’s manifest file.

7.23 The `setIcon()` Method

The setIcon method accepts exactly one argument. This argument MUST be either a a valid URI pointing to an image file inside the widget package, or it must be a valid instance of a WidgetIcon object. When invoked, the setIcon() method MAY change the application icon associated with the widget.

7.24 The `openURL()` Method

The openURL(url) method takes a valid URI as argument. When invoked, the url should be opened in the default browser of the operating system on which the widget runs. If there is no such browser or the url is not a valid URI, then the user agent must act as if the method was not invoked.

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

7.26 The `showNotification()` Method

The showNotification() method accepts two arguments. The first argument is a DOMString containing an informative message to be displayed to the end-user. The second argument is an optional reference to a function that is to be invoked if the user acknowledges the notification message, for instance by clicking on it.

8 The `WidgetIcon` interface

interface WidgetIcon {
  readonly attribute DOMString src;
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;
}

8.1 The `src` Attribute

The src attribute represents a valid URI to an image file inside the widget package that represents an iconic representation of the widget.

8.2 The `width` Attribute

The width represents the width of the icon in [CSS21] pixels.

8.3 The `height` Attribute

The height represents the height of the icon in [CSS21] pixels.

Acknowledgements

This section will be completed as the document matures.

Normative References

[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.
[ECMAScript]: ECMAScript Language Specification, Third Edition. ECMA, December 1999.
[HTML5]: HTML 5, I. Hickson, D. Hyatt, editors. W3C Working Draft, 2008.
[HTTP]: Hypertext Transfer Protocol — HTTP/1.1. RFC 2616, R. Fielding, et al. June 1999.
[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)
[Widgets-Updates]: Widgets 1.0: Updates. M. Caceres, Ed. W3C, W3C Working Draft 7 October 2008. (Work in progress)
[XMLHttpRequest]: The XMLHttpRequest Object. A van Kesteren. W3C Working Draft 15 April 2008. (Work in progress)

Informative References

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

Виджеты: API и события

Widgets 1.0: APIs and Events

W3C Working Draft 5 February 2009

Abstract

Status of This Document

Table of Contents

1 Introduction

1.1 The Widget Family of Specifications

2 Conformance

3 User Agents

3.1 Dependencies on Other Specifications

4 Global Definitions

5 Resolving DOM Nodes

6 The WindowWidget Interface

6.1 The Widget Attribute

7 The Widget Interface

7.1 The currentMode Attribute

7.2 The locale Attribute

7.3 The identifier Attribute

7.4 The currentIcon Attribute

7.5 The authorName Attribute

7.6 The authorEmail Attribute

7.7 The authorURL Attribute

7.8 The name Attribute

7.9 The description Attribute

7.10 The version Attribute

7.11 The width Attribute

7.12 The height Attribute

7.13 The preferences Attribute

7.14 The setPreference() Method

7.15 The getPreference() Method

7.16 The hide() Method

7.17 The show() Method

7.18 The onmodechange Callback

7.19 The onbeforeupdate Callback

7.20 The onafterupdate Callback

7.21 The hasFeature() Method

7.22 The icons Attribute

7.23 The setIcon() Method

7.24 The openURL() Method

7.25 The getAttention() Method

7.26 The showNotification() Method

8 The WidgetIcon interface

8.1 The src Attribute

8.2 The width Attribute

8.3 The height Attribute