W3C

Widgets 1.0: Packaging and Configuration

W3C Working Draft 28 May Candidate Recommendation 23 July 2009

This version:
http://www.w3.org/TR/2009/WD-widgets-20090528/ http://www.w3.org/TR/2009/CR-widgets-20090723/
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: Draft:
http://dev.w3.org/2006/waf/widgets/
Version history:
Twitter messages (non-editorial changes only): http://twitter.com/widgetspecs ( RSS )
Differences between latest editor's draft and latest version .
See the Last Call comments and how they were addressed.
Editors:
Marcos Cáceres , Opera Software ASA

Abstract

This document specification standardizes a packaging format for a class of software application known as a widget. widgets. 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 document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .

This is the 28 May 23 July 2009 Last Call Working Draft version Candidate Recommendation of the "Widgets Widgets 1.0: Packaging and Configuration" Configuration specification. The Last Call period ends on 19 June 2009. This version reflects over of two years work addressing requirements 1 W3C publishes a Candidate Recommendation to 25 of indicate that the Widgets 1.0: Requirements document [Widgets-Reqs] . The requirements were addressed and specified through extensive research, and via consultation with W3C members is believed to be stable and to encourage implementation by the public via developer community. The Web Applications (WebApps) Working Group expects to request that the Director advance this document to Proposed Recommendation once the Working Group's mailing lists ( WAF archive Group has developed a comprehensive Widgets 1.0: Packaging and Configuration test suite , WebApps archive and demonstrated at least two interoperable implementations (interoperable meaning at least two implementations that pass each test in the test suite ). The purpose of this Last Call is WebApps Working Group expects to give external interested parties a final opportunity show these implementations by October 2009. The Working Group does not plan to publicly comment request to advance to Proposed Recommendation prior to 01 November 2009.

Feedback based on how widgets should be packaged any aspect of this specification is welcome and configured before encouraged. However, there are certain features in the specification that the Working Group makes a call for implementations. The Working Group's goal is particularly interested in getting feedback on: these are marked as "feature at risk" within the specification. Whether such features are retained or dropped by the Working Group when the document progresses to make sure that vendor's requirements for packaging and configuration have been effectively addressed Proposed Recommendation will depend on the feedback received from implementers, other working groups, and clearly specified. the public.

This document is produced by the Web Applications WG , part of the Rich Web Clients Client Activity in the W3C Interaction Domain . It is expected that this document will progress along the W3C's Recommendation track.

Publication as a Working Draft 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.

Implementers should be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions. Note: User agents that wish to extend this specification in any way are encouraged to discuss their extensions on a public forum, such as public-Webapps so their extensions can be considered for standardization.

Table of Contents

1 Introduction

This section is non-normative.

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: 25 requirements relating to " Packaging " and " Configuration Document " of the 30 April 2009 Working Draft of the Widgets 1.0: Requirements Document:

  1. Packaging Format : see packaging format .
  2. Media Type : see the valid 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 table .
  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 , table of 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 files 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.

This section defines the typographical conventions used by this specification.

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 , MUST NOT must not , Required required , SHOULD should , SHOULD NOT should not , RECOMMENDED recommended , MAY may and OPTIONAL 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. Examples are non-normative.

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

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

Authoring guideline: Guideline: This is an authoring guideline. Authoring Guideline. Its purpose is to provide authors with best-practice authoring techniques. Authoring guidelines are non-normative.

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

1.5 2 Conformance

The key words must ,must not ,required ,should ,should not ,recommended ,may and optional in this specification [RFC2119] .

Some text in this specification is non-normative. Non-normative text includes:

Everything else in this specification is normative.

Please see the typographical conventions to see how authoring guidelines, examples, and notes of this specification are stylized.

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 .

A user agent may support other legacy/proprietary widgets.

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

An end-user is the actual human user of a widget.

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

A language tag is a text string that matches must match the production of a Language-Tag defined in the [BCP47] specifications. It is optional for a user agents agent 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, Bluetooth or a USB thumb drive, etc.). 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 .

Unsupported means the user agent does not implement a mentioned specification, or feature ,or is unable to render or otherwise process a mentioned media type .

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

3.0.1 Character Definitions

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

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

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

The key words must , must not , Required , should , should not , recommended , may and optional in this specification following Unicode code points are referred 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 forbidden characters in this specification:

A user agent .

3 4 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 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 document .

Note: Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the [Widgets-Test-Suite] . [P&C-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:

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

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

4.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 4.2 Internationalized 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 may support the Internationalized 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> 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> its:span and its:dir , then the user agent must do so in conformance to the processing rules defined by the [ITS] specification.

4 5 Conformance Checker

A conformance checker ( CC ) is a user agent that verifies if 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 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. CCs are It is not required optional for a CC to display all messages at once.

5 6 Zip Archive

The packaging format for the files of a widget are packaged using is the Zip archive format as defined in the [ZIP] file format specification(in other words, the [ZIP] file format is the packaging format for widgets). 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 claiming to be a Zip archive, that has not been verified to be a valid Zip archive .

A valid Zip archive is a data object that conforms must conform to the production of a .Zip .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. section of this specification.

Note: Step 2 of the steps for processing a widget package describes how a user agents verify agent verifies that a Zip archive conforms to this specification.

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

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

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

6.1 Invalid Zip archive

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.1.1 Conformance Checker Behavior

A CC must inform the author that a Zip archive that is split into multiple files or spans multiple volumes ,as defined in the [ZIP] specification, is an invalid Zip archive .

A CC must inform the author that a Zip archive that is encrypted, which is denoted by bit 0 of the general purpose field being set and by the presence of archive decryption header and an archive extra data record (all three of which are defined in the [ZIP] specification), is an invalid Zip archive .

A CC must inform the author that a Zip archive that contains zero file entries is an invalid Zip archive .

A CC must inform the author that a Zip archive that contains only folders is an invalid Zip archive .

5.1 6.2 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: Guideline: Only To ensure interoperability, compress file entries in Zip archives with [Deflate] or Stored (no compression); other compression formats will cause methods can result in in the widget package to be Zip archive being treated as an invalid Zip archive .

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

6.2.1 Conformance Checker Behavior

A conformance checker CC must verify that each file entry uses one of the valid compression methods . If a CC encounters a file entry that uses a compression method that is not one of the Stored valid compression method, methods , then the CC must inform the author that to recompressed 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 6.3 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 version supported version of the [ZIP] specification needed to extract the file data .

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

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 .

6.3.1 Conformance Checker Behavior

If a

A CC encounters a must inform the author of any file entry with a value for version needed to extract that is does not one of the match a valid versions needed to extract values, the the CC must inform the author value (meaning that user agents could potentially ignore the file is an invalid Zip archive . at run time).

5.3 6.4 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 treat all zip-relative 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] :

     = [ *localized-folder ] [ *folder-name ] 
                   [ file-name ] / 
                   [ localized-folder ] [ *folder-name ] / 
                   [ folder-name ] 
    = "locales" "/" Language-Tag "/"
file-name        = 1*254( *base-name [ file-extension ] ) 
        = allowed-chars       
   = "." 1*allowed-chars       
    = cp437-chars / utf8-chars    

Zip-rel-path   = [ *folder-name ] file-name /
[ locale-folder ] 1*folder-name /
locale-folder [ *folder-name ] file-name locale-folder = %x6c.%x6f.%x63.%x61.%x6c.%x65.%x73 ; "locales" "/" folder-name folder-name = file-name "/" = safe-chars / U+0080 and beyond = safe-chars / x80-FF = ALPHA / DIGIT / SP / "$" / "%" 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). The ABNF for Language-Tag is defined in the [BCP47] specification. Reserved characters must not appear anywhere in the file-name .

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

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

In addition, in the appropriate encoding indicator needs to be used, meaning that if case where the Zip relative path is encoded using [UTF-8] , then general purpose bit 11 of the local file header needs to be set to 1 ; otherwise, it language encoding flag (EFS) needs to be set to 0 . set.

