Widgets 1.0: Packaging and Configuration

Abstract

This document 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

Table of Contents

• 1 Introduction
  • 1.1 Design Goals and Requirements
  • 1.2 How This Document is Organized
  • 1.3 Typographic Conventions
  • 1.4 The Widget Family of Specifications
  • 1.5 Definitions
• 2 Conformance
• 3 User Agents
  • 3.1 Dependencies on Other Specifications and File Formats
  • 3.2 Internationalized Tag Set Support
• 4 Conformance Checker
• 5 Zip Archive
  • 5.1 Compression Methods
  • 5.2 Version of Zip Needed to Extract a File Entry
  • 5.3 Zip Relative Paths
  • 5.4 Reserved Characters
• 6 Widget Packages
  • 6.1 Invalid Widgets
  • 6.2 Files and Content Types
  • 6.3 Reserved File and Folder Names
  • 6.4 Digital Signatures
  • 6.5 Start Files
  • 6.6 Icons
  • 6.7 Media type
  • 6.8 File Extension
• 7 Internationalization and localization
  • 7.1 Localization guidelines
  • 7.2 Examples
  • 7.3 Folder-based localization
• 8 Configuration Document
  • 8.1 Namespace
  • 8.2 Proprietary Extensions
  • 8.3 Attribute Types
  • 8.4 Other Attributes
  • 8.5 The widget Element
  • 8.6 The name Element
  • 8.7 The description Element
  • 8.8 The author Element
  • 8.9 The license Element
  • 8.10 The icon Element
  • 8.11 The content Element
  • 8.12 The feature Element
  • 8.13 The param Element
  • 8.14 The preference Element
  • 8.15 Element-based localization
  • 8.16 Indicating Text Directionality with <its:span>
• 9 Steps for Processing a Widget Package
  • 9.1 Processing Rules
  • Step 1 - Acquire a Potential Zip Archive
  • Step 2 - Verify the Zip archive
  • Step 3 - Set the Configuration Defaults
  • Step 4 - Locate and Process the Digital Signatures
  • Step 5 - Derive the User Agent's Locale
  • Step 6 - Locate the Configuration Document
  • Step 7 - Process the Configuration Document
  • Step 8 - Locate the Start File
  • Step 9 - Locate the Default Icons
• Appendix
  • Linking To a Widget Package From a HTML Document
  • RelaxNG Schema for the Configuration Document
• Acknowledgements
• Normative References
• Informative References

1 Introduction

1.1 Design Goals and Requirements

1.2 How This Document is Organized

1.3 Typographic Conventions

1.4 The Widget Family of Specifications

1.5 Definitions

2 Conformance

3 User Agents

3.1 Dependencies on Other Specifications and File Formats

3.2 Internationalized Tag Set Support

4 Conformance Checker

5 Zip Archive

5.1 Compression Methods

5.2 Version of Zip Needed to Extract a File Entry

5.3 Zip Relative Paths

zip-rel-path     = [ *localized-folder ] [ *folder-name ] 
                   [ file-name ] / 
                   [ localized-folder ] [ *folder-name ] / 
                   [ folder-name ] 

locale-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 / "$" / "%" 
                    / "'" / "-" / "_" / "@" 
                    / "~" / "(" / ")" / "&" / "+" 
                    / "," / "." / "=" / "[" / "]" 

5.4 Reserved Characters

6 Widget Packages

A widget package is a valid Zip archive that contains:

• One or more start files, either located at the root of the widget package and/or at the root of locale folders or referenced by a correct content element's src attribute.
• One configuration document, which must be located at the root of the widget package.
• Zero or more icons, either located at the root of the widget package and/or at the root of locale folders or referenced by the icon element's src attribute.
• Zero or more arbitrary files located either at the root of the widget package and/or in arbitrary folders or in locale folders.
• Zero or more digital signatures located at the root of the widget package.

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

6.1 Invalid Widgets

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 (i.e., no content-type metadata, as described in the [HTML5] specification), 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 agents 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:

• Exists within the said widget package,
• is a usable file entry,
• is of a media type supported by the user agent, determined applying either the rule for identifying the media type of an image or the rule for identifying the media type of a file. Which rule needs to be applied is given when the term is used.

6.3 Reserved File and Folder Names

The reserved file names table, below, 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. Reserved file names must be treated as case-sensitive.

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.

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 out of scope of 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.

Custom start file

A custom start file is a start file identified via a content elements 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.

Default Start File

A default start file is a start file whose file-name case-sensitively matches a file-name given in the first column of the default start files table below and whose media type matches the media type given in the second 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.

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

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.

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.

An icon must be located either at the root of the widget package or at the root of a locale 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 media type of a custom icon is derived by the rule for identifying the media type of an image.

Default Icons

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

A user agent must derive the media type of a default icon from the second 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.

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 one intends it to be animated, 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 an 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 an 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

6.8 File Extension

7 Internationalization and localization

Internationalization, or i18n, is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language. Localization refers to the adaptation of a product, application or document content to meet the language, cultural and other requirements of a specific target market (a "locale").

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 package that contains content that an author has explicitly localized: that is, a widget package that contains a container for localized content, which itself contains one or more locale folders.

Unlocalized content is content included in the widget package or in the configuration document that has not been explicitly localized.

