W3C

Widgets 1.0: Packaging and Configuration

Editor's Draft 1 July 2009

This version:
http://www.w3.org/TR/2009/WD-widgets-??/
Latest version:
http://www.w3.org/TR/widgets/
Previous versions:
http://www.w3.org/TR/2009/WD-widgets-20090528/
http://www.w3.org/TR/2008/WD-widgets-20081222/
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)
Editors:
Marcos Cáceres, Opera Software ASA

Abstract

This specification standardizes a packaging format for a class of software application known as a widget. Widgets are client-side applications that are authored using Web standards, but whose content can also be embedded into Web documents. The specification relies on PKWare's Zip specification as the archive format, XML as a configuration document format, and a series of steps that runtimes follow when processing and verifying various aspects of a package. The packaging format acts as a container for files used by a widget. The configuration document is an XML vocabulary that declares metadata and configuration parameters for a widget. The steps for processing a widget package describe the expected behavior and means of error handling for runtimes while processing the packaging format, configuration document, and other relevant files. This document also defines expected behavior for conformance checkers, which are tools that aid authors in verifying that Zip archives and configuration documents conform to this specification.

This specification is part of the Widgets 1.0 family of specifications, which together standardize widgets as a whole.

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 1 July 2009 Candidate Recommendation of the Widgets 1.0: Packaging and Configuration specification. W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. The Web Applications (WebApps) Working Group expects to request that the Director advance this document to Proposed Recommendation once the Working Group has developed a comprehensive Widgets 1.0: Packaging and Configuration test suite, and demonstrated at least two interoperable implementations. The WebApps Working Group expects to show these implementations by September 2009. The Working Group does not plan to request to advance to Proposed Recommendation prior to 01 September 2009.

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 Candidate Recommendation 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.

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.

Table of Contents

1 Introduction

Widgets are full-fledged client-side applications that are authored using Web standards and packaged for distribution. They are typically downloaded and installed on a client machine or device where they run as stand-alone applications, but they can also be embedded into Web pages and run in 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).

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

  1. Packaging Format: see packaging format.
  2. Media Type: see widget media type.
  3. File Extension: see widget file extension.
  4. Internal Abstract Structure: see Zip archive and widget package.
  5. Reserved Resource Names: see reserved file names.
  6. Addressing Scheme: see valid path.
  7. Multilingual File Names: see Zip relative path, particularly in respect to support for [UTF-8].
  8. Localization Guidelines: see element-based localization, folder-based localization.
  9. Automatic Localization: see element-based localization, folder-based localization.
  10. Device Independent Delivery: all aspects of this document where developed with this requirement in mind.
  11. Data Compression: see the valid compression methods.
  12. Derive the Media Type of Resources: see the rule for identifying the media type of an image and the rule for identifying the media type of a file.
  13. Format and Schema: see configuration document, configuration defaults, and the RelaxNG Schema for the configuration document.
  14. Widget Metadata: see configuration document (particularly the elements).
  15. Authorship Metadata: see the author element.
  16. Copyright Notice and License Metadata: see the license element.
  17. Visual Rendering Dimensions: see the widget element.
  18. Declarative Bootstrap see the content element.
  19. Automated Bootstrap see the default start file.
  20. Iconic Representations: see the icon element, default icons table and custom icons table.
  21. Configuration Parameters: the param element (used in conjunction with the feature element).
  22. Author-defined Start-up Values (Preferences): see the preference element.
  23. Feature Access Declarations: see the feature element.
  24. Configuration Document Independence: see configuration document.
  25. Preferred Display Mode: see the viewmodes attribute of the widget element.

1.2 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 locale 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 aspects related to processing, which are described in detail in the second half of the document.

The second half, which starts with the section titled "Steps for Processing a widget package", defines the steps required to process a widget package as well as the expected behavior of a user agent as it processes the packaging format, the configuration document, and attempts to find localized content. The second half of this document also deals with error handling in the event that a user agent encounters unsupported or missing files, or DOM nodes that are in error 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.

1.3 Typographic Conventions

This section is non-normative.

Defined terms appear as this sample defined term. Such terms are referenced as sample defined term, providing a link back to the term definition.

Words that denote a conformance clause or testable assertion use keywords from [RFC2119]: MUST, MUST NOT, Required, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL.