Authors need to be aware that, at the time of writing, publication, there are some interoperability issues with regards to using characters outside the safe-chars range for file or folder names in a Zip archive. archive when using Zipping tools bundled with operating systems. The interoperability issues have arisen from non-conforming implementations of the [ZIP] specification across operating systems: very few, if any, correctly support encoding file names in Unicode.

If an author chooses to use cp437-chars or the UTF8-chars utf8-chars , they should need to 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.

6.4.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 Zip-rel-path .

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

5.4 6.5 Reserved Characters Forbidden in File Names

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

A user agent must ignore a file entry that contains control characters or reserved contain forbidden characters in the Zip relative path .

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

Reserved Characters Representative Glyph Unicode Character < U+003C LESS-THAN SIGN > U+003E GREATER-THAN SIGN : U+003A COLON " U+0022 QUOTATION MARK / U+002F SOLIDUS \ U+005C REVERSE SOLIDUS | U+007C VERTICAL LINE ? U+003F QUESTION MARK * U+002A ASTERISK ^ U+005E CIRCUMFLEX ACCENT ` U+0060 GRAVE ACCENT { U+007B LEFT CURLY BRACKET } U+007D RIGHT CURLY BRACKET ! U+0021 EXCLAMATION MARK

Authoring Guideline: Avoid using forbidden characters when naming the files used by a widget.

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): (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.

6.5.1 Conformance Checker Behavior

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

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

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

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

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

6 7 Widget Packages

A widget package is 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 7.1 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 table and reserved folder names table ).

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 user agent retrieves them from within a zip Zip archive.

A folder is a file entry whose file name field matches must match 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 must be a file that:

6.3 7.2 Reserved File and Folder Names

The reserved file names table, table , below, contains a list of base-name s and possible file-extension s that when combined form file-names file names that are reserved for some purpose by this specification. Reserved The first column of the reserved file names must be treated as case-sensitive. table, below, contains a case-sensitive list of file names. The second column of the table denotes the purpose for which the file name is reserved .

Reserved File Names Table
base-name file-extensions file name reserved for purpose
config xml config.xml Configuration document
icon.png Default icon
png, gif, ico, svg icon.gif Default icon
index icon.jpg html, htm, svg, xhtml, xht 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

Files named using the naming conventions for a distributor signature signatures and the naming convention for an author signature . The names of those files , as defined in the [Widgets-DigSig] specification, are also reserved for the purpose of in this specification.

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

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

6.4 7.3 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 beyond the 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 only to the implementation of the [Widgets-DigSig] specification. specification; the user agent must not make the digital signatures accessible to scripting or other content loading mechanisms, unless explicitly enabled by an access control mechanism.

6.5 7.4 Start Files

The

A start file of a widget package is designates a file that is used from the widget package to be loaded by the user agent when it instantiates the widget is instantiated. widget. This specification defines two kinds of start file: custom start file and default start file .

7.4.1 Custom start file Start File

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

7.4.2 Default Start File Files

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

A

If no custom start file has been declared, 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 ,

If a user agent must attempt to locate encounters a file entry whose file-name matches one matching a file name given in the file name column of the default start files table based on the order they appear in the default start files an arbitrary table below (from top to bottom). File names folder ,the user agent must treat that file as an arbitrary file. For example, " foo/bar/index.html " would be treated as case-sensitive. 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 a user agents agent to support the media types listed in the default start files table. table .

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

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

7.4.3 Conformance checker behavior 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 7.5 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 .

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

A user agent must derive the media type of a custom icon is derived by applying 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 .

7.5.2 Default Icons

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

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

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

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

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: Guideline: If using [SVG] as an icon format format, and one intends 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 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 SHOULD inform an the author that it is desirable, but optional, desirable 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 the author that these other formats might not be supported on by all user agents.

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

6.7 7.6 Media type Type

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

Authoring guideline: Guideline: Over If the wire (e.g. protocol over HTTP), 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 can 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.

7.6.1 Conformance Checker Behavior

A CC MUST inform the author if a widget package is not being served from a remote location with the valid widget media type .

6.8 7.7 File Extension

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

The widget file extension is Required required for widget packages on systems where it is customary for file names to include an extension a file-extension that symbolizes the (or is associated with) a media type .

Authoring guideline: Guideline: If it is anticipated that the widget will be distributed by non-HTTP means, means lacking MIME support, 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 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: 7.7.1 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 Conformance Checker Behavior

For when 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: By placing localized file content in locale folders , a process referred to as folder-based localization . 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 This example shows a widget that displays the days of the week based on the language ranges held by the user agent's locales . If the user agent is unable to match a language range to any locale folder , the widget displays /index.html at the root of the widget package . /config.xml <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> /sp/index.html <!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 weekdays.wgt index.html /*English*/ config.xml scripts engine.js locales fr/ index.html /*French*/ es/ index.html /*Spanish*/ pt/ index.html /*Portuguese*/ fi/ index.html /*Finnish*/ it/ index.html /*Italian*/ Complex Example The following is an example of a localized widget with multiple localized icons , start files and configuration documents . Some relevant things to note from the example: The Spanish version ( /locales/sp/ ) has its own localized icon. The Spanish ( locales/es ) and English ( locales/en/ ) versions of the widget use the un-localized script in /scripts/engine.js folder. On the other hand, the English-Australia ( en-au ) version uses a localized script ( en-au/scripts/engine.js ). /config.xml <widget xmlns="http://w3.org/ns/widgets"> <name xml:lang="ko">웃기는 고양이</name> <content src="cats.html"/> </widget> /locales/en-au/cats.html <!doctype html> <title>G'day! LOL Cats!</title> <script src="scripts/engine.js"> ... /locales/es/gatos.html <!doctype html> <title>Gatos Graciosos!</title> <script src="/scripts/engine.js"> ... LOLcats.wgt cats.html /*written in Korean*/ config.xml icon.png /*default icon*/ signature.xml /*not localizable*/ scripts/ engine.js /*default functionality*/ locales/ /*container for localized content*/ en-au/ cats.html scripts/ engine.js /*custom localized functionality*/ en/ cats.html /*international english version*/ es/ gatos.html /*Spanish version*/ icon.png /*localized icon*/ Fallback Behavior Example This specification allows authors to place files and folders they don't wish to localize at the root of the widget package. At runtime, if the user agent fails to find a file in a locale folder , it will always search at the root of the widget package for that missing file. The purpose of this "fallback" model is to reduce then number of files that need to be created to achieve localization of a widget package. The example below demonstrates how a user agent attempts to locate a file that is absent in a localized scenario: Firstly, the user agent will search for served over HTTP, a folder that matches the user agent's locale as closely as possible for the desired file. If the file is absent, the user agent will search for the absent file in any other sub folder that is in the language range of the current locale folder. If the above fails, the user agent will search for the absent file at the root of the widget package. So, for example, assume the user agent's locale is ' en-gb '. The user agent would fail to locate 'mast.png' so the next place it would look is in the ' en/ ' folder, where it would find the absent ' mast.png ' file. Now consider the for various Chinese variants: ' zh-Hans-CN ', ' zh-Hans ', and ' zh ' below. In this case, to find find the ' flag.png ' file for Mainland Chinese in simplified script ' zh-Hans-CN ', the user agent would first look in ' zh-Hans-CN ', followed by ' zh-Hans ', then in ' zh ' where the file is located. To find the ' mast.png ' file, the user agent would look in ' zh-Hans-CN ', followed by ' zh-Hans ', followed ' zh ', and finally at the root of the widget package where the absent file is actually located. /index.html <!doctype html> <title>Patriotic Boat</title> <script src="/scripts/engine.js"> </script> <body> <img src="flag.png"> <img src="mast.png"> boat.wgt index.html mast.png flag.png scripts/ engine.js locales/ en-gb/ flag.png en/ mast.png zh-Hans-CN/ zh-Hans/ zh/ flag.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 must 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 if the production of locale-folder file-extension 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. Authoring guideline: Authors need to avoid region, script or other subtags except where they add useful distinguishing information to a locale folder . In addition, avoid including empty locale folders in a widget package (unless there is a good reason to include them). An example of a widget that uses folder-based localization: widget.wgt config.xml index.html fun.gif locales/en/fun.gif locales/fr/french.html locales/fr/fun.gif Authors can further facilitate the localization process by grouping files into folder hierarchies made up of matching subtags , as is shown in the example below. However, widget packages localized at any folder level (e.g. " locales/zh/ ") needs to be fully functional as not a localized widget . That is, authors cannot simply put shared files into a language level folder , but need to put all files needed into the language level folder for the widget to work (for example, having " a.gif " in both the "/locales/zh-Hans/" folder and "/locales/zh/" ). Note also that the user agent treats any file extension or folder outside the container for localized content as unlocalized content . For example, all English versions can share the files " shared1.gif, shared2.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 This works at all sub-levels, so long as the parent subtag matches the child subtags. So, for example, the " CN " region below can make use of the localized files in the " zh-Hans " folder level, the " zh " folder level, and the unlocalized files at the root of the widget package. The user agent always prioritizes files in sub-folders over files in locale folders closer to the root of if the widget package . In the example below, assuming the widget's locale is " zh-hans-cn ", content in the " zh-Hans-CN" locale folder would have a higher priority than content in the zh-Hans locale folder , which in turn would have lacks a higher priority than content in the zh locale folder . The content in the zh locale folder file-extension would have a higher priority than content at the root of the widget package . .

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 .