A localized file is any file that has been placed inside a locale folder. The contents of the file should be translated, localized, or altered for the given context. A widget package may contain zero or more localized files. All files and folders, except digital signatures and the configuration document, can be localized.

For example, a locale folder "/locales/ja" (Japanese) might contain an HTML document translated into Japanese.

Authoring guideline: Locale folders need to be placed in the container for localized content (a locale folder not in a container for localized content will be treated as an arbitrary folder). Always provide a start file at the root of the widget package, in case the end-user's preferred language is not catered for by the widget.

7.1 Localization guidelines

This section is non-normative.

This specification provides two means that authors can use to explicitly localize the content of a widget:

1. By placing localized file content in locale folders, a process referred to as folder-based localization.
2. By explicitly marking XML elements in the configuration document as localized, a process referred to as element-based localization.

Both forms of localization are described below. Folder-based localization and element-based localization work in conjunction with each other. Folder-based and element-based localization rely on the user agent to match the language ranges held by the user agent's locales to the appropriate locale folders and/or localized XML elements in the widget's configuration document.

7.2 Examples

This section is non-normative.

This sections presents three examples of how widgets can be localized, each example is intended to showcase how the localization algorithm is intended to work.

Simple Example

<widget xmlns="http://w3.org/ns/widgets">
<name>What day is it?</name>
<description>

 This widget highlights the current day
 of the week.
</description>
</widget> 
  

<!doctype html>
<title>¿Qué día es?</title>
<script src="/scripts/engine.js"></script>
<body>
<p>Hoy es: lunes, martes, miércoles, 
   jueves, viernes, sábado, 
   domingo


  

Complex Example

<widget xmlns="http://w3.org/ns/widgets">
  <name xml:lang="ko">웃기는 고양이</name>
  <content src="cats.html"/>
</widget> 

  

<!doctype html>
<title>G'day! LOL Cats!</title>

<script src="scripts/engine.js">
...
  

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

Fallback Behavior Example

<!doctype html>
<title>Patriotic Boat</title>
<script src="/scripts/engine.js">
</script>
<body>
  <img src="flag.png"> 
  <img src="mast.png">

  

Conformance Checker Behavior

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

Upon encountering any locale folders named with a region or script subtag, a CC should inform an author to avoid region or script subtags from the IANA Language Subtag Registry.

7.3 Folder-based localization

This specification defines the concept of folder-based localization, which is the process whereby an author places files inside folders that are named in a manner that conforms to a language tag as defined in the [BCP47] specification. 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 in the IANA Language Subtag Registry. These locale folders are then placed inside the container for localized content.

The container for localized content is a folder at the root of the widget package whose folder-name case-sensitively match the string 'locales'. A container for localized content may contain zero or more locale folders.

A locale folder is a folder whose file name field matches the production of locale-folder and is a direct descendant of the container for localized content (e.g., "/locales/en-us", "/locales/fr", etc). A locale folder may contain zero or more arbitrary folders and/or files.

widget.wgt
  config.xml
  index.html
  fun.gif
  locales/en/fun.gif
  locales/fr/french.html  
  locales/fr/fun.gif

widget.wgt  
  index.html
  config.xml
  locales/en/shared1.gif
  locales/en/shared2.gif
  locales/en/a.gif
  locales/en-au/a.gif 
  locales/en-us/a.gif
  some/unlocalized.png

widget.wgt  
  locales/zh-Hans-CN/a.gif 
  locales/zh-Hans-CN/f.gif 
  locales/zh-Hans/a.gif
  locales/zh-Hans/b.gif
  locales/zh/a.gif
  locales/zh/b.gif
  locales/zh/c.gif
  a.gif
  b.gif
  c.gif
  d.gif
  f.gif
  g.gif
  index.html
  config.xml

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

<?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="index.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.

8.1 Namespace

8.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. For the sake of interoperability, extensions to the configuration document are not recommended.

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

8.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 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 that type of attribute.

Version attribute

The value of a version attribute is an arbitrary string (possibly empty) that denotes a software version identifier. 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*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.

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 of more code points in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). For example, the characters "2", "323", "23214", and so on. 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 hoe 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 values, 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.

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.

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.

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.

Path attribute

An attribute defined as containing a valid path. A valid path is one that matches the 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 a the file name filed of a file entry.

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

8.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, 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.

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

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 view port height of the instantiated 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. Which view modes should honor the value of this attribute is defined in the the [Widgets-Views] specification. It is optional for authors to use this attribute.

width

A numeric attribute greater than 0 that indicates the preferred view port width of the instantiated 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. Which view modes should honor the value of this attribute is defined in the 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, mini, or all. 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.

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

Usage Example

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

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

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.

Usage Example

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

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

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.

Usage Example

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

8.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 value of xml:lang (if any).

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.

Usage Example

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

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

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 present, the user agent should allow 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.

Usage Example

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

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

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

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

Usage Example

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

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

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.

charset

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] (a user agent are required to support [UTF-8]). It is optional for authors to use this attribute.

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

Usage Example

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

<widget xmlns="http://www.w3.org/ns/widgets">
  <name xml:lang="zh-cn">古老瓷地图</name>

  <name>Ancient Chinese Maps</name> 
  <content src="china-maps.html" charset="GB2312"/>
</widget>

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

