Enterprise 2.0 - возможность для компаний и корпораций снизить расходы на содержание IT-инфраструктуры и повысить эффективность затрат собственного бизнеса.

Наши проекты:

• Apple Life - “яблочный” форум
• Сделка Века 2.0 - мы пишем о SaaS, SOA, рассматриваем кейсы эффективного внедрения  продуктов Enterprise 2.0
• cowWorking - принципиально новый продукт Enterprise 2.0 категории полноценных виртуальных офисов. Дата запуска будет объявлена дополнительно. Следите за пресс-релизами.

Мы горячо поддерживаем:

• Технологию виджетов. Мы публикуем на нашем сайте официальные спецификации виджетов с переводами.

Для связи: max@sdelkaveka.ru

Widgets 1.0: Digital Signature

W3C Working Draft 14 April 2008

This Version:

http://www.w3.org/TR/2008/WD-widgets-digsig-20080414/

Latest Version:

http://www.w3.org/TR/widgets-digsig/

Previous Version:

None.

Latest Editor’s Draft:

http://dev.w3.org/2006/waf/widgets-digsig/

Version history:

Twitter messages (non-editorial changes only): http://twitter.com/widgetspecs (RSS)

Editor:

Marcos Caceres, Invited Expert

Copyright © 2008 W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This document defines a profile of the XML-Signature Syntax and Processing specification to allow a widget resource to be digitally signed. Vendors and authors can digitally sign widgets as a trust and quality assurance mechanism. Prior to instantiation, a widget user agent can use the digital signature to verify the authenticity and data integrity of the files in a widget resource. In the rare case where a widget damages the end-user’s device, the digital signature may provide a user with legal recourse to prove that a widget resource was signed by a particular author or publisher.

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 W3C First Public Working Draft of the Widgets 1.0: Digital Signature. This document is produced the Web Application Formats (WAF) Working Group (WG). This WG is part of the Rich Web Clients Activity and this activity is within the W3C’s Interaction Domain.

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

Table of Contents

• 1. Introduction
  • 1.1 Signature Profile
• 2. Conformance
• 3. Definitions
• 4. Procedure for Signing a Widget Resource
• 5. Procedure for Verifying a Digital Signature
• Acknowledgements
• References

1. Introduction

Digitally signing a widget resource involves signing all of its file entries using a unique private key that is known only to the signer. The resulting signature, along with the signer’s digital certificate, is structured into an XML document, and included at the root of a widget resource under the name signature.xml.

<?xml version="1.0" encoding="UTF-8"?>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">

	<SignedInfo>
		<CanonicalizationMethod
			Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
		<SignatureMethod
			Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
		<Reference URI="config.xml">

			<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
			<DigestValue>j6...8nk=</DigestValue>
		</Reference>
		<Reference URI="index.html">

     		<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
     		<DigestValue>lm...34=</DigestValue>
		</Reference>
		<Reference URI="icon.png">

			<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
			<DigestValue>pq...56=</DigestValue>
		</Reference>
	</SignedInfo>
	<SignatureValue>MC0E~LE=</SignatureValue>

	<KeyInfo>
		<X509Data>
			<X509Certificate>MI...lVN</X509Certificate>
		</X509Data>
	</KeyInfo>

</Signature>

1.1 Signature Profile

The signature scheme defined in this specification imposes a number of restrictions on the XML-Signature Syntax and Processing Specification [XMLDsig]:

1. Every file entry in a widget resource must be signed. The resulting digital signature must be serialized into an UTF-8 encoded XML document and placed at the root of the widget archive under the name signature.xml.
2. Reference elements must use the SHA1 as the digest method.
3. The signature method to produce the SignatureValue must be RSA-SHA1.
4. A KeyInfo element must be present and the digital certificate format must conform to the [X509v3] specification. Implementations must be prepared to accept all X.509 certificates versions identified in [X509v3] via the version field. To be clear, the value of the version field identifies the version of an X.509 certificate in the following way:
   • 0 is X.509 version 1,
   • 1 is X.509 version 2,
   • 2 is X.509 version 3,
   • if the version field is omitted, then the X.509 version is 1
5. SignatureProperties elements are ignored by this specification, but they may be present in a signature document.

(For SignatureProperties, we are considering defining one element: WidgetSigningProfile, with a version parameter. All of which would be signed.)

Note: The intention of these restrictions is to define a light-weight profile of [XMLDsig] that does not require widget user agents to implement [XPath].

2. Conformance

As well as sections marked as non-normative, 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].

There are two classes of product that can claim conformance to this specification:

• A digital signature document.
• A widget user agent

Products that generate a digital signature document must generate XML documents that conform to [XMLDsig] and adhere to the restrictions imposed by this specification.

Products that check the conformance of a digital signature document must not claim conformance to this specification, though they can claim to verify that a digital signature document conforms to this specification.

A widget user agent must behave as described by this specification in order to claim conformance, specially when faced with an invalid widget resource or a non-conforming digital signature document.

3. Definitions

A widget resource is a byte-stream or file that conforms to section 4.0 and section 5.0 of the [Widgets Packaging] specification.

A file entry is the amalgamation of data held by a local file header, file data, and (optional) data descriptor [ZIP] for each physical file stored in a zip archive.

A digital signature document is a well-formed XML document named signature.xml generated by applying the procedure for signing a widget resource described in this document. The document will conform to [XMLDsig].

An invalid zip archive in this specification is one where the digital signature document is either in error, or there is a mismatch between the data in the digital signature document and/or the data in a file entry (meaning that the authenticity or data integrity of the zip archive could not be verified). For rules on dealing with invalid zip archives, please see the “Dealing with Invalid Zip Archives” section in the [Widgets Packaging] specification.

A digitally signed widget resource is one that contains a file entry with a file name field that matches ‘signature.xml‘ in a any case form, though the lower case form is recommended. The signature.xml document must contain a Reference element for every file entry in the widget resource. In addition, the file data of the file entry must conform to [XMLDsig], but in accordance to the procedure for signing a widget resource.

A decompressed representation of a file entry is the data extracted from the data field of a local file header (and decompressed using [Deflate] when the compression method field is 8).

4. Procedure for Signing a Widget Resource

The procedure for signing a widget resource to produce a conforming digital signature document is as follows:

1. If the widget resource contains zero file entries, treat this zip archive as an invalid zip archive.
2. Let doc be a new XML [DOM3CORE] document encoded in UTF-8 [XML].
3. Create a SignedInfo element.
4. For each file entry in the widget resource, if the file name field of the local file header of the file entry does not case insensitively match signature.xml:
   1. Let path be the value of the file name field of the local file header.
   2. If general purpose bit 11 of the local file header is 0, then convert the character encoding of path from [CP437] to [UTF-8].
   3. Verify that path is a valid zip-relative-path, as defined in [Widgets Packaging].
   4. Create a Reference element.
   5. Create a URI attribute in the Reference element and assign it the value of path.
   6. Let hash-value be the digests of applying the SHA-1 algorithm to the file entry’s decompressed representation (see [XMLDsig] for how to do this).
   7. Create a DigestValue element and append the hash-value as a Text node.
   8. Create a DigestMethod element with an Algorithm attribute, and give that attribute the value http://www.w3.org/2000/09/xmldsig#sha1.
   9. Append this Reference element to the SignedInfo element.
5. Create a CanonicalizationMethod element and set the value of its Algorithm attribute to http://www.w3.org/TR/2001/REC-xml-c14n-20010315.
6. Create a SignatureMethod element and set the value of its Algorithm attribute to http://www.w3.org/2000/09/xmldsig#rsa-sha1.
7. Calculate the digest of the SignedInfo element using RSA-SHA1, sign it and place the signature in the <SignatureValue> element.
8. Place the signer’s certificate in the KeyInfo element.
9. Create a Signature element in the http://www.w3.org/2000/09/xmldsig# namespace.
10. Place the SignedInfo, SignatureValue, and KeyInfo elements into the Signature element.
11. Open the zip archive so that a file entry can be written (eg. as a buffered output stream).
12. Serialize the Signature element and all its children into a UTF-8 encoded XML file in canonical form and save it in the root of the widget resource as signature.xml overriding the contents of any existing signature.xml file entry.

5. Procedure for Verifying a Digital Signature

The procedure for verifying a digital signature is as follows. The algorithm first checks the validity of the digital signature and then verifies that all resources in a widget resource.

If a steps results in a false condition or is otherwise in error, then a widget user agent must treat the widget resource as an invalid zip archive and all processing of the widget resource must stop.

1. Find the the file entry whose file name field case insensitively matches signature.xml.
2. Parse the decompressed representation of signature.xml into a DOM tree using a valid XML Parser to check that the document is well-formed [XML].
3. Check that a Signature element exists and it contains a SignedInfo element.
4. Check that every file entry in the zip archive has a corresponding Reference element in the SingedInfo element:
   1. Let path be the value of the file name field of the local file header of the file entry.
   2. If general purpose bit 11 of the local file header of the file entry is 0, then convert the character encoding of path from [CP437] to [UTF-8].
   3. Check that path is a valid zip-relative-path (absolute URI references are considered in error)
5. Apply the Signature Validation algorithm as defined in [XMLDsig]:
   1. If the widget user agent cannot verify the certificate from its list of explicitly trusted root certificates, then the certificate must be treated as invalid.
6. Extract the decompressed representation of each file entry in the widget archive, making sure to retain the directory structure of each file entry.
   1. NEED SECURITY CONSIDERATIONS HERE.
