Widgets 1.0: Packaging and Configuration

Abstract

This specification standardizes a packaging format for software known as 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 is the 29 October 23 July 2009 Last Call Working Draft version Candidate Recommendation of the "Widgets Widgets 1.0: Packaging and Configuration" Configuration specification. This version addresses issues reported by implementers and interested parties during the first W3C publishes a Candidate Recommendation (CR) phase (see to indicate that the list of changes ). The purpose of this Last Call document is believed to give interested parties an opportunity be stable and to review encourage implementation by the changes that were made during CR. developer community. The working group Web Applications (WebApps) Working Group expects to republish request that the Director advance this document as to Proposed Recommendation once the Working Group has developed a Candidate Recommendation. comprehensive Widgets 1.0: Packaging and Configuration test suite ,and demonstrated at least two interoperable implementations (interoperable meaning at least two implementations that pass each test in the test suite ). The Last Call review period ends on 19 WebApps Working Group expects to show these implementations by October 2009. The Working Group does not plan to request to advance to Proposed Recommendation prior to 01 November 2009.

Feedback based on any aspect of this specification is welcome and encouraged. However, there are certain features in the specification that the Working Group 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 Proposed Recommendation will depend on the feedback received from implementers, other working groups, and the public.

This document is produced by the Web Applications WG , part of the Rich Web 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 . The public is encouraged to send comments to the Web Apps Working Group's public mailing list public-Webapps@w3.org ( archive ). See W3C mailing list and archive usage guidelines . A detailed list of changes from the previous version is also available from the W3C's CVS server.

Table of Contents

• 1 Introduction
  • 1.1 Design Goals and Requirements
  • 1.2 How This Document is Organized
  • 1.3 Typographic Conventions
  • 1.4 The Widget Family of Specifications
• 2 Conformance
• 3 Definitions 3.1 Character Definitions
• 4 User Agents
  • 4.1 Optional Aspects of the Zip Specification Dependencies on Other Specifications and File Formats
  • 4.2 Internationalization Tag Set Support
• 5 Conformance Checker
• 6 Zip Archive
  • 6.1 Invalid Zip archive
  • 5.1 6.2 Compression Methods
  • 5.2 6.3 Version of Zip Needed to Extract a File Entry
  • 5.3 6.4 Zip Relative Paths
  • 5.4 Interoperability Considerations 5.4.1 Paths Lengths 5.4.2 Character sets
  • 5.4.3 6.5 Characters Forbidden in File Names
• 6 7 Widget Packages
  • 6.1 Invalid Widget Package
  • 6.2 7.1 Files and Folders Content Types
  • 6.3 7.2 Reserved File and Folder Names
  • 6.4 7.3 Digital Signatures
  • 6.5 Start Files 6.5.1 Custom Start File 6.5.2 7.4 Default Start Files
  • 6.6 Icons 6.6.1 Custom Icons 6.6.2 7.5 Default Icons
  • 6.7 7.6 Media Type
  • 6.8 7.7 File Extension
• 7 8 Configuration Document
  • 7.1 Example Configuration Document
  • 7.2 8.1 Namespace
  • 7.3 8.2 Proprietary Extensions
  • 7.4 8.3 Attribute Types
  • 7.5 8.4 Other Attributes
  • 7.6 8.5 The widget Element 7.6.1 Attributes of the widget Element 7.6.2 Usage example
  • 7.7 8.6 The name Element 7.7.1 Attributes of the name Element 7.7.2 Usage Example
  • 7.8 8.7 The description Element 7.8.1 Attributes of the description Element 7.8.2 Usage Example
  • 7.9 8.8 The author Element 7.9.1 Attributes of the author Element 7.9.2 Usage Example
  • 7.10 8.9 The license Element 7.10.1 Attributes of the license Element
  • 7.10.2 Usage Example
  • 7.11 8.10 The icon Element 7.11.1 Attributes of the icon Element
  • 7.11.2 Usage Example
  • 7.12 8.11 The content Element 7.12.1 Attributes of the content Element 7.12.2 Usage Example
  • 7.13 8.12 The feature Element 7.13.1 Attributes of the feature Element
  • 7.13.2 Usage example
  • 7.14 8.13 The param Element 7.14.1 Attributes of the param Element
  • 7.14.2 Usage example
  • 7.15 8.14 The preference Element 7.15.1 Attributes of the preference Element 7.15.2 Usage example
  • 7.16 8.15 Indicating Text Directionality with its:span
• 8 9 Internationalization and localization
  • 8.1 9.1 Localization Model
  • 8.2 9.2 Folder-based localization
  • 8.3 9.3 Element-Based Localization
  • 8.4 9.4 Localization Examples 8.4.1 Simple Example 8.4.2 Complex Example
  • 8.4.3 Fallback Behavior Example
• 9 10 Steps for Processing a Widget Package
  • 9.1 10.1 Processing Rules 9.1.1 Rule for verifying a zip archive
  • 9.1.2 Rule for extracting file data from a file entry 9.1.3 Rule for Finding a File Within a Widget Package 9.1.4 Rule for Getting a Single Attribute Value 9.1.5 Rule for Getting a List of Keywords From an Attribute 9.1.6 Rule for Verifying a File Entry 9.1.7 Rule for Getting Text Content 9.1.8 Rule for Getting Text Content with Normalized White Space 9.1.9 Rule for Parsing a Non-negative Integer 9.1.10 Rule for Identifying the Media Type of a File 9.1.11 Rule for Determining if a Potential Zip Archive is a Zip Archive
  • Step 1 - Acquire a Potential Zip Archive 9.1.12 Acquisition of a potential Zip archive labeled with a media type 9.1.13 Acquisition of Potential Zip Archive not Labeled with a Media Type
  • Step 2 - Verify the Zip Archive
  • Step 3 - Set the Configuration Defaults
  • Step 4 - Locate and Process the Digital Signature
  • Step 5 - Derive the User Agent's Locale
  • Step 6 - Locate the Configuration Document
  • Step 7 - Process the Configuration Document 9.1.14 Terminology Used in Processing Algorithm 9.1.15 Algorithm to Process a Configuration Document
  • Step 8 - Locate the Start File
  • Step 9 - Process Locate the Default Icons