8.12 The feature Element

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. Using a feature element denotes that, at runtime, a widget may attempt to access the feature identified by the feature element's name attribute. A feature can have zero or more parameters associated with it.

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. A user agent can expose a feature through, for example, an API, in which case a user agents that supports the [Widgets-APIs] specification can allow authors to check if a feature loaded via the hasFeature() method.

Context in which this element may be used:

As a child of the widget element.

Content model:

Zero or more param elements.

Occurrences:

Zero or more.

Localizable via xml:lang:

No.

Attributes

name

A URI attribute that identifies a feature that may be needed by the widget at runtime (such as an API). It is required for authors to use this attribute.

required

A boolean attribute that indicates whether or not this feature must be available to the widget at runtime. In other words, the required attribute denotes that a feature is absolutely needed by the widget to function correctly, and without the availability of this feature the widget serves no useful purpose or won't execute properly. The default value when this attribute is absent is true, meaning that the feature must be made available to the widget by the widget at runtime. It is optional for authors to use this attribute.

Usage example

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

   <feature name="http://example.org/api.geolocation"
            required="false"/> 
</widget>

8.13 The param Element

The param element defines a parameter for a feature. A parameter is name-value pair that a user agent must associate with the corresponding feature for which the parameter is declared for. The relationship of a parameter to a feature is established by having a param element as a direct child of a feature element in document order.

Outside the context of a feature element, a param element does not represent anything and a user agent must ignore it.

Context in which this element may be used:

As a child of the feature element.

Content model:

Empty.

Occurrences:

Zero or more.

Localizable via xml:lang:

No.

Attributes

name

A string, which may be empty, that denotes the name of this parameter. It is required for authors to use this attribute.

value

A string, which may be empty, that denotes the value of this parameter. It is required for authors to use this attribute.

Usage example

<widget xmlns="http://www.w3.org/ns/widgets">
   <feature name="http://example.org/api.geolocation"> 
      <param name="accuracy" value="low"/> 
   </feature>

</widget>

8.14 The preference Element

The preference element allows authors to declare one or more preferences: a preference is a persistently stored name-value pair that is associated with the widget the first time the widget is instantiated. Unless an end-user explicitly requests that these values be reverted to the values as declared in the configuration document, a user agent must not revert to these values on subsequent initialization of the widget.

User agents that support [Widgets-APIs] must expose any declared preference to the author at runtime via scripting. In addition, unless a preference is explicitly marked as read-only (via the readonly attribute), it must be possible for authors to override and delete these values at runtime via the relevant methods defined in the [Widgets-APIs] specification.

Context in which this element may be used:

As a child of the widget element.

Occurrences:

Zero or more.

Expected children:

none.

Localizable via xml:lang:

No.

Attributes

name

A string that denotes the name of this preference. It is required for authors to use this attribute.

value

A string that denotes the value of this preference. The default value for when the value is missing is null. It is optional for authors to use this attribute.

readonly

A boolean attribute indicating whether this preference can be overwritten at runtime. The default value when this attribute is absent is false, meaning that the value can be overwritten at runtime. It is optional for authors to use this attribute.

Usage example

<widget xmlns="http://www.w3.org/ns/widgets">
   <preference name     = "skin" 
               value    = "alien"/>
   <preference name     = "api-key" 
               value    = "f6d3a312f9d742" 
               readonly = "true"/>

</widget>

8.15 Element-based localization

This specification defines the concept of element-based localization, which allows authors to use the xml:lang attribute to explicitly indicate that an XML element in the configuration document has been localized.

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

As part of their definition, the XML elements of the configuration document are marked as being localizable via xml:lang with the word "yes" or "no". If an element is marked as being localizable via xml:lang with the word "no", it means that the element is not localizable via element-based localization. In such a case, the user agent must not attempt to do any localization of that element in the manner described in this section regardless of whether the element contains an xml:lang attribute.

If an element is marked as being localizable via xml:lang with "yes", the user agent must attempt to match user agent's locales in the manner specified in Step 7.

8.16 Indicating Text Directionality with <its:span>

Although it is optional for a user agent to support [ITS], it is recommended that authors use the <its:span> element to indicate the directionality of text 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.

It is optional for authors to use any of the [ITS] attributes.

<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 each be used as a child of the following elements of the configuration document:

• name
• description
• author
• license

9 Steps for Processing a Widget Package

The steps for processing a widget package involves nine steps that a user agent SHOULD follow, in sequential order, responding accordingly if any of the steps result in an error or if the specification asks for the user agent to skip a step. 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 user agent to recover from an error and it will be forced to treat the widget as an invalid Zip archive (see rule for dealing with an invalid Zip archive).

The steps for processing a widget package and associated processing 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, but the end result must be indistinguishable from the result that would be obtained by following the specification.

9.1 Processing Rules

This section defines various processing rules on which the steps for processing a widget package rely on.

Rule for extracting file data from a file entry

The rule for extracting file data from a file entry is described in this section.

Given a path that matches a the file name field of a file entry within the zip archive, a user agent must to decompress (or otherwise extract) the file data of file entry into its original file representation. Exactly how to extract a file from a Zip archive is beyond the scope of this specification. Instead, implementers must follow the [ZIP] specification's instructions on how to extract a file for Zip archive.