7. Apply the Reference Validation algorithm as defined in [XMLDsig],
   1. THIS SECTION IS STILL UNDER DEVELOPMENT.
   2. Let base URI be the absolute path to where the widget archive was extracted (eg. file:///temp/widget/)
   3. Validate against the matched file entry’s decompressed representation. The relative URI references are evaluated with respect to a base URI that points at where the widget resource was demcompressed.

Acknowledgements

This section will be completed as the document matures.

References

This section will be completed as the document matures.

[Canonical XML]

Canonical XML. W3C Recommendation. J. Boyer. March 2001. http://www.w3.org/TR/2001/REC-xml-c14n-20010315. http://www.ietf.org/rfc/rfc3076.txt

[CP437]

cp437_DOSLatinUS to Unicode table. ftp://ftp.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/PC/CP437.TXT

[Deflate]

DEFLATE Compressed Data Format Specification version 1.3, P. Deutsch, The Internet Society, May 1996.

[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, S. Bradner. IETF, March 1997.

[UTF-8]

RFC 2279. UTF-8, a transformation format of ISO 10646. F. Yergeau. January 1998. http://www.ietf.org/rfc/rfc2279.txt

[Widgets Packaging]

Widgets 1.0: Packaging and Configuration.

[Widgets Requirements]

Widgets 1.0 Requirements, M. Caceres. W3C, July 2007.

[XML]

Extensible Markup Language (XML) 1.0 (Third Edition). T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, F. Yergeau. W3C, February 2004.

[XMLDsig]

XML-Signature Syntax and Processing. Mark Bartel, John Boyer, Barb Fox, Brian LaMacchia and Ed Simon, authors. Donald Eastlake, Joseph Reagle, and David Solo, editors. W3C, February 2002.

[XPath]

XML Path Language (XPath) Version 1.0. W3C Recommendation. J. Clark, S. DeRose. October 1999. http://www.w3.org/TR/1999/REC-xpath-19991116

[X509v3]

ITU-T Recommendation X.509 version 3 (1997). “Information Technology - Open Systems Interconnection - The Directory Authentication Framework” ISO/IEC 9594-8:1997.

[ZIP]

.ZIP File Format Specification. PKWare Inc.

Widgets 1.0: Packaging and Configuration

W3C Working Draft 22 December 2008

This version:

http://www.w3.org/TR/2008/WD-widgets-20081222/

Latest version:

http://www.w3.org/TR/widgets/

Previous versions:

http://www.w3.org/TR/2008/WD-widgets-20080414/

http://www.w3.org/TR/2007/WD-widgets-20071013/

http://www.w3.org/TR/2006/WD-widgets-20061109/

Latest Editor’s draft:

http://dev.w3.org/2006/waf/widgets/

Version history:

Twitter messages (non-editorial changes only): http://twitter.com/widgetspecs (RSS)

Editor:

Marcos Caceres, W3C Invited Expert

Copyright © 2008 W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This document 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 packaging format acts as a container for files used by a widget. The configuration document is an XML vocabulary that authors can use to declare metadata and configuration parameters for a widget. The steps for processing a widget resource describe the expected behavior and means of error handling for widget user agents while processing the packaging format, configuration document, and other relevant files. This document also defines conformance criteria and expected behavior for conformance checkers, which are tools that aid authors in verifying that Zip archives and configuration documents conform to this specification.

This document is part of the Widgets 1.0 Family of Specifications, which together standardize widgets.

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 is the 22 December 2008 Last Call Working Draft version of the “Widgets 1.0: Packaging and Configuration” specification. The Last Call period ends on 31 January 2009. This version reflects over of two years work addressing requirements 1 to 23 of the Widgets 1.0: Requirements document [Widgets-Reqs]. The requirements 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 widgets should be packaged and configured before the Working Group makes a call for implementations. The Working Group’s goal is to make sure that vendor’s requirements for packaging and configuration have been effectively addressed and clearly specified.

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. The public is encouraged to send comments to the Web Apps Working Group’s public mailing list public-Webapps@w3.org (archive). See W3C mailing list and archive usage guidelines. 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.

Table of Contents

1. 1 Introduction
   1. 1.1 Note to Last Call Reviewers
   2. 1.2 Design Goals and Requirements
   3. 1.3 How this Document is Organized
   4. 1.4 The Widget Family of Specifications
   5. 1.5 Global Definitions
2. 2 Conformance
3. 3 Widget User Agents
   1. 3.1 Dependencies on Other Specifications and File Formats
   2. 3.2 Internationalized Tag Set Support
   3. 3.3 Zip Support
4. 4 Conformance Checker
5. 5 Zip Archive
   1. 5.1 Compression Methods
   2. 5.2 Version of Zip Implementation Needed to Extract a File Entry
   3. 5.3 Zip Relative Paths
   4. 5.4 Reserved Characters
6. 6 Widget Resources
   1. 6.1 Invalid Widgets
   2. 6.2 Files and Content Types
   3. 6.3 Reserved File and Folder Names
   4. 6.4 Digital Signatures
   5. 6.5 Content Localization
   6. 6.6 Start file and Default Start Files
   7. 6.7 Custom Icons and Default Icons
   8. 6.8 Thumbnail
   9. 6.9 MIME Type
   10. 6.10 File Extension
7. 7 Configuration Document
   1. 7.1 Namespace
   2. 7.2 Proprietary Extensions
   3. 7.3 Attribute Types
   4. 7.4 The widget Element
   5. 7.5 The name Element
   6. 7.6 The description Element
   7. 7.7 The author Element
   8. 7.8 The license Element
   9. 7.9 The icon Element
   10. 7.10 The access Element
   11. 7.11 The content Element
   12. 7.12 The update Element
   13. 7.13 The feature Element
   14. 7.14 Window Modes
   15. 7.15 Indicating Text Directionality with <its:span>
8. 8 Steps for Processing a Widget Resource
   1. 8.1 Dealing with Invalid Widgets
   2. 8.2 Extracting the File Data from a File Entry
   3. Step 1 - Acquire a Potential Zip Archive
   4. Step 2 - Verify the Zip archive and its File Entries
   5. Step 3 - Set the Configuration Defaults
   6. Step 4 - Locate Digital Signatures for the Widget
   7. Step 5 - Process the Digital Signatures
   8. Step 6 - Determine the Base folder and Widget Locale
   9. Step 7 - Locate the Configuration Document
   10. Step 8 - Process the configuration document
   11. Step 9 - Locate the Start File
   12. Step 10 - Locate the default icons and thumbnail
9. Appendix
   1. Embedding a Widget Resource into an HTML Document
   2. RelaxNG Schema for the Configuration Document
10. Acknowledgements
11. Normative References
12. Informative References

1 Introduction

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.

1.1 Note to Last Call Reviewers

This section is non-normative.

The editor of this specification responds rapidly to all feedback and continuously makes corrections to this document. So, unless you are reading this document on the date of publication, it is extremely likely that this document has been superseded. Instead of reviewing this published draft, please review the latest editor’s draft and make sure you cite the date of that draft in the feedback you send to the Web Apps Working Group’s public mailing list public-Webapps@w3.org.

Please also be sure to check the mailing list archive to see if any issue you uncover has already been addressed. To help with cataloguing issues, prefix emails to the mailing list with the string [widgets]. Any and all feedback is welcomed.

1.2 Design Goals and Requirements

This section is non-normative.

The design goals and requirements for this specification are addressed in the Widgets 1.0 Requirements [Widgets-Reqs] document. This document addresses the following requirements:

• R1. Packaging Format, see packaging format.
• R2. MIME Type, see the widget MIME Type.
• R3. File Extension, see the widget file extension.
• R4. Internal Abstract Structure, see Zip archive and the widget resource.
• R5. Reserved Resources Names, see reserved file names.
• R6. Addressing Scheme, see valid path.
• R7. Multilingual Resource Names, see Zip relative path, particularly in respect to [UTF-8] support.
• R8. Localization Guidelines, see content localization.
• R9. Automatic Localization, see content localization.
• R10. Device Independent Delivery
• R11. Data Compression, see the valid compression methods.
• R12. Derive the MIME types of Resources, see rules for identifying the MIME type of a file.
• R13. Format and Schema, see the configuration document, configuration defaults, and the RelaxNG Schema for the configuration document.
• R14. Widget Metadata, see configuration document’s name, description, and license element.
• R16. Authorship Metadata, see configuration document’s author element.
• R16. Copyright Notice and License Metadata, see configuration document’s license element.
• R17. Visual Rendering Dimensions, see widget element’s width and height attributes.
• R18. Declarative Bootstrap, see content element.
• R19. Automated Bootstrap, see default start files.
• R20. Iconic Representations, see icon element and the default icons.
• R21. Configuration Parameters, see access element.
• R22. Feature Access Declarations, see feature element.
• R23. Configuration Document Independence, see configuration document.

1.3 How this Document is Organized

This section is non-normative.

The reader should be aware that this document is organized into two halves, but not explicitly marked as such. The first half defines the various aspects of what constitutes the packaging format, the configuration document, and reserved files, such as default icons and localized folders, as well as some of the expected behavior of conformance checkers, which are implementations that check the conformance of a Zip archive or a configuration document to this specification. Where possible, the first half avoids describing too many aspects related to processing, which are described in more detail in the second half of the document.

The second half, which starts in the section titled “Steps for Processing a Widget Resource“, defines the steps required to process a widget as well as the expected behavior of a widget user agent as it processes the packaging format, the configuration document, and attempts to perform internationalization. The second half of this document also deals with error handling in the event that a widget user agent encounters unsupported or missing files, or erroneous [DOM3Core] nodes in the configuration document. Wherever processing is relevant, sections in the first half of the document link to sections in the second half of the document.

This specification should be read like all other specifications. First, it should be read cover-to-cover; multiple times. Then, it should be read backwards at least once. Then it should be read by picking random sections from the contents list and following all the cross-references.

1.4 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 Widgets 1.0: APIs and Events [Widgets-APIs] specification defines APIs to store preferences and capture events. 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: Security Model [Widgets-Security] specification defines a security model that defines what a widget can or cannot do at runtime. 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].

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

An author is a person who creates a widget resource or an authoring tool that generates widget resources.

The [Widgets-Landscape] defines a widget as an end-user’s conceptualization of an interactive single purpose application for displaying and/or updating local data or data on the Web, packaged in a way to allow a single download and installation on a user’s machine, mobile phone, or Internet-enabled mobile device. Because widgets are packaged, they can be liberally shared by users without relying on [HTTP] (i.e., users can share widgets over Bluetooth or through other distribution channels).

Reserved means that a character, or text string, or a file that is identified by a particular file-name, has a specified purpose and meaning in this specification or in some other specification or system. The reason why something is reserved and how it must or must not be used is given when the term is used.

A character, or text string, or a file is arbitrary if it is not reserved.

The space characters, for the purposes of this specification, are [Unicode] code points:

• U+0020 SPACE,
• U+0009 CHARACTER TABULATION (tab),
• U+000A LINE FEED (LF),
• U+000B LINE TABULATION,
• U+000C FORM FEED (FF),
• U+000D CARRIAGE RETURN (CR).

The control characters, for the purpose of this specification, are [Unicode] code points in the range U+0000 NUL to U+001F INFORMATION SEPARATOR 1, and character U+007F DELETE.

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 are four classes of products that can claim conformance to this specification:

1. A widget user agent.
2. A widget resource.
3. A configuration document.
4. A conformance checker.

Products that generate widget resources and/or allow authoring of configuration documents must not claim conformance to this specification, though they can claim to produce widget resources or configuration documents that are conforming to this specification. Authoring tools and markup generators must generate conforming configuration documents and/or widget resources.

Products that check the conformance of widget resources or configuration documents can claim conformance to this specification. They can also claim to verify that a widget resource or a configuration document is conforming to the relevant section(s) of this specification.

3 Widget User Agents

A widget user agent is a user agent that attempts to implement this specification, as well as the [Widgets-APIs], [Widgets-Security], [Widgets-DigSig], and [Widgets-Updates] specifications.

A widget user agent must behave as described by this specification in order to claim conformance, even when faced with a non-conforming widget resource or a non-conforming configuration document.

Note: Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the [Widgets-Test-Suite]. Note, however, that 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.1 Dependencies on Other Specifications and File Formats

This specification relies on several other specifications, some of which are file formats.

A specification is said to be supported by a widget user agent if the widget user agent attempts to implement that specification. In addition, a widget user agent is said to support a particular file format if it is able to process or render that file format.

In addition to this specification, a widget user agent must support the following specifications and file formats:

• [ZIP], but with the exclusions listed in the Zip support section.
• [PNG], [GIF87], and [JPEG] and [GIF89] image files formats.
• [XML] and [XMLNS].
• [DOM3CORE].
• [HTML4].
• [XMLHttpRequest].
• [ECMAScript].
• [UTF-8].
• [Deflate].

A widget user agent may also support the following file formats as icons:

• [ICO].
• [SVGTiny].

3.2 Internationalized Tag Set Support

To facilitate content localization in configuration documents, a widget user agent should support the Internationalized Tag Set’s ([ITS]) its:span element and the its:dir attribute. Support of other ITS elements and attributes is not required.

Although this specification specifies the elements of the configuration document in which <its:span> and the its:dir attribute can be used (below), it does not define how they are to be interpreted and processed by a widget user agent. If a widget user agent implements <its:span> and its:dir, then the widget user agent must do so in conformance to the processing rules defined by the ITS specification.

3.3 Zip Support

A widget user agent is not required to implement or support any of the following aspects of the [ZIP] specification:

• Any decompression algorithm, other than [Deflate] and Stored (no compression) [ZIP].
• File spanning or multiple volumes.
• Zip64 extensions.
• Any digital signature method, other than the method defined in [Widgets-DigSig].
• Any decryption methods.
• Any patented aspects.

4 Conformance Checker

A conformance checker (CC) is a user agent that verifies that a widget resource or a configuration document conforms to this specification.This specification defines the expected behavior of conformance checkers in sections marked as conformance checker behavior throughout this document.

This specification asks CCs to inform authors of conformance violations, which means they should display messages to authors in a human readable manner that would assist them in correcting problems. Wording of messages is left to the discretion of implementers.

A widget user agent may behave as a conformance checker.

5 Zip Archive

The files of a widget are packaged using the [ZIP] file format (in other words, Zip is the packaging format for widgets).

A file entry is the amalgamation of data held by a local file header, file data, and (optional) data descriptor [ZIP] for each physical file stored in a Zip archive.

A potential Zip archive is a data object that has not been verified to be a valid Zip archive.

A valid Zip archive is a data object that conforms to the production of a .Zip file as defined by the Zip File Format Specification [ZIP], with the exclusion or support for the features and conditions defined in the Zip Support section. Step 2 of the Steps for Processing a Widget Resource describes how widget user agents verify that a Zip archive conforms to this specification.

The magic numbers for a Zip archive is the byte sequence: 50 4B 03 04.

To conform to this specification, a Zip archive must contain one or more file entries and must not be an invalid widget.

5.1 Compression Methods

The compression method is the compression algorithm or storage method used to encode the file data of a file entry. The compression method that is used to store the file data of a file entry is identified by the numeric value derived from the compression method field [ZIP].

The valid compression methods, as indicated by the compression method field, for a file entry are:

8

Data is compressed using [Deflate].

0

Data is Stored (no compression) [ZIP].

Author requirements: File data must be compressed with either [Deflate] or stored (no compression). Of the valid compression methods, [Deflate] is the recommended compression method. Using any other compression methods will result in an invalid widget.

Conformance checker behavior

A conformance checker must check that each file entry uses one of the valid compression methods. If a CC encounters a file entry that uses the Stored compression method, then it should inform the author that file entry should be recompressed with [Deflate]. If a CC encounters a compression method that is not a valid compression method, it must inform the author that the resource as an invalid widget.

5.2 Version of Zip Implementation Needed to Extract a File Entry

The version needed to extract is the 2-byte sequence in the local file header of a file entry that indicates the minimum version supported version of the [ZIP] specification needed to extract the file data.

The valid versions needed to extract values are as follows. Each value is assigned one or more meanings by the [Zip] specification:

0x100 (equivalent to 1.0)

Default value specified in Zip.

0x200 (equivalent to 2.0)

The file data may have been compressed using [Deflate],

or the file data may be a folder,

or the file may have been encrypted using traditional PKWARE encryption.

Note: If the Zip archive has been encrypted using traditional PKWARE encryption, then it will be treated as an invalid widget.

5.3 Zip Relative Paths

For the purpose of this specification, a Zip relative path is the variable-length string derived from a file name field of a local file header of a file entry.

The valid encodings for a Zip relative path are either [CP437] or [UTF-8]. It is recommended that the file name field be encoded using [UTF-8].

Author requirements: As stated in [Zip], the appropriate encoding indicator must be used, meaning that if the Zip relative path is encoded using [UTF-8], then general purpose bit 11 of the local file header must be set to 1; otherwise, it must be set to 0.

Note: A Zip relative path is said to be relative as it stores the string that represents file and folder names relative to where the Zip archive was created on a file system (e.g. images/bg.png), as opposed to storing an absolute path (e.g. c:imagesbg.png). The value of a Zip relative path will generally resemble the string value of a name of the file or folder(s) on the device on which the Zip archive was created, but with the exception of the path delimiter being a U+002F SOLIDUS “/” character.

Author requirements: It is recommended that authors keep their path lengths below 255 bytes. Note that a character can require more than one byte to encode, making the length of the path in characters less than 255.

A valid Zip relative path is one that case-insensitively matches the production of Zip-rel-path in the following [ABNF]. Note that ALPHA, DIGIT, and SP are defined in [ABNF] (but essentially represent alphanumerical characters and the U+0020 SPACE character). Language-Tag is defined in [BCP47]. In addition, reserved characters must not appear anywhere in the file-name.

Zip-rel-path     = [ *localized-folder ] [ *folder-name ] [ file-name ] /
                   [ localized-folder ] [ *folder-name ] / [ folder-name ]
localized-folder = "locales" "/" Language-Tag "/"
folder-name      = file-name "/"
file-name        = 1*254( *base-name [ file-extension ] )
base-name        = allowed-chars
file-extension   = "." 1*allowed-chars
allowed-chars    = cp437-chars / utf8-chars
utf8-chars       = safe-chars / U+0080 and beyond
cp437-chars      = safe-chars / x80-FF
safe-chars       = ALPHA / DIGIT / SP / "$" / "%" / "'" / "-" / "_" / "@"
                    / "~" / "!" / "(" / ")" / "^" / "&" / "+"
                    / "," / "." / "=" / "[" / "]" 

Note: Authors should be aware that, at the time of writing, there are some interoperability issues with regards to using characters outside the allowed-chars for file or folder names in a Zip archive. If an author chooses to use cp437-chars or the UTF8-chars, they should thoroughly test their widgets on various platforms prior to distribution; otherwise it is suggested that authors restrict file and folder names to the allowed-chars (characters in the US-ASCII range).

This specification does not put a restriction on the byte length of Zip relative paths, a widget user agent should be prepared to deal with path lengths longer than 250 bytes.

Conformance Checker Behavior

A CC must inform the author about any file entry whose file name field is not a valid Zip relative path.

A CC must inform the author of any Zip relative paths whose length exceed 250 bytes, and should inform the author of any Zip relative path whose length exceeds 120 bytes.

Note: Having excessively long path names (e.g. over 120 characters) can also result in interoperability issues on some operating systems. Note that a character can require more than one byte to encode, making the length of the path in characters less than 255.

5.4 Reserved Characters

In addition to the control characters, the following characters are reserved and must not appear anywhere in a file-name.

Note: These characters are reserved to maintain interoperability across various file systems and with generic [URI]s.

Note to authors: It is recommended that authors avoid using the following words as either a folder or a base-name in a Zip relative path as they are reserved by some operating systems (case insensitive): CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, CLOCKS$. For example, the following names are ok: “CON-tact.txt”, “printer.lpt1″, “DCOM1.pdf”. However, “com3.txt” “Lpt1″, “CoM9.gif” would not be. In addition, authors should avoid using 2 and 3 letters names for folders at the root of a widget resource.

In addition, authors should also avoid having a “.” U+002E FULL STOP as the last character of a file or folder name as some operating systems will remove the character when the file is extracted from the Zip archive onto the device. Authors should also avoid having the space character (SP) at the start or end of a file name. Authors should also take caution when using the “+” U+002B PLUS SIGN, as it might cause issues on some operating systems.

Conformance Checker Behavior

A CC must inform an author of the presence of any of the reserved characters or control characters in a file-name.

A CC should inform an author of the presence of a U+0020 SPACE character at the start or end of a file-name.

A CC should inform an author of the presence of any U+002E FULL STOP at the end of a file-name.

A CC should inform an author of any base-name that case insensitively matches any of the following strings: CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, CLOCKS$.

A CC may inform an author of the presence of any U+002B PLUS SIGN in a file-name.

6 Widget Resources

A widget resource is a valid Zip archive that contains:

• One or more start files, located at the root of the widget or in localized folders.
• Zero or more configuration documents, located at the root of the widget or in localized folders.
• Zero or more icons, located at the root of the widget or in localized folders.
• Zero or more thumbnail, located either at the root of the widget or in localized folders.
• Zero or more arbitrary files located either at the root of the widget or in arbitrary folders or in localized folders.
• Zero or more digital signatures located at the root of the widget.

See step 1 - Acquire a Potential Zip Archive for instructions on how to process a widget resource.

6.1 Invalid Widgets

During the steps for processing a widget resource, certain error conditions will result in a Zip archive being treated as an invalid widget. An invalid widget is a condition whereby a Zip archive, or a file within the Zip archive, is deemed to be corrupt beyond recovery or non-conforming to this specification.

See the section Dealing with Invalid Widgets for instructions on how a widget user agent must treat an invalid widget.

6.2 Files and Content Types

The root of the widget is the top-most folder level of the Zip archive. The root of the widget contains files and folders, some of which are reserved (see reserved file names).

A file is the decompressed representation of a file entry. Unlike [HTTP] resources, files within a Zip archive are not available in multiple representations, nor are they dynamically generated at runtime. Additionally, there is no notion of a [MIME] type within Zip (i.e., no Content-Type metadata), so widget user agents must use file extension to MIME mapping followed by content-type sniffing to determine the MIME type of a file.

A folder is a file entry whose file name field matches the production of folder-name in a valid Zip relative path (the last character of the file name field [ZIP] is a U+002F SOLIDUS) and whose version needed to extract is 0x200. A folder may logically contain files or other folders.

The base folder is the folder from which all relative paths are resolved.

File extension to MIME mapping is the process of mapping the file extension of a file to some MIME type.

Content-type sniffing is the process of determining the MIME type of a file by examining its content. Examination of content involves examining the bytes of a file for well-known patterns of byte sequences (e.g. the byte sequence EF BB BF, which identifies a text file as being encoded in [UTF-8]). Some of these patterns have been registered with the Internet Assigned Numbers Authority (IANA), as part of a MIME type registration, under the name magic numbers.

A processable file is a file that has been verified as residing inside a widget resource and that has a MIME type supported by the widget user agent.

6.3 Reserved File and Folder Names

The following table contains a list of base-names and possible file-extensions that when combined form file-names that are reserved for some purpose by this specification. All reserved file names must be treated as case insensitive.

The following table contains a list of folder-names that are reserved for some purpose by this specification. All reserved file names must be treated as case insensitive.

6.4 Digital Signatures

A widget resource contains a digital signature, and hence is digitally signed, if it contains one or more files that conform to the [Widgets-DigSig] specification.

The naming convention for digital signatures is a string that case-insensitively matches the production of dig-sig-file-names in the following ABNF:

dig-sig-file-names = "signature" *[0..9] ".xml"

6.5 Content Localization

Authors can localize the content of a widget by placing files inside folders that follow the Language Tag conventions set forth in [BCP47]; that is, by naming folders using values derived from the IANA Language Subtag Registry such as “en-us”, “en-gb”, and so on, but avoiding subtags marked as deprecated, grandfathered, or redundant. These localized folders are then placed inside the container for localized content (which is simply a folder called ‘locales/’ that sits at the root of the widget).

When an author places localized content in the container for localized content, the widget user agent will automatically select the appropriate localized version of a widget’s files based on locale information derived from the system locale. The system locale is the end-user’s preferred language and regional settings derived from the operating system or widget user agent (e.g. English, Australia).

Note: See also the Web Services Internationalization Usage Scenarios and the Unicode Locale Data Markup Language for an informative discussion on the term locale.

A localized widget is a widget resource that has a container for localized content, which contains one or more localized folders.

The container for localized content is a folder at the root of the widget whose the first five characters of the folder-name case insensitively match the string ‘locales/‘.

A localized folder is a folder whose file name field matches localized-folder. A widget resource may contain zero or more localized folders. Localized folders may contain zero or more arbitrary folders and/or files.

Author requirements: According to [BCP47], one should avoid region, script or other subtags except where they add useful distinguishing information to a localized folder. In addition, one should avoid including empty localized folders in a widget resource (unless there is a good reason to include them) as the a widget user agent will match them when it attempts to determine the base folder and widget locale.

A localized file is any resource that has been placed inside a localized folder. The contents of the resource may or may not be translated, localized, or altered for the given context. A widget resource may contain zero or more localized files. Any resource, except digital signatures, can be localized.

Note: A widget user agent will treat any localized digital signature as an arbitrary resource.

For example, a localized folder “/ja” (Japanese) might contain an HTML document translated into Japanese.

Author requirements: Localized folders must be at the root of the widget (a localized folder not at the root of the widget will be treated as an arbitrary folder). At runtime, the widget user agent will set the (HTML or XML) base of the start file to the localized folder (even if the start file does not reside inside the localized folder). Localizing a widget resource is optional and authors should provide a start file at the root of the widget. Please be aware that if localization fails, and there is no default start file at the root of the widget, then the widget user agent will treat the widget resource as an invalid widget.

Note: See Step 6 - determine the base folder and widget locale for the algorithm to process a localized widget.

Localized Widget Example

This section is non-normative.

The following is an example of a localized widget with multiple localized icons, start files and configuration documents. Some relevant things to note from the example:

• The config.xml file at the root configures English (en/, en-gb/) and Korean versions of the widget.
• All localized instances rely on the same un-localized script (engine.js)
• The Spanish version (es/) has its own custom configuration document and icon.

/en-au/cats.html

<!doctype html>
<h1>G'day! LOL Cats!</h1>
<script src="/scripts/engine.js">
...

---

/es/gatos.html

<!doctype html>
<h1>Gatos Graciosos!</h1>
<script src="/scripts/engine.js">
...

• LOLcats.wgt
  • cats.html /*written in Korean*/
  • config.xml /*configures English and Korean*/
  • icon.png /*default icon*/
  • signature.xml /*not localizable*/
  • scripts/
    • engine.js /*used by all HTML files*/
  • locales /*container for localized content*/
    • en-gb/
      • cats.html
    • en/
      • cats.html
    • es/
      • gatos.html /*Spanish version*/
      • config.xml /*different author and license*/
      • icon.png /*localized icon*/

Conformance Checker Behavior

A CC should inform the author if they have used deprecated, grandfathered, or redundant language tags from the IANA Language Subtag Registry.

Upon encountering any localized folders named with a region or script subtag, a CC should inform the author to avoid region or script subtags.

6.6 Start file and Default Start Files

The start file of a widget resource is a file that is used by the widget user agent when the widget is instantiated. When a start file is not explicitly declared via the content element or the content element’s src attribute is in error, the start file will be one of the default start files.

A default start file is a start file that a widget user agent will attempt to locate when the start file of the configuration defaults is null (i.e., when an author omitted the content element in the configuration document or the content element is in error).

The file-name and MIME type of the default start files is given by the following table. A widget user agent is only required to support the text/html MIME type; support of other MIME types is optional.

A widget user agent will attempt to locate a file entry whose file-name matches one of the default start files based on the order they appear in the table below (from top to bottom). File names must be treated as case insensitive.

See step 9 for instructions for finding a default start file.

Author requirements: Always include at least one start file in a widget resource.

Conformance checker behavior

A CC must check that the widget resource contains at least one start file by:

1. Checking within all configuration documents that the author has used a correct content element to point to a supported file that exists within the widget package.
2. Checking for the presence of a default start file at the root of the widget and in all localized folders.

If the widget does not contain a start file, or the start file is not one that is supported, then the CC must inform the author.

6.7 Custom Icons and Default Icons

An icon is an optional file that is used to represent the widget in various application contexts (e.g. the icon that the user double-clicks to instantiate a widget, or an icon in a dock or task bar or some other visual context). There are two kinds of icons defined by this specification, custom icons and default icons.

An icon must be located either at the root of the widget or in a localized folder.

Custom Icons

A custom icon is an icon explicitly declared to be used as an icon by an author via an icon element of the configuration document. The MIME type of a custom icon is derived by the rules for identifying the MIME type of a file.

Default Icons

A default icon is an icon whose file-name case insensitively matches a file-name given in the first column of the default icons table below and whose MIME type matches the MIME type given in the second column of the table.

A default icon must be located either at the root of the widget or in a localized folder.

A widget user agent must search for a default icon’s file-name based on the order they appear in the default icons table below (from top to bottom).

As indicated by the level of support column in the default icons table below, a widget user agent is required to support the image/png and image/gif MIME types; support of other MIME types is optional.

Conformance checker behavior

If no default icon has been included, and the CC determines that no custom icons have been declared in the configuration document, a CC should inform the author that it is desirable, but optional, to include a default icon.

If a CC encounters an icon in a format either than [PNG] or [GIF89] or [GIF87], then the CC should inform the author that these formats might not be supported on all widget user agents.

6.8 Thumbnail

A thumbnail is an optional file inside the widget resource that graphically represents the widget in a running state. The thumbnail must be located either at the root of the widget or in a localized folder.

To be treated as a thumbnail by the widget user agent, the file-name of a file entry must case insensitively match one of the file-name values given in the first column of the default thumbnails table below. In addition, the MIME type must match the MIME type given in the second column of the default thumbnails table below. A widget user agent will search for a thumbnail’s filename based on the order they appear in the table below (from top to bottom).

Author requirement: it is recommended that authors use a screenshot of their widget in its running state as the thumbnail.

Conformance checker behavior

If a CC determines that the widget resource does not contain a thumbnail, it may inform the author that the inclusion of a thumbnail is desirable but, nonetheless, optional.

6.9 MIME Type

The widget MIME Type is application/widget [MIME].

Author requirement: Over the wire (e.g. over HTTP), a widget resource must be labeled with an application/widget MIME type. Failure to correctly label a widget resource will likely result in it being treated as an invalid widget.

Note: Widget user agents can support other legacy/proprietary widget types, but they must remain conforming to this specification when dealing with widget resources.

Note: The application/widget MIME type has not yet been registered with IANA. This will happen when the specification reaches Candidate Recommendation status.

6.10 File Extension

A widget file extension is the string .wgt in any case form (e.g. my.wgt, my.WGt, my.WgT, etc. are all valid).

The file extension .wgt is required for widget resources on systems where it’s customary for file names to include an extension that symbolizes the MIME type.

Author requirement: As long as the widget resource is appropriately labeled as a application/widget when the widget resource is served over HTTP, the widget file extension is not required.

7 Configuration Document

A configuration document is an [XML] document that has a widget element at its root that is in the widget namespace.

A valid configuration document file name is config.xml, in any case form. Within a widget resource, a configuration document must have a valid configuration document file name.

Configuration documents can exist either at the root of the widget or in a localized folder.

Note: Any configuration document not at the root of the widget or not in a localized folder will be treated by the widget user agent as an arbitrary resource.

Author requirement: Authors should only place configuration documents in localized folders if the content of the configuration document has been localized. It is recommended that authors always include a configuration document at the root of the widget and, for constancy, that the config.xml filename be in lowercase form.

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
        identifier="http://datadriven.com.au/exampleWidget"
        version="2.0 Beta"
        height="200"
        width="200">
  <name>The example widget!</name>
  <update href="http://www.bla.com/update.php"/>

  <description>
    A sample widget to demonstrate some of the possibilities.
  </description>
  <author href="http://foo-bar.example.org/"
    email="foo-bar@example.org">Foo Bar Corp</author>
  <icon src="icons/example.png"/>
  <icon src="icons/boo.png"/>
  <content src="index.html"/>
  <access network="true"/>
  <license>
Example license (based on MIT License)
Copyright (c) 2008 The Foo Bar Corp.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  </license>
</widget>

Note: Implementers are encouraged to expose relevant information provided by the configuration document to the user. Having “visual metadata” encourages authors to make full use of the configuration document format.

See “Step 7 for instructions on how to process a configuration document.

7.1 Namespace

The widget namespace is http://www.w3.org/ns/widgets [XMLNS].

Authoring requirements: Authors must assign the widget namespace to the widget element. Authors should be aware that, if the namespace is missing then Zip archive will be treated as an invalid widget.

7.2 Proprietary Extensions

Vendors wishing to extend the configuration document format with their own [XML] elements and attributes (or those defined in other specifications) may do so by using a separate namespace [XMLNS]. This specification does not define a model for processing XML elements outside the widget namespace. For the sake of interoperability, extensions to the configuration document are not recommended.

<widget xmlns="http://www.w3.org/ns/widgets"
   xmlns:ex="http://widgextension.org/">
       <icon src="idle.png"  ex:role="inactive"/>
       <icon src="big.png" ex:role="big"/>
       <ex:datasource>{a:"b",c:"d"}</ex:datasource>
       <content src="widget.html"/>
</widget>

7.3 Attribute Types

This section defines the different attribute types used in the configuration document and what constitutes valid values for those attribute types. Some general rules for how attributes are to be processed by widget user agents and conformance checkers are also given in this section.

Version attribute

An attribute defined as containing a valid version-tag. A valid version-tag is a string that matches the production for valid-version-tag in the following [ABNF]:

valid-version-tag  = version-identifier  *[ "." version-identifier ]
version-identifier = ALPHA / DIGIT / SP / "$" / "%" / "'" / "-" / "_"
                    / "~" / "!" / "(" / ")" / "^" / "&" / "+" / "@"
                    / "," / "=" / "[" / "]" / "/" / "" / "*" / "?"
                    / "|"/ ":"

Author Requirements: it is recommended that authors create version strings that conform to the following [ABNF]:

rec-version-tag = 1*2DIGIT ["."  1*2DIGIT [ "." 1*2DIGIT] [ ALPHA / SP / DIGIT]]

Example valid version tags:

Version 1.0 Beta, 1.0 RC1, 1.0-Build/1580, Joey the dog [5.1.2100].

Example of recommended version tags:

1.0, 1.10.1beta1, 1.02.12rc1.

Note: For the purpose of this specification, version tags have no significant semantics; they are just treated as arbitrary strings (e.g. ‘1.0′ is not greater than ‘2.0′, but is simply different). This may change in future versions of this specification.

Numeric attribute

An attribute defined as containing a valid non-negative integer. A valid non-negative integer is a string that consists of one of more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). For example, the characters “2″, “323″, “23214″, and so on.