• Appendix
  • Media Type Registration for application/widget
  • Linking To a Widget Package From a HTML Document
  • RelaxNG Schema for the Configuration Document
• List of Changes Since Last Publication Acknowledgements
• Acknowledgements Change log
• Normative References
• Informative References

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" "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 documented addressed in the Widgets 1.0 Requirements [Widgets-Reqs] document.

This document addresses the 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 [Widgets-Relax NG Schema] RelaxNG Schema for the configuration document. document .
14. Widget Metadata : see configuration document (particularly the elements).
15. Authorship Metadata: see the author element.
16. Copyright Notice and License Metadata : see the license element.
17. Visual Rendering Dimensions : see the widget element.
18. Declarative Bootstrap see the content element.
19. Automated Bootstrap see the default start file .
20. Iconic Representations : see the icon element, default icons table and custom icons table .
21. Configuration Parameters : the param element (used in conjunction with the feature element).
22. Author-defined Start-up Values (Preferences) : see the preference element.
23. Feature Access Declarations : see the feature element.
24. Configuration Document Independence : see configuration document .
25. Preferred Display Mode : see the viewmodes attribute of the widget element.

1.2 How This Document is Organized

This section is non-normative.

This 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 , 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. Some text in this specification is non-normative. Non-normative text includes: sections marked with the text This section is non-normative , authoring guidelines, examples, and notes. Everything else in this specification is normative.

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

Words that denote a conformance clause or testable assertion use keywords from [RFC2119] : must , must not , required ,should , should not ,recommended , may and optional . The keywords must , must not , should , recommended , may and optional in this specification are to be interpreted as described in [RFC2119] .

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 issues these will disappear from the specification. spec. Issues are non-normative.

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

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

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:

• The list Widgets 1.0: APIs and Events specification defines API s to store preferences and capture events (see [Widgets-APIs] ).

• The Widgets 1.0: Digital Signature specification defines a means for widgets to be digitally signed using a custom profile of specifications the XML-Signature Syntax and Processing Specification (see [Widgets-DigSig] ).

• The Widgets: 1.0: Updates specification defines a version control model that make up allows widgets to be kept up-to-date over [HTTP] (see [Widgets-Updates] ).

• The Widgets 1.0: Access Requests specification defines a means to request access to URI-identifiable resources (e.g. resources on the Web) (see [Widgets-Access] ).

• The Widgets 1.0 Family 1.0: URI Scheme specification which defines a URI scheme for use inside widgets or other such applications of Specifications can be found web technology that do not run on the Working Group's wiki. Web (see [Widgets-URI] ).

• The Widgets 1.0: Media Query Extensions ,which defines extensions to CSS Media Queries, and a DOM interface for querying the media features of a widget (see [Widgets-Views] ).

2 Conformance

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

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

• sections marked with the text This section is non-normative ,
• authoring guidelines,
• examples,
• and notes.

Everything else in this specification is normative.

Please see the typographical conventions to see how authoring guidelines, examples, and notes of product 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: a

1. A user agent . Note: Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the [P&C-Test-Suite]
2. A widget package . Note, however, that passing all the tests in the test suite does not imply complete conformance to this specification; It only implies that the implementation conforms to aspects tested by the test suite (the test suite does not provide tests for any optional
3. A configuration document .
4. A conformance clauses). checker .

A user agent may support other legacy/proprietary widgets.

3 Definitions

The following terms definitions are used throughout this specification so they are gathered here for the readers convenience. The following list of terms is not exhaustive; specification. Please note that other terms are defined given throughout this specification. Arbitrary means that a character, or text string, or file-name , or folder-name is not reserved for the purpose of this specification. 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 . package.