Note: Please see Step 7 for details of how the elements of the configuration document are processed by a user agent.

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

A user agent must treat a valid configuration document file name case-sensitively.

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

User agents

A user agent must treat files in an arbitrary folder or locale folders that use the file name config.xml as an arbitrary file.

Authoring guideline: 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">

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

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

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

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

8.0.1 Conformance Checker Behavior

A CC must inform the author if there is no configuration document at the root of the widget package .

A CC must inform the author the file-name of the configuration document does not case-sensitively match the string " config.xml " (that is, by checking for the configuration document's file-name in other case forms.).

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

8.1.1 Conformance Checker Behavior

A CC must inform the author if the configuration document is lacking the widget 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 .

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>

8.2.1 Conformance Checker Behavior

A CC must inform the author of the presence of any proprietary extensions to the configuration document outside the widget namespace.

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 rules for how attributes are to be processed by a user agent or conformance checker are also given in this section.

User agents

A user agent 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.

Version Boolean attribute
The value of

A boolean attribute is a version keyword attribute that can only be used with a valid boolean value. A valid boolean value is an arbitrary a string (possibly empty) that denotes a software version identifier. This specification does not mandate any specific format, semantics, case-sensitively matches true or special processing rule for false .Unless specified otherwise, the format of this attribute type. In other words, all strings are valid for this attribute type within default behavior, which is used when the constraints of [XML] attributes. The value of this kind of attribute is retrieved using the rule for getting omitted or has a single attribute value . Author Guidelines: For the purpose of this specification, other than the structure of version tags has no semantics; they are just treated as arbitrary strings (e.g. '1.0' two allowed values, is not greater than '2.0', but false .The way a user agent interprets a boolean attribute is simply different). However, for the sake defined as part of consistency, one can choose to use an attribute's definition (see, for example, 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: feature 1.0 , 1.10.1beta1 , 1.02.12rc1 . element's Numeric attribute required 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, user agent must retrieve the characters "2", "323", "23214", and so on. The value of this kind of a boolean 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

For keyword attributes ,authors must use keywords in the case given in this specification. Implementations

User agents must only perform literal comparisons on the resulting value, keyword attributes , and must not use case insensitive case-insensitive comparisons. How the value of this attribute is retrieved by a user agent depends on the context in which is it used, so used: so, the rule for hoe how to retrieve the value is given when this attribute type is used. used in the specification.

Keyword list attribute

An attribute defined as taking one or more keywords as values, 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 .

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, must retrieve the feature element's required attribute). The value of this kind of a keyword list attribute is retrieved using the rule for getting a single list of keywords from an 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 A user agent must retrieve the value of this kind of attribute is retrieved using the rule for getting a single attribute value .

URI Numeric attribute
An

The value of a numeric attribute defined as is a string containing a valid URI. non-negative integer. A valid URI non-negative integer is one a string that matches the URI token consists of the [URI] specification one or more code points in the IRI token of range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). For example, the characters "002", "323", "23214", and so on.

A user agent must retrieve the [RFC3987] specification. The value of this kind of a numeric 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 Zip-rel-path or a zip-abs-path Zip-abs-path . A valid path is not a URI: a valid path represent a hierarchical path to a file inside a Zip archive ,which must exactly match the value of a file name field of a local file header of a file entry .This means that valid paths must not be URL encoded.

A zip Zip absolute path is one that case-insensitively matches the production of zip-abs-path Zip-abs-path in the following [ABNF] :

Zip-abs-path = "/" Zip-rel-path

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

The

A user agent must retrieve the value for a path attribute using the rule for getting a single attribute value .

IRI attribute

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

A user agent must retrieve the value for a IRI attribute using the rule for getting a single attribute value .

Version attribute

The value of a version attribute is retrieved an arbitrary string (possibly empty). This specification does not mandate any specific format, semantics, or special processing rule for the format of a version attribute .A user agent must allow any string, within the constraints allowed for [XML] attributes, as the value of a version attribute .

A user agent must retrieve the value for a version attribute using the rule for getting a single attribute value .

Authoring Guideline: 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]
*[ 1*ALPHA / SP / 1*DIGIT ]
Example version tags:
  • Version 1.0 Beta
  • 1.0 RC1
  • 1.0-Build/1580
  • Joey the dog [5.1.2100]
Example of rec-version-tag:
  • 1.0
  • 1.10.1 beta1
  • 1.02.12 RC1

8.4 Other Attributes

This section describes the behavior and expected usage of other relevant 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 and 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 an xml:lang attribute is retrieved must be processed by a user agent in accordance with the XML . [XML] specification.

A user agent must retrieve the value for an xml:lang attribute using the rule for getting a single attribute value .

Authoring guideline: 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 ( This feature is at risk )

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.

It is optional for authors to use the its:dir attribute with any element.

A user agent must retrieve the value for an its:dir attribute using the rule for getting a single attribute value .

8.5 The widget Element

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

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.

8.5.1 Attributes of the widget Element

id

A valid URI IRI attribute that denotes an identifier for the widget.

It is optional for authors to use this attribute. the id attribute with a widget element.

version

A version attribute that specifies the version of the widget.

It is optional for authors to use this attribute. the version attribute with a widget element.

height

A numeric attribute greater than 0 that indicates the preferred view port viewport height 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 . Which The view modes should that honor the value of this the height attribute is are defined in the the [Widgets-Views] specification.

It is optional for authors to use this attribute. the height attribute with a widget element.

width

A numeric attribute greater than 0 that indicates the preferred view port 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 . Which The view modes should that honor the value of this width attribute is are defined in the the [Widgets-Views] specification.

It is optional for authors to use this attribute. the xml:lang width attribute with a xml:lang widget attribute. It is optional for authors to use this attribute. element.

viewmodes

A keyword list attribute that denotes the view modes supported the widget. The value

An author SHOULD should be use one or more of the following valid view modes modes, as defined in the [Widgets-Views] specification: application , floating , fullscreen , or mini , or . In addition, the all . keyword can be used by authors to denote that all the valid view modes are supported by the widget.

The default value, which is used a user agent must use when the attribute is omitted absent or the attribute 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 Viewport and view mode are defined in the [Widgets-Views] specification.

It is optional for authors to use the viewmodes attribute with a widget element.

xml:lang

It is optional for authors to use the xml:lang attribute with a widget element.

8.5.2 Usage Example 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>

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.

8.6.1 Attributes of the name Element

xml:lang
xml:lang attribute.

It is optional for authors to use this attribute. the xml:lang attribute with an name element.

its:dir

A valid its:dir value .

It is optional for authors to use this attribute. the its:dir attribute with an name element.