Keyword attribute

An attribute defined as requiring a certain string value (e.g. apple or orange). The values must be specified exactly, in the case given in this specification, and with no leading or trailing space characters. Implementations must only perform literal comparisons, and must not use case insensitive comparisons nor trim attribute values before comparison.

Boolean attribute

A keyword attribute that can only be used with a valid boolean value: a valid boolean value is a string that case insensitively matches true or false. The default behavior, which is used when the attribute is omitted or has a value other than the two allowed values, is false. How a widget user agent is supposed to interpret a boolean attribute is described when the term is used.

MIME type attribute

An attribute defined as containing a valid MIME type. A valid MIME type is one that matches the production for valid-MIME-type in the following [ABNF]:

valid-MIME-type = type "/" subtype *(";" parameter)

The type , subtype, and parameter tokens are defined in [RFC2045].

URI attribute

An attribute defined as containing a valid URI. A valid URI is one that matches the URI token of [URI] or the IRI token of [RFC3987].

Path attribute

An attribute defined as containing a valid path. A valid path is one that matches the path token of [URI]. A path can be either absolute, meaning that it is already resolved to the root of the widget (e.g. “/images/bg.png”) or relative, meaning that it is resolved relative to some folder in the widget resource.

Window mode attribute

This feature is at risk! A keyword attribute whose value is one of the following valid window modes: application, floating, fullscreen, docked.

xml:lang attribute

A keyword attribute defined as containing a basic language range, defined in [BCP47], from the IANA Language Subtag Registry.The [XML] specification defines the xml:lang attribute and its influence on child elements that are XML text content. Widget user agents are not required to validate language ranges against the IANA Language Subtag Registry.

Author requirements: Authors should avoid subtags from the IANA Language Subtag Registry marked as deprecated, grandfathered, or redundant.

its:dir attribute

A keyword attribute defined as containing a valid its:dir value (i.e., ltr, or rtl, or lro, or rlo). To use the its:dir attribute, the its namespace (see [ITS]) must be declared on the element where it is used or somewhere in the element’s ancestor chain.

7.4 The widget Element

The widget serves as a container for the other elements; as such, it must be used.

Context in which this element must be used:

This is the root element of a configuration document.

Expected children (in any order):

name: zero or one.

description: zero or one.

icon: zero or more.

access: zero or one.

author: zero or one.

license: zero or one.

content: zero or one.

update: zero or one.

feature: zero or more.

Attributes

id

Optional. A valid URI that denotes a identifier for the widget.

version

Optional. A valid version-tag that specifies the version of the widget.

height