Initialization A media type means a user agent procedurally stepping through is defined in the steps for processing a widget package . [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 agent to validate language tags against the IANA Language Subtag Registry .

A media type widget is defined in by the [MIME] [Widgets-Landscape] specification. as an end-user's conceptualization of an interactive single purpose application for displaying and/or updating local data or data on the Web, packaged in a way to allow a single download and installation on a user's machine, mobile phone, or Internet-enabled device .Because widgets are packaged, they can be shared by users without relying on [HTTP] (i.e., users can share widgets over non-HTTP distribution channels, such as Bluetooth or a USB thumb drive).

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

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

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

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 .

A widget Initialization is defined by means a run through the [Widgets-Landscape] as an end-user's conceptualization of an interactive single purpose application steps for displaying and/or updating local data or data on the Web, packaged in a way to allow processing a single download and widget package after installation on of a user's machine, mobile phone, or Internet-enabled device . Because widgets are packaged, they can be shared by users without relying on [HTTP] . widget.

3.1 3.0.1 Character Definitions This section groups common sets of [Unicode] code points into definitions for the purpose processing in this specification.

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

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

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

• U+0009-U+000D
• U+0020 SPACE
• U+0085 NEL (control character next line)
• U+00A0 NBSP (NO-BREAK SPACE)
• U+1680 OGHAM SPACE MARK
• U+180E MONGOLIAN VOWEL SEPARATOR
• U+2000-U+200A (different sorts of spaces)
• U+2028 LS (LINE SEPARATOR)
• U+2029 PS (PARAGRAPH SEPARATOR)
• U+202F NNBSP (NARROW NO-BREAK SPACE)
• U+205F MMSP (MEDIUM MATHEMATICAL SPACE)
• U+3000 IDEOGRAPHIC SPACE

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

• U+0000 NUL-U+001F INFORMATION SEPARATOR 1,
• U+007F DELETE.

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

• The control characters ,
• 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.

4 User Agents

A user agent is an implementation of this specification that also supports [XML] , [XMLNS] , [UTF-8] , [DOM3CORE] , [SNIFF] , and [ZIP] (see optional aspects of the Zip specification ). In addition to widget packages , a user agent may support other legacy and proprietary application packaging formats. It is optional for a user agent to support the optional aspects of the Zip specification . 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 . Specifications. The user agent described is this specification is only concerned with how to processes Zip archives and configuration documents .

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

4.1 Note: Optional Aspects Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the Zip Specification [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.

4.1 Dependencies on Other Specifications and File Formats

The optional aspects of A user agent must support the following specifications:

• [XML].
• [XMLNS] .
• [DOM3CORE] .
• [UTF-8] .

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 specification Support are as follows. These

A user agent must support the [ZIP] specification. However, it is optional for user agent to support the following aspects represent general features defined in of the [ZIP] specification that this specification does not make use of: specification:

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

4.2 Internationalization Tag Set Support

This feature is at risk .

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

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

5 Conformance Checker

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

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

6 Zip Archive

5.1 6.1 Invalid Zip archive

6.2 Compression Methods

6.3 Version of Zip Needed to Extract a File Entry

6.4 Zip Relative Paths

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 "/" 
       = low-alpha  / DIGIT
      = %x61-71

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 

6.5 Characters Forbidden in File Names

6 7 Widget Packages

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

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

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

6.2 7.1 Files and Folders 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 user agent retrieves them from within a 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.

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

A processable file is must be a file that:

• Exists within the mentioned widget package . ,
• When when the rule for verifying Verifying a file entry File Entry is applied to the file, it returns true .
• Is is of a media type supported by the user agent, determined applying either the rule for identifying the media type of an image or the rule for identifying the media type of a file . Which rule needs to be applied is given when the file in question. term is used.

6.3 7.2 Reserved File and Folder Names

The reserved file names table , below, contains a list of file names that are reserved for some purpose by this specification. The first column of the reserved file names table 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 .

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

The reserved folder names table ,below, contains a list of file names that are reserved for some purpose by this specification. The first column of the reserved file names 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 .

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 an access control policy. The definition of such a policy mechanism is beyond the scope this specification, but may be defined to allow access to all or parts of the signature documents, or deny any such access.

An exception is if a user agent that implements this specification also implements the optional [Widgets-DigSig] specification, in which case the user agent must make signature documents available only to the implementation of the [Widgets-DigSig] 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

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

6.5.1 7.4.1 Custom Start File

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

6.5.2 7.4.2 Default Start Files

A default start file is a reserved start file at the root of the widget package or at the root of a locale folder whose file name case-sensitively and exactly matches a file name given in the file name column of the default start files table , and whose media type matches the media type given in the media type column of the table.

It is optional for a user agent If no custom start file to support has been declared, a default start file must appear at either the media types root of the widget package listed in or at the default start files table root of a locale folder .

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

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

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

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

6.6 7.4.3 Conformance Checker Behavior

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

1. Checking within the configuration document for a 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 ,then the CC must inform the author.

7.5 Icons

An icon is a an optional file that is used to represent the widget in various application contexts (e.g. the icon that the user actives to instantiate a widget, or an icon in a dock or task bar or some other visual context).

The icon is intended to help users of visual browsers to recognize the widget at a glance. There are two kinds of icons defined by this specification, custom icons and default icons .

6.6.1 7.5.1 Custom Icons

A custom icon is an icon explicitly declared by an author via an icon element in a of the configuration document .

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

6.6.2 7.5.2 Default Icons

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

A default icon must be located either at the root of the widget package or at the root of a locale folder , whose file name case-sensitively and exactly matches .

A user agent must derive the media type of a file name given in default icon from the file name 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).

It is Implementations that support the use of [SVG] as an icon format optional 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 support the media types listed in [SVGTiny] profile, and to specific feature strings:

[SVG]

http://www.w3.org/TR/SVG11/feature#SVG-static

[SVGTiny12]

http://www.w3.org/Graphics/SVG/feature/1.2/#SVG-animated

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

Conformance Checker Behavior

If no default icon has been included, and the CC determines that no custom icons table have been declared in the configuration document ,a CC SHOULD inform the author that it is 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 the author other formats might not be supported by all user agents.

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

6.7 7.6 Media Type

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

7.7.1 Conformance Checker Behavior

For when a widget file extension package is required for widget packages on systems where it not served over HTTP, a CC must inform the author if the file-extension is customary for file names to include not a file widget extension that symbolizes (or is associated with) or if the widget lacks a media type . file-extension .

7 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 has must have exactly one configuration document 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 .

It is A user agent optional must for authors to use the attributes of elements. treat a valid configuration document file name case-sensitively.

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

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

Authoring Guidelines: 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. To ensure interoperability, encode the configuration document as [UTF-8] .

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

<?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   = "widget">
 
  <name short="Example 2.0">

  <name short="Example 2.0">

    The example Widget!
  </name>
  <feature name="http://example.com/camera">
    <param name="autofocus" value="true"/>

  <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>
  <icon src="icons/example.png"/>
  <icon src="icons/boo.png"/>

  <author href  = "http://foo-bar.example.org/"
          email = "foo-bar@example.org">Foo Bar Corp</author>  

  <content src="myWidget.html"/>

  <icon src="icons/example.png"/>
  <icon src="icons/boo.png"/>  
  <content src="myWidget.html"/> 

  <license>
Example license (based on MIT License)
Copyright (c) 2008 The Foo Bar Corp.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

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>

  </license> 

</widget>

Note: Implementers are encouraged to expose relevant information provided by the configuration document to the user. Having "visual metadata" "visual metadata" encourages authors to make full use of the configuration document format. See Step 7 6 for instructions on how to process a configuration document.

Authoring Guidelines: The only mandatory element in a 8.0.1 Conformance Checker Behavior

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

A CC must inform the author the file-name element. All other elements and their respective attributes are optional. The following example shows of the smallest possible configuration document that a user agent will be able to process. <widget xmlns="http://www.w3.org/ns/widgets" /> does not case-sensitively match the string " config.xml " (that is, by checking for the configuration document's file-name in other case forms.).

7.2 8.1 Namespace

7.3 8.1.1 Proprietary Extensions Conformance Checker Behavior

This section A CC must inform the author if the configuration document is non-normative . lacking the widget namespace .

8.2 Proprietary Extensions

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

<widget xmlns="http://www.w3.org/ns/widgets"
   >
       <icon src="idle.png"  ex:role="inactive"/>
       />
       
       <content src="widget.html"/>
</widget>

<widget xmlns="http://www.w3.org/ns/widgets"
   xmlns:ex="http://example.org/">
       <icon src="idle.png"  ex:role="inactive"/>

       <icon src="big.png" ex:role="big"/>
       <ex:datasource>{a:"b",c:"d"}</ex:datasource>
       <content src="widget.html"/>
</widget>

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

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.

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 keyword string that case-sensitively matches true or false . Unless specified otherwise, the default behavior, which is used when the attribute is omitted or has a value other than the two allowed values, is false . The way a user agent interprets a boolean attribute is defined as part of an attribute's definition (see, for example, the feature element's required attribute).

A user agent must retrieve the value of a boolean attribute 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).

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

