Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
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 23 July 2009 Candidate Recommendation of the Widgets 1.0: Packaging and Configuration specification. W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. The Web Applications (WebApps) Working Group expects to request that the Director advance this document to Proposed Recommendation once the Working Group has developed a comprehensive Widgets 1.0: Packaging and Configuration test suite, and demonstrated at least two interoperable implementations (interoperable meaning at least two implementations that pass each test in the test suite). The 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 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.
widget
Elementname
Elementdescription
Elementauthor
Elementlicense
Elementicon
Elementcontent
Elementfeature
Elementparam
Elementpreference
Elementits:span
This section is non-normative.
Widgets are full-fledged client-side applications that are authored using Web standards and packaged for distribution. They are typically downloaded and installed on a client machine or device where they run as stand-alone applications, but they can also be embedded into Web pages and run in a Web browser. Examples range from simple clocks, stock tickers, news casters, games and weather forecasters, to complex applications that pull data from multiple sources to be "mashed-up" and presented to a user in some interesting and useful way (see [Widgets-Landscape] for more information).
This section is non-normative.
The design goals and requirements for this specification are addressed in the Widgets 1.0 Requirements [Widgets-Reqs] document.
This document addresses the 25 requirements relating to "Packaging" and "Configuration Document" of the 30 April 2009 Working Draft of the Widgets 1.0: Requirements Document:
author
element.license
element.widget
element.content
element.icon
element, default icons table and custom icons table.param
element (used in conjunction with the
feature
element).preference
element.feature
element.viewmodes
attribute of the widget
element.This section is non-normative.
The reader should be aware that this document is organized into two halves, but not explicitly marked as such. The first half defines the various aspects of what constitutes the packaging format, the configuration document, and reserved files, such as default icons and locale folders, as well as some of the expected behavior of conformance checkers, which are implementations that check the conformance of a Zip archive or a configuration document to this specification. Where possible, the first half avoids describing aspects related to processing, which are described in detail in the second half of the document.
The second half, which starts with the section titled "Steps for Processing a widget package", defines the steps required to process a widget package as well as the expected behavior of a user agent as it processes the packaging format, the configuration document, and attempts to find localized content. The second half of this document also deals with error handling in the event that a user agent encounters unsupported or missing files, or DOM nodes that are in error in the configuration document. Wherever processing is relevant, sections in the first half of the document link to sections in the second half of the document.
This section is non-normative.
This section defines the typographical conventions used by this specification.
Defined terms appear as this sample defined term. Such terms are referenced as sample defined term, providing a link back to the term definition.
Words that denote a conformance clause or testable assertion use keywords from [RFC2119]: must, must not, required, should, should not, recommended, may and optional.
Variables are formatted specially, e.g. variable. Code is
also specially formatted, such as code
.
Words in italics denote a formal definition given in an external specification.
This is an example. Examples are used to explain concepts or demonstrate how to use a feature. Examples are non-normative.
ISSUE: This is an issue. It implies something that Working Group is trying to fix. Eventually, all these will disappear from the spec. Issues are non-normative.
Note: This is a note, it usually contains useful supplementary information in a non-normative form.
This section is non-normative.
This specification is part of the Widgets 1.0 family of specifications, which together standardize widgets as a whole:
The Widgets 1.0: APIs and Events specification defines APIs 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 the XML-Signature Syntax and Processing Specification (see [Widgets-DigSig]).
The Widgets: 1.0: Updates specification defines a version control model that 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: URI Scheme specification which defines a URI scheme for use inside widgets or other such applications of web technology that do not run on the Web (see [Widgets-URI]).
The key words must, must not, required, should, should not, recommended, may and optional in this specification [RFC2119].
Some text in this specification is non-normative. Non-normative text includes:
This section is non-normative,
Everything else in this specification is normative.
Please see the typographical conventions to see how authoring guidelines, examples, and notes of this specification are stylized.
This specification describes the conformance criteria for user agents (relevant to implementers) and various resource types (relevant to authors).
There are four classes of products that can claim conformance to this specification:
A user agent may support other legacy/proprietary widgets.
The following definitions are used throughout this specification. Please note that other terms are given throughout this document and defined where they are used.
An author is a person who created a widget package or an authoring tool that generated a widget package.
A media type is defined in the [MIME] specification (see in particular RFC2046).
A language tag is a text
string that 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 widget is defined by the [Widgets-Landscape] as an end-user's
conceptualization of an interactive single purpose application for
displaying and/or updating local data or data on the Web, packaged in a
way to allow a single download and installation on a user's machine,
mobile phone, or Internet-enabled device
. Because widgets are
packaged, they can be shared by users without relying on [HTTP] (i.e., users can share widgets over non-HTTP
distribution channels, such as Bluetooth or a USB thumb drive).
Reserved means that a character, or text
string, or file-name
, or folder-name
has a specified purpose and
semantics in this specification or in some other specification or system.
The intended purpose for any reservation is given when the term is used.
Arbitrary means that a character, or text
string, or file-name
, or folder-name
is not reserved for the purpose of this specification.
Supported means that a user agent implements a mentioned specification, or conformance clause, or is able to process or otherwise render mentioned media type.
Unsupported means the user agent does not implement a mentioned specification, or feature, or is unable to render or otherwise process a mentioned media type.
Initialization means a run through the steps for processing a widget package after installation of a widget.
The space characters, for the purposes of this specification, are [Unicode] code points:
The Unicode white space characters are [Unicode] code points marked in the [Unicode] specification (version 5.0.0) with the property "White_Space". Those code points include:
The control characters, for the purpose of this specification, are [Unicode] code points:
The following Unicode code points are referred to as the forbidden characters in this specification:
A user agent is an implementation that supports this specification.
Note: The user agent described in this specification does not necessarily denote a "widget user agent" at large: that is, a user agent that implements all the specifications, and dependencies, defined in the Widgets 1.0: Family of Specifications. The user agent described is this specification is only concerned with how to processes Zip archives and configuration documents.
A user agent must behave as described by this specification in order to claim conformance, even when faced with a non-conforming widget package or a non-conforming configuration document.
Note: Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the [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.
A user agent must support the following specifications:
A user agent may support the [Widgets-DigSig] specification, the [Widgets-Updates] specification, the [Widgets-Access] specification, and the [Widgets-APIs] specification.
A user agent must support the [ZIP] specification. However, it is optional for user agent to support the following aspects of the [ZIP] specification:
To facilitate the localization of text nodes within XML elements in a configuration document, a user agent
may support
the Internationalization Tag Set's ([ITS])
its:span
element and the its:dir
attribute. It is optional for a user agent to support other ITS elements and attributes.
Although this specification defines the elements of the configuration document in which
its:span
element and the its:dir
attribute can be used (below), the
specification does not define how they are to be interpreted and processed
by a user agent. If a user agent implements its:span
and
its:dir
, then the user agent must do so in conformance to the processing rules defined
by the [ITS] specification.
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.
The packaging format for the files of a widget is the Zip archive format as defined in the [ZIP] file format specification.
A file entry is the data held by a local file header, file data, and (optional) data descriptor, as defined in the [ZIP] specification, for each physical file contained in a Zip archive.
A potential Zip archive is a data object claiming to be a Zip archive, that has not been verified to be a valid Zip archive.
A valid Zip archive is a data object that must conform to the production of a .Zip file as defined by the Zip File Format Specification [ZIP], with the exclusion or support for the features and conditions defined in the Zip Support section of this specification.
Note: Step 2 of the steps for processing a widget package describes how a user agent verifies that a Zip archive conforms to this specification.
The magic numbers for a Zip
archive is the byte sequence: 50 4B 03 04
.
To conform to this specification, a Zip archive must contain one or more file entries and must be a valid Zip archive.
Note: A valid Zip archive does not imply a conforming widget package. All valid Zip archives need to be further checked, using Step 2, to see if they qualify as a widget package.
An invalid Zip archive is a condition whereby a Zip archive, or a file within the Zip archive, is deemed to be corrupt beyond recovery or is non-conforming to, or unsupported by, this specification in such a way that it would not be possible for the user agent to continue processing. During the steps for processing a widget package, certain error conditions can result in a Zip archive being treated as an invalid Zip archive.
Upon encountering an invalid Zip archive, a user agent must apply the rule for dealing with an invalid Zip archive.
A CC must inform the author that a Zip archive that is split into multiple files or spans multiple volumes, as defined in the [ZIP] specification, is an invalid Zip archive.
A CC must inform the author that a Zip
archive that is encrypted, which is denoted by bit 0
of
the general purpose
field being set and by the presence of archive decryption header and an
archive extra data
record (all three of which are defined in the [ZIP] specification), is an invalid Zip archive.
A CC must inform the author that a Zip archive that contains zero file entries is an invalid Zip archive.
A CC must inform the author that a Zip archive that contains only folders is an invalid Zip archive.
A compression method is the compression algorithm or storage method used to encode the file data of a file entry. The compression method that is used to encode the file data of a file entry is identified by the numeric value derived from the compression method field defined in the [ZIP] specification.
The valid compression methods, as indicated by the compression method field, for a file entry are:
8
0
Of the valid compression methods, [Deflate] is the recommended compression method.
A CC must verify that each file entry uses one of the valid compression methods. If a CC encounters a file entry that uses a compression method that is not one of the valid compression methods, then the CC must inform the author to recompressed the file entry using one of the valid compression methods.
The version needed to extract is the 2-byte sequence in the local file header of a file entry that indicates the minimum supported version of the [ZIP] specification needed to extract the file data.
The valid versions needed to extract values are as follows. Each value is assigned one or more meanings by the [ZIP] specification:
Note: If the Zip archive has been encrypted using traditional PKWARE encryption, then the user agent will treat the Zip archive as an invalid Zip archive in Step 2.
A CC must inform the author of any file entry with a value for version needed to extract does not match a valid versions needed to extract value (meaning that user agents could potentially ignore the file at run time).
A Zip relative path is the variable-length string derived from the file name field of the local file header of a file entry.
Note: A Zip relative path is said to be relative as it stores the string that represents file and folder names relative to where the Zip archive was created on a file system (e.g. images/bg.png), as opposed to storing an absolute path (e.g. c:\images\bg.png). The value of a Zip relative path will generally resemble the string value of a name of the file or folder(s) on the device on which the Zip archive was created, but with the exception of the path delimiter being a U+002F SOLIDUS "/" character. Note also that a Zip relative path is not a URI reference; Zip relative paths need to be converted to URI references before they can be used in context that make use of URIs.
The valid encodings for a Zip relative path are either [CP437] or [UTF-8]. It is recommended that the file name field be encoded using [UTF-8].
For interoperability, manipulations of Zip relative paths must be performed on the string obtained by decoding the file name field using the appropriate encoding, and not on the bytes initially stored in the archive. For the sake of comparison and matching, it is recommended that a user agent treat all Zip-relative paths as [UTF-8].
A valid Zip relative path is
one that matches the production of Zip-rel-path
in the following [ABNF]:
Zip-rel-path = [ *folder-name ] file-name /
[ locale-folder ] 1*folder-name /
locale-folder [ *folder-name ] file-name
locale-folder = %x6c.%x6f.%x63.%x61.%x6c.%x65.%x73 ; "locales"
"/" folder-name
folder-name = file-name "/"
file-name = base-name [ file-extension ]
base-name = 1*allowed-char
file-extension = "." 1*allowed-char
allowed-char = safe-char / utf8-char
safe-char = ALPHA / DIGIT / SP / "$" / "%"
/ "'" / "-" / "_" / "@"
/ "~" / "(" / ")" / "&" / "+"
/ "," / "." / "=" / "[" / "]"
utf8-char = %x80-D7FF / %xF900-FDCF / %xFDF0-FFEF
/ %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD
/ %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD
/ %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD
/ %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD
/ %xD0000-DFFFD / %xE1000-EFFFD
Note that ALPHA
,
DIGIT
, and SP
are defined in the [ABNF] specification (but essentially represent
alphanumerical characters and the U+0020 SPACE code point respectively).
This specification does not put a restriction on the byte length of a Zip relative path, so a user agent must be able to deal with path lengths longer than 250 bytes.
A CC must inform the author about any file
entry whose file name
field does not match the production of a Zip-rel-path
.
A CC must inform the author of any Zip relative path whose length exceeds 120 characters.
A user agent must ignore a file that contain forbidden characters in the Zip relative path.
Note: These characters are reserved to maintain interoperability across various file systems and with [URI]s.
A CC must inform the author of the presence of any of the forbidden characters in a file-name
.
A CC should inform the author of the presence of a U+0020 SPACE
character at the start or end of a file-name
.
A CC should inform the author of the presence of any U+002E FULL
STOP at the end of a file-name
.
A CC should inform the author of any base-name
that case-insensitively matches
any of the following strings: CON
, PRN
,
AUX
, NUL
, COM1
, COM2
,
COM3
, COM4
, COM5
,
COM6
, COM7
, COM8
,
COM9
, LPT1
, LPT2
,
LPT3
, LPT4
, LPT5
,
LPT6
, LPT7
, LPT8
,
LPT9
, CLOCKS$
.
A CC may inform the author of the presence of any U+002B PLUS
SIGN in a file-name
.
A widget package must be a valid Zip archive that contains:
content
element's
src
attribute.icon
element's src
attribute.Note: See step 1 - Acquire a Potential Zip Archive for instructions on how to process a widget package.
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
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 must be a file that:
true
.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, 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.
file name | reserved for purpose |
---|---|
config.xml | Configuration document |
icon.png | Default icon |
icon.gif | Default icon |
icon.jpg | Default icon |
icon.ico | Default icon |
icon.svg | Default icon |
index.html | Default start file |
index.htm | Default start file |
index.svg | Default start file |
index.xhtml | Default start file |
index.xht | Default start file |
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 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.
folder name | reserved for purpose |
---|---|
locales | Container for localized content |
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.
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.
A custom start file is a start file identified via a content
element's src
attribute. The custom
start file must be a processable file inside the widget package, determined by applying the rule for identifying the
media type of a file. When a start file is
not explicitly declared via the content
element, then start file will be one of the default start
files.
A default start file is a reserved start file whose file name case-sensitively and exactly matches a file name given in the file name column of the default start files table, and whose media type matches the media type given in the media type column of the table.
If no custom start file has been declared, a default start file must appear at either the root of the widget package or at the root of a locale folder.
If a user agent encounters a file matching a file
name given in the file name column of the default start files table in an arbitrary folder, the user
agent must treat that file as an arbitrary file. For example,
"foo/bar/index.html
" would be treated as an arbitrary file.
file name | media type |
---|---|
index.htm | text/html |
index.html | text/html |
index.svg | image/svg+xml |
index.xhtml | application/xhtml+xml |
index.xht | application/xhtml+xml |
It is optional for a user 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.
A CC must verify that the widget package contains at least one start file by:
content
element to point to a processable file within the widget package.If the widget package does not contain a start file, then the CC must inform the author.
An icon is an optional file that is used to represent the widget in various application contexts (e.g. the icon that the user actives to instantiate a widget, or an icon in a dock or task bar or some other visual context).
The icon is intended to help users of visual browsers to recognize the widget at a glance. There are two kinds of icons defined by this specification, custom icons and default icons.
A custom icon is an icon
explicitly declared by an author via an icon
element 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.
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.
A user agent must derive the media type of a default icon from the media type column of the default icons table.
A user agent must search for a default icon's
file-name
based on the order they
appear in the default icons table (from
top to bottom).
file name | media type |
---|---|
icon.svg | image/svg+xml |
icon.ico | image/vnd.microsoft.icon |
icon.png | image/png |
icon.gif | image/gif |
icon.jpg | image/jpeg |
Implementations that support the use of [SVG] as an icon format may display declarative animation. However, for security reasons, a user agent must not execute scripts or interactivity defined within an [SVG] icon file. Animation and interactivity is defined as the set of features intended for use of SVG as a dynamic image, corresponding to the [SVGTiny] profile, and to specific feature strings:
http://www.w3.org/TR/SVG11/feature#SVG-static
http://www.w3.org/Graphics/SVG/feature/1.2/#SVG-animated
If no default icon has been included, and the CC determines that no custom icons have been declared in the configuration document, a CC SHOULD inform the author that it is desirable 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.
The valid widget media type is
application/widget
[MIME].
ISSUE: The
application/widget
media type has not yet been registered
with IANA. This will happen when the
specification reaches Candidate Recommendation status.
A CC MUST inform the author if a widget package is not being served from a remote location with the valid widget media type.
A widget file extension is the
text string that case-insensitively matches the string
".wgt
" any case form (e.g. .wgt
,
.WGt
, .WgT
, etc. are all valid).
The widget file extension is required for widget packages on systems where it
is customary for file names to include a file-extension
that symbolizes (or is
associated with) a media type.
For when a widget package is not served
over HTTP, a CC must inform the author if the file-extension
is not a widget
extension or if the widget lacks a file-extension
.
A configuration document is an
[XML] document that has a widget
element at its root that is
in the widget namespace. A widget package
must have exactly one configuration document, which
must be located at the root of the widget package.
Note: Please see Step 7 for details of how the elements of the configuration document are processed by a user agent.
A valid configuration
document file name is the string config.xml
.
A user agent must treat a valid configuration document file name case-sensitively.
Within a widget package, a configuration document must have a valid configuration document file name.
A user agent must treat files in an arbitrary folder or locale folders that use
the file name config.xml
as an arbitrary file.
The following is an example of a configuration document:
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns = "http://www.w3.org/ns/widgets"
id = "http://example.org/exampleWidget"
version = "2.0 Beta"
height = "200"
width = "200"
viewmodes = "application fullscreen">
<name short="Example 2.0">
The example Widget!
</name>
<feature name="http://example.com/camera">
<param name="autofocus" value="true"/>
</feature>
<preference name = "apikey"
value = "ea31ad3a23fd2f"
readonly = "true" />
<description>
A sample widget to demonstrate some of the possibilities.
</description>
<author href = "http://foo-bar.example.org/"
email = "foo-bar@example.org">Foo Bar Corp</author>
<icon src="icons/example.png"/>
<icon src="icons/boo.png"/>
<content src="myWidget.html"/>
<license>
Example license (based on MIT License)
Copyright (c) 2008 The Foo Bar Corp.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</license>
</widget>
Note: Implementers are encouraged to expose relevant information provided by the configuration document to the user. Having "visual metadata" encourages authors to make full use of the configuration document format. See Step 6 for instructions on how to process a configuration document.
A CC must inform the author if there is no configuration document at the root of the widget package.
A CC must inform the author
the file-name
of the configuration document does not
case-sensitively match the string "config.xml
" (that is, by
checking for the configuration document's file-name
in other case forms.).
The widget namespace URI for a configuration document is
http://www.w3.org/ns/widgets
[XMLNS].
A CC must inform the author if the configuration document is lacking the widget namespace.
Implementers intending to extend the configuration document format with their own [XML] elements and attributes (or those defined in other specifications) must do so by using a separate [XMLNS] namespace. This specification does not define a model for processing [XML] elements outside the widget namespace.
Example of extending the configuration document format:
<widget xmlns="http://www.w3.org/ns/widgets"
xmlns:ex="http://example.org/">
<icon src="idle.png" ex:role="inactive"/>
<icon src="big.png" ex:role="big"/>
<ex:datasource>{a:"b",c:"d"}</ex:datasource>
<content src="widget.html"/>
</widget>
A CC must inform the author of the presence of any proprietary extensions to the configuration document outside the widget namespace.
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.
A boolean attribute is a keyword
attribute that can only be used with a valid boolean value. A valid boolean value is a string that
case-sensitively matches true
or false
. Unless
specified otherwise, the default behavior, which is used when the
attribute is omitted or has a value other than the two allowed values,
is false
. The way a user agent interprets a boolean
attribute is defined as part of an attribute's definition (see, for
example, the feature
element's required
attribute).
A user agent must retrieve the value of a boolean attribute using the rule for getting a single attribute value.
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.
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.
An attribute whose value is defined as containing a valid media type.
A valid media type is string that
matches the production for valid-MIME-type
in the following
[ABNF]:
valid-MIME-type = type "/" subtype *(";" parameter)
The type
, subtype
, and parameter
tokens are defined in the [MIME] specification. A
user agent must retrieve the value of this kind of
attribute using the rule for getting a
single attribute value.
The value of a numeric attribute is a string containing a valid non-negative integer. A valid non-negative integer is a string that consists of one or more code points in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). For example, the characters "002", "323", "23214", and so on.
A user agent must retrieve the value of a numeric attribute using the rule for getting a single attribute value.
An attribute defined as containing a valid path. A valid path is one that matches the production of a
Zip-rel-path
or a Zip-abs-path
. A valid path is not a URI:
a valid path represent a hierarchical path to a file inside a Zip archive, which must
exactly match the value of a file name field of a local file header of a file entry. This means that valid paths must not be URL encoded.
A Zip 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.
An attribute defined as containing a valid IRI. A valid IRI is one that matches the IRI
token of the [RFC3987] specification.
A user agent must retrieve the value for a IRI attribute using the rule for getting a single attribute value.
The value of a version attribute is an arbitrary string (possibly empty). This specification does not mandate any specific format, semantics, or special processing rule for the format of 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.
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
attributeA keyword attribute defined as
containing a language tag. The [XML] specification defines the xml:lang
attribute and its influence on the
contents and attribute values of child elements.
The value of 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.
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
). To use the its:dir
attribute, the its
namespace (see [ITS]) must be declared on the element where it is used or
somewhere in the element's ancestor chain.
It is optional for authors to use the its:dir
attribute with any element.
A user agent must retrieve the value for an
its:dir
attribute using the rule for getting a
single attribute value.
widget
ElementThe widget
element serves as a container for the other elements of the configuration document.
name
: zero or
more (one element is
allowed per language).description
: zero or more (one element is allowed per
language).author
:
zero or one.license
:
zero or more (one element
is allowed per language).icon
: zero or
more (elements are grouped by
language).content
:
zero or one.feature
:
zero or more.preference
: zero or more.widget
Elementid
A IRI attribute that denotes an identifier for the widget.
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.
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]. 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]. 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 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.
It is optional for authors to use the viewmodes
attribute with a widget
element.
xml:lang
It is optional for authors to use the xml:lang
attribute with a widget
element.
The following example shows how the widget element can be used.
<widget xmlns="http://www.w3.org/ns/widgets"
id="http://example.org/exampleWidget"
version="2.0 Beta"
height="200"
width="200"
viewmodes="floating application">
<description>
An example of the possibilities.
</description>
</widget>
name
ElementThe name
element
represents the full human-readable name for a widget
that can be used, for example, in an application menu or in other
contexts.
widget
element.xml:lang
:xml:lang
attribute must be unique for any subsequent element
of this type.name
Elementxml:lang
It is optional for authors to use the xml:lang
attribute with an name
element.
its:dir
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).
It is optional for authors to use the short
attribute with an
name
element.
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.
The following example shows the usage of the name
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
The Ultimate Weather Widget
</name>
<name short="Boletim" xml:lang="pt">
Boletim Metereológico
</name>
</widget>
description
ElementThe description
element represents a
human-readable description of the widget.
widget
element.xml:lang
:xml:lang
attribute must be unique for any subsequent element
of this type.description
Elementxml:lang
It is optional for authors to use the xml:lang
attribute with an description
element.
its:dir
It is optional for authors to use the its:dir
attribute with an description
element.
An example usage of the description element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name>Tornado Chaser</name>
<description>
Combining the latest weather info with your GPS position,
this widget alerts you of any significant storm activity in your
area. When a big one hits, the widget plots the best route on a map based
on the storm's trajectory so you can chase it! With support for
built-in cameras, you can quickly upload all the meteorological action to
your blog or to the insane storm chaser web site! Awesome!
</description>
</widget>
author
ElementAn author
element represents people or an organization attributed with the creation
of the widget.
widget
element.xml:lang
:xml:lang
(if any).author
Elementhref
An IRI attribute whose value represents a IRI that the author associates with himself or herself (e.g., a homepage, a profile on a social network, etc.).
It is optional for authors to use the xml:lang
attribute with an author
element.
email
A string that represents an email address associated with the author.
It is optional for authors to use the email
attribute
with an author
element.
its:dir
It is optional for authors to use the its:dir
attribute with an author
element.
The following example shows the expected usage of the author
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name>Cup-a-Joe's Cafe Finder Widget</name>
<author href = "http://dahut.example.org/about/joe"
email = "joe@example.org">
Joey and Princesa Bacalhau
</author>
</widget>
license
ElementThe 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.
widget
element.xml:lang
:xml:lang
attribute must be unique for any subsequent element
of this type.license
Elementhref
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 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
It is optional for authors to use the xml:lang
attribute with a license
element.
its:dir
It is optional for authors to use the its:dir
attribute with a license
element.
This example shows the expected usage of the license
element's href
attribute.
<widget xmlns="http://www.w3.org/ns/widgets">
<license href="http://creativecommons.org/licenses/by/3.0/">
Creative Commons Attribution License
</license>
</widget>
This example shows the expected usage of the license
element when the href
attribute is
omitted.
<widget xmlns="http://www.w3.org/ns/widgets">
<license>
Copyright (c) 2008 The Foo-Bar Corporation
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.
</license>
</widget>
icon
ElementThe 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.
widget
element.xml:lang
:xml:lang
value are allowed.icon
Elementsrc
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 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 height
attribute is only applicable to
graphic formats that have no intrinsic width or height (e.g., SVG).
If the file pointed to by the src
attribute of the icon
element is a supported raster graphic 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.
This example shows the expected usage of the icon
element. The example declares
three icon elements, two of which are raster and one of which is an [SVGTiny] file. The raster graphics would be used for
display contexts smaller than 256x256 pixels. Document order of
the elements is irrelevant.
<widget xmlns="http://www.w3.org/ns/widgets">
<icon src="icons/medium.png"/>
<icon src="icons/big.svg" width="256" height="256"/>
<icon src="icons/tiny.png"/>
</widget>
This example shows the expected usage of the icon
element with the xml:lang attribute. Note that unlocalized icon
elements will also
be used by the user agent.
<widget xmlns="http://www.w3.org/ns/widgets">
<icon src="icons/big_en.svg" xml:lang="en"/>
<icon src="icons/big_jp.svg" xml:lang="jp"/>
<icon src="icons/medium.png" xml:lang="en"/>
<icon src="icons/medium.png" xml:lang="jp" />
<icon src="icons/tiny.png"/>
<icon src="icons/ultra-tiny.png"/>
</widget>
content
ElementThe content
element is used by an author to declare which custom start file the user agent will use
when it
widget
element.xml:lang
:content
Elementsrc
A path attribute that allows an author to point to a file within the widget package.
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
.
It is optional for authors to use the type
attribute with a
content
element.
encoding
A keyword attribute that denotes the
character encoding of the file identified by the src
attribute. The allowed value is the "name"
or "alias" of any "Character Set" listed in [IANA-Charsets].
A user agent must support [UTF-8], which has the "UTF-8
" name in [IANA-Charsets]; it is optional for a user agent to support other character encodings.
When the value of 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.
This example shows the expected usage of the content
element:
<widget xmlns="http://www.w3.org/ns/widgets">
<content src="myWidget.html"/>
</widget>
This example shows the content
element being used with a
encoding
attribute to override the default value of the
encoding
attribute (UTF-8
)
with the GB2312 character set, which the author has used to encode
simplified Chinese characters:
<widget xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="zh-cn">古老瓷地图</name>
<name>Ancient Chinese Maps</name>
<content src="china-maps.html" encoding="GB2312"/>
</widget>
This example shows the content
element being used with a type
attribute to
instantiate a widget created with a proprietary media type:
<widget xmlns="http://www.w3.org/ns/widgets">
<name>Location-Based Games Finder</name>
<content src="lbg-maps.swf" type="application/x-shockwave-flash"/>
<feature name="http://example.org/api.geolocation"
required="false"/>
</widget>
feature
ElementA feature is a runtime component (e.g. an
Application Programming Interface or video decoder) that is not part of
the specified set provided by the Widgets 1.0 family of
specifications. The feature
element serves as a standardized means
to request the binding of an (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 may have zero or more parameters associated with it.
widget
element.param
elements.xml:lang
:feature
Elementname
A IRI attribute that identifies a feature that may be needed by the widget at runtime (such as an API).
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 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.
The default value that a user agent must use when
the required
attribute is absent is
true
, meaning that the feature must be
made available to the widget by the user agent at runtime.
It is optional for authors to use the required
attribute with an feature
element.
This example demonstrates a widget that would like to use a fictional geo-location API feature, but would still be able to function if the feature cannot be made available to the widget by the user agent.
<widget xmlns="http://www.w3.org/ns/widgets">
<feature name = "http://example.org/api/geolocation"
required = "false"/>
</widget>
param
ElementThe param
element defines a parameter for a feature. A parameter is
name-value pair that a user agent must associate with the corresponding feature for which the parameter is declared for. 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).
feature
element.xml:lang
:param
Elementname
A string, which may be empty, that denotes the name of this parameter.
When a param
element is declared, it is required for
authors to use the name
attribute.
value
A string, which may be empty, that denotes the value of this parameter.
When a param
element is used, it is required for authors
to use the value
attribute.
This example demonstrates a widget that makes use of a fictional
geo-location feature where by its accuracy is set to "low
"
via a param
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<feature name="http://example.org/api.geolocation">
<param name="accuracy" value="low"/>
</feature>
</widget>
preference
ElementThe 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.
A user agent that supports
the [Widgets-APIs] specification 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.
widget
element.xml:lang
:preference
Elementname
A string that denotes the name of this preference.
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
").
It is optional for authors to use the value
attribute
with a preference
element.
readonly
A boolean attribute indicating whether this preference can be overwritten at runtime.
The default value that a user agent must use when
the readonly
attribute is absent is
false
, meaning that the value can be overwritten at
runtime.
It is optional for authors to use the readonly
attribute with a preference
element.
This example shows a widget where two preferences are set. The second
preference
is set as "read only"
via the readonly
attribute, which means the values of that
preference cannot be changed at runtime.
<widget xmlns="http://www.w3.org/ns/widgets">
<preference name = "skin"
value = "alien"/>
<preference name = "api-key"
value = "f6d3a312f9d742"
readonly = "true"/>
</widget>
its:span
Although it is optional for a user agent to support [ITS],
it is recommended that authors use the
its:span
element to indicate the directionality of text
content when needed. Directionality is indicated by either using the
dir
attribute, with one of the following valid its:dir
values, as
defined in ITS:
ltr
rtl
lro
rlo
It is optional for authors to use any of the [ITS] attributes.
This example shows ITS being used to correctly set the directionality of text:
<widget
xmlns="http://www.w3.org/ns/widgets"
xmlns:its="http://www.w3.org/2005/11/its">
<name>Yay for the
"<its:span dir="rtl">متعة الأسماك!</its:span>" Widget</name>
<description its:dir="rtl">متعة الأسماك! </description>
</widget>
The its:span
element may be used as a
child element of the following elements of the configuration document. In addition,
the its:dir
attribute may be used in the following elements of the configuration document:
If the its:span
element is used, or the its:dir
attribute is used, the [ITS] namespace
http://www.w3.org/2005/11/its/
) must be
declared in the configuration
document.
Internationalization, or i18n, is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language. Localization refers to the adaptation of a product, application or document content to meet the language, cultural and other requirements of a specific target market (a "locale").
Note: See also the Web Services Internationalization Usage Scenarios and the Unicode Locale Data Markup Language for an informative discussion on the term locale.
A localized content is content an author has explicitly localized: that is, a widget package that contains content localized using folder-based localization or a configuration document that contains content localized via element-based localization.
Unlocalized content is content
included in the widget package or in the configuration document that has not
been explicitly localized. In the case of widget package, this means
content outside the container
for localized content. In the case of a configuration document, this
means any element without an explicitly declared or inherited xml:lang
attribute.
A localized file is any file that has been placed inside a locale folder (i.e., localized content that makes use of element-based localization). A widget package may contain zero or more localized files. All files and folders, except for the digital signatures and the configuration document, can be localized via folder-based localization.
For example, a locale folder "/locales/ja" (Japanese) might contain an HTML document translated into Japanese.
This specification provides two means that authors can use to explicitly localize the content of a widget:
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.
This specification defines the concept of folder-based localization, which is
the process whereby an author places files inside folders
that are named in a manner that conforms to a language tag as defined in the [BCP47] specification. That is, by naming folders using
values derived from the IANA
Language Subtag Registry such as "en-us
",
"en-gb
", and so on, but avoiding subtags marked as deprecated, grandfathered, or redundant in the IANA
Language Subtag Registry. These locale folders are then placed inside the container for localized
content.
The container for localized
content is a reserved folder at the root of the widget package whose
folder-name
case-sensitively
matches the string 'locales
'. A container for localized
content may contain zero or more locale folders.
A locale folder is a folder whose file name
field matches the production of locale-folder
and is a direct descendant
of the container for localized
content (e.g., "/locales/en-us
",
"/locales/fr
", etc). A locale
folder may contain zero or more arbitrary folders and/or files.
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.
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.
The following is an example of element-based localization:
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
The Ultimate Weather Widget
</name>
<name short="Boletim" xml:lang="pt">
Boletim Metereológico
</name>
</widget>
As part of their definition, the XML elements of the configuration document are marked as
being localizable via
xml:lang
with either the word "yes" or "no".
If an element is marked as being localizable via xml:lang
with the word "no", it means that the
element is not localizable via element-based localization. In
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.
For example, if the author uses the xml:lang
attribute on the widget
element, then all child
elements inherit the value xml:lang. This means that the first name
element below
behaves as xml:lang="en"
had been explicitly used. However,
in the second name
element, the declaration of xml:lang="pt"
overrides
xml:lang="en" inherited from the widget
element.
<widget xmlns="http://www.w3.org/ns/widgets"
xml:lang="en">
<name short="Weather">
Behaves as if xml:lang="en"
</name>
<name xml:lang="pt">
The declaration of xml:lang="pt" overrides
xml:lang="en" inherited from the widget element.
</name>
</widget>
If an element is marked as being localizable via xml:lang
with "yes", the specification always
indicates if one element is
allowed per language or whether elements are grouped by
language:
One element is allowed per language means that only one element of a
type is allowed to be used per language (e.g., although many name
elements can be
present in a configuration
document, only one name
element will be selected by the user agent
for the English language). During processing (Step
7), the user agent must 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.
</description>
<description xml:lang="en">
This element would be ignored.
</description>
<description>
This element is unlocalized, and would be used if the user agent's
locale does not match any localized description elements.
</description>
</widget>
However, if the user agent locales
only contained "*
", 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 must use the first
element that 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.
</description>
<description xml:lang="en">
This element would be ignored.
</description>
<description>
In this case, this unlocalized element would be used.
</description>
</widget>
Elements are grouped by language 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>
This section is non-normative.
This section presents three examples of how widgets can be localized, each example is intended to showcase how the localization algorithm is intended to work.
This example shows a widget that displays the
days of the week based on the language ranges held by the user agent locales. If the user
agent is unable to match a language range to any locale folder, the widget displays
/index.html
at the root of the widget package.
/config.xml
<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>
/locale/es/index.html
<!doctype html>
<title>¿Qué día es?</title>
<script src="/scripts/engine.js"></script>
<body>
<p>Hoy es: lunes, martes, miércoles,
jueves, viernes, sábado,
domingo
The following is an example of a localized widget with multiple localized icons, start files and configuration documents. Some relevant things to note from the example:
/locales/es/
) has its own localized
icon.locales/es
) and English
(locales/en/
) versions of the widget use the un-localized
script in /scripts/engine.js
folder.en-au
) version
uses a localized script (en-au/scripts/engine.js
)./config.xml
<widget xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="ko">웃기는 고양이</name>
<content src="cats.html"/>
</widget>
/locales/en-au/cats.html
<!doctype html>
<title>G'day! LOL Cats!</title>
<script src="scripts/engine.js">
...
/locales/es/cats.html
<!doctype html>
<title>Gatos Graciosos!</title>
<script src="/scripts/engine.js">
...
This specification allows authors to place files and folders they don't wish to localize at the root of the widget package. At runtime, if the user agent fails to find a file in a locale folder, it will always search at the root of the widget package for that missing file. The purpose of this 'fallback' model is to reduce the number of files that need to be created in order to localize a widget package.
The example below demonstrates how a user agent attempts to locate a file that is absent in a localized scenario:
So, for example, assume the user agent's locale is
'en-gb
'. The user agent would fail to locate 'mast.png' so
the next place it would look is in the 'en/
' folder, where
it would find the absent 'mast.png
' file.
Now consider the for various Chinese variants:
'zh-hans-cn
', 'zh-hans
', and 'zh
'
below. In this case, to find the 'flag.png
' file for
Mainland Chinese in simplified script 'zh-hans-cn
', the user
agent would first look in 'zh-hans-cn
', followed by
'zh-hans
', then in 'zh
' where the file is
located.
To find the 'mast.png
' file, the user agent would look in
'zh-hans-cn
', followed by 'zh-hans
', followed
'zh
', and finally at the root of the widget package where
the absent file is actually located.
/index.html
<!doctype html>
<title>Patriotic Boat</title>
<script src="/scripts/engine.js">
</script>
<body>
<img src="flag.png">
<img src="mast.png">
The steps for processing a widget package involves nine steps that a user agent may follow, in sequential order, responding accordingly if any of the steps result in an error or if the specification asks for the user agent to skip a step. The procedures for what to do when an error is encountered are described as part of each step; however, there are times when it will not be possible for the user agent to recover from an error and it will be forced to treat the widget as an invalid Zip archive (see rule for dealing with an invalid Zip archive).
The steps for processing a widget package and associated processing rules are written with more concern for clarity than efficiency. As such, a user agent may optimize any of the parsing rules and the steps, or may perform the steps in a different order, but the end result must be indistinguishable from the result that would be obtained by following the specification.
This section defines various processing rules, which are a set of common algorithms used in the by the steps for processing a widget package.
The rule for extracting file data from a file entry is described in this section.
Given a path that matches the file name field of a file entry within the Zip archive, a user agent must decompress (or otherwise extract) the file data of file entry into its original file representation. Implementers must follow the [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.
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.
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.
Let path be the valid path to the file entry being sought.
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.
If the number of items in path-components is greater than
two, then check if the second item in path-components exactly
matches the string "locales
". If it does:
If the third item in path-components contains any
characters other than a U+002D HYPHEN-MINUS ("-") or characters the
range %x61-71
, then return null
and
terminate this algorithm. (I.e., The third item in
path-component can only contain lower-case ASCII characters
or zero or more hyphens).
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.
For each lang-range in the user agent locales:
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).
If path points to a file entry within the widget package, then let file be the result of applying the rule for extracting file data from a file entry to path.
If file is a processable file, then return file and terminate this algorithm.
If the path points to a file entry that is not a processable file, then return an error and terminate this algorithm.
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:
If a matching file entry is found, let file be the result of applying the rule for extracting file data from a file entry to path.
If file is a processable file, then return file and terminate this algorithm.
If file is not a processable file, then return an error and terminate this algorithm.
Otherwise, return null
.
The rule for getting a single attribute value is given in the following algorithm. The algorithm always returns a string, which may be empty.
Let result be the value of the attribute.
In result, replace any sequences of space characters (in any order) with a single U+0020 SPACE character.
In result, remove any leading or trailing U+0020 SPACE character.
Return result.
The rule for getting a list of keywords from an attribute is given by the following algorithm. The algorithm takes a string as input, and returns a list which may be empty.
Let result be the value of the attribute.
In result, replace any sequences of space characters (in any order) with a single U+0020 SPACE character.
In result, remove any leading or trailing U+0020 SPACE character.
In result, split the string at each occurrence of a U+0020 character, removing that U+0020 character in the process.
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.
If the value of the CRC-32 field (defined in
the [ZIP] specification) fails a CRC-32 check, return
false
and terminate this algorithm.
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.
The file name field is an
empty string, return false
and terminate this algorithm.
The file name field
contains forbidden characters,
return false
and terminate this algorithm.
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.
The file name field is an
invalid Zip relative
path, return false
and terminate this algorithm.
true
.The rule for getting text
content is given in the following algorithm. The
element
to be processed must be
interpreted as a [DOM3Core] Element
.
The algorithm always returns a string, which may be
empty.
A text node refers to any Text
node, including CDATASection
nodes (any Node
with node type TEXT_NODE
or CDATA_SECTION_NODE
)
as defined in the [DOM3Core] specification.
Let input be the Element
to be processed.
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.
Return the value of the textContent
attribute of
input.
The rule for getting text content with normalized white space is given in the following algorithm. The algorithm always returns a string, which may be empty.
Let input be the Element
to be processed.
Let result be the result of applying the rule for getting text content to input.
In result, convert any sequence of one or more Unicode white space characters into a single U+0020 SPACE.
Return result.
For example, the user agent would ignore the
author
and
blink
elements, but their Text
nodes would be
extracted. The resulting widget
name would be "The Awesome Super Dude Widget" and
the resulting widget short name would be "D A H U T
":
<widget xmlns="http://www.w3.org/ns/widgets">
<name short= "
D A H U T
">
The <blink>Awesome</blink>
<author email="dude@example.com">Super <blink>Dude</blink></author>
Widget</name>
</widget>
The rule for parsing a non-negative integer are as given in the following algorithm. When invoked, the algorithm must be followed in the order given, aborting at the first step that returns a value. This algorithm will either return zero, a positive integer, or an error.
There may be implementation-specific limits on the range of integers allowed, and behavior outside such limits is undefined by this specification.
Let input be the string being parsed.
Let result have the value 0
.
If the length of input is 0
, return
an error.
Let position be a pointer into input, initially pointing at the start of the string.
Let nextchar be the character in input at position.
If the nextchar is one of the space characters, increment position. If position is past the end of input, return an error. Otherwise, go to 5 in this algorithm.
If the nextchar is not one of U+0030 (0
) ..
U+0039 (9
), then return result.
If the nextchar is one of U+0030 (0
) .. U+0039
(9
):
Multiply result by ten.
Add the value of the nextchar to result.
Increment position.
If position is not past the end of input, go to 7 in this algorithm.
Return result.
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).
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.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
.file extension | magic number | media type | comment about magic number |
---|---|---|---|
.gif | 47 49 46 38 37 61 |
image/gif | The string "GIF87a ", a GIF signature. |
.gif | 47 49 46 38 39 61 |
image/gif | The string "GIF89a ", a GIF signature. |
.png | 89 50 4E 47 0D 0A 1A 0A |
image/png | The PNG signature. |
.ico | 00 00 01 00 |
image/vnd.microsoft.icon | A Windows Icon file format signature. |
.svg | image/svg+xml | SVG documents cannot be identified using a magic number, as they
don't have one; SVG must only matched by the
.svg file extension and processed in
accordance to the [SVGTiny] specification. |
|
.jpg | FF D8 |
image/jpeg | A JPEG SOI marker followed by the first byte of another marker. |
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 (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).
Let file be the file to be processed.
If file has a file-extension
, attempt to match the
file-extension
to one in the
file extensions column in the file
identification table. If there is a match, then return the media type value.
If file extension is absent, the media type of a file must be determined by using the rules set forth in the [SNIFF] specification.
file extensions | media type |
---|---|
.html | text/html |
.htm | text/html |
.css | text/css |
.js | application/javascript |
.xml | application/xml |
.txt | text/plain |
.wav | audio/x-wav |
.xhtml | application/xhtml+xml |
.xht | application/xhtml+xml |
The rule for determining if a potential Zip archive is a Zip archive is given by the following algorithm.
50 4B 03 04
). See also the informative note
below.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 involves acquiring a potential Zip archive and confirming that it is a Zip archive by applying the rule for determining if a potential Zip archive is a Zip archive. A user agent will acquire a potential Zip archive from a data transfer protocol that either labels resources with a media type (e.g. [HTTP]) or from a data transfer protocol that does not label resources with a media type (e.g., BitTorrent or Bluetooth):
When attempting to acquire a potential
Zip archive over some protocol that labels resources with a media type, a user agent must
only attempt to process resources labeled with the valid widget media type
(application/widget
), regardless of whether the resource
contains a file extension or not, by applying the rule for determining if
a potential Zip archive is a Zip archive. Unless the user agent supports legacy or proprietary media types, all other media types are in error and
the user agent must treat the potential Zip archive as an invalid Zip archive.
If the result of the user agent applying the rule for determining if
a potential Zip archive is a Zip archive is true
,
meaning that the potential
Zip archive is a Zip archive, then the user agent must proceed to Step 2. Otherwise,
if an error is returned, the user agent must treat
the potential Zip archive as an invalid Zip archive.
For example, in [HTTP], where the
Content-Type
header matches application/widget
.
If the protocol used for acquisition of a potential Zip archive does not provide, or otherwise include, a media type, then a user agent may treat the acquired potential Zip archive as if it has been acquired from a protocol that does not label resources with a media type (see sub-section below).
In this example, the media type of the
Content-Type
is not one supported
by the user agent, so the user agent would treat the potential Zip archive as an invalid Zip archive:
GET /foo.wgt HTTP/1.1
Host: www.example.com
Accept: application/widget
HTTP/1.1 200 OK
Date: Tue, 04 Sep 2007 00:00:38 GMT
Last-Modified: Mon, 03 Sep 2007 06:47:19 GMT
Content-Length: 1337
Content-Type: application/x-gadget
When acquiring a potential Zip archive that has not been labeled with a
media type (e.g., from a file system), a user agent must attempt to process the resource regardless of the
file extension (including situations when the file extension is absent)
by applying the rule
for determining if a potential Zip archive is a Zip archive. If the
rule for determining
if a potential Zip archive is a Zip archive return true
,
proceed to Step 2. Otherwise, if an error was
returned, the user agent must treat the potential Zip archive as an invalid Zip archive.
To verify that a Zip archive and its file entries conform to this specification, a user agent must perform the following checks. This specification does not provide the technical details of how to actually perform the checks, for which implementers must follow the [ZIP] specification.
The potential widget package can be considered verified only once the checks below have been completed.
If any of the following conditions are met, then a user agent must treat the Zip archive as an invalid Zip archive:
The Zip archive is split into multiple files or spans multiple volumes, as defined in the [ZIP] specification.
The Zip archive is encrypted (which is denoted by bit 0 of the general purpose field being set and by the presence of archive decryption header and an archive extra data record, all three of which are defined in the [ZIP] specification).
The Zip archive contains zero file entries (i.e., the archive is empty).
The Zip archive contains only folders.
A CC must verify each file
entry by applying the rule for verifying a file
entry. If the result of applying the rule for verifying a file
entry is false
, a CC must inform the author.
In 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 table, an implementation must treat the
value as null
(i.e., not as empty string and not as the text
string "null"
).
Variable | Type | Default Value | Overridden by | Description |
---|---|---|---|---|
author email | String | null |
Step 7 | The value of the author element's email attribute (if any). |
author href | IRI | null |
Step 7 | The value of the author element's href attribute (if any). |
author name | String | null |
Step 7 | The text content of the author element (if any). |
feature list | List | null |
Step 7 | A list of features that correspond to features that were requested
via feature
elements (if any). Each item in the list corresponds to a feature element's
name attribute,
whether it is required, and any associated parameters (if any). |
icons | List of file entries | null |
Step 7, Step 9 | The icons of the widget as they correspond to the default icons and to the occurrence of custom icons that are supported by the widget package (if any). |
start file encoding | String | UTF-8 |
Step 7 | The character encoding of the custom
start file, corresponding to either the content element's encoding
attribute (if any), or the default
encoding. |
start file content-type | String | text/html |
Step 7 | The media type of the start file, corresponding to the content element's
type attribute
or to a media type derived from the default start files table. |
widget config doc | File | null |
Step 6 | The file that is the configuration document for the widget package. |
widget description | String | null |
Step 7 | The text content of the description element in the configuration document. |
widget height | positive number | null |
Step 7 | The value of the widget element's height attribute in the configuration document (if any). |
widget id | String | null |
Step 7 | The value of the widget element's id attribute
in the configuration document
(if any). |
widget license | String | null |
Step 7 | The text content of the license element in the configuration document (if any). |
widget license file | File | null |
Step 7 | A file derived if the value of the license element's
href is a Zip relative path to a file within the widget package. |
widget license href | IRI | null | Step 7 | The value of the license element's href attribute in the configuration document (if any). |
widget name | String | null |
Step 7 | The text content of the name element in the configuration document (if any). |
widget preferences | List | null | Step 7 | The widget's preferences, corresponding to the preference
elements in the configuration
document (if any). Unless an end-user explicitly requests that
these values be reverted to the values as declared in the configuration
document, a user agent must not reset the value of
the widget preferences
variable on subsequent initialization of the widget. |
widget short name | String | null |
Step 7 | The value of the name element's short attribute in the configuration document(if any). |
Variable | Type | Default Value | Overridden by | Description |
widget version | String | null |
Step 7 | The value of the widget element's version attribute in the configuration document (if any). |
widget width | positive number | null |
Step 7 | The value of the widget element's width attribute in the configuration document (if any). |
widget window modes | List of strings | floating |
Step 7 | The value of the widget element's viewmodes
attribute in the configuration
document (if any). |
widget start file | File entry | null |
Step 7, Step 8 | The start file for the widget package, corresponding to either one
of the default start files
table or the file identified by the content element's
src attribute. |
user agent locales |
List of strings |
null |
Step 5 | A list of language tags. |
This step only applies to a user agent that supports the [Widgets-DigSig] specification. If the user agent does not support [Widgets-DigSig], go to Step 5.
The algorithm to locate digital signatures is defined in the [Widgets-DigSig] specification, under the section named Locating and Processing Digital Signatures.
The end-user's language ranges represents the end-user's preferred languages and regional settings, which are derived from the operating system or directly from the user agent. As there are numerous ways a user agent can derive the end-user's preferred languages and regional settings, the means by which those values are derived are beyond the scope of this specification and left up to the implementation.
For example, the end-user may have specified her preferred languages and regional settings at install time by selecting a preferred language, or languages from a list, or a list of preferred languages and regional settings could have been dynamically derived from the end-user's geographical location, etc.
The algorithm to derive the user agent locales is as follows:
Let unprocessed locales list be a comma-separated list
that contains the end-user's language ranges.
Each item in the unprocessed locales must be a string in lowercase form, that conforms to
the production of a Language-Tag
, as defined in the [BCP47] specification. A string that conforms to the
production of a Language-Tag
is referred to as a language range [BCP47] (e.g. 'en-au
', which is the
range of English as spoken in Australia, and 'fr-ca
',
which is the range of French as spoken in Canada, etc.). A language
range is composed of one or more subtags that
are delimited by a U+002D HYPHEN-MINUS ("-
").
The first item of the unprocessed locales must represent the user's most preferred language range (i.e., the language/region combination the user agent assumes the end-user most wants to see content in), followed by the next most preferred language range, and so forth.
For example, in an unprocessed locales
list that contains 'en-us,en,fr,es
', English as
spoken in the United States is preferred over English, and English is
preferred over French, and French is preferred over Spanish, and
Spanish is preferred over unlocalized
content.
For each range in the unprocessed locales list:
If this range begins with the subtag '*
' (e.g. "*-us
"
or just "*
"), or contains any space characters, skip all the steps in
this algorithm below, and move onto the next range.
If this range contains any subtag '*
', remove the
'*
' and its preceding hyphen (U+002F
)
(e.g., 'en-*-us
' becomes 'en-us
').
While range contains subtags:
Add the value of the range to the user agent locales.
Remove the right most subtag from range and append the resulting value to user agent locales. Continue removing the right most subtag and adding the result to user agent locales until there are no subtags left in range.
For example, if the range was
"zh-hans-cn", then the user
agent locales become
"zh-hans-cn,zh-hans,zh
".
Move onto the next range and go to step 1 in this algorithm.
Append the value "*
" to the end of user agent locales.
For example, an unprocessed locales list
that contains "en-us,en-au,en,fr-ca,zh-hans-cn
" would result
in a user agent locales that
contains
"en-us,en,en-au,en,en,fr-ca,fr,zh-hans-cn,zh-hans,zh,*
".
For example, an unprocessed locales list
that contains "en-us,en,fr-ca,en,en-ca
"would result in a
user agent locales that
contains "en-us,en,en,fr-ca,fr,en,en-ca,en,*
".
This step involves searching within the Zip archive for a configuration document.
The algorithm to locate the configuration document is as follows:
config.xml
).null
), then a user agent must treat the
Zip archive as an invalid Zip archive.The purpose of processing the configuration document is to override 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 processing algorithm and describes how localized elements are processed.
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 that a user agent must act as if the element, attribute, or file that is in error is not 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).
A CC should process a configuration document using the algorithm to process a 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.
The algorithm to process a configuration document is as follows:
Let doc be the result of loading the widget config doc as a [DOM3Core] Document
using a [XMLNS]-aware parser.
If the document is not namespace well-formed [XML], terminate this algorithm and treat this widget package as an invalid Zip archive.
Let root element be the documentElement
of
doc.
If the root element is not a widget
element in the widget namespace, then treat this widget
package as an invalid Zip archive.
Otherwise, the element is a widget
element:
If the id
attribute is used, let id be the
result of applying the rule for getting a
single attribute value to the id
attribute. If
id is a valid IRI, then let
widget id be the value of the
id.
If the version
attribute is used, then let widget version be the result of
applying the rule
for getting a single attribute value to the version
attribute.
If the height
attribute is used, then let
normalized height be the result of applying the rule for parsing a
non-negative integer to the value of the attribute. If the
normalized height is not in error
and greater than 0
, let widget height be the value of
normalized height. If the attribute is in error and the user agent must ignore it.
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
, let widget width be the value of
normalized width. If the attribute is in error and the user agent must ignore it.
If the viewmodes
attribute is used, let viewmodes
list be the result of applying the rule for getting a
list of keywords from an attribute. From the viewmode
list, remove any unsupported items,
and any items that are not one of the valid view modes, and any duplicated
items. Let widget window
modes be the value of viewmodes list.
If any other attribute declared in the widget
element, in any XML
namespace, apart from xml:lang
, is
used, then ignore that attribute.
If the widget
element does not contain any child
elements, then terminate this algorithm and go to Step 8.
Let element list be an empty list.
For each range in the user agent locales, starting from the first and moving to the last:
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.
Append matching elements to the element list.
For each range in the user agent locales, starting from the first and moving to the last:
Let matching elements be the result of applying lookup to the child elements of type icon
that are direct
descendents of the root element and whose xml:lang
attribute matches the current
range. Document order
must be retained in the resulting matching
elements list.
If matching elements is not empty, append matching elements to element list and continue to step 8 in this algorithm.
If matching elements is empty, continue to the next range.
Let unlocalized elements be all child elements that are direct descendents of the root element that do not have a declared xml:lang attribute (i.e., match unlocalized content). Document order must be retained in the resulting list.
Append unlocalized elements to the element list.
For each element in the elements list, if the element is one of the following:
name
element:If this is not the first name
element encountered, then the user agent
must ignore the element and
its child nodes. Stop processing this element and proceed
to the next element in the elements list.
If this is the first name
element encountered,
Let widget name be the result of applying the rule for getting text content with normalized white space to this element.
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.
description
element:If this is not the first description
element encountered, then
the user agent must ignore
the element and its child nodes. Stop processing this
element and proceed to the next element in the
elements list.
If this is the first description
element encountered, let
widget description be the
result of applying the rule
for getting text content to this element.
license
element:If this is not the first license
element encountered, then the user
agent must ignore this
element, its attributes, and any child nodes. Stop processing this
element and proceed to the next element in the
elements list.
Let license text be the result of applying the rule for getting text content to this element. Associate license text with widget license.
If the href
attribute is used, then let potential license href be the
result of applying the rule for getting a
single attribute value to the href
attribute.
If potential license href is not a valid IRI or a valid
path, then the href
attribute is in
error and the user agent must ignore it.
If potential license href is a valid IRI, then 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 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 Stop processing this element and proceed to the next element in the elements list. Otherwise, let widget license file be the value of file.
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 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,
If the height
attribute is used, let
potential height
be the result of applying
the rule for
parsing a non-negative integer to the attribute's value. If the
potential height
is not in error and greater than 0
, then
associate the potential
height
with file. Otherwise,
the attribute is in error and the user agent
must ignore it.
If the width
attribute is used,
let potential width be the result of applying the rule for parsing a
non-negative integer to the attribute's value. If the
potential width is not in error
and greater than 0
, then associate the potential width with
file. Otherwise, the attribute is in error and the user agent must ignore it.
Add file and any associated potential width and/or potential height to the list of icons.
author
element:If this is not the first author
element encountered, then the user
agent must ignore this
element and any child nodes. Stop processing this element
and proceed to the next element in the elements
list.
If this is the first author
element used, then:
If the href
attribute is used, let
href-value be the value of applying the rule for getting a
single attribute value to the href
attribute.
If href-value is a valid IRI,
then let author href be the
value of the href
attribute. Otherwise, the user agent
must ignore the attribute.
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.
Let author name be the result of applying the rule for getting text content with normalized white space to this element.
preference
element:If a value
attribute is used, but the name
attribute is
absent, then this element is in error and the
user agent must ignore it.
Otherwise,
Let preference be an empty object.
Let name be the result of applying the rule for getting a
single attribute value to the name
attribute.
If the name is an empty string, then this element is in error and the user agent must ignore it. Stop processing this element and proceed to the next element in the elements list. Otherwise, associate name with preference.
Let value be the value of the value
attribute. Associate the value with preference.
If a readonly
attribute is used, 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, let the value of readonly be the value
'false
'. Associate
readonly with the preference.
Add the preference and the associated name, value and readonly variables the list of widget preferences.
content
element:If this is not the first content
element encountered, then the user
agent must ignore this
element and its child nodes. Stop processing this element
and proceed to the next element in the elements
list.
If this is the first content
element,
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.
Let path be the result of applying the rule for getting a
single attribute value to the value of the src
attribute.
If path is a valid path, let file be the result of applying the rule for finding a file within a widget package to path. If path is not a valid path, then a user agent must treat the widget package as an invalid Zip archive.
If the type
attribute of the content
element is absent, then check if
file is supported by
the user agent by applying the rule for
identifying the media type of a file. If the file is supported, let the
widget start file be the
file referenced by the src
attribute and let start file content-type be
the supported
media type as was derived by applying the rule for
identifying the media type of a file.
If the type
attribute is used, let content-type be the result of
applying the rule for getting a
single attribute value to the value of the type
attribute. If the value of
content-type
is supported by
the user agent, then let the start file content-type be
the value of content type. If value
of content-type is invalid or unsupported by the user agent, then a user
agent must treat the widget package as an invalid Zip archive.
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 the encoding
attribute. If
content-encoding is unsupported by the user agent, then a user
agent should use the default encoding (UTF-8
).
feature
element:If a required
attribute of this feature
element
is used, but no name
attribute is used, then this element,
its attributes, and its children are in error
and must be ignored by the user agent. Stop processing this
element and proceed to the next element in the
elements list.
Let feature-name be the result of applying the rule for getting a
single attribute value to the value of the name
attribute.
If a required
attribute is used, let
required-feature be the result of applying the rule for getting a
single attribute value to the required
attribute. If
required-feature is not a valid boolean value, let the value
of required-feature be the value 'true
'.
If feature-name is not a valid
IRI, and required-feature is true
, then
treat this widget as an invalid Zip
archive.
If feature-name is not supported by the user agent, and
required-feature is true
, then treat this
widget as an invalid Zip
archive.
If feature-name is not supported by the user agent, and
required-feature is false
, then this
element, its attributes, and its children are in
error and must be ignored by the user agent. Stop processing this
element and proceed to the next element in the
elements list.
Associate the value of required-feature with feature-name.
If the feature
element contains param
elements as
direct descendants, then, for each child param
element that is a direct
descendent of this feature
element, starting from the first
moving to the last in document
order:
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).
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).
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).
If, and only if, param-name is not in error or an empty string, let
param-value be the result of applying the rule for getting
a single attribute value to the value
attribute. If the param-value is an
empty string, then this param
element is in
error and the user agent must ignore it.
Associate param-name and param-value with feature-name.
Append feature-name, and any associated required-feature, and associated parameters, to the feature list.
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.This step only applies if a custom start
file was not specified in the configuration document (i.e., if
widget start file of the table of configuration
defaults is null
), in which case the user agent must attempt to find a default start file. If widget start file contains a file, then skip Step 8 and go to Step
9.
When attempting to locate a default start
file, a user agent must attempt to locate a file entry whose file-name
matches one of the default start
files based on the order they appear in the default start files table (from top
to bottom). File names in the default
start files table must be treated by the user
agent case-sensitively.
null
or in error, ignore this
file name and move onto the next file name in the
default start files table.This step describes how to locate the default icons.
For each file name in the default icons table (from top to bottom) that has a media type that is supported by the user agent:
true
, then add the
value of potential-icon to the icons list of the table of configuration
defaults:
This section is non-normative.
This section only applies to HTML user agents [HTML5][HTML4] [XHTML1.1].
Auto-discovery enables a user agent to identify and install a widget package that is associated with an HTML page. When a page points to a widget package, user agents should expose the presence of the widget package to the end-user and allow the end-user to install the widget.
The link type "widget
" indicates that a link of
this type references a document that is a widget
package. In HTML, it may be specified for the a
,
area
and link
elements to
create a hyperlink.
For example:
<a rel="widget"
href="http://example.org/exampleWidget">
The Example Widget
</a>
This section is non-normative.
The following is the Relax NG for the configuration document, which is a [RelaxNG] schema representation of the elements, and their attributes, of the configuration document. A conformance checker may use this schema to validate elements of a configuration document within the limits of the [RelaxNG] specification.
# Widgets 1.0 (Working Draft) RELAX NG schema
default namespace widgets = "http://www.w3.org/ns/widgets"
namespace its = "http://www.w3.org/2005/11/its/"
namespace local = ""
extension = ( attr.allowed | anyElement )*
anyElement = ( element * - widgets:* { any } | text )*
any = ( attribute * { text } | anyElement )*
attr.allowed = attribute * - (local:* | xml:lang | its:dir) { text }
attr.xmllang = attribute xml:lang { xsd:language }
attr.itsdir = attribute its:dir { "ltr" | "rtl" | "lro" | "rlo" }
data.positiveNumber = xsd:string { pattern="[1-9]\d*" }
data.boolean = ( string "true" | string "false" )
start = elem.widget
elem.widget = element widget {
attr.xmllang?,
attribute id { xsd:anyURI }?,
attribute version { text }?,
attribute height { data.positiveNumber }?,
attribute width { data.positiveNumber }?,
attribute viewmodes {
list {
( "application"
| "floating"
| "fullscreen"
| "mini"
| "all" )*
}
}?,
( elem.name*
& elem.description*
& elem.icon*
& elem.author?
& elem.license*
& elem.content?
& elem.feature*
& elem.preference*
& extension )
}
elem.name = element name {
attr.xmllang?,
attr.itsdir?,
attribute short { text }?,
extension
}
elem.description = element description {
attr.xmllang?,
attr.itsdir?,
extension
}
elem.icon = element icon {
attr.allowed*,
attribute src { xsd:anyURI },
attribute height { data.positiveNumber }?,
attribute width { data.positiveNumber }?,
empty
}
elem.author = element author {
attr.xmllang?,
attr.itsdir?,
attribute href { xsd:anyURI }?,
attribute email { xsd:string { pattern=".+@.+" } }?,
extension
}
elem.license = element license {
attr.xmllang?,
attr.itsdir?,
attribute href { xsd:anyURI }?,
extension
}
elem.content = element content {
attr.allowed*,
attribute src { xsd:anyURI },
attribute type { text }?,
attribute encoding { text }?,
empty
}
elem.feature = element feature {
attribute name { xsd:anyURI },
attribute required { data.boolean }?,
( elem.param?
& extension )
}
elem.param = element param {
attribute name { text },
attribute value { text },
extension
}
elem.preference = element preference {
attr.xmllang?,
attribute name { text },
attribute value { text }?,
attribute readonly { data.boolean }?,
extension
}
Special thanks go to Arve Bersvendsen, Anne van Kesteren, Robin Berjon, and Charles McCathieNevile who helped edit various versions of this specification.
Special thanks also to David Håsäther for creating and maintaining the RelaxNG Schema for the configuration document format.
A huge thanks to Sam "gsnedders" Sneddon, whose Anolis specification-generator was used to generate this document.
Parts of this document reproduce text and behavior from the [HTML5] specification and from the XBL 2.0 specification (as permitted by both specifications by their copyright statements).
Graphic icons used some examples of this specification were created by Yusuke Kamiyamane and are available for use under a Creative Commons Attribution 3.0 license.
The editors would also like to thank the following people for their contributions to this specification:
Addison Phillips, Alexander Dreiling, Arun Ranganathan, Arthur Barstow, Bárbara Barbosa Neves, Brian Wilson, Bjoern Hoehrmann, Benoit Suzanne, Bert Bos, Boris Zbarsky, Bradford Lassey, Cameron McCormack, Cliff Schmidt, Claudio Venezia, Coach Wei, Corin Edwards, Dan Brickley, David Clarke, Dean Jackson, David Pollington, Doug Schepers, Ed Voas, Felix Sasaki, Francois Daoust, Gautam Chandna, Geir Pedersen, Gene Vayngrib, Gorm Haug Eriksen, Guido Grassel, Hari Kumar G, Ian Hickson, Jay Sweeney, Jere Käpyaho, Jim Ley, Jon Ferraiolo, Jose Manuel Cantera Fonseca, Josh Soref, Jouni Hakala, Joey Bacalhau, Kevin Lawver, Kai Hendry, Krzysztof Maczyński, Lachlan Hunt, Marc Silbey, Marcin Hanclik, Mark Baker, Mikko Pohja, Mohamed Zergaoui, Olli Immonen, Philipp Heltewig, Philip Taylor, Scott Wilson, Stephen Paul Weber,