Optional. A valid non-negative integer greater than 0 that controls the initial height dimensions of the instantiated widget in CSS pixels [CSS21]. When the value is missing, the widget user agent will assume the value 300.

width

Optional. A valid non-negative integer greater than 0 that controls the initial width dimensions of the instantiated widget in CSS pixels [CSS21]. When the value is missing, the widget user agent will assume the value 150.

mode

This feature is at risk! Optional. A valid window mode. When the value is missing, the widget user agent will assume the value default.

xml:lang

Optional. A basic language range.

Note: The width and height attributes are only relevant to widgets with a visual output.

Usage Example

This section is non-normative.

The following example shows how the widget element can be used. It also demonstrates the use of the xml:lang attribute.

<widget xmlns="http://www.w3.org/ns/widgets"
        id="http://datadriven.com.au/exampleWidget"
        version="2.0 Beta"
        height="200"
        width="200"
        xml:lang="pt">
  <description>este é um exemplo das possibilidades!</description>
</widget>

7.5 The name Element

The name element represents a human-readable name for a widget resource that can be used, for example, in an application menu or in other contexts.

Context in which this element may be used:

In a widget element.

Content model:

Any.

Occurrences:

Zero or one.

Attributes

xml:lang

Optional. A basic language range.

its:dir

Optional. A valid its:dir value.

Usage Example

This section is non-normative.

The following example shows the usage of the name element.

<widgets xmlns="http://www.w3.org/ns/widgets">
   <name xml:lang="pt">Boletim Metereológico</name>
</widget>

7.6 The description Element

The description element represents a human-readable description of the widget.

Context in which this element may be used:

In a widget element.

Content model:

Any.

Occurrences:

Zero or one.

Attributes

xml:lang

Optional. A basic language range.

its:dir

Optional. A valid its:dir value.

Usage Example

This section is non-normative.

An example usage of the description element.

<widgets xmlns="http://www.w3.org/ns/widgets">
  <name>Tornado Chaser</name>
  <description>
Combining the latest weather info with your GPS position,
this widget alerts you of any significant storm activity in your
area. When a big one hits, the widget plots the best route on a map based
on the storm's trajectory so you can chase it! With support for
built-in cameras, you can quickly upload all the meteorological action to
your blog or to the insane storm chaser web site! Awesome!
  </description>
</widget>

7.7 The author Element

An author element represents people or an organization attributed with the creation of the widget.

Context in which this element may be used:

In the widget element.

Content model:

Any.

Occurrences:

Zero or one.

Attributes

href

Optional. A URI attribute that represents a link that is associated with the author (e.g. the homepage of the author).

email

Optional. A string that represents an email address associated with the author.

xml:lang

Optional. A basic language range.

its:dir

Optional. A valid its:dir value.

Usage Example

This section is non-normative.

The following example shows the expected usage of the author element.

<widgets xmlns="http://www.w3.org/ns/widgets">
        <name>Cup-a-Joe's Cafe Finder Widget</name>
        <author href  = "http://cup-a-joes-website-visit-us.com"
                email = "joe@cup-a-joes-website-visit-us.com">
          Joey and Princesa Bacalhau
        </author>
</widget>

7.8 The license Element

The license element represents an end-user license agreement or a copyright statement for the widget.

Context in which this element may be used:

In the widget element.

Content model:

Any.

Occurrences:

Zero or one.

Attributes

href

Optional. A valid URI that points to a representation of a software and/or content license. When the href attribute is present, the widget user agent should allow users the ability to view or otherwise access the referenced license.

xml:lang

Optional. A basic language range.

its:dir

Optional. A valid its:dir value.

Usage Example

This section is non-normative.

This example shows the expected usage of the license element’s href attribute.

<widgets xmlns="http://www.w3.org/ns/widgets">
  <license href="http://creativecommons.org/licenses/by/3.0/">
        Creative Commons Attribution License
  </license>
</widget>

This example shows the expected usage of the license element when the href attribute is omitted.

<widgets xmlns="http://www.w3.org/ns/widgets">
  <license>
  Copyright (c) 2008 The Foo-Bar Corporation
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  USE OR OTHER DEALINGS IN THE SOFTWARE.
   </license>
</widget>

7.9 The icon Element

The icon element represents a custom icon for the widget. A widget user agent should expose a custom icon in a way that it is visible to the end user.

Context in which this element may be used:

In the widget element.

Content model:

Empty.

Occurrences:

Zero or more.

Attributes

src

Required. A valid path that points to an image file inside the widget resource.

width

Optional. A valid non-negative integer greater than 0 that represents the width of the icon in CSS pixels [CSS21]. This attribute is only applicable to graphic formats that have no intrinsic width or height (e.g., SVG). If the file pointed to by the src is a supported raster graphic, this value may be ignored by the widget user agent. If the file pointed to by the src is a vector graphic format, then this value will be used.

height

Optional. A valid non-negative integer greater than 0 that represents the height of the icon in CSS pixels [CSS21].This attribute is only applicable to graphic formats that have no intrinsic width or height (e.g., SVG). If the file pointed to by the src is a supported raster graphic, this value may be ignored by the widget user agent. If the file pointed to by the src is a vector graphic format, then this value will be used.

Author requirement: Authors should not use the width and height attributes for raster graphic formats (as the values will be ignored).

Usage Example

This section is non-normative.

This example shows the expected usage of the icon element. The example declares three icon elements, two of which are raster and one of which is an [SVGTiny] file. The raster graphics would be used for display contexts smaller than 256×256 pixels. Tree order of the elements is irrelevant.

<widgets xmlns="http://www.w3.org/ns/widgets">
  <icon src="icons/medium.png"/>
  <icon src="icons/big.svg" width="256" height="256"/>
  <icon src="icons/tiny.png"/>
</widget>

7.10 The access Element

The access element indicates, through its attributes, what kind of security permissions are afforded to the widget by the widget user agent. When the access element is absent, a widget user agent must deny access to networked resources and to plugins.

Context in which this element may be used:

In the widget element.

Content model:

Empty.

Occurrences:

Zero or one.

Expected children:

none.

Attributes

network

Optional. A boolean attribute that indicates that the widget might need to access network resources as specified in [Widgets-Security].

plugins

Optional. A boolean attribute that indicates that the widget might need browser plugins (such as Flash or Java) to function. Plugin means a runtime component that is not bound to the security model of a widget user agent. In other words, a plugin operates under its own security model and policies (e.g., Flash and Java applets).

Note: Widget user agents are not required to support, or otherwise implement, proprietary plugins.

Conformance checkers requirements: If the access element is used, at least one of its attributes must be used.

Usage example

This section is non-normative.

This example shows the expected usage of the access element. Assume the flash_version.html file combines Adobe Flash and HTML content.

<widget
  xmlns ="http://www.w3.org/ns/widgets"
  width ="400"
  height="500">
  <name>Flight Tracker</name>
  <access network="true" plugins="true"/>
  <content src="flash_version.html"/>
</widget>

7.11 The content Element

The content element is used by an author to declare which start file the widget user agent will use when it instantiates the widget.

Context in which this element may be used:

In the widget element.

Content model:

Empty.

Occurrences:

Zero or one.

Attributes

src

Required. A path attribute that allows an author to point to a file within the widget resource.

type

Optional. A MIME Type attribute that indicates the MIME type of the file referenced by the src attribute. When the value is missing, the widget user agent will assume the value text/html.

charset

Optional. A keyword attribute that denotes the character set of the file identified by the src attribute. The allowed values are any name of a character set listed in [IANA-Charsets] (widget user agents are only required to support UTF-8). When the value is missing, the widget user agent will assume the value UTF-8.

Usage example

This section is non-normative.

This example shows the expected usage of the content element.

<widgets xmlns="http://www.w3.org/ns/widgets">

  <content src="myWidget.html"/>
</widgets>

This example shows the content element being used with a charset attribute to override the default value of this attribute (UTF-8) with the GB2312 character set, which the author has used to encode simplified Chinese characters.

<widgets xmlns="http://www.w3.org/ns/widgets">
  <name xml:lang="zh-cn">古老瓷地图</name>
  <content src="china-maps.html" charset="GB2312"/>
</widgets>

This example shows the content element being used with a type attribute to instantiate a widget created with a proprietary MIME type.

<widgets xmlns="http://www.w3.org/ns/widgets">
  <name>Location-Based Games Finder</name>
  <content src="lbg-maps.swf" type="application/x-shockwave-flash"/>
  <access network="true" plugins="true"/>
</widgets>

7.12 The update Element

The update element points, via the href attribute, to an update description document (see [Widgets-Updates]). The update description document is processed by the widget user agent to check for the availability of an updated version of the widget.

Context in which this element may be used:

In the widget element.

Content model:

Empty.

Occurrences:

Zero or one.

Attributes

href

Required. A URI attribute that indicates the location of an update description document as described in [Widgets-Updates].

Usage example

This section is non-normative.

This example shows the expected usage of the update element.

<widget xmlns   = "http://www.w3.org/ns/widgets"
        id      = "http://example.com/myWidget"
        version = "1.0">
  <update
   href="http//example.com/update.php?widget=myWidget&amp;version=1.0"/>
</widget>

7.13 The feature Element

The feature is used by an author to denote that, at runtime, a widget may require access to a feature. A feature is a runtime component (e.g. an API) that is not part of the standard set provided by the Widgets 1.0 family of specifications.

When a feature element is nested inside another feature element, it denotes a fallback relationship: if the feature identified by the outermost element is unavailable, then the widget user agent will check for the availability of the feature identified by the child’s element’s name attribute.

Note: the feature element is not a means to import javascript libraries or other resources available on the Web. The feature element should be viewed as a standardized way to request the binding of an (URI) identifiable runtime component to a widget for use at runtime.

Context in which this element may be used:

In the widget element or in the feature element.

Occurrences:

Zero or more.

Expected children:

feature: Zero or one.

Attributes

name

Required. A URI attribute that identifies a feature required by the widget at runtime (such as an API).

required

Optional. A boolean attribute that indicates that this feature or a feature identified in a child feature element must be available to the widget at runtime.

Usage example

This section is non-normative.

<widget xmlns="http://www.w3.org/ns/widgets">
   <feature name="urn:proprietary.camera.api" required="true">
      <!-- can't find it? use the alternative one -->
      <feature name="http://w3.org/apis/camera"/>
   </feature>
</widget>

7.14 Window Modes

Warning: Feature at risk! This specification does not define the semantics of the window modes. We seek input regarding what, if anything, should be specified in this spec versus what should be left as an implementation detail. The widget element’s mode attribute and associated window modes will be dropped without substantial evidence that they are needed.

7.15 Indicating Text Directionality with <its:span>

Although it is optional for a widget user agent to implement [ITS], it is recommended that authors use the <its:span> element to indicate the directionality of arbitrary content when needed. Directionality is indicated by either using the dir attribute, with one of the following valid its:dir values, as defined in ITS:

ltr

Left to right text.

rtl

Right to left text.

lro

Left-to-right override.

rlo

Right-to-left override.

<widget
   xmlns="http://www.w3.org/ns/widgets"
   xmlns:its="http://www.w3.org/2005/11/its">
  <name>Yay for the
  "<its:span dir="rtl">متعة الأسماك!</its:span>" Widget</name>

  <description its:dir="rtl">متعة الأسماك! </description>
</widget>

The its:dir attribute and the <its:span> element can be used as a child of the following elements of the configuration document:

• name
• description
• author
• license

8 Steps for Processing a Widget Resource

Note: The following steps and associated parsing rules are written with more concern for clarity than efficiency. As such, user agents may optimize any of the parsing rules and the steps, or may perform the steps in a different order, so long as the end result is indistinguishable from the result that would be obtained by following the specification.

The steps for processing a widget resource involves ten steps that a widget user agent must follow, in sequential order, responding accordingly if any of the steps result in an error. The procedures for what to do when an error is encountered are described as part of each step; however, there are times when it will not be possible for the widget user agent to recover from an error and it will be forced to treat the widget as an invalid widget. What to do in a situation when a widget user agent encounters and invalid widget is described below.

Once a widget resource has been successfully processed, a widget user agent may install and instantiate the widget resource as described in [Widgets-Security].

8.1 Dealing with Invalid Widgets

This section describes what to do in the event a widget user agent needs to treat a Zip archive as an invalid widget.

In the event that an implementation encounters an invalid widget during the steps for processing a widget resource, the widget user agent must abort all processing of the steps for processing a widget resource and may inform the end-user with an appropriate localized error message (see example in the note below). The wording of an appropriate localized error message is left to the discretion of implementers; however, their presence is nonetheless recommended.

An example of an appropriate error dialog would be “This widget cannot be installed because it was created using an unsupported compression method.”

8.2 Extracting the File Data from a File Entry

When processing a widget resource, a widget user agent will have to decompress (or otherwise extract) the file data of file entry into its original representation. Specifying exactly how to extract file entries from a Zip archive is beyond the scope of this specification. Instead, implementers must follow the processing rules defined in the [ZIP] specification to extract file entries for Zip archive.

A widget user agent is not required to extract all the file entries in a Zip archive at the same time. It may extract specific file entries as they are needed for processing or rendering.

Note: As a security precaution, implementations are discouraged from extracting file entries from untrusted widgets directly onto the file system. Instead, implementations should consider a virtual file system or mapping to access files inside a Zip archive.

Step 1 - Acquire a Potential Zip Archive

Step 1 involves acquiring a potential Zip archive and checking if it is a Zip archive by using the rules for determining if a potential Zip archive is a Zip archive. A widget user agent will acquire a potential Zip archive from a data transfer protocol that either labels resources with a [MIME] type (e.g. [HTTP]) or from a data transfer protocol that does not label resources with a [MIME] type (e.g., BitTorrent, Bluetooth, etc.).

An implementation is not required to acquire all the bytes of a potential zip archive before applying the rules for determining if a potential Zip archive is a Zip archive. It may perform the check once it has acquired the first four bytes of the resource.

Acquisition of potential Zip archive labeled with a MIME type

When attempting to acquire a potential Zip archive over some protocol that labels resources with a MIME type, a widget user agent must only attempt to process resources labeled with the widget MIME type (application/widget) regardless of file extension or no file extension. Unless the widget user agent supports legacy or proprietary MIME types, all other MIME types are in error and the widget user agent must treat the potential Zip archive as an invalid widget.

For example, in [HTTP], where the Content-Type header matches application/widget.

If the protocol used for acquisition of a potential Zip archive does not provide, or otherwise include a MIME type, then a widget user agent may treat the acquired potential Zip archive as if it has been acquired from a protocol that does not label resources with a MIME type.

Acquisition of potential Zip archive not labeled with a MIME type

A widget user agent must attempt to process a resource regardless of the file extension (including situations when there is no file extension) by applying the rules for determining if a potential Zip archive is a Zip archive.

Rules for Determining if a potential Zip archive is a Zip archive

The rules for determining if a potential Zip archive is a Zip archive is as follows.

If the first four bytes of the potential Zip archive do not match the magic numbers for a Zip archive (50 4B 03 04) then a widget user agent must treat the resource as an invalid widget. Otherwise, the widget user agent must treat the potential Zip archive as a Zip archive.

With the Zip archive, the widget user agent must verify the Zip archive and its file entries.

Step 2 - Verify the Zip archive and its File Entries

To verify that a Zip archive and its file entries conform to this specification, a widget user agent must perform the following checks. This specification does not provide the technical details of how to actually perform the checks. Instead, implementers must follow the [Zip] specification.

The potential widget resource can be considered verified only once the checks below have been completed.

If any of the following conditions occur/apply (indicating that a condition is met), then a widget user agent must treat the Zip archive is an invalid widget:

1. The zip archive is split into multiple files or spans multiple volumes [ZIP].
2. The Zip archive is encrypted (which is denoted by general purpose bit 0 being set and by the presence of archive decryption header and an archive extra data record [ZIP]).
3. The Zip archive is digitally signed using any of the digital signature methods defined in [ZIP].
4. The Zip archive contains zero file entries.
5. The Zip archive contains only folders.