User agents must only perform literal comparisons on keyword attributes ,and must not use 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, the rule for how to retrieve the value is given when this attribute type is used in the specification.

Keyword list attribute

An attribute defined as taking one or more keywords as a value, which are separated by space characters .

A user agent must retrieve the value of a keyword list attribute using the rule for getting a list of keywords from an attribute .

Media type attribute

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

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

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

The type , subtype , and parameter tokens are defined in the [MIME] specification. A user agent must retrieve the value of this kind of attribute using the rule for getting a single attribute value .

Numeric attribute

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

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

Path attribute

An attribute defined as containing a valid path. A valid path is one that matches the production of a Zip-rel-path or a Zip-abs-path . Authoring Guidelines: A valid path is not a URI: a valid path represent a hierarchical path to a file inside a Zip archive , which must exactly matches match the value of a file name field of a local file header of a file entry . This means that valid paths need must not be URL encoded.

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

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

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

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 the [IRI] [RFC3987] specification.

Authoring Guidelines: Because of

A user agent must retrieve the risk of confusion between IRIs that would be equivalent if dereferenced, value for a IRI attribute using the use of %-escaped characters in feature names is strongly discouraged. rule for getting a single attribute value .

Version attribute

The value of a version attribute is any an arbitrary string value (possibly empty) within the constraints allowed for [XML] attributes. 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 Guidelines: 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
]

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

7.5 8.4 Other Attributes

This section describes the behavior and expected usage of other relevant attributes that are part of the [XML] specification and the [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 nodes. elements.

The value of an xml:lang attribute must be processed by a user agent in accordance with the [XML] specification.

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

Authoring Guidelines: 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 , rtl , lro , or rlo ). Authoring Guidelines: To use the its:dir attribute, the its namespace (see [ITS] ) needs to must be declared on the element where it is used, 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 .

7.6 8.5 The widget Element

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

Context in which this element is must be used:

widget This is the root element of a configuration document .

Occurrences:

Exactly one, at 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. more ( elements are grouped by language ).

content : zero or one.

feature : zero or more.

preference : zero or more.

Localizable:

No.

7.6.1 8.5.1 Attributes of the widget Element

id

An A IRI attribute that denotes an identifier for the widget.

Authoring Guidelines:

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

version

A version attribute that specifies the version of the widget.

Authoring Guidelines:

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

height

A numeric attribute greater than 0 that indicates the preferred viewport height of the instantiated custom start file in CSS pixels [CSS21] . Authoring Guidelines: It is optional for authors to use the height attribute with a widget element. This value is only applicable to particular view modes , meaning that for certain view modes this value is ignored . The view modes that honor the value of the height attribute are defined in the [Widgets-Views] specification.

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

width

A numeric attribute greater than 0 that indicates the preferred viewport width of the instantiated custom start file in CSS pixels [CSS21] . Authoring Guidelines: It is optional for authors to use the width attribute with a widget element. This value is only applicable to particular view modes , meaning that for certain view modes this value is ignored . The view modes that honor the value of the height width attribute are defined in the [Widgets-Views] specification.

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

viewmodes

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

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

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

Authoring Guidelines:

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

xml:lang

Authoring Guidelines:

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

7.6.2 8.5.2 Usage example

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

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

7.7 8.6 The name Element

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

Context in which this element is 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. Authoring Guidelines: The Yes, but the value of the xml:lang attribute needs to must be unique for any subsequent element of this type.

7.7.1 8.6.1 Attributes of the name Element

xml:lang

Authoring Guidelines:

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

its:dir

A valid its:dir value .

Authoring Guidelines:

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

short

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

Authoring Guidelines:

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

7.7.2 8.6.2 Conformance Checker Behavior

A CC must inform an author if the value of the short attribute is longer in length than the text content of the name element.

8.6.3 Usage Example

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

</widget>

7.8 8.7 The description Element

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

Context in which this element is 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. Authoring Guidelines: The Yes, but the value of the xml:lang attribute needs to must be unique for any subsequent element of this type.

7.8.1 8.7.1 Attributes of the description Element

xml:lang

Authoring Guidelines:

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

its:dir

A valid its:dir value .

Authoring Guidelines:

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

7.8.2 8.7.2 Usage Example

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

<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 dahut activity in your
area. When a big one walks by, the widget plots the best route on a map based
on the dahut's trajectory so you can chase it! With support for
built-in cameras, you can quickly upload all the Alpine action to
your blog or to the insane dahut chaser web site! Awesome!

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>

</widget>

7.9 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 is may be used:

As a child of the widget element.

Content model:

Any.

Occurrences:

Zero or one.

Localizable via xml:lang :

No. Only the first instance of this element in document order will be used, regardless of the value of xml:lang (if any).

7.9.1 8.8.1 Attributes of the author Element

href

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

Authoring Guidelines:

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

email

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

Authoring Guidelines:

It is optional for authors to use the email attribute with an author element.

its:dir

A valid its:dir value .

Authoring Guidelines:

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

7.9.2 8.8.2 Usage Example

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

<widget xmlns="http://www.w3.org/ns/widgets">
    <name>Cup-a-Joe's Cafe Finder Widget</name>
    <author href  = "http://dahut.example.org/about/joe"
            email = "joe@example.org">

    <author href  = "http://dahut.example.org/about/joe" 
            email = "joe@example.org">

      Joey and Princesa Bacalhau
    </author>
</widget>

</widget>

7.10 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 is 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. Authoring Guidelines: The Yes, but the value of the xml:lang attribute needs to must be unique for any subsequent element of this type. The content of localized

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