It is optional for a user agent to extract all the files in a Zip archive at the same time. The user agent may extract specific files as they are needed for processing.

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

Rule for dealing with an invalid Zip archive

The rule for dealing with an invalid Zip archive is described in this section. In the event that an implementation encounters an invalid Zip archive during the steps for processing a widget package, the user agent must abort all processing of the steps for processing a widget package and should inform the end-user with an appropriate localized error message. The wording of an appropriate localized error message is left to the discretion of implementers; however, its presence is nonetheless recommended.

Rule for finding a file within a widget package

The rule for finding a file within a widget package is given in the following algorithm. The algorithm returns either a file, null, or an error.

1. Let path be the Zip relative path to the file entry being sought.

2. If the path starts with a U+002F SOLIDUS (e.g., "/style/master.css"), meaning that the path is an zip absolute path, then:

   1. Remove the first U+002F SOLIDUS from path and search at the root of the widget package for a file entry whose file name field matches path. If none if found, return null and terminate this algorithm.

   2. If a matching file entry is found, let file be the result of applying rule for extracting file data from a file entry to path.

   3. If file is a processable file, then return file and terminate this algorithm.

   4. If file is not a processable file, then return an error and terminate this algorithm.

3. For each lang-range in the user agent's locales:

   1. Let path be the concatenation of the string "locales/", the lang-range, a U+002F SOLIDUS character, and the name of the path (e.g., locales/en-us/cats.png, where "en-us" is the lang-range and "cats.png" is the path).

   2. If path points to a file entry within the widget package, then return the corresponding file.

   3. If the path points to a file entry that is not a processable file, then return an error and terminate this algorithm.

4. If every lang-range in the user agent's locales have been searched, then search for a file entry whose file name field matches path at the root of the widget package:

   1. If a matching file entry is found, let file be the result of applying the rule for extracting file data from a file entry to path.

   2. If file is a processable file, then return file and terminate this algorithm.

   3. If file is not a processable file, then return an error and terminate this algorithm.

5. Otherwise, return null.

Rule for getting a single attribute value

The rule for getting a single attribute value is given in the following algorithm. The algorithm always returns a string, which may be empty.

1. Let result be the value of the attribute.

2. In result, replace any sequences of U+0009, U+000A, U+000D, and U+0020 characters (in any order) with a single U+0020 SPACE character.

3. In result, drop any leading or trailing U+0020 SPACE character.

4. Return result.

Rule for getting a list of keywords from an attribute

The rule for getting a list of keywords from an attribute is given by the following algorithm.

1. Let result be the value of the attribute.

2. In result, replace any sequences of U+0009, U+000A, U+000D, and U+0020 characters (in any order) with a single U+0020 SPACE character.

3. In result, drop any leading or trailing U+0020 SPACE character.

4. In result, chop the string at each occurrence of a U+0020 character, dropping that character in the process.

5. Return result.

Rule for Verifying a File Entry

The rule for verifying a file entry is given in the following algorithm.

An unusable file entry is one where by any of following conditions occur/apply (indicating that a condition is met). If a user agent encounters an unusable file entry, it must ignore the file entry: To ignore a file entry means that the user agent must act as if the said file does not exist within the Zip archive.

For the file entry, check the following data in the local file header:

1. The value of the CRC-32 field (defined in the [ZIP] specification) 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 an invalid Zip relative path.

A usable file entry is one that is not an unusable file entry.

Rule for Getting Text Content

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

1. Let input be the [DOM3Core] Element to be processed.

2. If the user agents supports [ITS], and if the input element has the dir attribute from the [ITS] namespace or any children with a valid its:dir value, then process input and its descendant text nodes in accordance to the [ITS] specification.

3. Return the value of the textContent property for input.

Rule for Getting Text Content with Normalized White Space

The rule for getting text content with normalized white space is given in the following algorithm.

1. Let input be the element to be processed.

2. Let result be the result of applying the Rule for Getting Text Content to input.

3. In result, excluding any U+0020 SPACE code points, convert any sequence of one or more characters marked with the [Unicode] property "White_Space" into a single U+0020 SPACE.

4. In result, convert any sequence of two or more U+0020 SPACE code point into a single U+0020 SPACE and remove any leading or trailing U+0020 SPACE characters.

5. Return result.

<widget xmlns="http://www.w3.org/ns/widgets">
   <name short= "
          D   A   H   U  T 
">
     The <blink>Awesome</blink> 
     <author email="dude@example.com">Super <blink>Dude</blink></author>

     Widget</name>
</widget>
  

Rule for Parsing a Non-negative Integer

The rule for parsing a non-negative integer are as given in the following algorithm. When invoked, the algorithm 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. A user agent must ignore leading and trailing space characters.

Note: There may be implementation-specific limits on the range of integers allowed, and behavior outside such limits is undefined.

1. Let input be the string being parsed.

2. Let result have the value 0.

3. If the length of input is 0, return an error.

4. Let position be a pointer into input, initially pointing at the start of the string.

5. Let nextchar be the character in input at position.

6. If the nextchar is one of the space characters, increment position. If position is past the end of input, return an error. Otherwise, go to 5 in this algorithm.

7. If the nextchar is not one of U+0030 (0) .. U+0039 (9), then return result.

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 7 in this algorithm.

9. Return result.

Rule for Identifying the Media Type of an Image