Variables are formatted specially, e.g. variable. Code is also specially formatted, such as code.

Words in italics denote a formal definition given in an external specification.

This is an example. Examples are used to explain concepts or demonstrate how to use a feature.

ISSUE: This is an issue. It implies something that Working Group is trying to fix. Eventually, all these will disappear from the spec.

Note: This is a note, it usually contains useful supplementary information in a non-normative form.

Authoring guideline:This is an authoring guideline. Its purpose is to provide authors with best-practice authoring techniques.

This is an editorial note. It denotes something that the editor is working on or some rough notes. The reader should ignore these! Eventually, all these will disappear from the spec.

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: Automatic Updates [Widgets-Updates] specification defines a version control model that allows widgets to be kept up-to-date over [HTTP]. The Widgets 1.0: Access Requests [Widgets-Access] specification allows authors to request access to URI-identifiable resources (e.g. resources on the Web).

1.5 Definitions

The following definitions are used 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 created a widget package or an authoring tool that generated a widget package.

A media type is defined in the [MIME] specification (see in particular RFC2046).

A language tag is a text string that matches production of a Language-Tag defined in the [BCP47] specifications. It is optional for user agents to validate language tags against the IANA Language Subtag Registry.

A widget is defined by the [Widgets-Landscape] 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 device. Because widgets are packaged, they can be shared by users without relying on [HTTP] (i.e., users can share widgets over non-HTTP distribution channels, such as Bluetooth or a USB thumb drive).

Reserved means that a character, or text string, or file-name, or folder-name has a specified purpose and semantics in this specification or in some other specification or system. The intended purpose for any reservation is given when the term is used.

Arbitrary means that a character, or text string, or file-name, or folder-name is not reserved for the purpose of this specification.

Supported means that a user agent implements a mentioned specification, or conformance clause, or is able to process or otherwise render mentioned media type.

Initialization means a run through the steps for processing a widget package after installation of a widget.

1.5.1 Character Definitions

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

The Unicode white space characters are are [Unicode] code points marked in the [Unicode] specification (version 5.0.0) with the property "White_Space".

The control characters, for the purpose of this specification, are [Unicode] code points:

The following Unicode code points are referred to as the forbidden characters in this specification:

2 Conformance

As well as sections marked as non-normative, all authoring guidelines, 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).

There are four classes of products that can claim conformance to this specification:

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

While a conforming user agent may support other legacy/proprietary widget types in order to conform to this specification, a user agent must treat widget packages as according to this specification.

3 User Agents

A user agent is an implementation that supports this specification.

Note: The user agent described in this specification does not necessarily 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 how to processes Zip archives and configuration documents.

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

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.

ISSUE: test-suite is not done yet, it will be completed when we go to Candidate Recommendation.

3.1 Dependencies on Other Specifications and File Formats

A user agent must support the following specifications:

A user agent may support the [Widgets-DigSig] specification, the [Widgets-Updates] specification, the [Widgets-Access] specification, and the [Widgets-APIs] specification.

3.1.1 Zip Support

A user agent must support the [ZIP] specification. However, it is optional for user agent to support the following aspects of the [ZIP] specification:

3.2 Internationalization Tag Set Support

This feature is at risk.

To facilitate the localization of text nodes within XML elements in a configuration document, a user agent MAY support the Internationalization Tag Set's ([ITS]) its:span element and the its:dir attribute. It is optional for a user agent to support other ITS elements and attributes.

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

4 Conformance Checker

A conformance checker (CC) is a user agent that verifies whether a widget package and a configuration document conform to this specification. A CC checks the conformance of either a widget package or a configuration document by implementing the assertions made in sections labeled conformance checker behavior throughout this document.

In those sections, this specification asks CCs to inform authors of conformance violations, which means they display advisory messages to authors in a manner that assists them in making their widgets valid and conforming. Wording of advisory messages is left to the discretion of implementers. It is optional for a CC to display all messages at once.

5 Zip Archive

The packaging format for the files of a widget is the Zip archive format as defined in the [ZIP] file format specification.

A file entry is the data held by a local file header, file data, and (optional) data descriptor, as defined in the [ZIP] specification, for each physical file contained 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.

Note: Step 2 of the steps for processing a widget package describes how 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 be a valid Zip archive.