7.10.1 8.9.1 Attributes of the license Element

href

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

When the href attribute is used, the user agent should provide users the ability to view or otherwise link to the referenced license.

If the Authoring Guidelines: href attribute contains a valid path to a file within the widget package, then the user agent 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 the href attribute with a license element.

xml:lang

Authoring Guidelines:

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

its:dir

A valid its:dir value .

Authoring Guidelines:

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

7.10.2 8.9.2 Usage Example

<widget xmlns="http://www.w3.org/ns/widgets">
  <license href="http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231">
        W3C Software License

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

  </license>
</widget>

</widget>

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

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

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>

</widget>

7.11 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 is may be used:

As a child of the widget element.

Content model:

Empty.

Occurrences:

Zero or more. 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.

7.11.1 8.10.1 Attributes of the icon Element

src

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

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

width

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

It is optional for authors to use 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] . The .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 Authoring Guidelines: src attribute of the icon element is a supported raster graphic format, then the user agent 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 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 Guidelines: Guideline: Refrain from using the width and height attributes for raster graphic formats, as widget user agent will ignore these values.

7.11.2 8.10.2 Usage Example

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

8.10.3 Usage Example

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

7.12 8.11 The content Element

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

Context in which this element is may be used:

As a child of the widget element.

Content model:

Empty.

Occurrences:

Zero or one.

Localizable via xml:lang :

No. Relies on folder-based localization .

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

Authoring Guidelines:

When a content element is used, it is required for authors to use 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 .

Authoring Guidelines:

It is optional for authors to use the type attribute with a content element. When the value is absent, the user agent will assume the value text/html .

encoding

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

Authoring Guidelines: Where aliases are given by the [IANA-Charsets] registry, authors are encouraged to use the value of the "preferred MIME name" (if any) from the registry. The default encoding is

A user agent must support [UTF-8] , which has the name " " UTF-8 " " name in the [IANA-Charsets] registry. Aside from the default encoding , ; it is optional for a user agent to support other character encodings.

When the value of Authoring Guidelines: encoding is absent or in error ,the user agent 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".

7.12.2 8.11.2 Usage Example

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

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

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

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

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

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

  <content src="lbg-maps.swf" type="application/x-shockwave-flash"/>
  <feature name="http://example.org/api.geolocation"
           required="false"/> 
</widget>

7.13 8.12 The feature Element

A feature is a URI identifiable runtime component (e.g. an Application Programming Interface or video decoder). decoder) that is not part of the specified set provided by the Widgets 1.0 family of specifications . The feature element serves as a standardized means to request the binding of an IRI (IRI) identifiable runtime component to a widget for use at runtime. Using a feature element denotes that, at runtime, a widget 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 has may have zero or more parameters associated with it.

Context in which this element is 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.

7.13.1 8.12.1 Attributes of the feature Element

name

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

Authoring Guidelines:

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

required

A boolean attribute that indicates whether or not this feature has to must be available to the widget at runtime. 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.

Authoring Guidelines: It is optional for authors to

The default value that a user agent must use when the required attribute with an is absent is true ,meaning that the feature element. However, authors need to must be aware that a made available to the widget by the user agent will behave as at runtime.

It is optional for authors to use the required attribute had been set to true when the with an required feature attribute is absent, meaning that the named feature needs to be available at runtime or the widget will be treated as an invalid widget package . element.

7.13.2 8.12.2 Usage example

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

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

7.14 8.13 The param Element

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

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 has no function or meaning).

Context in which this element is may be used:

As a child of the feature element.

Content model:

Empty.

Occurrences:

Zero or more.

Localizable via xml:lang :

No.

7.14.1 8.13.1 Attributes of the param Element

name

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

Authoring Guideline:

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

value

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

Authoring Guidelines:

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

7.14.2 8.13.2 Usage example

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

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

</widget>

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

A user agent that supports the [Widgets-APIs] specification will must expose any declared preference to the author at runtime via 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 preference values at runtime via the relevant methods defined in the [Widgets-APIs] specification.

Context in which this element is may be used:

As a child of the widget element.

Occurrences:

Zero or more.

Expected children:

none.

Localizable via xml:lang :

No.

7.15.1 8.14.1 Attributes of the preference Element

name

A string that denotes the name of this preference .

Authoring Guidelines:

When a preference element is used, it is required for authors to use 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 absent is null (i.e., the data value null ,and not a string " null ").

Authoring Guidelines:

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

readonly

A boolean attribute indicating whether this preference can, or cannot, can be overwritten at runtime (e.g., via an author script). When set to true , it means runtime.

The default value that a user agent must use when the preference cannot be overwritten. When set to readonly attribute is absent is false , it means meaning that the preference value can be overwritten. overwritten at runtime.

Authoring Guidelines:

It is optional for authors to use the readonly attribute with a preference element. If the readonly attribute is absent, the user agent will act as if the readonly attribute had been set to false (meaning that the preference can be overwritten at runtime).

7.15.2 8.14.2 Usage example

<widget xmlns="http://www.w3.org/ns/widgets">
   <preference name     = "skin"
               value    = "alien"/>
   <!-- The preference below will be protected
        from modification and deletion at runtime -->
   <preference name     = "api-key"
               value    = "f6d3a312f9d742"
               readonly = "true"/>
</widget>

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

</widget>

7.16 8.15 Indicating Text Directionality with its:span

This section feature is informative. at risk .

Authoring Guidelines: 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 its:dir dir attribute, with one of the following valid its:dir value s, as defined in [ITS] : ITS:

ltr

Left to right text.

rtl

Right to left text.

lro

Left-to-right override.

rlo

Right-to-left override.

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

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

  <description its:dir="rtl"> </description>
</widget>

  <name>Yay for the  
  "<its:span dir="rtl">متعة الأسماك!</its:span>" Widget</name>
  <description its:dir="rtl">متعة الأسماك! </description>

</widget>

The its:span element can may be used as a child element of the following elements of the configuration document . In addition, the its:dir attribute can may be used in the following elements of the configuration document :

• name
• description
• author
• license

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

8 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"). "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 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 a 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 folder-based element-based localization ). A widget package contains 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/ " "/locales/ja" (Japanese) might contain an HTML document translated into Japanese.