The rule for identifying the media type of an image are given by following algorithm. It is optional for user agents to support any of the media types listed in the media type identification table.

1. Let file be the file to be processed.
2. If file 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 media type value and terminate this algorithm.
3. If file has no file-extension, if the first bytes of the file matches one of the byte sequences in the bytes in hexadecimal column of the following table, then return the media type in the corresponding cell in the second column on the same row. Otherwise, return unknown/unknown.

Rule for Identifying the media type of a file

The rule for identifying the media type of a file are given by the following algorithm. It is optional for user agents to support the media types given in the file identification table below.

1. Let file be the file to be processed.

2. If file 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 media type value.

3. If file extension is absent, the media type of a file must be determined by using the rules set forth in the [SNIFF] specification.

Step 1 - Acquire a Potential Zip Archive

Step 2 - Verify the Zip archive

Step 3 - Set the Configuration Defaults

User agents must assume the following configuration defaults at this point of processing.

When a null value is assigned to a variable in the configuration defaults table, an implementation must treat the value as null(i.e., not as empty string and not as the text string "null").

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

Step 4 - Locate and Process the Digital Signatures

Step 5 - Derive the User Agent's Locale

Step 6 - Locate the Configuration Document

Step 7 - Process the Configuration Document

The purpose of processing the configuration document is to override the configuration defaults, which are used during instantiation and at runtime, and to select the appropriate localized content (if any) that must eventually be presented to the end-user.

In this step, the user agent must make use of the lookup algorithm, which is defined in section 3.4 of [RFC4647] (part of [BCP47]), to match elements in the configuration document to the language ranges held by the user agent's locales (if any). What to do when more then one element of a type are matched by the user agent depends on whether one element is allowed per language or whether elements are grouped by language:

One element is allowed per language:

This means that only one element of this type is allowed per language, so the user agent must only use the first element, in document order, that matches a language range in the user agent's locales and ignore any subsequent repetitions of the element that contain a matching xml:lang value (even if the content of any proceeding matching element is different).

For example, assume the user agent's locales only contains the following language range: "en-us" (English as used in the United States). As only one instance of the description element is allowed per language, in the following code the user agent would match the first description element but would ignore the second (and any other subsequent) description element.

<widget xmlns="http://www.w3.org/ns/widgets">
   
   <description xml:lang="en">
      This element would be used. 
   </description>
   
   <description xml:lang="en">
      This element would be ignored.  
   </description>

   <description>
      This element would be used if the user agent's 
      locale does not match any localized description
      elements.
   </description>

</widget>

However, if the user agent's locales was "*", or did not match any of the localized description elements, then the user agent would match the third description element above.

Elements are grouped by language:

This means that the user agent must match all elements of a particular type whose xml:lang attribute match the language ranges held by the user agent's locales.

The term in error is used in this Step to mean that an element or attribute or file in a configuration document is not conforming to the rules of this specification. How an element or an attribute is to be treated when it is in error is always given when the term is used.

During the processing of a configuration document, an error condition can ask the user agent ignore an object (e.g., a file or a DOM node). This means that the user agent must act as if that object is not present.

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

To associate means that two or more bits of information are bound and stored together for the purpose of later processing (e.g., the name of a feature, and if it is required, and any associated parameters). How associated data is represented is left up-to the implementation (e.g., a user agent could use an array, or an object, or a hash map, etc.).

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

1. Let doc be the result of loading the widget config doc as a [DOM3Core] Document using a [XMLNS]-aware parser.

2. If the document is not well-formed [XML], terminate this algorithm and treat this widget package as an invalid Zip archive.

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 package as an invalid Zip archive.

5. Otherwise,

   the element is a widget element:

   If any of the following attributes are in error or invalid, then the user agent must ignore those attribute.

   If the id attribute is used, let id be the result of applying the rule for getting a single attribute value to the id attribute. If id is a valid URI, then let widget id be the value of the id.

   If the version attribute is used, then let widget version be the result of applying the rule for getting a single attribute value to the version attribute.

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

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

   If the viewmodes attribute is used, let viewmodes list be the result of applying the rule for getting a list of keywords from an attribute. From the viewmode list, remove any unsupported items, or any items that are not one of the valid view modes, or any duplicated items. Let widget window modes be the value of viewmodes list.

   If any other attribute, in any XML namespace, apart from xml:lang, is used, then the attribute is in error the user agent must ignore it.

   If the widget element does not contain any child elements, then terminate this algorithm and go to Step 8. Otherwise, continue this algorithm.

6. Let element list be an empty list.

   For each range in the user agent's locales, starting from the first and moving to the last:

   1. Let matching elements be the result of applying lookup to the child elements of type name, description, and license that are direct descendents of the root element and whose xml:lang attribute matches the current range. Document order must be retained in the resulting matching elements list.

   2. Append matching elements to the element list.

7. For each range in the user agent's locales, starting from the first and moving to the last:
   1. Let matching elements be the result of applying lookup to the child elements of type icon that are direct descendents of the root element and whose xml:lang attribute matches the current range. Document order must be retained in the resulting matching elements list.
   2. If matching elements is not empty, append matching elements to element list and continue to step 8 in this algorithm.
   3. If matching elements is empty, continue to the next range.