Note: A valid Zip archive does not imply a conforming widget package. All valid Zip archives need to be further checked, using Step 2, to see if they qualify as a widget package.

5.1 Compression Methods

A 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 encode the file data of a file entry is identified by the numeric value derived from the compression method field defined in the [ZIP] specification.

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) as defined in the [ZIP] specification.

Authoring guideline: Only compress Zip archives with [Deflate] or Stored (no compression); other compression formats will cause the widget package to be treated as an invalid Zip archive.

Of the valid compression methods, [Deflate] is the recommended compression method.

5.1.1 Conformance Checker Behavior

A conformance checker must verify 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 the CC must inform the author that the file entry should be recompressed using the [Deflate] compression algorithm, as that is the recommended compression method.

If a CC encounters a compression method that is not one of the valid compression methods,then the CC must inform the author that the Zip archive is an invalid Zip archive.

5.2 Version of Zip 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 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:

1.0
Default value specified in the [ZIP] specification.
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 the user agent will treat the Zip archive as an invalid Zip archive in Step 2.

5.2.1 Conformance Checker Behavior

If a CC encounters a file entry with a value for version needed to extract that is not one of the valid versions needed to extract values, the CC must inform the author that the file is an invalid Zip archive.

5.3 Zip Relative Paths

A Zip relative path is the variable-length string derived from the file name field of the local file header of a file entry.

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:\images\bg.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. Note also that a Zip relative path is not a URI reference; Zip relative paths need to be converted to URI references before they can be used in context that make use of URIs.

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

For interoperability, manipulations of Zip relative paths must be performed on the string obtained by decoding the file name field using the appropriate encoding, and not on the bytes initially stored in the archive. For the sake of comparison and matching, it is recommended that a user agent internally treats all Zip-relative paths as [UTF-8].

A valid Zip relative path is one that case-insensitively matches the production of Zip-rel-path in the following [ABNF]:

zip-rel-path   = [ *folder-name ] file-name /
[ locale-folder ] 1*folder-name /
locale-folder [ *folder-name ] file-name locale-folder = "locales" "/" folder-name folder-name = file-name "/" file-name = base-name [ file-extension ] base-name = 1*allowed-char file-extension = "." 1*allowed-char allowed-char = safe-char / utf8-char safe-char = ALPHA / DIGIT / SP / "$" / "%" / "'" / "-" / "_" / "@" / "~" / "(" / ")" / "&" / "+" / "," / "." / "=" / "[" / "]" utf8-char = %x80-D7FF / %xF900-FDCF / %xFDF0-FFEF
/ %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD
/ %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD
/ %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD
/ %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD
/ %xD0000-DFFFD / %xE1000-EFFFD

Note that ALPHA, DIGIT, and SP are defined in the [ABNF] specification (but essentially represent alphanumerical characters and the U+0020 SPACE code point respectively).

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

Authoring guideline:

Authors need to keep path lengths below 250 bytes. Unicode code points may require more than one byte to encode a character, which can result in a path whose length is less than 250 characters but whose size is greater than 250 bytes.

In addition, in the case where the Zip relative path is encoded using [UTF-8], the language encoding flag (EFS) needs to be set.

Authors need to be aware that, at the time of writing, there are some interoperability issues with regards to using characters outside the safe-chars range 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 safe-chars (characters in the US-ASCII range). In addition, having excessively long path names (e.g. over 120 characters) can also result in interoperability issues on some operating systems.

5.3.1 Conformance Checker Behavior

A CC must inform the author about any file entry whose file name field does not match the production of a zip-rel-path.

A CC must inform the author of any Zip relative path whose length exceeds 120 characters.

5.4 Disallowed Characters

Forbidden characters must not appear anywhere in the file-name.

A user agent must ignore a file that contain forbidden characters in the Zip relative path.

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

Authoring Guideline: 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, 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. Furthermore, avoid having the space character (SP) at the start or end of a file name; and take caution when using the "+" U+002B PLUS SIGN, as it might cause issues on some operating systems.

5.4.1 Conformance Checker Behavior

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

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

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

A CC should inform the 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 the author of the presence of any U+002B PLUS SIGN in a file-name.

6 Widget Packages

A widget package must be a valid Zip archive that contains:

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