Authoring Guidelines: 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.

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

8.2 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 contains 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 contains may contain zero or more arbitrary folders and/or files.

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

 config.xml
  

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.

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

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

</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" "yes" or "no". "no".

If an element is marked as being localizable via xml:lang with the word "no", "no", it means that the element is not localizable via element-based localization . In other words, exclusion of an xml:lang on an element indicates that that element is unlocalized content , except in the case whereby a parent element uses xml:lang (this maintains consistency with the behavior of xml:lang as specified in the [XML] specification). Explicitly declaring xml:lang overrides any xml:lang value inherited from a parent element.

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

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

   <name short="Weather">
    

   <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 xml:lang="pt">
    The declaration of xml:lang="pt" overrides
    xml:lang="en" inherited from the widget element. 

   </name>
</widget>

</widget>
  

If an element is marked as being localizable via xml:lang with "yes", "yes", the specification always indicates that only 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 will must only match the first element, in document order , that matches a language range in the user 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 United States). As only one instance of the description element is allowed per language, in the following code the user agent would match the first description element but would ignore the second and third description elements.

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

<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 xml:lang="en">
      This element would be ignored.  

   </description>
   <description>
      This element is unlocalized, and would be used if the user agent's

      This element is unlocalized, and would be used if the user agent's 

      locale does not match any localized description elements.
   </description>
</widget>

</widget>

However, if the user agent locales only contained " " * ", ", or did not match any of the localized 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 locales , the user agent will must use the first element that is unlocalized content , 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: " " jp " " (Japanese). As only one instance of the description element is allowed per language, in the following code the user will agent ignore the first two description elements, but would match the third (unlocalized) description element.

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

<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 xml:lang="en">
      This element would be ignored.  

   </description>
   <description>
      In this case, this unlocalized element would be used.
   </description>
</widget>

</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 that matches the language ranges of the user agent locales ,as well as elements of that particular name that are unlocalized content .

For example, assume that the user agent locales contains the following language ranges: " jp,en " (Japanese and english). As multiple instances of the icon 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"/>
</widget>

Now assume that the user agent locales contains the following language range: " jp " (Japanese). In the following code, the user agent would ignore the first icon element, but match the second, third, and fourth 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>

8.4 9.4 Localization Examples

This section is non-normative.

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

8.4.1 9.4.1 Simple Example

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

<widget xmlns="http://www.w3.org/ns/widgets">
<name>What day is it?</name>
<description>
 This widget highlights the current day
 of the week.
</description>
</widget>

</widget> 
  

<!doctype html>
<title>¿Qué día es?</title>
<script src="scripts/dayfinder.js"></script>

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

<body>
<p>Hoy es: lunes, martes, miércoles,
   jueves, viernes, sábado,

<p>Hoy es: lunes, martes, miércoles, 
   jueves, viernes, sábado, 

   domingo

  

8.4.2 9.4.2 Complex Example

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

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

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

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

...
  

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

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

8.4.3 9.4.3 Fallback Behavior Example

<!doctype html>
<title>Patriotic Boat</title>
<script src="scripts/engine.js">

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

</script>
<body>
  <img src="flag.png">
<img
src="mast.png">

  <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 follows 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 widget package . In the event that a user agent encounters an invalid widget package Zip archive during the steps (see rule for processing a widget package , a user agent dealing with an invalid Zip archive must abort all processing of the steps for processing a widget package . ).

The steps for processing a widget package and associated processing rules , are written with more concern for clarity than efficiency. As such, a user agent may optimize any of the parsing rules and the steps, or may perform the steps in a different order, but the end result needs to 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 , which are a set of common algorithms used during in the by the steps for processing a widget package .

9.1.2 10.1.1 Rule for extracting file data from a file entry

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

Let Given a path be the zip relative path that identifies matches the file entry being sought. Let file entry name field be the of a file entry identified by the path . Let file be within the result of decompressing Zip archive ,a user agent must decompress (or extracting) otherwise extract) the file data from of file entry using into its original file representation. Implementers must follow the [Zip] . Return [ZIP] specification's instructions on how to extract a file . from the Zip archive.

Note: For efficiency, a user agent can extract specific files as they are needed for 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 could use, for example, a virtual file system or mapping to access files inside a widget package .

9.1.3 10.1.2 Rule for Dealing with an Invalid Zip archive

The rule for dealing with an invalid Zip archive is described in this section.

In the event that an implementation encounters an invalid Zip archive during the steps for processing a widget package ,the user agent must abort all processing of the steps for processing a widget package .

In the case the UA is a CC, it must inform the author that the Zip archive is an invalid Zip archive .

10.1.3 Rule for Finding a File Within a Widget Package

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

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 valid path to the file entry being sought by the user agent. If the path starts with a U+002F SOLIDUS (e.g., " /style/master.css "), then remove the first U+002F SOLIDUS from path. sought.

2. Let path-components be the result of splitting path at each occurrence of a U+002F SOLIDUS character, removing that U+002F SOLIDUS character in the process.

3. If the number of items in path-components is greater than two, then check if the first second item in path-components case-sensitively exactly matches the string " " locales ", then: ". If the path-components does not contain a second item, then return null . it does:

   1. If the second third item in path-components is not contains any characters other than a valid U+002D HYPHEN-MINUS ("-") or characters the range language-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.

4. If the path starts with a U+002F SOLIDUS (e.g., " /style/master.css "), meaning that the path is an Zip absolute path ,then remove the first U+002F SOLIDUS from path.

5. For each lang-range in the user agent locales :

   1. Let path be the concatenation of the string " " locales/ ", ", the lang-range , a U+002F SOLIDUS character, and 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 case-sensitively matches the file name field of points to a file entry within the widget package that is a folder , , then return an error and terminate this algorithm. If path case-sensitively matches the file name field of a file entry within the widget package that is a file , 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.

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

   1. If path points to a file entry within the widget package that is a folder , then return an error and terminate this algorithm. If path points to a matching file entry within the widget package that is a file , 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 the path points to a file entry that is not a processable file , then return an error and terminate this algorithm.

7. Otherwise, return null .