short

A string that represents the short a condensed name for a widget. Ideally, widget (e.g., a name that could be used in context were only limited space is available, such as underneath an icon).

It is optional for authors to use the value short attribute with an name element.

8.6.2 Conformance Checker Behavior

A CC should must be shorter inform an author if the value of the short attribute is longer in length than the contents text content of the name element. Otherwise, the short attribute should not be used. It is optional for authors to use this attribute.

8.6.3 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

    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.

8.7.1 Attributes of the description Element

xml:lang
xml:lang attribute.

It is optional for authors to use this attribute. the xml:lang attribute with an description element.

its:dir

A valid its:dir value .

It is optional for authors to use this attribute. the its:dir attribute with an description element.

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

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

8.8.1 Attributes of the author Element

href
A URI

An IRI attribute that whose value represents a link IRI that is associated with the author (e.g. the homepage of the author). associates with himself or herself (e.g., a homepage, a profile on a social network, etc.).

It is optional for authors to use this attribute. the xml:lang attribute with an author element.

email

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

It is optional for authors to use this attribute. the xml:lang email attribute with an xml:lang author attribute. It is optional for authors to use this attribute. element.

its:dir

A valid its:dir value .

It is optional for authors to use this attribute. the its:dir attribute with an author element.

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

    <author href  = "http://dahut.example.org/about/joe" 
            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.

8.9.1 Attributes of the license Element

href

A valid URI IRI or a valid path that points to a representation of a software and/or content license.

When the href attribute is present, used, the user agent should allow 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 MUST 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. the xml:lang href attribute with a license element.

xml:lang attribute.

It is optional for authors to use this attribute. the xml:lang attribute with a license element.

its:dir

A valid its:dir value .

It is optional for authors to use this attribute. the its:dir attribute with a license element.

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

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 . Yes, multiple repetitions of the same xml:lang value are allowed.

8.10.1 Attributes of the icon Element

src
Required .

A path attribute that points to a file inside the widget package. It

When an icon element is used, it is required for authors to use this the src attribute.

width

A numeric attribute greater than 0 that represents the width of the icon in CSS pixels [CSS21] . This attribute The width 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 of an icon element is a supported raster graphic, then the user agent will must ignore this value.

If the file pointed to by the src attribute of an icon element is of a supported vector graphic format, then this value the user agent must be used. use this value.

It is optional for authors to use this attribute. the width attribute of an icon element.

height

A numeric attribute greater than 0 that represents the height of the icon in CSS pixels [CSS21] .This .The height 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 of the icon element is a supported raster graphic, graphic format, then the user agent will must 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. the height attribute of an icon element.

xml:lang

It is optional for authors to use the xml:lang attribute with an icon element.

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

8.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 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.10.3 Usage Example

This example shows the expected usage of the icon element with the xml:lang attribute. Note that unlocalized icon elements will also be used by the user agent.

<widget xmlns="http://www.w3.org/ns/widgets">  <icon src="icons/big_en.svg" xml:lang="en"/>
  <icon src="icons/big_jp.svg" xml:lang="jp"/>
  <icon src="icons/medium.png" xml:lang="en"/>  <icon src="icons/medium.png" xml:lang="jp" />
  <icon src="icons/tiny.png"/>
  <icon src="icons/ultra-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 .

8.11.1 Attributes of the content Element

src

A path attribute that allows an author to point to a file within the widget package . It

When a content element is used, it is required for authors to use this the src 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. the type attribute with a content element.

charset encoding

A keyword attribute that denotes the character set encoding of the file identified by the src attribute. The allowed values are any name value is the "name" or "alias" of a character set any "Character Set" listed in [IANA-Charsets] (a .

A user agent are required must to support [UTF-8] , which has the " UTF-8 ). It " name in [IANA-Charsets] ; it is optional for authors a user agent to use this attribute. support other character encodings.

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

It is optional for authors to use the encoding attribute with a content element.

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

8.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 charset encoding attribute to override the default value of this the encoding 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>

8.12 The feature Element

A feature is a runtime component (e.g. an API) Application Programming Interface or video decoder) that is not part of the standard 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 (IRI) identifiable runtime component to a widget for use at runtime. Using a feature element denotes that, at runtime, a widget may can attempt to access the feature identified by the feature element's name attribute. How a user agent makes use of features depends on the user agent's security policy, hence activation and authorization requirements for features are beyond the scope of this specification.

A feature can may 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.

8.12.1 Attributes of the feature Element

name

A URI IRI attribute that identifies a feature that may be needed by the widget at runtime (such as an API). It API ).

When the feature element is declared, it is required for authors to use this the name attribute.

required

A boolean attribute that indicates whether or not this feature must be available to the widget at runtime. In other words, the When set to true ,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.

When set to false ,the required attribute denotes that a widget can function correctly without the feature being supported or otherwise made available by the user agent.

The default value that a user agent must use when this the required attribute is absent is true , meaning that the feature must be made available to the widget by the widget user agent at runtime.

It is optional for authors to use this attribute. the required attribute with an feature element.

8.12.2 Usage example

This example demonstrates a widget that would like to use a fictional geo-location API feature, but would still be able to function if the feature cannot be made available to the widget by the user agent.

<widget xmlns="http://www.w3.org/ns/widgets">
   <feature name="http://example.org/api.geolocation"
            required="false"/> 

   <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 A author establishes the relationship of between a parameter to a and feature is established by having a param element as a direct child of a feature element in document order .

Outside

A user agent must ignore any param element outside the context of a feature element (outside the context of a feature element, a param element does not represent anything and a user agent must ignore it. has no function or meaning).

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.

8.13.1 Attributes of the param Element

name

A string, which may be empty, that denotes the name of this parameter . It

When a param element is declared, it is required for authors to use this the name attribute.

value

A string, which may be empty, that denotes the value of this parameter . It

When a param element is used, it is required for authors to use this the value attribute.

8.13.2 Usage example

This example demonstrates a widget that makes use of a fictional geo-location feature where by its accuracy is set to " low " via a param element.

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

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

A user agent must not revert to these values on subsequent initialization of the widget. User agents that support supports the [Widgets-APIs] specification must expose any declared preference to the author at runtime via scripting. scripting in the manner described in the [Widgets-APIs] specification. 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 preference 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.

8.14.1 Attributes of the preference Element

name

A string that denotes the name of this preference . It

When a preference element is used, it is required for authors to use this the name attribute.

value

A string that denotes the value of this preference . The default value that a user agent must use for when the value attribute is missing absent is null . (i.e., the data value null ,and not a string " null ").

It is optional for authors to use this attribute. the value attribute with a preference element.

readonly

A boolean attribute indicating whether this preference can be overwritten at runtime.

The default value that a user agent must use when this the readonly attribute is absent is false , meaning that the value can be overwritten at runtime.

It is optional for authors to use this attribute. the readonly attribute with a preference element.

8.14.2 Usage example

This example shows a widget where two preferences are set. The second preference is set as read only, "read only" via the readonly attribute, which means the values of that preference cannot be changed at runtime.

<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 Indicating Text Directionality with its:span

This feature is at risk .

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 value s, 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.

This example shows ITS being used to correctly set the directionality of text:

<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:span element may be used as a child element of the following elements of the configuration document .In addition, the its:dir attribute may be used in the following elements of the configuration document :

If the its:span element is used, or the its:dir attribute is used, the [ITS] namespace http://www.w3.org/2005/11/its/ ) must be declared in the configuration document .

9 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 content is content an author has explicitly localized :that is, a widget package that contains content localized using folder-based localization or a configuration document that contains content localized via element-based localization .

Unlocalized content is content included in the widget package or in the configuration document that has not been explicitly localized. In the case of widget package, this means content outside the container for localized content .In the case of a configuration document, this means any element without an explicitly declared or inherited xml:lang attribute.

A localized file is any file that has been placed inside a locale folder (i.e., localized content that makes use of element-based localization ). A widget package may contain zero or more localized files. All files and folders, except for the digital signatures and the configuration document ,can be localized via folder-based localization .

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). In addition, authors making used of localization features provided by this specification should translate, localize, or alter localized content for a the given locale, and test their widgets thoroughly.