Next, for each file entry in the Zip archive, the widget user agent must perform the following checks. If any of the following conditions occur/apply (indicating that a condition is met), then the widget user agent must treat the Zip archive as an invalid widget. For each file entry in the Zip archive, check the following data from the local file header:

1. The value of the CRC-32 field (defined in [ZIP]) fails a CRC-32 check.
2. The version needed to extract is greater than 20 (meaning the archive is using a feature unsupported by this specification, such as Zip64).
3. The value of the compression method field is not one of the valid compression methods (0 or 8).
4. The file name field is an empty string.
5. The file name field contains reserved characters.
6. The file name field is a sequence exclusively composed of (one or more) space characters or a mixed sequence of space characters and U+002E FULL STOP (”.”) (e.g. ” . . “).
7. The file name field is not a valid Zip relative path.
8. There two are resources whose file name fields, upon normalization, case insensitively match (’images/BG.png‘ and ‘iMaGeS/bG.pNg‘ are considered canonically equivalent)

A widget user agent must now set the configuration defaults (step 3).

Step 3 - Set the Configuration Defaults

Widget user agents must assume the following configuration defaults at this point of processing:

Once the above configuration defaults have been set, a widget user agent must attempt to locate digital signatures for the widget (step 4).

Step 4 - Locate Digital Signatures for the Widget

The algorithm to locate digital signatures for the widget is as follows:

1. Let signatures be an empty list.
2. For each file entry in the Zip-archive, if the file name field case insensitively matches the naming convention for digital signatures, append this file entry to the list of signatures.
3. If signatures is empty, terminate this algorithm and go to step 6.
4. Otherwise, sort the list of signatures by the file name field in descending order (i.e. signature001.xml followed by signature9.xml followed by signature.xml).
5. Go to Step 5 and process the digital signatures.

Step 5 - Process the Digital Signatures

The following algorithm describes how to process the list of signatures created in step 4.

Note: How a widget user agent uses a digital signature is determined by the security policy implemented by that widget user agent. As such, this specification does not mandate processing rules dependent on the verification of one or more digital signature documents or on the revocation status obtained for the certificates associated with a verified digital signature document.

For each file entry in signatures, apply the Procedure for Verifying a Digital Signature Document in the [Widgets-DigSig] specification in the order they appear in the signatures list:

1. If the file entry is a verified digital signature, as defined in [Widgets-DigSig], set signed to true.
2. If the file entry is deemed by the [Widgets-DigSig] to be an invalid widget, then a widget user agent must treat this widget as an invalid widget.
3. If the widget user agent determines that an exit criteria, as defined in [Widgets-DigSig], has been met, terminate this algorithm and go to step 6. Otherwise, select the next file entry in the signatures list and go to 1 in this algorithm.
4. If every file entry has been processed in accordance to [Widgets-DigSig], but no exit criteria has been met, then go to step 6.

Step 6 - Determine the Base folder and Widget Locale

Before attempting to locate the configuration document, the widget user agent must check for the existence of any localized folders that match the end-user’s language preferences (as contained by the wua-language list).

This step makes use of the lookup mechanism as defined in section 3.4 of [RFC4647] (part of [BCP47]). The aim is to match, in order, one of the language ranges in the wua-language list to a localized folder in the widget resource.

The algorithm to determine the base folder and widget locale are as follows:

1. If the wua-language list is ‘empty‘, or null, or ‘i-default‘, or contains a single ‘*‘, or is a sequence of items that only contain the ‘*‘ character, then terminate this algorithm and attempt to locate the configuration document.
2. For each range in the wua-language list:
   1. If this range is a single ‘*‘, then terminate this algorithm and attempt to locate the configuration document.
   2. If this range begins with the subtag ‘*‘, then skip this range and, skipping all the steps below, repeat number 2 of this algorithm.
   3. Else if this range contains a subtag ‘*‘, remove the ‘*‘ and its preceding hyphen (U+002F) and continue (for example, ‘en-*-US‘ becomes ‘en-US‘).
   4. Let potential range be the concatenation of the string ‘localized/‘ and the range (e.g. “en-us” becomes “locales/en-us“).
   5. For each file entry in the widget resource, check if the first characters of the file name field match the potential language range (e.g., if the potential range is ‘locales/en-us‘, then ‘locales/en-us/anyfile‘ would match),
      1. If they match:
         1. Let widget locale be the value of the current range in lowercase form.
         2. Let base folder be the potential range.
         3. Terminate this algorithm and attempt to locate the configuration document.
      2. Else, remove the last subtag of the range and repeat this step 2.d. (e.g., if the range is currently “en-US”, make the range “en” and search for ‘locales/en‘).
3. If no match is made, attempt to locate the configuration document (step 7).

For example, if the wua-language list is “en-AU” and a match is made on file entry whose name is “locales/En-Au/config.xml”, then base folder would be “”locales/En-Au/”, and the widget locale would be “en-au”.

For example, if the wua-language list is “de-CH,fr-CH,it-CH” and folders included “locales/de”, “locales/fr-FR” , and “locales/IT”, then the folder “locales/de” would be matched, then base folder would be “locales/de” and the widget locale would be “de”.

Step 7 - Locate the Configuration Document

This step involves searching within the zip archive for a configuration document. The configuration document, if it exists, will be located at either the root of the widget or in a localized folder.

The algorithm to locate the configuration document is as follows:

1. Search the widget resource for a file entry whose file name field case insensitively matches the concatenation of the base folder and the string config.xml (e.g. locales/en-us/config.xml). If a match is made, set config doc to be this file entry.
2. If no match is made, search for a file entry residing at the root of the widget whose file name field case insensitively matches config.xml. If a match is made, set config doc to be this file entry.
3. If no match is made, attempt to locate the start file, otherwise process the configuration document (step 8).

Step 8 - Process the configuration document

The config doc must be processed as described in the following sub-sections. The purpose of processing the configuration document is to override the configuration defaults, which are used during instantiation and at runtime [Widgets-security]).

The main algorithm for processing a configuration document is given by the rules for processing a configuration document. To maintain interoperability across implementations, this step also makes use of the following rules for processing certain attribute types and files:

• Rules for parsing a non-negative Integer.
• Rules for removing whitespace.
• Rules for identifying the MIME type of an image.
• Rules for identifying the MIME type of a file.

Rules for Processing a Configuration Document

The rules for processing a configuration document are given in the following algorithm.

The term in error is typically used to mean that an element or attribute in a configuration document is not conforming to the rules of this specification. Rules for how an element or an attribute are to be treated when it is in error are always given when the term is used. Typically the specification will say that the erroneous DOM nodes must be ignored, meaning that the widget user agent must act as if those nodes were not present.

An element or an attribute is correct if it is not in error.

The term text node refers to any Text node, including CDATASection nodes (any Node with node type 3 or 4) as defined in [DOM3Core].

1. Let doc be the result of loading the widget config doc as a [DOM3Core] Document using a [XMLNS]-aware parser. The parser must support xml:lang, and process any occurrence of the xml:lang attribute in accordance to the [XML] specification.
2. If the document is not well-formed [XML], terminate this algorithm and treat this widget resource as an invalid widget.
3. Let root element be the documentElement of doc.
4. If the root element is not a widget element in the widget namespace, then treat this widget resource as an invalid widget.
5. Otherwise,

   it is a widget element:

   If any one of the following attributes is in error or invalid, then that attribute must be ignored. All declared attributes must be processed.

   If the id attribute is used, and it is a valid URI, then let widget id be the value of the id attribute.

   If the version attribute is used, and it is a valid version-tag, then let widget version be the value of the version attribute.

   If the height attribute is used, apply the rules for parsing a non-negative integer to its value. If the value is not in error and greater than 0, let widget height be the value of the height attribute.

   If the width attribute is used, apply the rules for parsing a non-negative integer to its value. If the value is not in error and greater than 0, let widget width be the value of the width attribute.

   If the mode attribute is used, and it is a valid window mode, then let widget window mode be the value of the mode attribute. This feature is at risk!

   If the widget element does not contain any child elements, then terminate this algorithm and go to step 9.

6. For each child element that is a direct descendent of the root element, starting from the first moving to the last in tree order, if it is:

   A name element

   If this is not the first name element, then this element and its child nodes are in error and must be ignored.

   If this is the first name element encountered, then let widget name be the result of applying the rules for getting text content to this element.

   A description element

   If this is not the first description element, then this element and its child nodes are in error and must be ignored.

   If this is the first description element encountered, then let widget description be the result of applying the rules for getting text content to this element.

   An author element

   If this is not the first author element, then this element and its child nodes are in error and must be ignored.

   If this is the first author element used, then:

   1. let author name be the result of applying the rules for getting text content to this element.
   2. If the href attribute is used, and it is a valid uri, then let author href be the value of the href attribute. Otherwise, the attribute is in error and must be ignored.
   3. If the email attribute is used, then let author email be the value of the email attribute.

   A license element

   If this is not the first license element, then this element and its child nodes are in error and must be ignored.

   If this is the first license element used, then

   1. Let widget license be the result of applying the rules for getting text content to this element.
   2. If the href attribute is used, and it is a valid uri, then let widget license href be the value of the href attribute. However, if the attribute is in error then it must be ignored.

   An icon element

   If the file identified by the src attribute is missing, or not a valid path, or corrupt, or is an unsupported MIME type, or already exists in the icons list, then this element is in error and must be ignored. Otherwise:

   1. If the a src attribute is a valid path that points to a file, apply the rules for identifying the MIME type of an image. If the MIME type is supported, then add the file entry identified by the value of the src attribute to the list of icons.
   2. If the height attribute is used, apply the rules for parsing a non-negative integer to its value. If the value is not in error and greater than 0, make the value of the height attribute a property of this file entry.
   3. If the width attribute is used, apply the rules for parsing a non-negative integer to its value. If the value is not in error and greater than 0, make the value of the width attribute a property of this file entry.

   A content element

   If this is not the first content element, then this element and its child nodes are in error and must be ignored.

   If this is the first content element and it has a src attribute that is a valid path that points to a file, then check if the file is supported by the widget user agent by applying the rules for identifying the MIME type of a file. If the file is supported, let the widget start file be the file entry referenced by the src attribute. If the src attribute is missing, or in error, then a widget user agent must treat the widget resource as an invalid widget.

   If the type attribute is used and there is a correct src attribute, and it is a valid MIME type that is supported, then let the start file content-type be the value of the type attribute. If the MIME type is invalid, or unsupported by the widget user agent, then a widget user agent must treat the widget resource as an invalid widget. Otherwise, the attribute is in error and must be ignored.

   If the charset attribute is used and there is a correct src attribute, and it is an encoding that is supported by the widget user agent, then let the start file encoding be the value of the charset attribute. If the encoding is invalid, or unsupported by the widget user agent, then a widget user agent may use the default encoding (UTF-8) or treat the widget as an invalid widget. Otherwise, the attribute is in error and must be ignored.

   A feature element

   If the name attribute is not a valid URI, then this element is in error and must be ignored.

   If the name attribute is a valid URI, then normalize the value of the name attribute using [URI] normalization. If upon [URI] normalization the feature identified by the name attribute is supported by the widget user agent, then add the normalized value of the name attribute to the list of features. Otherwise, the attribute is in error and the element must be ignored.

   An access element

   If this is not the first access element, then this element and its child nodes are in error and must be ignored.

   If this is the first access element and if the network attribute is used, and it is a valid boolean value, then let allow network be the value of the network attribute. Otherwise, the attribute is in error and must be ignored.

   If this is the first access element and if the plugins attribute is used, and it is a valid boolean value, then let allow plugins be the value of the plugins attribute. Otherwise, the attribute is in error and must be ignored.

   An update element

   If this is not the first update element, then this element and its child nodes are in error and must be ignored.

   If this is the first update element used and the href attribute is used, and it is a valid uri, then let update href be the value of the href attribute.

   A Comment node, or a ProcessingInstruction node, or a Text node that only contains space characters, or a CDATASection node that only contains space characters, or anything else:

   This is in error and must be ignored.

7. Once all the elements have been processed go to step 9.

Rules for Getting Text Content

The rules for getting text content are given in the following algorithm. The algorithm always returns a string, which may be empty.

Let input be the element to be processed.

1. Let result be an empty string.
2. If the widget user agents supports [ITS]:
   1. If the element has the dir attribute from the [ITS] namespace with a valid its:dir value, then process its text nodes in accordance to the [ITS] specification.
3. Ignoring any Text nodes that only contain space characters, or CDATASection nodes that only contain space characters, let result be the concatenation of the input’s text nodes, in document order, as a string:
   1. If the node is an element that contains any Text nodes, recursively apply the rules for getting text content to that element and concatenate the returned value to result.
4. While position doesn’t point past the end of input, append character to the end of result and let position become the character in input.
5. Return result.

<widget xmlns="http://www.w3.org/ns/widgets">
   <name>
     The <blink>Awesome</blink>
     <author email="dude@example.com">Super <blink>Dude</blink></author>
     Widget</name>
</widget>

Rules for Parsing a Non-negative Integer

The rules for parsing a non-negative integer are as given in the following algorithm. When invoked, the steps must be followed in the order given, aborting at the first step that returns a value. This algorithm will either return zero, a positive integer, or an error. Leading spaces are ignored. Trailing spaces and any trailing garbage characters are ignored.

1. Let input be the string being parsed.
2. Let result have the value 0.
3. Let input be the result of applying the rules for removing whitespace on input.
4. If the length of input is 0, return an error.
5. Let position be a pointer into input, initially pointing at the start of the string.
6. Let nextchar be the character in input at position.
7. If the nextchar is not one of U+0030 (0) .. U+0039 (9), then return an error.
8. If the nextchar is one of U+0030 (0) .. U+0039 (9):
   1. Multiply result by ten.
   2. Add the value of the nextchar to result.
   3. Increment position.
   4. If position is not past the end of input, go to step 6.
9. Return result.

Rules for Removing Whitespace

The rules for removing whitespace are as given in the following algorithm. As with the previous algorithms, when this one is invoked, the steps must be followed in the order given, aborting at the first step that returns a value. This algorithm returns a string with all space characters removed.

1. Let input be the string to be parsed.
2. Let result be the empty string.
3. While position doesn’t point past the end of input and the character at position is not one of the space characters, append character to the end of result and let position become the character in input.
4. Return result.

Rules for Identifying the MIME type of an Image

The rules for identifying the MIME type of an image are given by the following algorithm. Widget user agents are required to support the MIME types given in the table below, except for image/svg+xml, which is optional.

1. If the file entry has a file extension, attempt to match the file extension to one in the first column in the image identification table. If there is a match, then return the MIME Type value and terminate this algorithm.
2. If the file entry has no file extension, if the first bytes of the decompressed file entry’s data field matches one of the byte sequences in the bytes in hexadecimal column of the following table, then return the MIME type in the corresponding cell in the second column on the same row. Otherwise, return unknown/unknown.

Rules for Identifying the MIME Type of a file

The rules for identifying the MIME type of a file are given by the following algorithm. Widget user agents are required to support the MIME types given in the table below.

1. If the file entry has a file extension, attempt to match the file extension to one in the first column in the file identification table. If there is a match, then return the MIME Type value.
2. If there is no file extension, the MIME type of a file can be sniffed by using the rules set forth in [HTML5]’s section on determining the type of a resource. To reduce the risk of exposing the end-user to malicious attacks, those rules must be followed by a widget user agents exactly as specified in [HTML5].

Step 9 - Locate the Start File

This step involves finding and verifying the start file.