9.1.4 10.1.4 Rule for Getting a Single Attribute Value

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

1. Let result be the value of the attribute.

2. In result , replace any sequences of space characters (in any order) with a single U+0020 SPACE character.

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

4. Return result .

9.1.5 10.1.5 Rule for Getting a List of Keywords From an Attribute

The rule for getting a list of keywords from an attribute is given by the following algorithm. The algorithm takes a string as input, and returns a list which can may be empty.

1. Let result be the value of the attribute to be processed. attribute.

2. In result , replace any sequences of space characters (in any order) with a single U+0020 SPACE character.

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

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

5. Return result.

9.1.6 10.1.6 Rule for Verifying a File Entry

The rule for verifying a file entry is given in the following algorithm. The algorithm always returns a boolean value.

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

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

2. The version needed to extract is greater than 20 (meaning the archive is using a feature unsupported by this specification, such as Zip64), return false and terminate this algorithm.

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

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

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

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

7. return true .

9.1.7 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 can 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 Element to be processed.

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

9.1.8 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 can may be empty.

1. Let input be the Element to be processed.

2. Let result be the result of applying the rule for getting text content to input .

3. In result , convert any sequence of one or more Unicode white space characters into a single U+0020 SPACE.

4. In result , remove any leading or trailing U+0020 SPACE character. Return result .

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

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

</widget>
  

9.1.9 10.1.9 Rule for Parsing a Non-negative Integer

The rule for parsing a non-negative integer is are as given in the following algorithm. This When invoked, the algorithm returns must be followed in the number order given, aborting at the first step that returns a value. This algorithm will either return zero, a positive integer, or an error.

There may be implementation-specific limits on the range of integers allowed, and behavior outside such limits is 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 and terminate this algorithm. error. Otherwise, go to step 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 .

9.1.10 10.1.10 Rule for Identifying the Media Type of an Image

The rule for identifying the media type of an image 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 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 match one of the byte sequences in the bytes in the magic number column of the following table, then return the media type in the corresponding cell in the media type column on the same row. Otherwise, return unknown/unknown .

10.1.11 Rule for Identifying the Media Type of a File