9.1 Localization Model

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 and element-based localization rely on the user agent to match the language ranges held by the user agent locales to the appropriate locale folders and/or localized XML elements in the widget's configuration document .

9.2 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 reserved folder at the root of the widget package whose folder-name case-sensitively matches 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.

Authoring Guideline: Authors need to avoid region, script or other subtags except where they add useful distinguishing information to a locale folder .In addition, avoid including empty locale folders in a widget package (unless there is a good reason to include them).

An example of a widget that uses folder-based localization:

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
 index.html
 config.xml
  

Authors can further facilitate the localization process by grouping files into folder hierarchies made up of matching subtags, as is shown in the example.

Assuming the widget's locale is "zh-hans-cn":

This works at all sub-levels, so long as the parent subtag matches the child subtags. So, for example, the " cn " region can make use of the localized files in the "zh-hans" folder level, the "zh" folder level, and the unlocalized files at the root of the widget package .The user agent always prioritizes files in sub-folders over files in locale folders closer to the root of the widget package .Conversely, if the widget's locale were " en-us ", references to a.gif, b.gif, c.gif and d.gif would all resolve to the files in the root of the widget package.

Note also that the user agent treats any file or folder outside the container for localized content as unlocalized content .

9.2.1 Conformance Checker Behavior

A CC should inform the author if there are empty locale folders in the widget package .

A CC should inform the author if the folder-name of any folder uses deprecated, grandfathered, or redundant language tags from the IANA Language Subtag Registry .

A CC should inform the author to avoid region or script subtags from the IANA Language Subtag Registry for the names of folders.

9.3 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 [XML] element in the configuration document has been localized .

The following is an example of element based element-based localization:

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

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

   The Ultimate Weather Widget
   </name>
   <name short="Boletim" xml:lang="pt">

   <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 either 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 other words, exclusion of an xml:lang on an element indicates that that element is unlocalized content ,except in the manner described in this section regardless case whereby a parent element uses xml:lang (this maintains consistency with the behavior of whether xml:lang as specified in the element contains an [XML] specification). Explicitly declaring xml:lang attribute. overrides any xml:lang value inherited from a parent element.

For example, if the author uses the xml:lang attribute on the widget element, then all child elements inherit the value xml:lang. This means that the first name element below behaves as xml:lang="en" had been explicitly used. However, in the second name element, the declaration of xml:lang="pt" overrides xml:lang="en" inherited from the widget element.

<widget xmlns="http://www.w3.org/ns/widgets" 
 xml:lang="en">
   <name short="Weather">
    Behaves as if xml:lang="en"
   </name>
   <name xml:lang="pt">
    The declaration of xml:lang="pt" overrides
    xml:lang="en" inherited from the widget element. 
   </name>
</widget>
  

If an element is marked as being localizable via xml:lang with "yes", the specification always indicates if one element is allowed per language or whether elements are grouped by language :

One element is allowed per language :

One element is allowed per language means that only one element of a type is allowed to be used per language (e.g., although many name elements can be present in a configuration document ,only one name element will be selected by the user agent for the English language). During processing ( Step 7 ), the user agent must attempt to only match the first element, in document order ,that matches a language range in the user agent's agent locales and ignore any subsequent repetitions of the element that contain a matching xml:lang value (even if that element's content is different).

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


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

8.16
Indicating
Text
Directionality
with

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

However, if the user agent locales only contained " <its:span> * ", or did not match any of the localized Although it is optional for description elements, then the user agent would match the third description element above.

In the case whereby the author does not use an xml:lang attribute, and no element of a particular type with xml:lang matches the user agent to support locales [ITS] , it is , the user agent recommended must that authors use the <its:span> first element to indicate the directionality of text that unlocalized content when needed. Directionality is indicated by either using , in document order ,that matches the element type being sought.

For example, now assume that the user agent locales only contains the following language range: " dir jp attribute, with " (Japanese). As only one instance of the description element is allowed per language, in the following valid code the user will agent ignore the first two description elements, but would match the third (unlocalized) description element.


its:dir

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

Elements are grouped by language :

Elements are grouped by language means that multiples of an element are allowed per language (e.g., multiple icon elements are allowed per language). During processing ( Step 7 ), the user agent must match all elements with a particular name (e.g., icon ) having an xml:lang attribute value s, that matches the language ranges of the user agent locales , as defined in ITS: well as elements of that particular name that are unlocalized content .

For example, assume that the user agent locales contains the following language ranges: " ltr jp,en " (Japanese and english). As multiple instances of the Left to right text. icon rtl element are allowed per language, in the following code the user agent match all the following icon elements. Note that unlocalized content elements are also matched.


<widget xmlns="http://www.w3.org/ns/widgets"> 
 <icon xml:lang="en" src="icons/a.png"/>
 <icon xml:lang="jp" src="icons/b.png"/>
 <icon src="icons/c.png"/>
 <icon src="icons/d.png"/>

Right
to
left
text.

</widget>

Now assume that the user agent locales contains the following language range: " lro jp " (Japanese). In the following code, the user agent would ignore the first Left-to-right override. icon rlo element, but match the second, third, and fourth Right-to-left override. icon elements.


<widget xmlns="http://www.w3.org/ns/widgets"> 
 <icon xml:lang="en" src="icons/a.png"/>
 <icon xml:lang="jp" src="icons/b.png"/>
 <icon src="icons/c.png"/>
 <icon src="icons/d.png"/>
</widget>

It

9.4 Localization Examples

This section is optional non-normative. for authors

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

9.4.1 Simple Example

This example shows a widget that displays the days of the week based on the language ranges held by the user agent locales .If the user agent is unable to match a language range to use any locale folder ,the widget displays /index.html at the root of the [ITS] attributes. widget package .

For example,

config: /config.xml

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

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

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


file: /locale/es/index.html

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

  

</widget>

9.4.2 Complex Example

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

config: /config.xml

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


file: /locales/en-au/cats.html

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


file: /locales/es/cats.html

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

9.4.3 Fallback Behavior Example

This specification allows authors to place files and folders they don't wish to localize at the root of the widget package. At runtime, if the user agent fails to find a file in a locale folder ,it will always search at the root of the widget package for that missing file. The purpose of this 'fallback' model is to reduce the number of files that need to be created in order to localize a widget package .

The example below demonstrates how a user agent attempts to locate a file that is absent in a localized scenario:

  1. Firstly, the user agent will search for a folder that matches the user agent's locale as closely as possible for the desired file.
  2. If the file is absent, the user agent will search for the absent file in any other sub-folder that is in the language range of the current locale folder.
  3. If the above fails, the user agent will search for the absent file at the root of the widget package.

So, for example, assume the user agent's locale is ' en-gb '. The user agent would fail to locate 'mast.png' so the next place it would look is in the ' en/ ' folder, where it would find the absent ' mast.png ' file.

Now consider the for various Chinese variants: ' zh-hans-cn ', ' zh-hans ', and ' zh ' below. In this case, to find the ' flag.png ' file for Mainland Chinese in simplified script ' zh-hans-cn ', the user agent would first look in ' zh-hans-cn ', followed by ' zh-hans ', then in ' zh ' where the file is located.

To find the ' mast.png ' file, the user agent would look in ' zh-hans-cn ', followed by ' zh-hans ', followed ' zh ', and finally at the root of the widget package where the absent file is actually located.

file: /index.html

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

9 10 Steps for Processing a Widget Package

The steps for processing a widget package involves nine steps that a user agent SHOULD may 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, a user agents agent 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 10.1 Processing Rules

This section defines various processing rules on , which are a set of common algorithms used in the by the steps for processing a widget package rely on. .

10.1.1 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 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 Implementers must follow the [ZIP] specification's instructions on how to extract a file for from the Zip archive.

It is optional for a user agent to extract all the files in