6.1 Invalid Widgets

An invalid Zip archive is a condition whereby a Zip archive, or a file within the Zip archive, is deemed to be corrupt beyond recovery or is non-conforming to, or unsupported by, this specification in such a way that it would not be possible for the user agent to continue processing. During the steps for processing a widget package, certain error conditions can result in a Zip archive being treated as an invalid Zip archive.

Upon encountering an invalid Zip archive, a user agent must apply the rule for dealing with an invalid Zip archive.

6.2 Files and Content Types

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

A file is the decompressed physical representation of a file entry (i.e., a file extracted into its physical form as it was prior to being added to the Zip archive).

Note: Unlike [HTTP] resources, file entries within a Zip archive are not available in multiple representations, nor are files dynamically generated from URI query parameters when the use agent retrieves them from within a Zip archive.

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 is a U+002F SOLIDUS) and whose version needed to extract is 2.0.

A folder may contain zero or more file entries or zero or more folders.

File-extension to media-type mapping is the process whereby a user agent maps the file-extension of a file to a media type.

Content-type sniffing is the process of determining the media type of a file by examining the initial bytes of a file for standardized sequence of bytes known as magic numbers (e.g. the byte sequence 47 49 46 38 37 61, which is the signature for a GIF89a image file format). The patterns used by this specification have all been standardized with the Internet Assigned Numbers Authority (IANA), as part of a media type registration.

As there is no notion of a media type within Zip, a user agent must perform file-extension to media-type mapping, followed by content-type sniffing, in order to determine the media type of a file.

For sniffing the content type of images formats, a user agent must use the rule for Identifying the media type of an image. For other file formats, a user agent must use the rule for Identifying the media type of a file.

A processable file is a file that:

6.3 Reserved File and Folder Names

The reserved file names table, below, contains a list of file names that are reserved for some purpose by this specification. The file names of the first column of the reserved file names table must be treated as case-sensitive.

Reserved File Names Table
file name reserved for purpose
config.xml Configuration document
icon.png Default icon
icon.gif Default icon
icon.jpg Default icon
icon.ico Default icon
icon.svg Default icon
index.html Default start file
index.htm Default start file
index.svg Default start file
index.xhtml Default start file
index.xht Default start file

The [Widgets-DigSig] specification also defines the naming conventions for a distributor signature and the naming convention for an author signature. The names of those files are also reserved for the purpose of this specification.

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

Reserved folder names
folder-name reserved for purpose
locales Container for localized content

6.4 Digital Signatures

A widget package contains a digital signature, and hence is digitally signed, if the widget package contains one or more files that conform to the [Widgets-DigSig] specification. The file naming convention for digital signatures files is defined in the [Widgets-DigSig] specification.

A user agent must prevent a browsing context of a widget from accessing (e.g., via scripts, CSS, HTML, etc.) the contents of a digital signature document unless an access control mechanism explicitly enables such access, e.g. via a an access control policy. The definition of such a policy mechanism is beyond the scope this specification, but may be defined to allow access to all or parts of the signature documents, or deny any such access. An exception is if a user agent that implements this specification also implements the optional [Widgets-DigSig] specification, in which case the user agent must make signature documents available to the implementation of the [Widgets-DigSig] specification.

6.5 Start Files

The start file of a widget package is a file that is used by the user agent when the widget is instantiated. This specification defines two kinds of start file: custom start file and default start file.

6.5.1 Custom start file

A custom start file is a start file identified via a content element's src attribute. The custom start file must be a processable file inside the widget package, determined by applying the rule for identifying the media type of a file. When a start file is not explicitly declared via the content element, then start file will be one of the default start files.

6.5.2 Default Start File

A default start file is a reserved start file whose file name case-sensitively and exactly matches a file name given in the file name column of the default start files table, and whose media type matches the media type given in the media type column of the table.

A default start file must appear at either the root of the widget package or at the root of a locale folder.

If a user agent encounters a file matching a file name given in the file name column of the default start files table in an arbitrary folder, the user agent must treat that file as an arbitrary file. For example, "foo/bar/index.html" would be treated as an arbitrary file.

Default Start Files Table
file name media type
index.htm text/html
index.html text/html
index.svg image/svg+xml
index.xhtml application/xhtml+xml
index.xht application/xhtml+xml