The rule for identifying the media type of a file 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 (e.g., during (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. Let content-type be an empty string. Let extension be an empty string. Let name If file be the has a file-name file-extension component of the zip relative path that identifies , attempt to match the file file-extension . For example, the name for " some/zip/rel/path/hello.png " would be " hello.png ". If the first character of the name is a U+002E 'FULL STOP' character, and the file name contains no other U+002E 'FULL STOP' character, then go to step 10 of this algorithm. For example, if the name is " .htaccess ", jump to step 10 and derive the MIME type using the [SNIFF] specification. If the first character of the name is not a U+002E 'FULL STOP' character, but name contains one or more U+002E 'FULL STOP' characters, then let extension be the sequence of characters from the last U+002E 'FULL STOP' (inclusive) to the end of name (if any). The value of extension for the file name " cat.html " would be ". html ". The value of extension for "...html" would be ".html". And the value of extension for "hello." would be an empty string. If the first character of the name is a U+002E 'FULL STOP' character, and the file name contains another U+002E 'FULL STOP' character, then let extension be the sequence of characters from the last U+002E 'FULL STOP' (inclusive) to the end of name (if any). For example, if the name is " .myhidden.html ", then the extension would be " .html ". If extension is an empty string, go to step 10 in this algorithm. Check that each character in the extension is either in the U+0041-U+005A range or in the U+0061-U+007A range (ASCII uppercase and lowercase characters, respectively): If any character in the extension is outside the U+0041-U+005A range and the U+0061-U+007A range, then go to step 10 in this algorithm. For example, if the extension is " .pñg ", the go to step 10 in this algorithm. If all characters in the extension are in either of in the U+0041-U+005A range or in the U+0061-U+007A range, then attempt to case-insensitive match the value of extension to one of the values in the file extension extensions column in the file identification table . If there is a match, then return let content-type be the corresponding value from the media type column. Go to step 11. value.

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

4. Return the value of content-type .

9.1.11 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 2 - Verify the Zip Archive

Step 3 - Set the Configuration Defaults

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

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

Step 4 - Locate and Process the Digital Signature

Step 5 - Derive the User Agent's Locale

Step 6 - Locate the Configuration Document

Step 7 - Process the Configuration Document

The purpose of processing the configuration document is to override the values in the table of configuration defaults , which are used during initialization and at runtime, and to select the appropriate localized content (if any) to be presented to the end user.

In conjunction to the algorithm for processing a configuration document given below, this section firstly defines some terminology used by the processing algorithm and describes how localized elements are processed.

9.1.14 10.1.16 Terminology Used in Processing Algorithm

In the algorithm to process a configuration document , the The term in error is used in this Step to mean that an element, or attribute, or file in a configuration document is 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; but will generally require the user agent to ignore any element, attribute, or file that is in error. To ignore means to that a user agent must act as if the element, attribute, or file that is in error is absent (i.e., not declared or included by the author) in the widget package or configuration document. A user agent must , however, keep a record of all element types it has attempted to process even if they were ignored (this is to determine if the user agent has attempted to process an element of a given type already). In the case the user agent is asked to ignore an [XML] element or node, a user agent must : Stop processing the current element , ignoring all of the element 's attributes and child nodes (if any), and proceed to the next element in the elements list . Make a record that it has attempted to process an element of that type. In the following example, the user agent ignores both content elements. The user agent ignores the first because it lacks a src attribute. The user agent ignores the second because it is not the first content element to be encountered by the user agent. present.

To associate means that two or more 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, an object, a hash map, etc.).

The lookup algorithm is defined in section 3.4 of [RFC4647] (part of [BCP47] ). It is used in this Step to to match localized content in the configuration document to the language ranges held by the user agent locales (if any).

9.1.15 10.1.17 Algorithm Conformance Checker Behavior

A CC should process a configuration document using the algorithm to Process process a Configuration Document configuration document .However, where an element or attribute is in error, or invalid, the conformance checker must inform 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 an [XML] parser that is both a [XMLNS] -aware and xml:lang aware. parser.

2. If doc the document is not namespace well-formed [XML] , then the user agent must terminate this algorithm and treat this widget package as an invalid widget package 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 the user agent must terminate this algorithm and treat this widget package as an invalid widget package Zip archive .

5. Otherwise, the element is a widget element:

   1. If the id attribute is used, then let id be the result of applying the rule for getting a single attribute value to the id attribute. If id is a valid IRI , then let widget id be the value of the id . If the id is in error , then the user agent must ignore the attribute.

   2. If the version attribute is used, then let widget version value be the result of applying the rule for getting a single attribute value to the version attribute. If the version is an empty string, then the user agent must ignore the attribute; otherwise, let widget version be the value of version value .

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

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

   5. If the viewmodes attribute is used, then 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. From the viewmode list , remove items, and any duplicated items from right to left. For example, veiwmode list with a value that are not one of " application fullscreen application widget fullscreen application " would become " application fullscreen widget ". the valid view modes ,and any duplicated items. Let widget window modes be the value of viewmodes list .

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

   7. If the widget element does not contain any child elements, then the user agent must terminate this algorithm and go to Step 8 .

6. Otherwise, let Let element list be an empty list.

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

   1. If the value of range is not "*", then retaining document order , let 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. If the value of

   For each range is "*", retaining document order , let in the unlocalized user agent locales ,starting from the first and moving to the last:

   1. Let matching elements be all the result of applying lookup to the child elements of type icon that are direct descendents of the root element that do not have an implicit or explicit and whose xml:lang attribute (i.e., match unlocalized content ). Append unlocalized elements to matches the current element list range . For example, consider the following configuration document. <widget xmlns="http://www.w3.org/ns/widgets"> <name>El Widget!</name> <name xml:lang="fr">Le Widget</name> <name xml:lang="en">The Widget</name> </widget> For a use agent whose user agent locales Document order contains " en,fr,* ", must be retained in the resulting matching elements would be in the following order: list.

      <name xml:lang="en">The Widget</name>
   2. <name xml:lang="fr">Le Widget</name> <name>El Widget!</name>

      For a use agent whose If user agent locales matching elements contains " en,* ", the is not empty, append matching elements would be to element list and continue to step 8 in the following order: this algorithm.

      <name xml:lang="en">The Widget</name>
   3. <name>El Widget!</name>

      If matching elements is empty, continue to the next range .

8. For Let unlocalized elements be all child elements that are direct descendents of the root element that do not have a use agent whose declared user agent locales xml:lang contains " jp,* ", attribute (i.e., match unlocalized content ). Document order must be retained in the resulting list.

9. Append matching unlocalized elements would be in to the following order: element list .

   <name>El Widget!</name>

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 by the user agent, 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 by the user agent, then the user agent must : encountered,

    1. Record that an attempt has been made by the user agent to process a name element. 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 by the user agent, 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 by the user agent, then the user agent must : Record that an attempt has been made by the user agent to process a 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 by the user agent, encountered, then the user agent must ignore this element, its attributes, and any child nodes. Stop processing this element . If this is and proceed to the first license next element used, then the user agent must : Record that an attempt has been made by in the user agent to process a license element. 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 IRI or a valid path , then the href attribute is in error and the user agent must ignore the attribute. it.

    If potential license href is a valid IRI , then let 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 file be the result of applying the rule for finding a file within a widget package to license href .

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

    An icon element:

    If the src attribute of this icon element is 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 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 a file 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, then 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 height attribute is in error and the user agent must ignore the attribute. it.

    2. If the width attribute is used, then 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 width attribute is in error and the user agent must ignore the attribute. 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 by the user agent, 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 the user agent must : then:

    1. Record that an attempt has been made by the user agent to process a author element. If the href attribute is used, then 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 IRI , then let author href be the value of the href attribute. Otherwise, if href-value is not a valid IRI , then the user agent must ignore the href 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 of the preference element is used, but the name attribute is absent, then this preference element is in error and the user agent must ignore this element . it.

    Otherwise, the user agent must :

    1. Let 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 name is an empty string, then this element is in error ; and the user agent must ignore it. Stop processing this element . If widget preferences already contains a preference whose name case-sensitively matches and proceed to the value of name , then this next element is in error ; ignore this the element elements list . If name was not in error , let preference be an empty object. Associate Otherwise, associate name with preference .

    4. Let value be the result of applying the rule for getting a single attribute value to of the value attribute. Associate the value with preference .

    5. If a readonly attribute is used, then let readonly be the result of applying the rule for getting a single attribute value to the readonly attribute. If readonly is not a valid boolean value , then let the value of readonly be the value ' false '. Associate readonly with the preference .

    6. Add the preference and the associated name , value and readonly variables the list of widget preferences .

    A content element:

    If this is not the first content element encountered by the user agent, 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, then the user agent must :

    1. Record that an attempt has been made by the user agent to process a content element. If the src attribute of the content element is 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 not a valid path , then the user agent must ignore this element .

       If path is a valid path , then let file be the result of applying the rule for finding a file within a widget package to path . If file path is null or in error, not a valid path , then the a user agent must ignore treat the widget package this element . 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 , then 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, then let content-type be the result of applying the rule for getting a single attribute value to the value of the type attribute. 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 widget package Zip archive .

    6. If the encoding attribute is used, then let content-encoding be the result of applying the rule for getting a single attribute value to the value of the encoding attribute. If content-encoding is supported by the user agent, then let the start file encoding be the value of content-encoding . the encoding attribute. If content-encoding is empty or unsupported by the user agent, then a user agent must should ignore use the default encoding ( attribute. A param element: If this param element is not a direct child of a feature element, then the user agent must ignore this param UTF-8 element . Note: How a param element is to be processed when it is inside a feature element is defined below. ).

    A feature element:

    If a required attribute of this feature element is used, but no name attribute is used, then the user agent this element, its attributes, and its children are in error and must ignore 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, then 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 , then let the value of required-feature be the value ' true '.

    3. If feature-name is not a valid IRI , and required-feature is true , then the user agent must treat this widget as an invalid widget package Zip archive .

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

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

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

    7. If the feature element contains any 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, then 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 .

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

    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 that is not a direct child of a feature element.