Note: For efficiency, a Zip archive at the same time. The user agent may can extract specific files as they are needed for processing. Note: processing rather than extracting all the files at once. As a security precaution, implementations are discouraged from extracting file entries from un-trusted widgets directly onto the file system. Instead, implementations should consider could use, for example, a virtual file system or mapping to access files inside a widget package .

10.1.2 Rule for dealing Dealing with an invalid 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 .

In the case the UA is a CC, it should must inform the end-user with an appropriate localized error message. The wording of an appropriate localized error message is left to author that the discretion of implementers; however, its presence Zip archive is nonetheless recommended . an invalid Zip archive .

10.1.3 Rule for finding Finding a file within File Within a widget package 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.

Note: This specification does not define how links in documents other than the configuration document are to be dereferenced. For handling links in other documents, such as (X)HTML, CSS, SVG, etc., please refer to the [Widgets-URI] specification.

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

  2. If
  3. Let path-components be the result of splitting path starts with at each occurrence of a U+002F SOLIDUS (e.g., " /style/master.css "), meaning character, removing that U+002F SOLIDUS character in the process.

  4. If the number of items in path path-components is an zip absolute path , then: Remove greater than two, then check if the first U+002F SOLIDUS from second item in path path-components and search at exactly matches the root of string " locales ". If it does:

    1. If the widget package for a file entry whose third item in file name field path-components matches path . If none if found, contains any characters other than a U+002D HYPHEN-MINUS ("-") or characters the range %x61-71 ,then return null and terminate this algorithm. (I.e., The third item in path-component can only contain lower-case ASCII characters or zero or more hyphens).

    2. Otherwise, continue.
  5. 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 . If file is starts with a processable file , then return file and terminate this algorithm. If file U+002F SOLIDUS (e.g., " /style/master.css "), meaning that the path is not a processable file an Zip absolute path , then return an error and terminate this algorithm. remove the first U+002F SOLIDUS from path.

  6. For each lang-range in the user agent's agent 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 let file . be the result of applying the 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 the path points to a file entry that is not a processable file , then return an error and terminate this algorithm.

  7. If every lang-range in the user agent's agent locales have been searched, then search for a file entry whose file name field matches path at from 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.

  8. Otherwise, return null .

10.1.4 Rule for getting Getting a single attribute value 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 space characters (in any order) with a single U+0020 SPACE character.

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

  4. Return result .

10.1.5 Rule for getting Getting a list List of keywords from Keywords From an attribute Attribute

The rule for getting a list of keywords from an attribute is given by the following algorithm. The algorithm takes a string as input, and returns a list 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 space characters (in any order) with a single U+0020 SPACE character.

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

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

  5. Return result.

10.1.6 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 The algorithm always returns a file entry means that the user agent must act as if the said file does not exist within the Zip archive . boolean value.

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

  1. The
  2. If the value of the CRC-32 field (defined in the [ZIP] specification) fails a CRC-32 check. check, return false and terminate this algorithm.

  3. The version needed to extract is greater than 20 (meaning the archive is using a feature unsupported by this specification, such as Zip64). The value of the compression method field is not one of the valid compression methods ( 0 or Zip64), return 8 false ). and terminate this algorithm.

  4. The file name field is an empty string. string, return false and terminate this algorithm.

  5. The file name field contains reserved forbidden characters . , return false and terminate this algorithm.

  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. " . .   "). " . .   "), return false and terminate this algorithm.

  7. The file name field is an invalid Zip relative path . , return false and terminate this algorithm.

  8. return true .
A usable file entry is one that is not an unusable file entry .

10.1.7 Rule for Getting Text Content

The rule for getting text content is given in the following algorithm. The element to be processed must be interpreted as a [DOM3Core] Element .The algorithm always returns a string, which may be empty.

A 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 input be the [DOM3Core] Element to be processed.

  2. This feature is at risk . If the user agents agent 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 attribute of input .

10.1.8 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. The algorithm always returns a string, which may be empty.

  1. Let input be the element Element to be processed.

  2. Let result be the result of applying the Rule rule for Getting Text Content getting text content to input .

  3. In result , excluding any U+0020 SPACE code points, convert any sequence of one or more Unicode white space 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 .

For example, the user agent would ignore the author and blink elements, but their Text nodes would be extracted. The resulting widget name would be " The Awesome Super Dude Widget " and the resulting widget short name would be "D " D A H U T": T ":

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

10.1.9 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. undefined by this specification.

  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 .

10.1.10 Rule for Identifying the Media Type of an Image

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

Note: This rule is only to be applied when explicitly instructed to by the specification (during Step 7 ).

  1. Let file be the file to be processed.
  2. If file has a file-extension , attempt to match the file-extension to one of the strings in the first file extension 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 match one of the byte sequences in the bytes in hexadecimal the magic number column of the following table, then return the media type in the corresponding cell in the second media type column on the same row. Otherwise, return unknown/unknown .
gif gif png ico svg jpg
Media Type Identification Table
file extension Magic Number magic number Media Type media type Comment comment about magic number
.gif 47 49 46 38 37 61 image/gif The string " GIF87a ", a GIF signature.
.gif 47 49 46 38 39 61 image/gif The string " GIF89a ", a GIF signature.
.png 89 50 4E 47 0D 0A 1A 0A image/png The PNG signature.
.ico 00 00 01 00 image/vnd.microsoft.icon A 0 word following by a 1 word, a Windows Icon file format signature.
.svg none, see comment.   image/svg+xml user agents that support SVG should parse files documents cannot be identified using a magic number, as they don't have one; SVG must only matched by the .svgfile extension and processed in accordance to the [SVGTiny] specification.
.jpg FF D8 image/jpeg A JPEG SOI marker followed by the first byte of another marker.

10.1.11 Rule for Identifying the media type Media Type of a file File

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

Note: This rule is only to be applied when explicitly instructed to by the specification (during Step 7 ). There are situations where alternative means are defined by the specification to identify the media type of a file (e.g., by the presence of the content element's type attribute or deriving the media type of a default start file from the default start files 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 file extensions 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.

html, htm js xml txt wav, wave
file identification table File Identification Table
File Extensions file extensions media type
.html text/html
.htm css text/html
.css text/css
.js application/javascript
.xml application/xml
.txt text/plain
.wav audio/x-wav
.xhtml xhtml, xht application/xhtml+xml
.xht application/xhtml+xml

10.1.12 Rule for Determining if a Potential Zip Archive is a Zip Archive

The rule for determining if a potential Zip archive is a Zip archive is given by the following algorithm.

  1. Let potential archive be the acquired resource.
  2. Check if the first four bytes of potential archive match the magic numbers for a Zip archive ( 50 4B 03 04 ). See also the informative note below.
  3. If the first four bytes do not match the magic numbers for a Zip archive ,then return an error.
  4. Otherwise, return true .

Note: A user agent can inspect the potential archive once it has acquired the first four bytes of the potential Zip archive or can wait until all the data of the potential Zip archive has been completely acquired.

Step 1 - Acquire a Potential Zip Archive

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

10.1.13 Acquisition of potential Zip archive labeled with a media type

When attempting to acquire a potential Zip archive over some protocol that labels resources with a media type , a user agent must only attempt to process resources labeled with the valid widget media type ( application/widget ) ), regardless of whether the resource contains a file extension or not. not, by applying the rule for determining if a potential Zip archive is a Zip archive . Unless the user agent supports legacy or proprietary media types, types , all other media types are in error and the user agent must treat the potential Zip archive as an invalid Zip archive .

If the result of the user agent applying the rule for determining if a potential Zip archive is a Zip archive is true ,meaning that the potential Zip archive is a Zip archive ,then the user agent must proceed to Step 2 .Otherwise, if an error is returned, the user agent must treat the potential Zip archive as an invalid Zip archive .

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

If the protocol used for acquisition of a potential Zip archive does not provide, or otherwise include, a media type , then a user agent may treat the acquired potential Zip archive as if it has been acquired from a protocol that does not label resources with a media type . (see sub-section below).