8. Let unlocalized elements be all child elements that are direct descendents of the root element that do not have a declared xml:lang attribute (i.e., match all unlocalized content). Document order must be retained in the resulting list.

9. Append unlocalized elements to the element list.

10. For each element in the elements list, if the element is one of the following:

    A name element:

    If this is not the first name element encountered, then the user agent must ignore the element and its child nodes. Stop processing this element and proceed to the next element in the elements list.

    If this is the first name element encountered,

    1. Let widget name be the result of applying the rule for getting text content with normalized white space to this element.

    2. If the short attribute is used, then let widget short name be the result of applying the rule for getting a single attribute value to the short attribute.

    A description element:

    If this is not the first description element encountered, then the user agent must ignore the element and its child nodes. Stop processing this element and proceed to the next element in the elements list.

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

    A license element:

    If this is not the first license element encountered, then the user agent must ignore this element, its attributes, and any child nodes. Stop processing this element and proceed to the next element in the elements list.

    Let license text be the result of applying the rule for getting text content to this element. Associate license text with widget license.

    If the href attribute is used, then let license href be the result of applying the rule for getting a single attribute value to the href attribute.

    If license href is not a valid uri or a valid path, then the href attribute is in error and the user agent must ignore it.

    If license href is a valid uri, then associate license href with widget license. Stop processing this element and proceed to the next element in the elements list.

    If license href is a valid path, then let license file the result of applying the rule for finding a file within a widget package to license href.

    If license file is not a processable file, as determined by applying the rule for identifying the media type of a file, then stop processing this element and proceed to the next element in the elements list. Otherwise, associate license file with widget license.

    An icon element:

    If the src attribute is missing, then the user agent must ignore this element and its attributes. Stop processing this element and proceed to the next element in the elements list.

    Let path be the result of applying the rule for getting a single attribute value to the src attribute. If path is not a valid path, then the user agent must ignore this element and its attributes. Proceed to the next element in the elements list.

    Let file the result of applying the rule for finding a file within a widget package to path. If file is in error, then the user agent must ignore this element and its attributes. Stop processing this element and proceed to the next element in the elements list.

    If file is not a processable file, as determined by applying the rule for identifying the media type of an image, or already exists in the icons list, then the user agent must ignore this element. Stop processing this element and proceed to the next element in the elements list.

    Otherwise,

    1. If the height attribute is used, let potential height be the result of applying the rule for parsing a non-negative integer to the attribute's value. If the potential height is not in error and greater than 0, then associate the potential height with file. Otherwise, the attribute is in error and the user agent must ignore it.

    2. If the width attribute is used, let potential width be the result of applying the rule for parsing a non-negative integer to the attribute's value. If the potential width is not in error and greater than 0, then associate the potential width with file. Otherwise, the attribute is in error and the user agent must ignore it.

    3. Add file and any associated potential width and/or potential height to the list of icons.

    An author element:

    If this is not the first author element encountered, then the user agent must ignore this element and any child nodes. Stop processing this element and proceed to the next element in the elements list.

    If this is the first author element used, then:

    1. If the href attribute is used, let href-value be the value of applying the rule for getting a single attribute value to the href attribute.

    2. If href-value is a valid uri, then let author href be the value of the href attribute. Otherwise, the user agent must ignore the attribute.

    3. If the email attribute is used, then let author email be the result of applying the rule for getting a single attribute value to the email attribute.

    4. Let author name be the result of applying the rule for getting text content with normalized white space to this element.

    A preference element:

    If a value attribute is used, but the name attribute is absent, then this element is in error and the user agent must ignore it.

    Otherwise,

    1. Let preference-name be the result of applying the rule for getting a single attribute value to the name attribute.

    2. If the preference-name is an empty string, then this element is in error and the user agent must ignore it. Stop processing this element and proceed to the next element in the elements list.

    3. Let preference-value be the value of the the value attribute. Associate the preference-value with the preference-name derived above.

    4. Add the preference-name and the associated preference-value to the list of preferences.

    An access element:

    A user agent that does not support the [Widgets-Access] specification must ignore this element. Stop processing this element and proceed to the next element in the elements list.

    Otherwise, if the user agent supports the [Widgets-Access], refer to the [Widgets-Access] specification for how to process this element.

    An update element:

    A user agent that does not support the [Widgets-Updates] specification must ignore this attribute. Stop processing this element and proceed to the next element in the elements list.

    Otherwise, if the user agent supports the [Widgets-Updates], refer to the [Widgets-Updates] specification for how to process this element.

    A content element:

    If this is not the first content element encountered, then the user agent must ignore this element and its child nodes. Stop processing this element and proceed to the next element in the elements list.

    If this is the first content element,

    1. If the src attribute is missing, then the user agent must ignore this element and its attributes. Stop processing this element and proceed to the next element in the elements list.

    2. Let path be the result of applying the rule for getting a single attribute value to the value of the src attribute.

    3. If path is a valid path, let file be the result of applying the rule for finding a file within a widget package to path. If path is not a valid path, then a user agent must treat the widget package as an invalid Zip archive.

    4. If the type attribute is absent, then check if file is supported by the user agent by applying the rule for identifying the media type of a file. If the file is supported, let the widget start file be the file referenced by the src attribute and let start file content-type be the supported media type as was derived by applying the rule for identifying the media type of a file.

    5. If the type attribute is used, let content-type be the result of applying the rule for getting a single attribute value to the value of the type attribute. If content-type is a valid media type, then check if the value of content type is supported as a start file by the user agent. If the value of content-type is supported by the user agent, then let the start file content-type be the value of content type. If value of content-type is invalid or unsupported by the user agent, then a user agent must treat the widget package as an invalid Zip archive.

    6. If the charset attribute is used, then let content-charset be the result of applying the rule for getting a single attribute value to the value of the charset attribute. If content-charset is supported by the user agent, then let the start file encoding be the value of the charset attribute. If content-charset is unsupported by the user agent, then a user agent should use the default encoding (UTF-8).

    A feature element:

    If a required attribute is used, but no name attribute is used, then this element, its attributes, and its children are in error and must be ignored by the user agent. Stop processing this element and proceed to the next element in the elements list.

    1. Let feature-name be the result of applying the rule for getting a single attribute value to the value of the name attribute.

    2. If feature-name is not a valid URI, then the user agent must ignore this element, its attributes, and its children. Stop processing this element and proceed to the next element in the elements list.

    3. If feature-name is not supported by the user agent, then this element, its attributes, and its children are in error and must be ignored. Stop processing this element and proceed to the next element in the elements list.

    4. If a required attribute is used, let required-feature be the result of applying the rule for getting a single attribute value to the required attribute. If required-feature is not a valid boolean value, let the value of required-feature be the value 'true'.

    5. Associate the value of required-feature with feature-name.

    6. If the feature element contains param elements as direct descendants, then, for each child param element that is a direct descendent of this feature element, starting from the first moving to the last in document order:

       1. If a value attribute is used, but the name attribute is absent, then this param element is in error and the user agent must ignore it. Stop processing this param element and move onto the next param element (if any).

       2. If a name attribute is used, but the value attribute is absent, then this param element is in error and the user agent must ignore it. Stop processing this param element and move onto the next param element (if any).

       3. Let param-name be the result of applying the rule for getting a single attribute value to the name attribute. If the param-name is an empty string, then this param element is in error and the user agent must ignore it. Stop processing this param element and move onto the next param element (if any).

       4. If, and only if, param-name is not in error or an empty string, let param-value be the result of applying the rule for getting a single attribute value to the value attribute. If the param-value is an empty string, then this param element is in error and the user agent must ignore it.

       5. Associate param-name and param-value with feature-name.

    7. Append feature-name, and any associated required-feature, and associated parameters, to the feature list.

    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 a param element, or anything else:

    This is in error and the user agent must ignore it.