It is optional for user agents to support the media types listed in the default start files table.

Note: See Step 8 for instructions on finding a default start file.

Authoring guideline: Always include at least one start file in a widget package.

6.5.3 Conformance checker behavior

A CC must verify that the widget package contains at least one start file by:

  1. Checking within the configuration document for a correct content element to point to a processable file within the widget package.
  2. Checking for the presence of a default start file at the root of the widget package and in all locale folders.

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

6.6 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 actives to instantiate a widget, or an icon in a dock or task bar or some other visual context). The icon is intended to help users of visual browsers to recognize the widget at a glance. There are two kinds of icons defined by this specification, custom icons and default icons.

6.6.1 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 media type of a custom icon is derived by the rule for identifying the media type of an image.

A custom icon can be located either at the root of the widget package, or at the root of a locale folder, or in an arbitrary folder.

6.6.2 Default Icons

A default icon is a reserved icon whose file name case-sensitively and exactly matches a file name given in the file name column of the default icons table.

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

Default Icons Table
file name media type
icon.svg image/svg+xml
icon.ico image/vnd.microsoft.icon
icon.png image/png
icon.gif image/gif
icon.jpg image/jpeg

A user agent must derive the media type of a default icon from the media type column of the default icons table.

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

Implementations that support the use of [SVG] as an icon format may display declarative animation. However, for security reasons, a user agent must not execute scripts or interactivity defined within an [SVG] icon file. Animation and interactivity is defined as the set of features intended for use of SVG as a dynamic image, corresponding to the [SVGTiny] profile, and to specific feature strings:

[SVG]
http://www.w3.org/TR/SVG11/feature#SVG-static
[SVGTiny12]
http://www.w3.org/Graphics/SVG/feature/1.2/#SVG-animated

Authoring guideline: If using [SVG] as an icon format, and the intention is for it to be animated, then use declarative animation. Also, avoid creating icons that depend on scripts for animation and interactivity.

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 MUST inform the author that it is desirable, but optional, to include a default icon.

If a CC encounters an icon in the [SVG] format, the CC may inform the author if the icon includes script or interactive functionality.

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

If a CC encounters an icon in the [SVG] format, then the CC must inform the author if the icon does not conform to the [SVGTiny] specification.

6.7 Media type

The widget media type is application/widget [MIME].

Authoring guideline: If the protocol over which the widget package is transferred supports the [MIME] specification, then Make sure that the widget is labeled with an application/widget media type. Failure to correctly label a widget package will result in it being treated as an invalid Zip archive.

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

6.8 File Extension

A widget file extension is the text string that case-insensitively matches the string ".wgt" any case form (e.g. .wgt, .WGt, .WgT, etc. are all valid).

The widget file extension is Required for widget packages on systems where it is customary for file names to include an extension that symbolizes the media type.

Authoring guideline: If it is anticipated that the widget will be distributed by non-HTTP means, then include the widget file extension. The widget file extension is not necessary if the widget package is labeled as a application/widget when served over HTTP.

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 widget package must have exactly one configuration document, which must be located at the root of the widget package.

A valid configuration document file name is the string config.xml, to be treated as case-sensitive.

Within a widget package, a configuration document must have a valid configuration document file name.

User agents must treat files in an arbitrary folder or locale folders that use the file name config.xml as an arbitrary file.

Authoring guideline: Be sure to always include a configuration document at the root of the widget package and that the config.xml file name is in lowercase form.

The following is an an example of a configuration document:

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns       = "http://www.w3.org/ns/widgets" 
        id          = "http://example.org/exampleWidget" 
        version     = "2.0 Beta" 
        height      = "200" 
        width       = "200"
        viewmodes = "application fullscreen">

  <name short="Example 2.0">
    The example Widget!
  </name>

  <feature name="http://example.com/camera">

    <param name="autofocus" value="true"/> 
  </feature>

  <preference name     ="apikey" 
              value    ="ea31ad3a23fd2f"
              readonly ="true" />
  <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="myWidget.html"/> 

  <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 6 for instructions on how to process a configuration document.

7.1 Namespace

The widget namespace URI for a configuration document is http://www.w3.org/ns/widgets [XMLNS].