In this example, the media type of the Content-Type is not one supported by the user agent, so the user agent would treat the potential zip Zip archive as an invalid Zip archive :

Request
GET /foo.wgt HTTP/1.1
Host: www.example.com
Accept: application/widget
Response
HTTP/1.1 200 OK
Date: Tue, 04 Sep 2007 00:00:38 GMT
Last-Modified: Mon, 03 Sep 2007 06:47:19 GMT
Content-Length: 1337
Content-Type: application/x-gadget

10.1.14 Acquisition of potential Zip archive not labeled with a media type

A

When acquiring a potential Zip archive that has not been labeled with a media type (e.g., from a file system), a user agent must attempt to process a the resource regardless of the file extension (including situations when the file extension is absent) by applying the rule for determining if a potential Zip archive is a Zip archive . Rule for Determining if a potential Zip archive is a Zip archive It is optional for a user agent to acquire all the bytes of a potential zip archive before applying the rule for determining if a potential Zip archive is a Zip archive . A user agent may apply If the rule for determining if a potential Zip archive is a Zip archive once it has acquired the first four bytes of the potential zip archive . The rule for determining if a potential Zip archive is a Zip archive are as follows: If the first four bytes of the potential Zip archive do not match the magic numbers for a Zip archive ( return 50 4B 03 04 ) then a user agent must treat the resource as an invalid Zip archive true ,proceed to Step 2 . Otherwise, if an error was returned, the user agent must treat the potential Zip archive as a an invalid Zip archive and proceed to Step 2 .

Step 2 - Verify the Zip archive Archive

Verify zip archive

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

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

If any of the following conditions are met, then a user agent must treat the Zip archive as an invalid Zip archive :

  1. The Zip archive is split into multiple files or spans multiple volumes , as defined in the [ZIP] specification.

  2. The Zip archive is encrypted (which is denoted by bit 0 of the general purpose field being set and by the presence of archive decryption header and an archive extra data record , all three of which are defined in the [ZIP] specification).

  3. The Zip archive contains zero file entries . (i.e., the archive is empty).

  4. The Zip archive contains only folders .

It is optional , but nevertheless

10.1.15 Conformance Checker Behavior

A CC recommended , that a user agent must verify each file entry by using applying the rule for verifying a file entry before proceeding to step 3 . If the result of applying the rule for verifying a file entry is false ,a CC must inform the author.

Step 3 - Set the Configuration Defaults

User agents

In this Step, a user agent must assume set the following variables and default values as defined in the table of configuration defaults at this point of processing. below.

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

Table of Configuration Defaults
Variable Type Default Value Overridden by Description
author email String null Step 7 The email value of the author who created the widget, corresponding to the author element's email attribute. attribute (if any).
author href URI IRI null Step 7 The URI associated with the author who created the widget, corresponding to value of the author element's href attribute. attribute (if any).
author name String null Step 7 The name of the author who created the widget, corresponding to the text content of the author element. element (if any).
feature list List null Step 7 A list of features that correspond to features that were requested, requested via feature elements, by the author and are supported by the user agent. elements (if any). Each item in the list corresponds to a feature element's name attribute, whether it is required, and any associated parameters . (if any).
icons List of file entries null Step 7 , Step 9 The icons of the widget as they correspond to the default icons and to the occurrence of custom icons that are supported by the widget package . (if any).
start file encoding String UTF-8 Step 7 The character encoding of the custom start file , corresponding to either the content element's charset encoding attribute (if any). any), or the default encoding .
start file content-type String text/html Step 7 The media type of the start file, file , corresponding to the content element's type attribute or to a media type derived from the default start file files table .
main widget config doc File entry null Step 6 The file entry that is the configuration document for the widget package located at the root of the widget package. .
localized config doc widget description File entry String null Step 6 7 The file entry text content of the description that is element in the configuration document for the widget package .
widget description height String positive number null Step 7 The description given to the widget by the author, corresponding to the text content value of the description widget element element's height attribute in the configuration document . (if any).
widget height id unsigned short String null Step 7 The widget's visual height, corresponding to value of the widget element's height id attribute in the configuration document . (if any).
widget id license String null Step 7 The identifier, corresponding text content of the license element in the configuration document (if any).
widget license file File null Step 7 A file derived if the value of the license element's href is a Zip relative path to a file within the widget package .
widget license href IRI null Step 7 The value of the license element's id href attribute in the configuration document . (if any).
widget license name Object String null Step 7 The software license assigned to the widget by the author, corresponding to the text content of the license name element in the configuration document . (if any).
widget name preferences String List null Step 7 The widget's name, preferences , corresponding to the name preference element elements in the configuration document . (if any). 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 reset the value of the widget preferences variable on subsequent initialization of the widget.
widget short name String null Step 7 The widget's alternative short name, corresponding to value of the name element's short attribute in the configuration document . (if any).
Variable Type Default Value Overridden by Description
widget version String null Step 7 The widget's version, corresponding to value of the widget element's version attribute in the configuration document . (if any).
widget width unsigned short positive number null Step 7 The widget's visual width, corresponding to value of the widget element's width attribute in the configuration document . (if any).
widget window modes List of strings floating Step 7 The window mode that corresponds to value of the content widget element's viewmodes attribute in the configuration document . (if any).
widget start file File entry null Step 7 , Step 8 The start file for the widget package , corresponding to either one of the default start files table or the file identified by the content element's src attribute.
user agent's agent locales

List of strings

null Step 5 The user agent's locales is a A list of language tags that represent the end-user's preferred language and regional settings derived from the operating system or user agent. .
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

This step only applied applies to a user agents agent that support supports the [Widgets-DigSig] specification. If the user agent does not support [Widgets-DigSig] , go to Step 5 .

The algorithm to locate digital signatures is defined in the [Widgets-DigSig] specification, under the section named Locating and Processing Digital Signatures for the Widget. .

Step 5 - Derive the User Agent's Locale

The end-user's language ranges represents the end-user's preferred languages and regional settings, which are derived from the operating system or directly from the user agent. As there are numerous ways a user agent can derive the end-user's preferred languages and regional settings, the means by which those values are derived are beyond the scope of this specification and left up to the implementation.

For example, the end-user may have specified her preferred languages and regional settings at install time by selecting a preferred language, or languages from a list, or a list of preferred languages and regional settings could have been dynamically derived from the end-user's geographical location, etc.

The algorithm to derive the user agent locales is as follows:

  1. Let unprocessed locales lists list be a comma-separated list that represents contains the end-user's language ranges . Each item in the unprocessed locales must be a string shorter than eight characters, in lowercase form, that conforms to the production of a Language-Tag , as defined in the [BCP47] specification. A string that conforms to the production of a Language-Tag is referred to as a language range [BCP47] (e.g. ' en-au ', which is the range of English as spoken in Australia, and ' fr-ca ', which is the range of French as spoken in Canada, etc.). A language range is composed of one or more subtags that are delimited by a U+002D HYPHEN-MINUS (" (" - "). ").

    The unprocessed locales lists must contain one or more language ranges . If for some reason the user agent is unable to derive the end-user's language ranges , the unprocessed locales lists must contain a single U+002A ASTERISK ( * ) character.

    The first item of the unprocessed locales must represent the user's most preferred language range (i.e., the language/region combination the user agent assumes the end-user most wants to see content in), followed by the next most preferred language range, and so forth.

    For example, in an unprocessed locales lists list that contains ' en-us,en,fr,es ', English as spoken in the United States is preferred over English, and English is preferred over French, and French is preferred over Spanish, and Spanish is preferred over unlocalized content .

  2. For each range in the unprocessed unprocessed locales lists list :

    1. If this range begins with the subtag ' * ' (e.g. " *-US *-us " or just " * "), or is longer than eight characters, or contains any space characters , skip all the steps in this algorithm below, and move onto the next range .

    2. If this range contains any subtag ' * ', remove the ' * ' and its preceding hyphen ( U+002F ) (e.g., ' en-*-us ' becomes ' en-us ').

    3. While range contains subtags :

      1. Add the value of the range to the user agent's agent locales .

      2. Remove the right most subtag from range (e.g., " zh-hans-cn " becomes " zh-hans ") and append the resulting value to user agent's agent locales . Continue removing the right most subtag and adding the result to user agent's agent locales until there are no subtags left in range .

        For example, if the range was "zh-hans-cn", then the user agent locales become " zh-hans-cn,zh-hans,zh ".

      3. Move onto the next range and go to step 1 in this algorithm.

    4. If the user agent's locales contains duplicate language ranges ; for each duplicated range, remove all duplicate ranges except
    5. Append the right most one. So, for example, value " fr,en-us,en,en-au,en,fr,en * " would become " fr,en-us,en,en-au ". Append the value "*" to the end of user agent's agent locales .