11. Once all the elements in the elements list have been processed, go to Step 8.

Step 8 - Locate the Start File

This step only applies if a custom start file was not specified (i.e., if widget start file is null), in which case the user agent must attempt to find a default start file. If widget start file contains a file, then skip this Step and go to Step 9.

1. For each file name in the default start files table (from top to bottom) that has a media type that is supported by the user agent:
   1. Let potential-start-file be the result of applying the rule for finding a file within a widget package to file name.
   2. If potential-start-file is null or an error, ignore this file name and move onto the next file name in the default start files table.
   3. If potential-start-file is a file, then:
      1. Let widget start file be the value of potential-start-file.
      2. Let start file content-type be the media type given in the second column of the default start files table.
      3. Terminate this algorithm and go to Step 9.
2. If after searching for every file in the default start files table no default start file is found, then the user agent must treat this widget as an invalid Zip archive.

Step 9 - Locate the Default Icons

This step describes how to locate the default icons.

For each file name in the default icons table (from top to bottom) that has a media type that is supported by the user agent:

1. Let potential-icon be the result of applying the rule for finding a file within a widget package to file name.
2. If the following conditions are all true, then add the value of potential-icon to the icons list of the configuration defaults:
   • The value of potential-icon is a file.
   • The potential-icon is a processable file, determined by the media type given in the second column of the default icons table.
   • The potential-icon does not already exist in the icons list of the configuration defaults.
3. Move onto the next file name in the default icons table.

Appendix

Linking To a Widget Package From a HTML Document

This section is non-normative.

This section only applies to HTML user agents [HTML5][HTML4] [XHTML1.1].

Auto-discovery enables a user agent to identify and install a widget package that is associated with an HTML page. When a page points to a widget package, user agents should expose the presence of the widget package to the end-user and allow the end-user to install the widget.

The link type "widget" indicates that a link of this type references a document that is a widget package. 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.

The following is the [RelaxNG] schema representation of the elements, and their attributes, of the configuration document. A conformance checker may use this schema to validate elements of a configuration document within the limits of the [RelaxNG] specification.

# Widgets 1.0 (Working Draft) RELAX NG schema

default namespace widgets = "http://www.w3.org/ns/widgets"
namespace its = "http://www.w3.org/2005/11/its"
namespace local = ""

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" )

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 viewmodes {
    list {
      ( "application"
      | "floating"
      | "fullscreen"
      | "mini"
      | "all" )*
    }
  }?,
  ( elem.name*
  & elem.description*
  & elem.icon*
  & elem.author?
  & elem.license*
  & elem.content?
  & elem.feature*
  & elem.preference*
  & extension )
}