1. If the widget start file is not null, terminate this algorithm and go to step 10.
2. If the widget start file is null, then try to find one of the default start files in the base folder.
3. If none is found, and the base folder is not the root of the widget, attempt to find one of the default start files at the root of the widget. If none are found, then treat this widget resource as an invalid widget.
4. If one of the default start files is found, let the widget start file be the file entry of that default start file.
5. If the start file is not null, check that it is a correct file of a supported MIME Type.

Step 10 - Locate the default icons and thumbnail

A widget user agent must search for an icon’s file name based on the order they appear in the default icons table (from top to bottom).

1. Search for any of the default icons that reside in the base folder.
2. If the base folder is not the root of the widget, attempt to find default icons at the root of the widget.
3. For each default icon found, if the default icon file entry does not exist in the icons list, then add the file entry to the list of icons.

A widget user agent must search for a thumbnail’s file name based on the order they appear in the default thumbnails table (from top to bottom).

1. Search for any of the default thumbnails that reside in the base folder.
2. If the base folder is not the root of the widget, attempt to find default thumbnails at the root of the widget.
3. If the filename field of a file entry matches one of the file name’s from the default thumbnails table, then let widget thumbnail be the matching file entry.

The link type “widget” indicates that a link of this type references a document that is a widget resource. In HTML, it may be specified for the a, area and link elements to create a hyperlink.

<a rel="widget"
   href="http://example.org/exampleWidget">The Example Widget</a>

RelaxNG Schema for the Configuration Document

This section is non-normative.

This schema may be out of date, we only update it prior to publication. You can get the latest draft from http://hasather.net/widgets/widgets.rnc.

The following is the RelaxNG schema representation of the elements and attributes of the configuration document. Products that check the conformance of widget resources or configuration documents can use this schema to validate configuration documents.

# Widgets 1.0 (Working Draft) RELAX NG schema
# Latest draft at http://hasather.net/widgets/widgets.rnc
default namespace widgets = "http://www.w3.org/ns/widgets"
namespace its = "http://www.w3.org/2005/11/its"
namespace local = ""

start = elem.widget

elem.widget = element widget {
  attr.xmllang?,
  attribute id { xsd:anyURI }?,
  attribute version { text }?,
  attribute height { data.positiveNumber }?,
  attribute width { data.positiveNumber }?,
  attribute mode { "application" | "fullscreen" | "floating" | "docked" }?,
  ( elem.name?
  & elem.description?
  & elem.icon*
  & elem.access?
  & elem.author?
  & elem.license?
  & elem.content?
  & elem.update?
  & elem.feature*
  & extension )
}

elem.name = element name {
  attr.xmllang?,
  attr.itsdir?,
  extension
}

elem.description = element description {
  attr.xmllang?,
  attr.itsdir?,
  extension
}

elem.icon = element icon {
  attr.allowed*,
  attribute src { xsd:anyURI },
  attribute height { data.positiveNumber }?,
  attribute width { data.positiveNumber }?,
  empty
}

elem.access = element access {
  attr.allowed*,
  attribute network { data.boolean }?,
  attribute plugins { data.boolean }?,
  attribute files { data.boolean }?,
  empty
}

elem.author = element author {
  attr.xmllang?,
  attr.itsdir?,
  attribute href { xsd:anyURI }?,
  attribute email { xsd:string { pattern=".+@.+" } }?,
  extension
}

elem.license = element license {
  attr.xmllang?,
  attr.itsdir?,
  attribute href { xsd:anyURI }?,
  extension
}

elem.content = element content {
  attr.allowed*,
  attribute src { xsd:anyURI },
  attribute type { text }?,
  attribute charset { text }?,
  empty
}

elem.update = element update {
  attr.allowed*,
  attribute href { xsd:anyURI }?,
  empty
}

elem.feature = element feature {
  attribute name { xsd:anyURI },
  attribute required { data.boolean }?,
  ( elem.feature?
  & extension )
}

extension = ( attr.allowed | anyElement )*
anyElement = ( element * - widgets:* { any } | text )*
any = ( attribute * { text } | anyElement )*

attr.allowed = attribute * - (local:* | xml:lang | its:dir) { text }
attr.xmllang = attribute xml:lang { xsd:language }
attr.itsdir = attribute its:dir { "ltr" | "rtl" | "lro" | "rlo" }

data.positiveNumber = xsd:string { pattern="[1-9]d*" }
data.boolean = ( string "true" | string "false" )

Acknowledgements

Special thanks go to Arve Bersvendsen, Anne van Kesteren and Charles McCathieNevile who helped edit the initial version of this specification.

Special thanks also to David Håsäther for creating and maintaining the RelaxNG Schema for the configuration document.

A huge thanks to Bárbara Barbosa Neves for her patience and for doing last minute proof-reads in the dead of night.

Parts of this document reproduce text and behavior from the HTML5 specification and from the XBL 2.0 specification (as permitted by both specifications by their copyright statements).

Graphic icons used some examples of this specification were created by Yusuke Kamiyamane and are available for use under a Creative Commons Attribution 3.0 license.

The editor would also like to thank the following people for their contributions to this specification:

• Addison Phillips
• Alexander Dreiling
• Arun Ranganathan
• Arthur Barstow
• Brian Wilson
• Bjoern Hoehrmann
• Benoit Suzanne
• Bert Bos
• 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
• Gautam Chandna
• Geir Pedersen
• Gene Vayngrib
• Gorm Haug Eriksen
• Guido Grassel
• Ian Hickson
• Jay Sweeney
• Jere Kapyaho
• Jim Ley
• Jon Ferraiolo
• Jose Manuel Cantera Fonseca
• Jouni Hakala
• Joey Bacalhau
• Kevin Lawver
• Krzysztof Maczyński
• Lachlan Hunt
• Marc Silbey
• Mark Baker
• Mikko Pohja
• Mohamed Zergaoui
• Olli Immonen
• Philipp Heltewig
• Philip Taylor
• Stephen Paul Weber
• Tex Texin
• Thomas Landspurg
• Yang Wong
• Zachary Fitz-Walter

Normative References

[ABNF]

RFC 5234, Augmented BNF for Syntax Specifications: ABNF. D. Crocker and P. Overell. January 2008.

[BCP47]

BCP 47, Tags for the Identification of Languages. A. Phillips (Ed.) and M. Davis (Ed.). September 2006.

[CP437]

IBM CPGID 00437. ftp://ftp.software.ibm.com/software/globalization/gcoc/attachments/CP00437.txt

[CSS21]

Cascading Style Sheets, level 2 revision 1; CSS 2.1 Specification. Bert Bos, Ian Hickson, Tantek Çelik, Håkon Wium Lie. W3C, April 2006.

[Deflate]

DEFLATE Compressed Data Format Specification version 1.3, P. Deutsch, The Internet Society, May 1996.

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

[HTML4]

HTML 4.01 Specification, D. Raggett, A. Le Hors, I. Jacobs, 24 December 1999. Latest version available at: http://www.w3.org/TR/html401

[GIF87]

Graphics Interchange Format. CompuServe Incorporated, June 15, 1987.

[GIF89]

Graphics Interchange Format (sm). CompuServe Incorporated, 1990.

[ICO]

Vendor Tree - vnd.microsoft.icon. S Butcher. 3 September, 2003. IANA Media Type Assignment. http://www.iana.org/assignments/media-types/image/vnd.microsoft.icon

[ITS]

Internationalization Tag Set (ITS) Version 1.0, C. Lieske and F. Sasaki, W3C Recommendation 03 April 2007. Available at http://www.w3.org/TR/2007/REC-its-20070403/

[JPEG]

ISO/IEC 10918. Information Technology Digital Compression And Coding Of Continuous-tone Still Images International Organization for Standardization (ISO).

[HTTP]

RFC 2616, Hypertext Transfer Protocol — HTTP/1.1. R. Fielding, et al. June 1999.

[HTML5]

HTML 5 (work in progress), I. Hickson, D. Hyatt, editors. W3C, 2008.

[IANA-Charsets]

IANA Character Set Registry, http://www.iana.org/assignments/character-sets

[MIME]

RFC 2045, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed and N. Borenstein. November 1996.

[PNG]

Portable Network Graphics (PNG) Specification (Second Edition), David Duce, ed., 10 November 2003.

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. March 1997.

[RFC2822]

Internet Message Format. P. Resnick. April 2001.

[RFC3987]

RFC 3987, Internationalized Resource Identifiers (IRIs). M. Duerst, M. Suignard. January 2005.

[RFC2045]

RFC2045, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, N. Freed. November 1996.

[RFC4647]

RFC4647. Matching of Language Tags, A. Phillips and M. Davis. September 2006.

[SVGTiny]

Mobile SVG Profiles: SVG Tiny and SVG Basic. W3C Recommendation 14 January 2003.

[Unicode]