For example, an unprocessed locales lists list that contains " en-us,en-au,en,fr-ca,zh-hans-cn ", would decompose to " en-us,en,en-au,en,fr-ca,fr,zh-hans-cn,zh-hans,zh ", and after step 4 is applied the would result in a user agent's agent locales would contain the following items: that contains " en-us,en,en-au,fr-ca,fr,zh-hans-cn,zh-hans,zh en-us,en,en-au,en,en,fr-ca,fr,zh-hans-cn,zh-hans,zh,* ".

For example, an unprocessed locales lists list that contains " en-us,en,fr-ca,en,en-ca " would decompose to " en-us,en,en,fr-ca,fr,en,en-ca,en " "would result in step 3, and after step 4 is applied the a user agent's agent locales would contain the following items: that contains " "en-us,en,fr-ca,fr,en-ca" . en-us,en,en,fr-ca,fr,en,en-ca,en,* ".

Step 6 - Locate the Configuration Document

This step involves searching within the Zip archive for a configuration document .

The algorithm to locate the configuration document is as follows:

  1. Search at the root of the widget package for a file entry whose file name field case-sensitively matches the valid configuration document file name ( config.xml ).
  2. If a match is made, set let widget config doc to be the result of applying rule for extracting file data from a file entry to the matching file entry . If no match is made (meaning that widget config doc is null ), then a user agent must treat the Zip archive as an invalid Zip archive .

Step 7 - Process the Configuration Document

The purpose of processing the configuration document is to override the table of configuration defaults , which are used during instantiation initialization and at runtime, and to select the appropriate localized content (if any) that must eventually to be presented to the end-user. 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] ), conjunction to match elements in the algorithm for processing a 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 given below, this section firstly defines some terminology used by the user agent depends on whether one element is allowed per language or whether processing algorithm and describes how localized 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). processed.

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, 10.1.16 Terminology Used 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 . Processing Algorithm

The term in error is used in this Step to mean that an element element, or attribute attribute, or file in a configuration document is not conforming non-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 used; but will generally require the user agent to ignore any element, attribute, or file that is in error. To ignore an object (e.g., a file or a DOM node). This means that the a user agent must act as if that object is not present. An element the element, attribute, or an attribute is correct if it file that is not in error . is not present.

To associate means that two or more bits pieces 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 lookup refers algorithm is defined in section 3.4 of [RFC4647] (part of [BCP47] ). It is used in this Step to any Text node, including CDATASection nodes (any Node with node type TEXT_NODE to match localized content in the configuration document to the language ranges held by the user agent locales (if any).

10.1.17 Conformance Checker Behavior

A CC should process a configuration document using the algorithm to process a configuration document .However, where an element or CDATA_SECTION_NODE ) as defined attribute is in error, or invalid, the [DOM3Core] conformance checker must inform specification. the author.

A CC may validate a configuration document against the Relax NG for the configuration document .

10.1.18 Processing Algorithm

The algorithm to process a configuration document is as follows:

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

    1. 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 IRI , then let widget id be the value of the id .

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

    3. If the height attribute is used, then let normalized height be the result of apply applying 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 attribute is in error and the user agent must ignore it.

    4. If the width attribute is used, then let normalized width be the result of apply applying 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 attribute is in error and the user agent must ignore it.

    5. 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 and any items that are not one of the valid view modes , or and any duplicated items. Let widget window modes be the value of viewmodes list .

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

    7. 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 agent 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 agent 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 potential license href be the result of applying the rule for getting a single attribute value to the href attribute.

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

    If potential license href is a valid uri IRI , then associate license href with widget license href be the value of potential license href . 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 Stop processing this element and proceed to the next element in the elements list . Otherwise, associate let widget license file with be the value of widget license file .

    An icon element:

    If the src attribute of this icon element is missing, absent, 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. attribute of this icon element. 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 be 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 IRI , 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 preference be an empty object.

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

    3. If the preference-name 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 . Otherwise, associate name with preference .

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

    5. Add the preference-name and the associated
    6. If a readonly attribute is used, let preference-value readonly to be the list result of preferences . An access element: A user agent that does not support applying the [Widgets-Access] specification must ignore rule for getting a single attribute value this element. Stop processing this element and proceed to the next readonly attribute. If element readonly in is not a valid boolean value ,let the value of elements list . Otherwise, if the user agent supports the [Widgets-Access] , refer to readonly be the [Widgets-Access] specification for how to process this element. An value ' update false element: A user agent that does not support the [Widgets-Updates] specification must ignore '. Associate this attribute. Stop processing this element and proceed to the next element readonly in with the elements list preference .

      Otherwise, if
    7. Add the user agent supports preference and the [Widgets-Updates] , refer to associated name ,value and readonly variables the [Widgets-Updates] list of widget preferences 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 of the content element is missing, absent, 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 of the content element 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 encoding attribute is used, then let content-charset content-encoding be the result of applying the rule for getting a single attribute value to the value of the charset encoding attribute. If content-charset content-encoding is supported by the user agent, then let the start file encoding be the value of the charset encoding attribute. If content-charset content-encoding is unsupported by the user agent, then a user agent should use the default encoding ( UTF-8 ).

    A feature element:

    If a required attribute of this feature element 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 a required attribute is used, let feature-name 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 URI boolean value , then let the user agent must ignore this element, its attributes, value of required-feature be the value ' true '.

    3. If feature-name is not a valid IRI , and its children. Stop processing required-feature is true ,then treat this element and proceed to the next widget as an invalid Zip archive .

    4. If element feature-name in is not supported by the user agent, and elements list . required-feature is true ,then treat this widget as an invalid Zip archive .

    5. If feature-name is not supported by the user agent, and required-feature is false , 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 .

    6. 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 '.
    7. Associate the value of required-feature with feature-name .

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

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

    A The user agent must ignore any Comment node, or a ProcessingInstruction node, or a Text node that only contains Unicode white space characters , or a CDATASection node that only contains Unicode white space characters , or a param element, or anything else: This element that is in error and the user agent must ignore not a direct child of a feature it. element.
  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 in the configuration document (i.e., if widget start file of the table of configuration defaults 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 8 and go to Step 9 .

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 (from top to bottom). File names in the default start files table must be treated by the user agent case-sensitively.

  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, in error , ignore this file name and move onto the next file name in the default start files table. 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 media type column of the default start files table. 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 table of configuration defaults :
  3. Move onto the next file name in the default icons table. 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.

For example:

<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 Relax NG for the configuration document ,which is a [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 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 }?,

  attribute encoding { 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 Geoffrey " 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, Hari Kumar G, Ian Hickson, Jay Sweeney, Jere Kapyaho, Käpyaho, Jim Ley, Jon Ferraiolo, Jose Manuel Cantera Fonseca, Josh Soref, Jouni Hakala, Joey Bacalhau, Kevin Lawver, Kai Hendry, Krzysztof Maczyński, Lachlan Hunt, Marc Silbey, Marcin Hanclik, Mark Baker, Mikko Pohja, Mohamed Zergaoui, Olli Immonen, Philipp Heltewig, Philip Taylor, Scott Wilson, Stephen Paul Weber, Tex Texin,Thomas Landspurg, Yang Wong, Zachary Fitz-Walter.

Change log

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 Reso Resource Identifier (URI): Generic Syntax .RFC3986, 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,