Authoring requirements: Be sure to declare the widget namespace as part of the widget element. If the namespace is absent, then Zip archive will be treated as an invalid Zip archive.

7.2 Proprietary Extensions

Implementers intending to extend the configuration document format with their own [XML] elements and attributes (or those defined in other specifications) must do so by using a separate [XMLNS] namespace. This specification does not define a model for processing [XML] elements outside the widget namespace.

Example of extending the configuration document format:

<widget xmlns="http://www.w3.org/ns/widgets"
   xmlns:ex="http://example.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 rule for how attributes are to be processed by a user agent or conformance checker are also given in this section.

User agents should impose their own implementation-specific limits on the values of otherwise unconstrained attribute types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

An attribute is invalid if its value does not conform to its said attribute type; that is, if the value of the attribute is in error given the processing rules for that type of attribute.

Boolean attribute

A boolean attribute is a keyword attribute that can only be used with a valid boolean value. A valid boolean value is a string that case-sensitively matches true or false. Unless specified otherwise, the default behavior, which is used when the attribute is omitted or has a value other than the two allowed values, is false. The way a user agent interprets a boolean attribute is defined as part of an attribute's definition (see, for example, the feature element's required attribute). The value of this kind of attribute is retrieved using the rule for getting a single attribute value.

Keyword attribute

A keyword is a string that is reserved for the purpose of this specification. The value of a keyword attribute is a keyword that is one of a finite set specified in the attribute's definition (e.g. the its:dir attribute defines ltr, rtl, lro, or rlo as its only possible values). Authors must use keywords in the case given in this specification. Implementations must only perform literal comparisons on the resulting value, and must not use case-insensitive comparisons. How the value of this attribute is retrieved depends on the context in which is it used, so the rule for how to retrieve the value is given when this attribute type is used.

Keyword list attribute

An attribute defined as taking one or more keywords as a value, which are separated by space characters. The value of this kind of attribute is retrieved using the rule for getting a list of keywords from an attribute.

Media type attribute

An attribute whose value is defined as containing a valid media type. A valid media type is string 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 the [MIME] specification. The value of this kind of attribute is retrieved using the rule for getting a single attribute value.

Numeric attribute

The value of a numeric attribute is a string containing a valid non-negative integer. A valid non-negative integer is a string that consists of one or more code points in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). For example, the characters "002", "323", "23214", and so on. The value of this kind of attribute is retrieved using the rule for getting a single attribute value.

Path attribute

An attribute defined as containing a valid path. A valid path is one that matches the production of a zip-rel-path or a zip-abs-path. A Zip absolute path is one that case-insensitively matches the production of zip-abs-path in the following [ABNF]:

zip-abs-path = "/" zip-rel-path

Note: A zip-abs-path is invalid in the file name field of a file entry.

The value of this kind of attribute is retrieved using the rule for getting a single attribute value.

URI attribute

An attribute defined as containing a valid URI. A valid URI is one that matches the URI token of the [URI] specification or the IRI token of the [RFC3987] specification. The value of this kind of attribute is retrieved using the rule for getting a single attribute value.

Version attribute

The value of a version attribute is an arbitrary string (possibly empty). This specification does not mandate any specific format, semantics, or special processing rule for the format of this attribute type. In other words, all strings are valid for this attribute type within the constraints of [XML] attributes. The value of this kind of attribute is retrieved using the rule for getting a single attribute value.

Author Guidelines: For the purpose of this specification, the structure of version tags has no semantics; they are just treated as arbitrary strings (e.g. '1.0' is not greater than '2.0', but is simply different). However, for the sake of consistency, one can choose to use the following [ABNF]:

rec-version-tag = 1*DIGIT ["."  1*DIGIT [ "." 1*DIGIT]
                  [ 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.1 beta1, 1.02.12 rc1.

7.4 Other Attributes

This section describes the behavior and expected usage of other attributes that are supported either by default as part of the [XML] specification (as is the case with xml:lang) or if the user agent implements the optional [ITS] specification.

xml:lang attribute

A keyword attribute defined as containing a language tag. The [XML] specification defines the xml:lang attribute and its influence on the contents and attribute values of child elements. The value of this kind of attribute is retrieved in accordance with the XML.

Authoring guideline: Avoid subtags from the IANA Language Subtag Registry marked as deprecated, grandfathered, or redundant. The intended purpose of the xml:lang attribute is to declare the primary language of an element, its attributes, and its descendent nodes.

its:dir attribute

A keyword attribute defined as containing a valid its:dir value (i.e., ltr, rtl, 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. It is optional for authors to use this attribute.

7.5 The widget Element

The widget element serves as a container for the other elements.

Context in which this element must be used:
This is the root element of a configuration document.
Occurrences:
Exactly one, and must be the root element of the [XML] document.
Expected children (in any order):
name: zero or more (one element is allowed per language).
description: zero or more (one element is allowed per language).
author: zero or one.
license: zero or more (one element is allowed per language).
icon: zero or more (elements are grouped by language).
content: zero or one.
feature: zero or more.
preference: zero or more.
Localizable:
No.

7.5.1 Attributes

id
A valid URI that denotes an identifier for the widget. It is optional for authors to use this attribute.
version
A version attribute that specifies the version of the widget. It is optional for authors to use this attribute.
height
A numeric attribute greater than 0 that indicates the preferred viewport height of the custom start file in CSS pixels [CSS21]. This value is only applicable to particular view modes (e.g., floating and application mode), meaning that for certain view modes this value is ignored. The view modes that honor the value of this attribute are defined in the [Widgets-Views] specification. It is optional for authors to use this attribute.
width
A numeric attribute greater than 0 that indicates the preferred viewport width of the instantiated custom start file in CSS pixels [CSS21]. This value is only applicable to particular view modes (e.g., floating and application mode), meaning that for certain view modes this value is ignored. The view modes that honor the value of this attribute are defined in the [Widgets-Views] specification. It is optional for authors to use this attribute.
xml:lang
xml:lang attribute. It is optional for authors to use this attribute.
viewmodes
A keyword list attribute that denotes the view modes supported the widget. The value SHOULD be one or more of the following valid view modes as defined in the [Widgets-Views] specification: application, floating, fullscreen, or mini. In addition, the all keyword can be used to denote that all the valid view mode are supported by the widget. The default value, which is used when the attribute is omitted or has a value other than one of the valid view modes, is floating. The first item represents the author's preferred view mode, followed by the next most preferred view mode and so forth. It is optional for authors to use this attribute.

Viewport and view mode are defined in the [Widgets-Views] specification.

7.5.2 Usage Example

The following example shows how the widget element can be used.

<widget xmlns="http://www.w3.org/ns/widgets" 
        id="http://example.org/exampleWidget" 
        version="2.0 Beta" 
        height="200" 
        width="200"
        viewmodes="floating application">
  <description>

   An example of the possibilities.
  </description>
</widget>

7.6 The name Element

The name element represents the full human-readable name for a widget 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 more (one element is allowed per language).
Localizable via xml:lang:
Yes, but the value of the xml:lang attribute must be unique for any subsequent element of this type.

7.6.1 Attributes

xml:lang
xml:lang attribute. It is optional for authors to use this attribute.
its:dir
A valid its:dir value. It is optional for authors to use this attribute.
short
A string that represents the short name for a widget. Ideally, the value should be shorter in length than the contents of the name element. Otherwise, the short attribute should not be used. It is optional for authors to use this attribute.

7.6.2 Usage Example

The following example shows the usage of the name element.

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

</widget>

7.7 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 more (one element is allowed per language).
Localizable via xml:lang:
Yes, but the value of the xml:lang attribute must be unique for any subsequent element of this type.

7.7.1 Attributes

xml:lang
xml:lang attribute. It is optional for authors to use this attribute.
its:dir
A valid its:dir value. It is optional for authors to use this attribute.

7.7.2 Usage Example

An example usage of the description element.

<widget 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.8 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:
As a child of the widget element.
Content model:
Any.
Occurrences:
Zero or one.
Localizable via xml:lang:
No. Only the first instance of this element in document order will be used, regardless of the value of xml:lang (if any).

7.8.1 Attributes

href
A URI attribute that represents a link that is associated with the author (e.g. the homepage of the author). It is optional for authors to use this attribute.
email
A string that represents an email address associated with the author. It is optional for authors to use this attribute.
xml:lang
xml:lang attribute. It is optional for authors to use this attribute.
its:dir
A valid its:dir value. It is optional for authors to use this attribute.

7.8.2 Usage Example

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

<widget xmlns="http://www.w3.org/ns/widgets">
    <name>Cup-a-Joe's Cafe Finder Widget</name>

    <author href  = "http://dahut.example.org" 
            email = "joe@example.org">
      Joey and Princesa Bacalhau
    </author>
</widget>

7.9 The license Element

The license element represents a software license, which includes, for example, a usage agreement, redistribution statement, and/or a copyright license terms under which the content of the widget package is provided.

Context in which this element may be used:
As a child of the widget element.
Content model:
Any.
Occurrences:
Zero or more (one element is allowed per language).
Localizable via xml:lang:
Yes, but the value of the xml:lang attribute must be unique for any subsequent element of this type.

Authoring Guideline: Localized license shouldn't be used to present different versions of a license, just translations of the same license.

7.9.1 Attributes

href
A valid URI or a valid path that points to a representation of a software and/or content license. When the href attribute is used, the user agent should provide users the ability to view or otherwise link to the referenced license.
If the href attribute contains a valid path to a file within the widget package, then the user agent should use the rule for identifying the media type of a file to identify the media type of the file being referenced. It is optional for authors to use this attribute.
xml:lang
xml:lang attribute. It is optional for authors to use this attribute.
its:dir
A valid its:dir value. It is optional for authors to use this attribute.

7.9.2 Usage Example

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

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

<widget 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.10 The icon Element

The icon element represents a custom icon for the widget. A 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:
As a child of the widget element.
Content model:
Empty.
Occurrences:
Zero or more (elements are grouped by language).
Localizable via xml:lang:
No. Relies on folder-based localization.

7.10.1 Attributes

src
Required. A path attribute that points to a file inside the widget package. It is required for authors to use this attribute.
width
A numeric attribute 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 attribute is a supported raster graphic, then the user agent will ignore this value. If the file pointed to by the src attribute is of a vector graphic format, then this value must be used. It is optional for authors to use this attribute.
height
A numeric attribute 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 attribute is a supported raster graphic, then the user agent will ignore this value. If the file pointed to by the src attribute is a vector graphic format, then this value must be used. It is optional for authors to use this attribute.

Authoring guideline: Refrain from using the width and height attributes for raster graphic formats, as the widget user agent will ignore these values.

7.10.2 Usage Example

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 256x256 pixels. Document order of the elements is irrelevant.

<widget 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.11 The content Element

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

Context in which this element may be used:
As a child of the widget element.
Content model:
Empty.
Occurrences:
Zero or one.
Localizable via xml:lang:
No. Relies on folder-based localization.

7.11.1 Attributes

src
A path attribute that allows an author to point to a file within the widget package. It is required for authors to use this attribute.
type
A media type attribute that indicates the media type of the file referenced by the src attribute. When the value is absent, the user agent will assume the value text/html. It is optional for authors to use this attribute.
encoding
A keyword attribute that denotes the character encoding of the file identified by the src attribute. The allowed value is the "name" or "alias" of any "Character Set" listed in [IANA-Charsets]. A user agent MUST support [UTF-8], which has the "UTF-8" name in [IANA-Charsets]; all other character encodings are optional.
It is optional for authors to use this attribute.

When the value of encoding is absent or in error, the user agent will assume the default encoding which is the value UTF-8.

Authoring Guideline: Where aliases are given by the [IANA-Charsets], authors are encouraged to use those aliases marked as "preferred MIME name".

 
 

7.11.2 Usage Example

This example shows the expected usage of the content element:

<widget xmlns="http://www.w3.org/ns/widgets">
  <content src="myWidget.html"/>
</widget>

This example shows the content element being used with a encoding 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:


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

</widget>

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

<widget xmlns="http://www.w3.org/ns/widgets">
  <name>Location-Based Games Finder</name>
  <content src="lbg-maps.swf" type="application/x-shockwave-flash"/>
  <feature name="http://example.org/api.geolocation"
           required="false"/> 
</widget>

7.12 The feature Element

A feature is a runtime component (e.g. an Application Programming Interface or video decoder) that is not part of the specified set provided by the Widgets 1.0 family of specifications. The feature element serves as a standardized means to request the binding of an (URI) identifiable runtime component to a widget for use at runtim