The Unicode Consortium. The Unicode Standard, Version 5.0.0, defined by: The Unicode Standard, Version 5.0 (Boston, MA, Addison-Wesley, 2007. ISBN 0-321-48091-0). (See http://www.unicode.org/unicode/standard/versions for the latest version and additional information on versions of the standard and of the Unicode Character Database).

[URI]

RFC 3986, Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee, R. Fielding and L. Masinter. January 2005.

[UTF-8]

RFC 3629, UTF-8, a transformation format of ISO 10646, F. Yergeau. November 2003.

[Widgets-APIs]

Widgets 1.0: API’s and Events. A. Bersvendsen and M. Caceres. Forthcoming.

[Widgets-DigSig]

Widgets 1.0: Digital Signature. M. Caceres, Ed. W3C, W3C Working Draft 14 April 2008.

[Widgets-Security]

… forthcoming.

[Widgets-Updates]

Widgets 1.0: Updates. M. Caceres. W3C Working Draft 7 October 2008.

[XML]

Extensible Markup Language (XML) 1.0 (Third Edition). T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, F. Yergeau. W3C, February 2004.

[XMLHttpRequest]

The XMLHttpRequest Object. A van Kesteren. W3C Working Draft 15 April 2008. (Work in progress)

[XMLNS]

Namespaces in XML (Second Edition), T. Bray, D. Hollander, A. Layman, R. Tobin. W3C, August 2006. The latest version of the Namespaces in XML specification is available at http://www.w3.org/TR/REC-xml-names/

[ZIP]

.ZIP File Format Specification (Version 6.3.2, revised September 28, 2007). PKWare Inc.

Informative References

[Widgets-Landscape]

Widgets 1.0: The Widget Landscape (Q1 2008). M. Caceres. W3C Working Draft. 14 April 2008.

[Widgets-Reqs]

Widgets 1.0 Requirements, M. Caceres, Ed. W3C, July 2007.

[Widgets-Test-Suite]

… forthcoming.

[XHTML]

“XHTML 1.0: The Extensible HyperText Markup Language“, W3C Recommendation, S. Pemberton et al., 26 January 2000.
Available at: http://www.w3.org/TR/2000/REC-xhtml1-20000126

Widgets 1.0: The Widget Landscape (Q1 2008)

W3C Working Draft 14 April 2008

This version:

http://www.w3.org/TR/2008/WD-widgets-land-20080414/

Latest version:

http://www.w3.org/TR/widgets-land/

Latest Editor’s Draft:

http://dev.w3.org/2006/waf/widgets-land/

Previous version:

none.

Version history:

Twitter messages (non-editorial changes only): http://twitter.com/widgetspecs (RSS)

Editor:

Marcos Caceres, Invited Expert

Copyright © 2008 W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This document surveys a group of market-leading widget user agents with the aim to inform the requirements of the Widgets 1.0: Requirements document. The survey exposes commonalities and fragmentation across widget user agents, and discusses how fragmentation currently affects, amongst other things, authoring, security, distribution and deployment, internationalisation and the device-independence of widgets. The document concludes by making a set of recommendations on what aspects of widgets require standardization to reduce fragmentation to ultimately standardize a cross-platform widget solution.

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 W3C First Public Working Draft of the Widgets 1.0: Landscape. Once all the comments about this document will have been addressed, the Working Group intends to publish a final version of this document as a W3C Working Group Note.

The W3C Membership and other interested parties are invited to 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.

This document is produced by the Web Application Formats WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will become a Working Group Note. 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.

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.

Table of Contents

• 1. Introduction
  • 1.1 Purpose
• 2. Terms
• 3. Widgets and Widget User Agents
  • 3.1 Differences from Web Widgets
  • 3.2 Differences from Java Applets
• 4. Packaging for Distribution and Deployment
  • 4.1 Packaging Formats, file extensions and Media Types
• 5. Metadata and Configuration
  • 5.1 Metadata
    • 5.1.1 Fragmentation Issues
• 6. Authoring and Scripting
  • 6.1 APIs
  • 6.2 Widget object: properties and events
• 7. User interface and Accessibility
• 8. Instantiation
• 9. Internationalization and Localization
• 10. Digital Signatures
• 11. Automatic Updates
• 12. Device Independence
• 13. Security Models
• 14. Icons
• 15. Standardizable Aspects of Widgets
• Acknowledgments
• References
  • Related Sources

1. Introduction

This document surveys the widget landscape by examining how market-leading widget user agents address issues around:

• distribution and deployment,
• metadata and configuration,
• user interface and accessibility,
• authoring,
• internationalization and localization,
• device-independence,
• Initialization,
• automatic updates,
• and security.

The market-leading widget user agents that are included in the survey are listed below. The widget user agents were subjectively chosen because of their perceived prevalence in the market place. This survey was conducted independently of any vendor and no vendor explicitly requested they be included in the survey.

The inclusion of the widget user agents in this survey does not indicate endorsement of the standardization process by any particular vendor (in other words, just because a widget user agent appears should not be taken to mean that they will implement any part of the Widgets 1.0 specifications).

1.1 Purpose

The purpose of this document is to provide a holistic overview of the widget space and provide information to aid in standardization process of widgets by the Web Application Formats Working Group. As such, this document provides:

• A consistent set of terms that can be used throughout the standardization process, including in specifications.
• A definition of what constitutes a widget and a widget user agent for the sake of standardization (and what does not constitute a widget).
• A discussion of what role various technologies play in the lifecycle of a widget.
• Comparison matrices that clearly demonstrate fragmentation and interoperability across the widget landscape.
• A list of standardizable aspects of widgets.

2. Terms

This section defines some of the key terms related to widgets.

Widget:

For the purpose of this standardization process, a widget is an end-user’s conceptualization of an interactive single purpose application for displaying and/or updating local data or data on the Web, packaged in a way to allow a single download and installation on a user’s machine or mobile device. A widget may run as a stand alone application (meaning it can run outside of a Web browser), or may be embedded into a Web document. In this document, the runtime environment on which a widget is run is referred to as a widget user agent and a running widget is referred to as an instantiated widget. Prior to instantiation, a widget exists as a widget resource.

Widget user agent:

The user agent (software application) that hosts an instantiated widget. Generally speaking, widget user agents are either directly built on, or provide similar functionality to a Web browser. An increasing number are actually built directly on top of Web browsers so they are able to process/render HTML documents, while others incorporate Web browser components like ECMAScript interpreters. widget user agents are built for many different software platforms and devices, including Microsoft’s Windows, Apple’s MacOS, Symbian, Linux, and so on; and some widget user agents, such as the Konfabulator and Opera Widgets, run on multiple platforms.

Instantiated widget:

The runtime manifestation of a decompressed widget resource whose start file has been instantiated on a widget user agent. The instantiated widget may have been configured through a configuration document. The ability for an instantiated widget to be programmed and behave interactively is provided via a widgets API.

Icon:

An image or symbolic representation of an instantiated widget. Icons are usually used to represent the widget in non-running context, such as menus and docks. Some widget user agents, such as Konfabulator, allow authors to dynamically change the icon at runtime. For example, a weather widget might update its icon as the weather or time of day changes.

Widget resource:

A resource created from some packaging format that encapsulates the resources of a widget for the purposes of distribution and deployment. On the wire, a widget resource is identified by an arbitrary widget media type.

Media type:

An media type that formally associates a widget resource with some proprietary widget user agent. For example, Joost’s widget engines requires that widgets be served over HTTP with a application/vnd.joost.joda-archive media type.

Packaging format:

The physical data format used to create a widget resource. For example, the flat-file format described in the Konfabulator Reference or the Zip file format supported by Opera Widgets and Microsoft’s Vista Sidebar.

Resource:

Any file or directory used by an instantiated widget that resides either inside a widget resource or is accessible over HTTP. In a widget resource, resources may be organized in directories and may have versions of those directories tailored for localization purposes. Examples of resources include images, text, markup, style sheets, executable scripts, and sounds.

Start file:

A resource either inside the widget resource or on the Web that when instantiated represents the widget. If an instantiated widget contains a configuration document, the widget user agent may configure the start file through that configuration document.

Configuration document:

A distinguished resource where authors can declare metadata and/or configuration parameters for a widget. A widget user agent uses a configuration document to configure a widget upon instantiation. The configuration document may also define the relationship between resources in the widget resource. The configuration document usually takes the form of an XML file; for example, the config.xml resource bundled with an Opera widget.

Metadata:

Data declared in the configuration document about a widget that relates to authorship or classification, but does not affect the behavior of the widget at runtime (eg. the author’s name and email).

Configuration parameter:

Any declaration in the configuration document that affords the widget with functionality beyond its default behavior (eg. declaring that the widget will require network access).

Bootstrap:

A mechanism that either declaratively or automatically finds the start file in an instantiated widget.

Widget API:

A set of programming interfaces that provide functionality specific to and instantiated widget. Current APIs range extensively in the level of functionality they provide an author; see for example Microsoft’s API for accessing the operating system in the Sidebar Reference.

3. Widgets and Widget User Agents

Since around 2003, a relatively new kind of application has seen significant proliferation onto desktop computers and, more recently, web-enabled portable devices like mobile phones. This kind of application is generally referred to by developers as a widget engine: a piece of software that is able to run other smaller applications known as widgets or gadgets. On the user’s desktop, widgets have gradually taken the place of some traditional single-purpose applications. Typical examples of widgets range from simple clocks, CPU gauges, post-it notes, games, battery-life indicators, to more sophisticated web-enabled widgets like weather forecasters, news readers, email checkers, photo albums and currency converters.

There are literally thousands of unique widgets available for download on the web, which users generally collect to create personal widget inventories. These widget inventories provide users with access to online services that they commonly use. This means that, in a lot of instances, users don’t need to open up a web browser to get the information that they want (eg. to check the weather). This is an aspect of widgets that makes them particularly attractive on mobile devices, where the monetary cost of downloading web pages is currently an issue for many users.

For developers, some widgets differ from traditional binary applications in that they are created using the same open technologies used to create web pages. Widget engines mimic, in many ways, the behavior of web browsers: an increasing number are actually built directly on top of web browsers so they are able to render web pages, while others incorporate web browser components such as ECMAScript interpreters. To developers and vendors, this means that most widgets are significantly easier to create than applications developed with lower-level programming languages such as Java and C#.

Amidst the popular rise of widgets and widget engines lay a number of issues for users, developers, current vendors and new vendors wanting to enter the market. By surveying various aspects that pertain to widget user agents, this document discusses these issues so they may be resolved through the W3C standardization process.

As shown in figure 1, a widget is instantiated on a widget user agent and can make use of a number of technologies that serve a different role (eg. distribution and deployment, etc). However, some of those technologies have not yet been formally standardized (items marked with an asterisk), which has contributed to fragmentation across the widget space.

3.1 Differences from Web Widgets

Web widgets (also known as modules or badges) are fragments of HTML, CSS, and ECMAScript (or possibly an Adobe Flash movie) that are either declaratively or dynamically included into a Web document. A common example of Web widgets is one that downloads a set of icon-sized images from a photo-sharing Web site and displays those images as a slide-show based on a set of user preferences (eg. the images tagged ‘vacation Italy’); such Web widgets are commonly seen embedded into social networking Web sites and blogs. Popular providers of Web widgets include:

• Google Homepage Gadgets (iGoogle Gadgets),
• WordPress Widgets,
• and Microsoft Live Gadgets.

Unlike widgets, Web widgets a hosted on the server-side and are embedded into HTML documents prior to being served to the client. The creation of a Web widget usually involves having an author specify, in XML or some other format (eg. PHP), what the widget does and which APIs the Web widget depends on. This document is then uploaded to a server, where when it is served to a client, it is transformed into HTML, CSS, and ECMAScript. For example, the input column of the table below shows a typical iGoogle gadget specification:

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="hello world example" />
<Content type="html"><![CDATA[
<h1>Hello, world!</h1>
]]></Content>
</Module>

After being processed on the server-side, the code in the input column is transformed to HTML, CSS, and ECMAScript and inserted into the served document as either an iframe or as HTML elements (see the the Output column above). The actual code that Google generates from the example is too large to be included in this document.

Functional Differences

Because Web widgets and a widget have a reliance of Web technologies, their offer much of the same functionality. However, differences exist in:

• the packaging format,
• the security model,
• and the APIs.

In relation to the packaging format , Web widgets are generally not packaged or downloaded as a single file (except in the case of Adobe Flash movies). Instead, Web widgets are commonly dynamically instantiated through a mix of ECMAScript, HTML elements, and CSS. However, similar to a widget as described in this document, some Web widgets make use of a dynamically loaded RSS file or JSON as a configuration document format.

In relation to security models, unlike a widget, Web widgets are generally part of a HTML document’s DOM and so are bound to all the security constraints imposed by Web browsers.This means that Web widgets cannot make cross-domain requests, cannot autonomously access resources on an end-user’s device, access system-level properties like the make, model, or usage percentage of the CPU, or execute system level commands like creating or deleting files, while widgets that run on most market-leading widget user agents generally can. In other words, some widget user agents provide a more relaxed security model than the one afforded to Web widgets by Web browsers.

The ability for a widget to perform actions beyond the security scope of Web widgets is partially afforded by widget-specific APIs. For example, on Windows Vista’s Sidebar, a widget can be scripted to create a new folder on the end-user’s hard drive by calling 'System.Shell.Folder.newFolder(strNewFolderName)'. See Microsoft’s Sidebar Reference or Konfabulator Reference for more examples of API functionality that is beyond the scope of Web widgets.

Another difference is how widget user agents handle internationalization when compared to Web widgets (Web Browsers). On the Web, internationalization is sometimes handled through HTTP’s Accept-Language header: this works by allowing the Web Browser to send the end-user’s preferred language to a server (eg. Accept-Language: en-us). If the server contains a version of the desired resource in the end-user’s language of choice, then the localized resource may be returned to the end-user. A widget, on the other hand, may sometimes contained all localized resources inside the widget resource in folders named using the common language-region pattern (eg. /en-us/). When the widget is instantiated, the widget user agent attempts to match one of these specially named folders to user’s language preferences. See the Internationalization and Localization section for more information.

3.2 Differences from Java Applets

Widgets and Java applets share many commonalities. For instance, both widgets and applets rely on a pre-installed runtime engine for execution: java applets rely on the presence of the Java Runtime Environment (JRE), while widgets rely on the presence of their target widget engine. Widget and Java applets also share many similar functional aspects, like being able to do asynchronous HTTP requests to download resources from the Web.

It is argued that the most notable difference between them is that widgets are easier for authors to create than Java applets. This argument is made because widgets are created using HTML, CSS, and ECMAScript, which have very forgiving error handling and a short learning curve compared to Java. Another difference is that Java Applets are intended to run inside Web pages, while widgets as described in this document generally serve the purpose of stand-alone applications that run outside of a Web browser.

4. Packaging for Distribution and Deployment

Packaging refers to encapsulating all the necessary resources and metadata required by the widget into a single file for the purpose of distribution and deployment. Distribution and deployment refers to getting a widget from the Web to run on an user’s device as easily as possible.

4.1 Packaging Formats, file extensions and Media Types

The de facto standard for packaging widgets is the Zip file format, but with vendors requesting that their developers use a vendor specified file extension (ie. not .zip, but .widget, or .gadget, etc) when packaging their widgets.

Once a widget has been packaged for distribution, it is put onto a web server and served with an appropriate media type. The purpose of a media type is to allow a browser, for instance, to automatically associate a widget resource with the appropriate widget user agent. For example, widgets served for Operas widget engine are served with the application/x-opera-widgets media type and associated with the Opera browser. If a widget engine has correctly registered itself with the operatig system to be the program of choice to deal with a particular media type media type and/or file extension with, the web browser should automatically pass widgets to the widget engine without the end-user having to select the widget resource manually.

End-users generally acquire widget resources directly from vendors (eg. Apple, Yahoo!) who often host dedicated online galleries where users can search for widgets and where developers can submit or update widgets they have created. However, authors are free to distribute their widgets from their own web sites.

Packaging Format

The packaging format is supported widget user agent.

Compression

The compressions algorithm supported by the widget user agent.

File extension

The file extensions that associates a widget with a widget user agent.

Media type

As widgets are generally distributed via the Web, vendors usually assign them an arbitrary MIME type. The MIME type, which is usually used in conjunction with the file extension, helps a widget user agent associate the a widget with the appropriate widget user agent.

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

Interoperable Aspects

• Zip format
• Deflate compression

Fragmentation Issues

• There is no consistent file extension for widgets; each vendor uses their own unique file extension.
• Nowhere is it defined exactly which parts of the Zip specification should be supported by a widget user agent. Zip is a large specification that is constantly evolving. Zip supports multiple compression algorithms and features. If a widget is packaged using the wrong compression algorithm, it might not be interoperable with another widget engine or device. Although the issue of compression is not currently a major issue, it has the potential to become one as widgets become more prevalent on mobile devices and computers start to work natively in 64-bit.
• There is no standardized Media Type, which results in widgets served over HTTP being associated with only one kind of widget engine. One media type per widget engine results in vendor lock-in.

5. Metadata and Configuration

A widget resource will typically include a configuration document, in which an author declares metadata and/or some configuration parameters that a widget user agent may use to configure a widget upon instantiation. All market leading widget engines use XML as the preferred format for storing metadata.

XML vocabulary

The proprietary specification that defines the semantics of the elements and attributes that authors should use when marking up a configuration document.

File name

The name of the file as

Required?

Is the configuration document required for the widget user agent to instantiate the widget. This was tested by attempting to instantiate a widget without a configuration document present inside the widget resource.

Uses XMLNS

Does the configuration document require authors to declare a namespace. Also tested using a bogus namespace on the root element xmlns=”"

Conforming Parser?

Is the XML parser used by the widget user agent conformant to the XML specification and XMLNS aware?

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authorities information about any particular widget user agent, please visit the vendor’s web site.

Interoperable Aspects

• XML is the preferred format for structuring metadata.

Fragmentation Issues

• The XML dialects are all different.
• XML parsers are generally non-conforming to the XML and XMLNS specifications.

5.1 Metadata

Metadata refers to how authors store information about their widget inside the widget, and how that data is made accessible to people or machines.

In practice, the inclusion of any metadata elements is generally considered optional but is nonetheless recommended by vendors. Widget user agents generally make use of metadata elements in different application contexts such as menus, lists, and about-boxes. The most common metadata elements captured in configuration documents include:

Root element:

The element found at the root of each configuration document, which contains all other elements in the document.

Name:

The human readable name of the widget as it appears in menus or other contexts.

Unique identifier:

An author assigned unique identifier for the widget.

Version identifier:

Some string that identifies the version of the widget.

Description:

A human readable description of the widget, generally describing what it does.

Copyright:

Copyright information.

Authorship:

information about the authorship of the widget, including the author’s name, email, and the organization that they may be affiliated with

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

Interoperable Aspects

• Although element names differ, the semantics captured by elements is relatively consistent.

5.1.1 Fragmentation Issues

• There some fragmentation in regards to recording the description, authorship information and copyright.

Configuration parameters

The most common configuration parameters include:

Bootstrap:

A way to identify the start file (or main content), including a way to identify the content type of the start file (eg. type=”HTML”).

Network:

The need for a widget to access the network.

Width and height:

The initial rendering dimensions (width, height).

Plugins:

The intention to use plugins (eg. Flash and Java).

Platform:

The minimum version of the widget user agent required to run the widget.

Please note that some configuration parameters have a close relationship to the security model of widgets.

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

Interoperable Aspects

TBW

Fragmentation Issues

TBW

6. Authoring and Scripting

Authoring refers to how widgets are created, marked-up and scripted. In terms of authoring, there is a fairly congruent set of commonalities that most widget user agents share, and which authors exploit when authoring a widget: mainly their reliance on Web standards and protocols, and a strong focus on rapid development. Most widget user agents will typically support HTTP, IRIs, and Unicode, as well as ECMAScript, the DOM, and the ability to render markup languages, like HTML and CSS. Widget user agents also generally support multimedia resources, such as images, sounds, and some even video.

To make authoring of widgets possible, widget user agents provide authors with Application Programming Interfaces (APIs) that are mostly identical to those found in Web browsers, as well as APIs that provide functionality that is specific to widgets. Also, because of the rise in popularity of Ajax-style development, many widget user agents now implement the XMLHttpRequest object or some similar mechanism for making asynchronous data requests over HTTP.

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

explain functionality exclusively available to widgets (run programs, cross domain requests)

Interoperable Aspects

• All widget user agents support XMLHttpRequest.
• All but one support HTML and CSS as layout

Fragmentation Issues

• There is some limited fragmantation is regards to support of proprietary technologies, such as Flash.

6.1 APIs

TBW

Open page in browser

Open a web document in the standard system browser

Preferences

Get, set and delete user preferences

Close widget

Destroy instance of currently running widget

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

Interoperable Aspects

TBW

Fragmentation Issues

TBW

6.2 Widget object: properties and events

6.2.1 Properties of the Widget object

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

6.2.2 Events

TBW

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

Accessing the file system

TBW

Execute system level commands or open applications.

//If no callbackHandler is present, the command is executed synchronously.
//If callbackHandler is present, command is executed asynchronously. callbackHandler needs to except an argument.
CommandObject widget.system(String command, [Function callbackHandler])

interface CommandObject{
        String property outputString; //the standard out
        String errorString; //any error that was thrown
        String status. //the command's exit status

        // allows handler to receive incremental output (eg ping.)
        EventListener onreadoutput(function handler);
        function cancel(); // cancel the command
        function write(String value); //write a string to standard in
        function close(); //send (EOF) to standard in
}

void widget.openApplication(HexNum Uid, String param)

opens an S60 application in stand-alone mode. Values cannot passed back from the opened application to the widget. A widget cannot open another widget using this method.

Interoperable Aspects

TBW

Fragmentation Issues

TBW

7. User interface and Accessibility

Accessibility refers to how end-users, and those with special needs, can access the content and use the interactive elements of an instantiated widget. Most market-leading widget user agents allow widgets to be authored using HTML, CSS, and ECMAScript. HTML, when authored with care, is generally regarded to be an accessible technology whose structure and semantics are generally well understood and correctly implemented by most market-leading widget user agents. To extend It is also therefore theoretically possible for authors to make their widgets fairly accessible by applying, for example, the relevant sections of the Web Content Accessibility Guidelines (WCAG).

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

Interoperable Aspects

TBW

Fragmentation Issues

TBW

8. Instantiation

What addressing mechanism does the widget user agent support at runtime to get to resources inside the package? (ie. how does a developer address and include things like images or sounds in their widget?)

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

TBW: discusses different ways that the start file of widget is located: 1. having a preset name (eg. index.html ala Opera Widgets). Having it declared in the configuration document (ala Joost), Having it match a search pattern (ala Konfabulator)

Interoperable Aspects

TBW

Fragmentation Issues

TBW

9. Internationalization and Localization

internationalization refers to the technical aspects that allow a widget to work in multilingual contexts without requiring an author to make significant engineering changes to a widget. Localization is the processes where by a widget is adapted to use the local conventions of particular end-users (eg. using a particular dialect). To allow authors to distribute a widget to multiple locales, the majority of vendors provide guidelines explain to authors how to make effective use of internationalization mechanisms built into widget user agents. When authors follow localization guidelines, a widget user agent can use automated mechanisms to select the appropriate localized resources for a widget based on a system’s locale information; thus making it easier for authors to create localized widgets.

In the widget space, internationalization is commonly achieved in one of two ways:

• One way is to have authors place localized resources into specifically named folders that identify the language and region (eg. “/en-au/” for English Australian) of localized content. If the widget user agent can identify the end-user’s locale, and the widget package contains matching localized content, then a localized widget will be presented to the end-user.
• Another way is to have authors place localized textual content inside a specifically named text file, which is in turn placed inside specially named folders (eg. “/en-au/Localizable.strings“). Inside the text file, localized strings are identified by an unique identifier and must be formatted using a special syntax. For instance, Konfabulator uses a special syntax for localizing strings, for example:

"greeting" = "g'day mate!";
"greeting_gfx" = "/en-au/images/greet.png";

Note that this method only localizes textual content, but can be used to also identify the path or URI to localized resources. At runtime, the widget user agent makes those localized strings available via a scripting interface:

//would set the button's label to "g'day mate!"
myButton.label = widget.getLocalizedString("greeting");

myButton.style.background = widget.getLocalizedString("greeting_gfx");

When automated internationalization is not provided by a widget user agent, authors usually result to using arbitrary solutions to achieve localization. Such is the case for Opera widgets.

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

Interoperable Aspects

TBW

Fragmentation Issues

TBW

10. Digital Signatures

A digital signature is the product of applying a secret numeric key (known as a private key) and an encryption algorithm over some data to produce a unique hash value. The only way to validate a digital signature is to use a corresponding public key in a process known as asymmetric cryptography.

Although not widely supported by market-leading widget user agents, some widget user agents allow an author to digitally sign a widget resource. Digitally signing a widget resource involves calculating the hash values of all the resources inside the widget resource and encrypting those values using a unique private key that is known only to the author. The resulting data is bundled inside the widget resource with a digital certificate, which an author can obtain from a certification authority (such as VeriSign) for a charge.

A digital certificate is therefore a trust mechanism intended to verify to a user that an author really did sign the widget resource. A widget user agent can use the digital certificate to verify the authenticity and data integrity of the widget resource. In the rare case where a widget damages the end-user’s device, the digital certificate provides a user with a legal means to prove that a widget resource was signed by a particular author or publisher.

Because digital certificates can come from untrusted sources, widget user agents will include root certificates from sources that it trusts. Root certificates are explicitly trusted and are considered impossible to forge. For example, the Konfabulator is bundled with the Yahoo! root certificate which it uses to verify widgets signed by Yahoo! Inc. are in fact signed by Yahoo! Inc.

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

Interoperable Aspects

• The use of X509 certificates.

Fragmentation Issues

• General lack of support for digital signatures.

11. Automatic Updates

Automatic updates refers to a service that allows a widget user agent to automatically check if a new or different version of an installed widget resource has become available, and somehow acquire the new version and install it. Automatic updates models work by allowing authors to assign a unique identifier and version identifier to a widget resource (eg. id="http://example.com/my.wdgt" version="1.2").

To keep a widget resource up to date, the widget user agent periodically checks if a different version of a widget resource has become available on a remote server. In the case of the Konfabulator, it does this by sending an XML document that identifies the widget via an unique identifier, and what version the end-user currently has installed. If a new version of the widget resource is available on the server, the server sends back an XML file that contains a URL from where the widget user agent can acquire the latest version. The widget user agent then informs the end-user that an update to a widget has become available and if they want to perform the update. If the end-user agrees, then the widget user agent downloads the latest version of the widget resource, archives the old version, installs the new one in its place. The updated widget is re-instantiated with its preexisting preferences (eg. an updated weather forecaster widget will generally not require the end-user to re-input their preferred city after an update).

Interoperable Aspects

TBW

Fragmentation Issues

• General lack of support for automatic updates.

12. Device Independence

Need to read up on how Nokia Web Runtime recommends authors deal with migration of Dashboard widgets, etc.

Interoperable Aspects

TBW

Fragmentation Issues

TBW

13. Security Models

Security model refers to the security policies under which a widget user agent operates that either prevents or allows an instantiated widget from performing particular actions (eg. accessing the network or reading/writing files). When compared to Web browsers, some market-leading widget user agents have a comparatively relaxed security model that allows an instantiated widget to read, write, modify, and/or delete files, automatically upload files, automatically download files, execute local applications, and even perform cross-domain request to “mash-up” data from multiple different sources. All without the end-user having any indication that their privacy and security might be at risk.

The ability to perform most of the aforementioned actions is strictly forbidden in documents running in Web Browsers. Such a relaxed security model has been generally positive in the widget space with very useful and powerful widgets being developed. However, this has created an environment where users are left extremely vulnerable to malicious attacks, and serious security risks have been demonstrated. Some market-leading widget user agents, such as Opera Widgets, have a much tighter security model that adheres more closely to the security model of a Web Browser; as such, they may be less prone to serious security issues.

Need to discuss how security declarations are made using pInfo list or Opera’s security element.

Interoperable Aspects

TBW

Fragmentation Issues

TBW

14. Icons

*Although care has been take to ensure the accuracy of the information contained in this table, there is no guarantee that the information is complete, correct, or up-to-date. To obtain authoritative information about any particular widget user agent, please visit the vendor’s web site.

This section will describe how icons are used by different widget engines. It will discuss static icons (images, pngs), and dynamic icons, such as Yahoo!’s icons. Might also talk briefly about iPod/Phone icons here too, as they are dynamic.

Interoperable Aspects

PNG, GIF87/89

TBW

Fragmentation Issues

TBW

15. Standardizable Aspects of Widgets

The following list represents the aspects of a widget that members of the working group have identified as requiring standardization to reduce fragmentation in the widget space. Aspects that are currently outside the scope of the working group charter are proceeded by the text “out of scope“. To address aspects beyond the scope of the working group, the working group will require liaison with other working groups at the W3C and possibly other related consortia such as the OMA and the OAA.

Standardizable aspects of widgets include:

• Finding a suitable packaging format capable of encapsulating and structuring resources for distribution and deployment, including:
  • The relevant technical aspects of the physical packaging format that make the format interoperable across multiple platforms and mobile devices.
  • The abstract container, including required parts and hierarchies (eg. required files and folders, if any).
  • The model by which the internal structure of a widget resource can be exploited by an instantiated widget for localization purposes in internationalized contexts.
  • A means for an instantiated widget to address resources in a widget resource at runtime.
  • A file extension.
  • A MIME type to formally denote that a widget resource distributed over HTTP conforms to the Widgets 1.0: Packaging specification.
  • A widely supported digital signature format that adequately provides data security, authenticity and non-repudiation.
• The configuration document language including:
  • The structure, semantics, and processing model for a vocabulary that would make up the configuration document format.
  • Metadata elements pertaining to authorship (eg. author’s name, email, etc).
  • Metadata elements pertaining to the widget (eg. id, title, description, etc).
  • Configuration parameters (eg. width, height, network access, etc).
  • A bootstrap mechanism that allows the widget user agent to find the start file of a widget resource.
  • A model for finding a start file of a widget resource when a bootstrap is unavailable or is in error.
  • A means for distinguishing the configuration document from other resources.
  • A means to declare an alternative representation of a widget (eg. an image icon) for when a widget has not been instantiated.
• A widgets API that could be implemented by a widget user agent and made available to an instantiated widget that would allow authors to:
  • Access preferences particular to each instantiated widget.
  • Access runtime configuration properties and other relevant platform properties (out of scope).
  • Access to services particular to the device on which the widget has been instantiated (eg. camera, short message service, address book, etc) (out of scope).
  • The ability to instantiate other applications on an end-user’s device (out of scope).
  • Access metadata values that the author declared in the configuration document.
  • Capture events and access properties that are particular to each instantiated widget.
  • Control alternative runtime representations of a widget (eg. the docked representation).
• The security model/policies that determines what an instantiated widget can access while running on a end-user’s device.
• A pre-existing language to declare the user interface in an accessible manner (eg. mandating the use of HTML or some other XML vocabulary).
• A HTTP-based model for a widget user agent to check if an updated version of a widget resource has become available for download.

Standardizable aspects of widget engines include:

• TBW

Acknowledgments

The editor would particularly like to thank Corin Edwards for his help on improving the design on of figure 1.

The editor would like to thank to the following people who have contributed to this document (ordered by first name):

• Alexander Dreiling
• Anne van Kesteren
• Arthur Barstow
• Arun Ranganathan
• Benoit Suzanne
• Bert Bos
• Bradford Lassey
• Cameron McCormack
• Cliff Schmidt
• Claudio
• Coach Wei
• Corin Edwards
• Dan Brickley
• David Pollington
• Dean Jackson
• Debra Polson
• Doug Schepers
• Ed Voas
• Gene Vayngrib
• Guido Grassel
• Jay Sweeney
• Jim Ley
• Jose Manuel Cantera Fonseca
• Kevin Lawver
• Krzysztof Maczyński
• Lachlan Hunt
• Marc Silbey
• Mark Baker
• Mikko Pohja
• Philipp Heltewig
• Stephen Paul Weber
• Thomas Landspurg
• Yang Wong
• Zachary Fitz-Walter

References

Ajax

Ajax: A New Approach to Web Applications. J. J. Garrett. February 18, 2005. Adaptive Path. Available at http://www.adaptivepath.com/publications/essays/archives/000385.php

Apple pList

Introduction to Property List Programming Topics for Core Foundation, Apple Computer Inc, 7 February 2006. Available at http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFPropertyLists/index.html

CSS

Cascading Style Sheets, level 2, revision 1, B. Bos, T. Çelik, I. Hickson, and H. Wium Lie. W3C Candidate Recommendation 19 July 2007. Available at http://www.w3.org/TR/CSS21

DOM

Document Object Model (DOM) Level 1 Specification, L. Wood et al., 1 October 1998. Available at http://www.w3.org/TR/REC-DOM-Level-1

Dashboard Reference

Dashboard Reference, Apple Computer, Inc, May 2006. Available at http://developer.apple.com/documentation/AppleApplications/Reference/Dashboard_Ref/index.html

Google Gadgets

Google Desktop Sidebar Scripting API, Google Inc., 2006. Available at http://desktop.google.com/script.html

JSON

The application/json media type for ECMAScript Object Notation. D. Crockford. July 2006. Available at http://www.ietf.org/rfc/rfc4627.txt

Opera Spec

Opera Widgets Specification 1.0, A. Bersvendsen (Editor), Opera Software, 30 Apr, 2007. Available at http://oxine.opera.com/widgets/documentation/widget-configuration.html

Sidebar Reference

Windows Sidebar Reference, Microsoft Corporation, 2006. Available at http://msdn2.microsoft.com/en-us/library/aa965853.aspx

XML Internationalization and Localization

XML Internationalization and Localization. Savourel, Y. Sams Publishing, Indiana. June 2001.

Konfabulator Reference

Konfabulator Reference 4.5 Reference Manual Yahoo! Inc., April 14, 2006. Available at http://Widgets.yahoo.com/gallery/dl_item.php?item=WidgetEngineReference_3.1.1.pdf

WCAG

Web Content Accessibility Guidelines 1.0. W. Chisholm, G. Vanderheiden, and I. Jacobs. W3C Recommendation, 5 May 1999. Available at http://www.w3.org/TR/WAI-WEBCONTENT/

ECMAScript

ECMAScript Language Specification, Third Edition. ECMA, December 1999. Available at http://www.ecma-international.org/publications/standards/Ecma-262.htm

HTML

HTML 4.01 Specification, D. Raggett, A. Le Hors, I. Jacobs, 24 December 1999. Available at http://www.w3.org/TR/html401/

HTTP

Hypertext Transfer Protocol — HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk Nielsen, L. Masinter, P. Leach and T. Berners-Lee, June 1999. Available at http://www.ietf.org/rfc/rfc2616.txt

MIME Type

Multipurpose Internet Mail Extensions (MIME) Part Two: media types, N. Freed and N. Borenstein, November 1996. Available at http://www.ietf.org/rfc/rfc2046.txt.

Unicode

The Unicode Standard, The Unicode Consortium, Version 5.

XML

Extensible Markup Language (XML) 1.0 Specification (Second Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, 6 October 2000. Available at http://www.w3.org/TR/REC-xml/

XMLHttpRequest

The XMLHttpRequest object. A. van Kesteren. 2006. W3C Working Draft, Available at http://www.w3.org/TR/XMLHttpRequest/

X.509

CCITT, Recommendation X.509: The Directory Authentication Framework, 1988.

IRI

Internationalized resource Identifiers (IRIs), M. Duerst, M. Suignard. IETF, January 2005. RFC3987 is Available at http://www.ietf.org/rfc/rfc3987

Zip

.ZIP File Format Specification. PKWare Inc., September 2007. Available at http://www.pkware.com/documents/casestudies/APPNOTE.TXT

Related Sources

Light Web Applications

Setting the scope for light-weight Web-based applications. B. Bos. Work in Progress. 26 Feb 2004. Available at http://www.w3.org/People/Bos/Webapps.html

XML Packaging

XML Packaging Working Group Charter, J. Nava. W3C. Available at http://www.w3.org/XML/2000/07/xml-packaging-charter.html

Semantic Webapps

Semantic Webapps? Lightweight RDF interfaces for SVG. Sept 7, SVGOpen 2004, Japan. Available from: http://www.w3.org/2001/sw/Europe/talks/200409-svgopen/slide1-0.html

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

Copyright © 2009 W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

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.

Table of Contents

1. 1 Introduction
   1. 1.1 The Widget Family of Specifications
2. 2 Conformance
3. 3 User Agents
   1. 3.1 Dependencies on Other Specifications
4. 4 Global Definitions
5. 5 Resolving DOM Nodes
6. 6 The WindowWidget Interface
   1. 6.1 The Widget Attribute
7. 7 The Widget Interface
   1. 7.1 The currentMode Attribute
   2. 7.2 The locale Attribute
   3. 7.3 The identifier Attribute
   4. 7.4 The currentIcon Attribute
   5. 7.5 The authorName Attribute
   6. 7.6 The authorEmail Attribute
   7. 7.7 The authorURL Attribute
   8. 7.8 The name Attribute
   9. 7.9 The description Attribute
   10. 7.10 The version Attribute
   11. 7.11 The width Attribute
   12. 7.12 The height Attribute
   13. 7.13 The preferences Attribute
   14. 7.14 The setPreference() Method
   15. 7.15 The getPreference() Method
   16. 7.16 The hide() Method
   17. 7.17 The show() Method
   18. 7.18 The onmodechange Callback
   19. 7.19 The onbeforeupdate Callback
   20. 7.20 The onafterupdate Callback
   21. 7.21 The hasFeature() Method
   22. 7.22 The icons Attribute
   23. 7.23 The setIcon() Method
   24. 7.24 The openURL() Method
   25. 7.25 The getAttention() Method
   26. 7.26 The showNotification() Method
8. 8 The WidgetIcon interface
   1. 8.1 The src Attribute
   2. 8.2 The width Attribute
   3. 8.3 The height Attribute
9. Acknowledgements
10. Normative References
11. Informative References

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.

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

• [XMLHttpRequest]
• [Widgets-update]

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.