elem.name = element name {
  attr.xmllang?,
  attr.itsdir?,
  attribute short { text }?,
  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.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.feature = element feature {
  attribute name { xsd:anyURI },
  attribute required { data.boolean }?,
  ( elem.param?
  & extension )
}

elem.param = element param {
  attribute name { text },
  attribute value { text },
  extension
}

elem.preference = element preference {
  attr.xmllang?,
  attribute name { text },
  attribute value { text }?,
  attribute readonly { data.boolean }?,
  extension
}

Acknowledgements

Special thanks go to Arve Bersvendsen, Anne van Kesteren, Robin Berjon, and Charles McCathieNevile who helped edit various versions of this specification.

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

A huge thanks to Sam "gsnedders" Sneddon, whose Anolis specification-generator was used to generate this document.

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 editors would also like to thank the following people for their contributions to this specification:

Addison Phillips, Alexander Dreiling, Arun Ranganathan, Arthur Barstow, Bárbara Barbosa Neves, Brian Wilson, Bjoern Hoehrmann, Benoit Suzanne, Bert Bos, Boris Zbarsky, Bradford Lassey, Cameron McCormack, Cliff Schmidt, Claudio Venezia, Coach Wei, Corin Edwards, Dan Brickley, David Clarke, Dean Jackson, David Pollington, Doug Schepers, Ed Voas, Felix Sasaki, Francois Daoust, Gautam Chandna, Geir Pedersen, Gene Vayngrib, Gorm Haug Eriksen, Guido Grassel, Ian Hickson, Jay Sweeney, Jere Kapyaho, Jim Ley, Jon Ferraiolo, Jose Manuel Cantera Fonseca, Jouni Hakala, Joey Bacalhau, Kevin Lawver, Kai Hendry, 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]

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

[BCP47]

Tags for the Identification of Languages, BCP 47. 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, B. Bos, I. Hickson, T. Çelik, H. Wium Lie. W3C Candidate Recommendation 23 April 2009.

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

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

[ITS]

Internationalization Tag Set (ITS) Version 1.0, C. Lieske and F. Sasaki, W3C Recommendation 03 April 2007.

[JPEG]

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

[HTTP]

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

[IANA-Charsets]

IANA Character Set Registry.

[MIME]

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

Multipurpose Internet Mail Extensions(MIME) Part Two: Media Types, RFC2046, N. Freed and N. Borenstein, IETF, 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.RFC2119, S. Bradner. March 1997.

[RFC3987]

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

[RFC4647]

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

[SNIFF]

Content-Type Processing Model. A. Barth and I. Hickson. Google, Inc. January 9, 2009

[SVG]

Scalable Vector Graphics (SVG) 1.1 Specification. J. Ferraiolo, 藤沢 淳, D. Jackson. W3C Recommendation 14 January 2003.

[SVGTiny]

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

[SVGTiny12]

Scalable Vector Graphics (SVG) Tiny 1.2 Specification. O. Andersson, R. Berjon, E. Dahlström, A. Emmons, J. Ferraiolo, A. Grasso, V. Hardy, S. Hayman, D. Jackson, C. Lilley, C. McCormack, A. Neumann, C. Northway, A. Quint, N. Ramani, D. Schepers, A. Shellshear. W3C Recommendation, 22 December 2008.

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

[URI]

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

[UTF-8]

UTF-8: A Transformation format of ISO 10646, RFC 3629, F. Yergeau. IETF, November 2003.

[Widgets-Access]

Widgets 1.0: Access Requests. R. Berjon, M. Cáceres, A. Bersvendsen. Unpublished Editor's Draft.

[Widgets-APIs]

Widgets 1.0: API's and Events. A. Bersvendsen and M. Cáceres. W3C Working Draft 23, April 2009 (Work in progress).

[Widgets-DigSig]

Widgets 1.0: Digital Signature. F. Hirsch, M. Cáceres, and M. Priestley. W3C Working Draft 30 April 2009 (Work in progress).

[Widgets-Views]

Widgets 1.0: Media Query Extensions. A. Bersvendsen and M. Caceres. Unpublished editors' draft.

[XML]

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

[XMLNS]

Namespaces in XML (Second Edition), T. Bray, D. Hollander, A. Layman, R. Tobin. W3C, August 2006.

[ZIP]

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

Informative References

[HTML4]

HTML 4.01 Specification, D. Raggett, A. Le Hors, I. Jacobs, 24 December 1999.

[HTML5]

HTML 5, I. Hickson and D. Hyatt. W3C Working Draft, 2008.

[RelaxNG]

RELAX NG Specification, J. Clark and M. Makoto. Committee Specification 3 December 2001.

[Widgets-Landscape]

Widgets 1.0: The Widget Landscape (Q1 2008). M. Cáceres. W3C Working Draft. 14 April 2008 (Work in progress).

[Widgets-Updates]

Widgets 1.0: Updates. M. Cáceres. W3C Working Draft, 7 October 2008 (Work in progress).

[Widgets-Reqs]

Widgets 1.0 Requirements, M. Cáceres and M. Priestley. W3C Working Draft, 30 April 2009 (Work in progress).

[Widgets-Test-Suite]

forthcoming.

[XHTML1.1]

XHTML™ 1.1 - Module-based XHTML - Second Edition. S. McCarron and M. Ishikawa. W3C Working Draft 16 February 2007.