Copyright © 2009 W3C ® ( MIT , ERCIM , Keio ), All Rights Reserved. W3C liability , trademark and document use rules apply.
This document specification standardizes a packaging format for
a class of software application known as a
widget. widgets. Widgets are
client-side applications that are authored using Web standards, but
whose content can also be embedded into Web documents. The
specification relies on PKWare's Zip specification as the archive
format, XML as a configuration document format, and a series of
steps that runtimes follow when processing and verifying various
aspects of a package. The packaging format acts as a container for
files used by a widget. The configuration document is an XML
vocabulary that declares metadata and configuration parameters for
a widget. The steps for processing a widget package describe the
expected behavior and means of error handling for runtimes while
processing the packaging format, configuration document, and other
relevant files. This document also defines expected behavior for
conformance checkers, which are tools that aid authors in verifying
that Zip archives and configuration documents conform to this
specification.
This specification is part of the Widgets 1.0 family of specifications , which together standardize widgets as a whole.
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 28 May 23 July 2009 Last Call
Working Draft version Candidate
Recommendation of the "Widgets
Widgets 1.0: Packaging and Configuration" Configuration specification. The Last Call period ends on 19 June 2009. This version
reflects over of two years work addressing requirements 1
W3C publishes a Candidate
Recommendation to 25 of
indicate that the Widgets 1.0: Requirements document [Widgets-Reqs] . The requirements were addressed and
specified through extensive research, and via consultation with W3C
members is believed to be stable
and to encourage implementation by the
public via developer community. The Web Applications (WebApps)
Working Group expects to request that the Director advance this
document to Proposed Recommendation once the Working
Group's mailing lists ( WAF archive
Group has developed a comprehensive Widgets
1.0: Packaging and Configuration test suite , WebApps
archive and demonstrated at least two
interoperable implementations (interoperable meaning at least two
implementations that pass each test in the test suite ). The purpose of this Last Call is WebApps Working Group expects to give external interested parties a final
opportunity show these implementations
by October 2009. The Working Group does not plan to
publicly comment request to advance to Proposed Recommendation prior to
01 November 2009.
Feedback based on how widgets should be packaged any aspect of this specification is welcome and
configured before encouraged. However, there are certain features in the
specification that the Working Group makes a call for implementations. The Working Group's
goal is particularly interested in
getting feedback on: these are marked as "feature at risk" within
the specification. Whether such features are retained or dropped by
the Working Group when the document progresses to make sure that vendor's requirements for packaging and
configuration have been effectively addressed Proposed Recommendation will depend on the feedback
received from implementers, other working groups, and
clearly specified. the public.
This document is produced by the Web Applications WG , part of
the Rich Web
Clients Client Activity in the W3C Interaction Domain . It is
expected that this document will progress along the W3C's
Recommendation track.
Publication as a Working Draft
Candidate Recommendation does not imply
endorsement by the W3C Membership. This is a draft document and may
be updated, replaced or obsoleted by other documents at any time.
It is inappropriate to cite this document as other than work in
progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy .W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
You can find the latest Editor's Draft of this
document in the W3C's CVS repository
, which is updated on a very regular
basis. . The public is encouraged to send
comments to the Web Apps Working Group's public mailing list
public-Webapps@w3.org (
archive
). See W3C mailing list and
archive usage guidelines . A detailed list of changes
from the previous version is also available from the W3C's CVS
server.
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 following
requirements: 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 , MUST NOT must not
, Required
required , SHOULD should , SHOULD NOT should
not , RECOMMENDED recommended , MAY may and
OPTIONAL optional .
Variables are formatted specially, e.g. variable .
Code is also specially formatted, such as code
.
Words in italics denote a formal definition given in an external specification.
This is an example. Examples are used to explain concepts or demonstrate how to use a feature. Examples are non-normative.
ISSUE: This is an issue. It implies something that Working Group is trying to fix. Eventually, all these will disappear from the spec. Issues are non-normative.
Note: This is a note, it usually contains useful supplementary information in a non-normative form.
This section is non-normative.
This specification is part of the Widgets 1.0 family of
specifications , which together standardize widgets as a
whole. whole:
The Widgets 1.0: APIs and Events [Widgets-APIs] specification defines APIs API s to store
preferences and capture events.
events (see [Widgets-APIs]
).
The Widgets 1.0: Digital Signature [Widgets-DigSig] specification defines a means for
widgets to be digitally signed using a custom profile of the
XML-Signature Syntax and Processing Specification. Specification (see [Widgets-DigSig] ).
The Widgets: 1.0: Automatic
Updates [Widgets-Updates]
specification defines a version control model that allows widgets
to be kept up-to-date over [HTTP] . (see [Widgets-Updates] ).
The Widgets 1.0: Access Requests [Widgets-Access] specification allows authors defines a
means to request access to URI-identifiable resources (e.g.
resources on the Web). 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 matches must match the production of a
Language-Tag
defined in the [BCP47] specifications. It is optional for a user
agents agent to validate language tags against the
IANA
Language Subtag Registry .
A widget is defined by the [Widgets-Landscape] as an end-user's
conceptualization of an interactive single purpose application for
displaying and/or updating local data or data on the Web, packaged
in a way to allow a single download and installation on a user's
machine, mobile phone, or Internet-enabled device
. Because
widgets are packaged, they can be shared by users without relying
on [HTTP] (i.e., users can share widgets over
non-HTTP distribution channels, such as BlueTooth, Bluetooth
or a USB thumb drive, etc.).
drive).
Reserved means that a character, or
text string, or file-name
,
or folder-name
has a
specified purpose and semantics in this specification or in some
other specification or system. The intended purpose for any
reservation is given when the term is used.
Arbitrary means that a character, or
text string, or file-name
,
or folder-name
is not
reserved for the purpose of this
specification.
Supported means that a user agent implements a mentioned specification, or conformance clause, or is able to process or otherwise render mentioned media type .
Unsupported means the user agent does not implement a mentioned specification, or feature ,or is unable to render or otherwise process a mentioned media type .
Initialization means a run through the steps for processing a widget package after installation of a widget.
The space characters , for the purposes of this specification, are [Unicode] code points:
The Unicode white space characters are [Unicode] code points marked in the [Unicode] specification (version 5.0.0) with the property "White_Space". Those code points include:
The control characters , for
the purpose of this specification, are [Unicode] code points in the
range points:
The key words must , must not , Required ,
should , should not , recommended , may and optional in this
specification following Unicode code
points are referred to
be interpreted as described in [RFC2119] . This specification
describes the conformance criteria for
user agents (relevant to implementers) and various resource types
(relevant to authors). There are four classes of products that can
claim conformance to forbidden
characters in this
specification:
A user agent is an implementation that supports this specification.
Note: The user agent
described in this specification does not necessarily denote a "
widget user agent " at large:
that is, a user agent that implements all the specifications, and
dependencies, defined in the Widgets 1.0: Family of Specifications.
The user agent described is this specification is only concerned
with how to processes zip Zip archives and configuration documents .
A user agent must behave as described by
this specification in order to claim conformance, even when faced
with a non-conforming widget package
or a non-conforming configuration documents document
.
Note: Implementers
can partially check their level of conformance to this
specification by successfully passing the test cases of the
[Widgets-Test-Suite] . [P&C-Test-Suite] Note, however, that
passing all the tests in the test suite does not imply conformance
to this specification; It only implies that the implementation
conforms to aspects tested by the test suite.
ISSUE:
test-suite is not done yet, it will be completed when we go to Candidate
Recommendation.
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 may support the Internationalized Internationalization Tag Set's ( [ITS] ) its:span
element and the
its:dir
attribute. It is
optional for a user agent to support other ITS elements and
attributes.
Although this specification defines the elements of the configuration document in which
element and the <its:span> its:spanits: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
and <its:span> its:spanits: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 if whether a widget package and a configuration document conform to
this specification. A CC checks the conformance of
either a widget package or a configuration document by
implementing the assertions made in sections labeled
conformance checker behavior
Conformance Checker Behavior
throughout this document.
In those sections, this specification asks CCs to inform authors of conformance violations, which
means they display advisory messages to authors in a manner that
assists them in making their widgets
valid and conforming. Wording of advisory messages is left to the
discretion of implementers. CCs are
It is not required optional for a
CC
to display all messages at once.
The packaging
format for the files of a widget are packaged using is
the Zip archive format as defined in
the [ZIP] file format specification(in other words, the [ZIP] file format is
the packaging format for widgets). specification.
A file entry is the data held by a local file header , file data , and (optional) data descriptor , as defined in the [ZIP] specification, for each physical file contained in a Zip archive .
A potential Zip archive is a data object claiming to be a Zip archive, that has not been verified to be a valid Zip archive .
A valid Zip archive is a data
object that conforms must conform to the production of a .Zip .Zip
file as defined by the Zip File Format
Specification [ZIP] , with the exclusion
or support for the
features and conditions defined in the Zip
Support section. section of this specification.
Note: Step 2 of the steps for processing a
widget package describes how a user
agents verify agent verifies that a Zip archive conforms to this
specification.
The magic numbers for
a Zip archive is the byte sequence: 50 4B 03 04
.
To conform to this specification, a Zip
archive must contain one or more file entries and must not be an invalid a valid Zip
archive .
Note: A valid
zip Zip
archive does not imply a conforming widget package . All valid zip Zip archives need
to be further checked, using Step 2 , to see
if they qualify as a widget package.
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 conformance checker CC must verify that
each file entry uses one of the valid compression methods . If a
CC encounters a file entry that uses a
compression method that is not one of the Stored valid
compression method, methods , then the CC must
inform the author that to recompressed
the file entry should be recompressed using the [Deflate] compression algorithm, as that is the
recommended compression method. If a CC encounters a compression
method that is not one of the valid compression methods ,then the CC must inform the author that the zip archive
is an invalid Zip archive .
The version needed to
extract is the 2-byte sequence in the local file header of a file entry that indicates the minimum version supported version of the [ZIP] specification needed to extract the file data .
The valid versions needed to extract values are as follows. Each value is assigned one or more meanings by the [ZIP] specification:
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 encounters a must inform the author of
any file entry with a value for
version needed to
extract that is does not one of the
match a valid versions needed to
extract values, the the CC must inform
the author value (meaning that
user agents could potentially ignore the file
is an invalid Zip archive . at run time).
A Zip relative path is the variable-length string derived from the file name field of the local file header of a file entry .
Note: A Zip relative path is said to be relative as it stores the string that represents file and folder names relative to where the Zip archive was created on a file system (e.g. images/bg.png ), as opposed to storing an absolute path (e.g. c:\images\bg.png ). The value of a Zip relative path will generally resemble the string value of a name of the file or folder(s) on the device on which the Zip archive was created, but with the exception of the path delimiter being a U+002F SOLIDUS "/" character. Note also that a Zip relative path is not a URI reference; Zip relative paths need to be converted to URI references before they can be used in context that make use of URIs.
The valid encodings for a Zip relative path are either [CP437] or [UTF-8] . It is recommended that the file name field be encoded using [UTF-8] .
For interoperability, manipulations of Zip relative paths
must be performed on the string obtained by
decoding the file name
field using the appropriate encoding, and not on the
bytes initially stored in the archive. For the sake of comparison
and matching, it is recommended that a user
agent internally treat all zip-relative Zip-relative paths as [UTF-8]
.
A valid Zip relative
path is one that case-insensitively matches the production of
Zip-rel-path
in the
following [ABNF] :
= [ *localized-folder ] [ *folder-name ] [ file-name ] / [ localized-folder ] [ *folder-name ] / [ folder-name ] = "locales" "/" Language-Tag "/" file-name = 1*254( *base-name [ file-extension ] ) = allowed-chars = "." 1*allowed-chars = cp437-chars / utf8-charsZip-rel-path = [ *folder-name ] file-name /
[ locale-folder ] 1*folder-name /
locale-folder [ *folder-name ] file-name locale-folder = %x6c.%x6f.%x63.%x61.%x6c.%x65.%x73 ; "locales" "/" folder-name folder-name = file-name "/"= safe-chars / U+0080 and beyond = safe-chars / x80-FF = ALPHA / DIGIT / SP / "$" / "%"file-name = base-name [ file-extension ] base-name = 1*allowed-char file-extension = "." 1*allowed-char allowed-char = safe-char / utf8-char safe-char = ALPHA / DIGIT / SP / "$" / "%" / "'" / "-" / "_" / "@" / "~" / "(" / ")" / "&" / "+"/ "," / "." / "=" / "[" / "]"/ "," / "." / "=" / "[" / "]" utf8-char = %x80-D7FF / %xF900-FDCF / %xFDF0-FFEF
/ %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD
/ %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD
/ %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD
/ %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD
/ %xD0000-DFFFD / %xE1000-EFFFD
Note that ALPHA
, DIGIT
, and SP
are defined in the [ABNF] specification (but essentially represent
alphanumerical characters and the U+0020 SPACE code point
respectively). The ABNF for Language-Tag is
defined in the [BCP47] specification. Reserved characters must not
appear anywhere in the file-name .
This specification does not put a restriction on the byte length of a Zip relative path , so a user agent must be able to deal with path lengths longer than 250 bytes.
A CC must
inform the author about any file entry whose file name field does not match the
production of a
.zip-rel-path Zip-rel-path
A CC must
inform the author of any Zip
relative paths whose length exceed 250 bytes A CC
must inform an the author of any
Zip relative path whose length exceeds 120 bytes. characters.
A user agent must ignore a file entry that
contains control characters or reserved
contain forbidden
characters in the Zip relative
path .
Note: These characters are reserved to maintain interoperability across various file systems and with [URI] s.
A CC must
inform an
the author of the presence of any of
the reserved characters or control
forbidden characters in a file-name
.
A CC should
inform an
the author of the presence of a U+0020
SPACE character at the start or end of a file-name
.
A CC should
inform an
the author of the presence of any
U+002E FULL STOP at the end of a file-name
.
A CC should
inform an
the author of any base-name
that case
insensitively case-insensitively
matches any of the following strings: CON
,
PRN
, AUX
, NUL
,
COM1
, COM2
, COM3
,
COM4
, COM5
, COM6
,
COM7
, COM8
, COM9
,
LPT1
, LPT2
, LPT3
,
LPT4
, LPT5
, LPT6
,
LPT7
, LPT8
, LPT9
,
CLOCKS$
.
A CC may
inform an
the author of the presence of any
U+002B PLUS SIGN in a file-name
.
A widget package is 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
use user
agent retrieves them from within a zip
Zip archive.
A folder is a file
entry whose file name
field matches must match the production of folder-name
in a valid Zip relative path (the last
character of the file name
field is a U+002F SOLIDUS) and whose version needed to extract is
2.0.
File-extension to
media-type mapping is the process whereby a user agent maps
the file-extension
of a
file to a media type .
Content-type sniffing is the process of determining the media type
of a file by examining the initial bytes of a file for standardized
sequence of bytes known as magic numbers (e.g. the byte sequence 47
49 46 38 37 61 , which is the signature for a GIF89a image file
format). The patterns used by this specification have all been
standardized with the Internet Assigned Numbers Authority (IANA),
as part of a media type registration. As there is no notion of a
media type within Zip (i.e., no content-type metadata , as
described in the [HTML5] specification), a user agent must perform
file-extension to media-type mapping, followed by content-type
sniffing , in order to determine the media type of a file. For
sniffing the content type of images formats, a user agents must use
the rule for Identifying the media type of an image . For other
file formats, a user agent must use the rule for Identifying
the media type of a file .
A processable file is must be a
file that:
true
.The reserved file names
table, table , below, contains a list of base-name s and possible file-extension s that when
combined form file-names file
names that are reserved for some
purpose by this specification. Reserved
The first column of the reserved file
names must be treated as
case-sensitive. table, below, contains
a case-sensitive list of file names. The second column of the table
denotes the purpose for which the file name is reserved .
reserved for purpose | |
---|---|
Configuration document | |
icon.png | Default icon |
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 a distributor
signature signatures and the
naming convention for an author signature .
The names of those files , as
defined in the [Widgets-DigSig] specification, are also reserved for the
purpose of in this
specification.
The reserved folder names
table, table , below, contains a list of folder-names file
names that are reserved for some
purpose by this specification. All
The first column of the reserved
folder file
names must be treated as
case-sensitive. table, below, contains
a case-sensitive list of file names. The second column of the table
denotes the purpose for which the file name is reserved .
reserved 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 a an access control policy. The definition of such
a policy mechanism is out of
beyond the scope of this specification, but may
be defined to allow access to all or parts of the signature
documents, or deny any such access.
An exception is if a user agent that implements this
specification also implements the optional
[Widgets-DigSig] specification, in
which case the user agent must make signature
documents available only to the
implementation of the [Widgets-DigSig] specification. specification; the user agent must not make the digital signatures accessible to scripting or
other content loading mechanisms, unless explicitly enabled by an
access control mechanism.
A start
file of a widget package is
designates a file
that is used from
the widget package to be loaded by the user agent when
it instantiates the widget is instantiated. widget. This specification defines two kinds of
start file: custom start file and
default start file .
A custom start file is a
start file identified via a content
elements element's
src
attribute.
The custom start file must be a processable file inside the widget package , determined by applying the
rule for
identifying the media type of a file . When a start file is not explicitly declared via the
content
element, then start file will be one of
the default start files .
A default start file is a
reserved
start file whose file-name file name
case-sensitively and exactly matches a
file-name file
name given in the first
file name column of the default start files table below , and whose media
type matches the media type given in
the second media
type column of the table.
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 must attempt to locate encounters a file entry whose file-name
matches one matching a file name given
in the file name column of the default start files table based on the order
they appear in the default start
files an arbitrary table below (from top to bottom). File names
folder
,the user agent must treat that file as an
arbitrary
file. For example, " foo/bar/index.html
"
would be treated as case-sensitive. an
arbitrary
file .
file name | media type |
---|---|
index.htm | text/html |
index.html | text/html |
index.svg | image/svg+xml |
index.xhtml | application/xhtml+xml |
index.xht | application/xhtml+xml |
It is optional for a user agents
agent to support the media types listed in the default start files table. table .
Note: See Step 8 for instructions on finding a default start file .
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 , or the start
file is not one that is supported by a particular user agent,
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 . An icon must
be located either at the root of the widget package or at the root
of a locale folder .
A custom icon is an icon explicitly declared to be
used as an icon by an author via an icon
element of the
configuration document .
The
A user agent must derive the media type
of a custom icon is
derived by applying the
rule for
identifying the media type of an image .
A custom icon can be located either at the root of the widget package ,or at the root of a locale folder ,or in an arbitrary folder .
A default icon is an a reserved icon whose file-name
file name case-sensitively and exactly matches a file-name file name
given in the first file name column of the default icons table. table .
A user agent must derive the media type of
a default icon from the second column of the default icons table. A
default icon must be located either at
the root of the widget
package or at the root of a locale
folder .
A user agent must derive the media type of a default icon from the media type column of the default icons table .
A user agent must search for a default
icon's file-name
based on the
order they appear in the default
icons table (from top to bottom).
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 MUST SHOULD
inform an
the author that it is desirable, but optional, desirable to include a default icon .
If a CC encounters an icon in the [SVG] format, the CC may inform the author if the icon includes script or interactive functionality.
If a CC encounters an icon in a
format other than [PNG] or [GIF89] or [GIF87] , then the CC
should inform an the author
that these other formats might not be supported on
by all user agents.
If a CC encounters an icon in the
[SVG] format, then the CC must MAY inform the author
if the icon does not conform to the [SVGTiny] specification.
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
in " any case form
(e.g. .wgt
, .WGt
, .WgT
,
etc. are all valid).
The widget file extension
is Required
required for widget packages on
systems where it is customary for file names to include an extension a
file-extension
that symbolizes
the (or is
associated with) a media type
.
For when a container for localized content , which itself contains
one or more locale folders . Unlocalized content is content
included in the widget package
or in the configuration document that has not
been explicitly localized. A localized file is any file that has been placed inside a locale folder .
The contents of the file should be translated, localized, or
altered for the given context. A widget package may contain zero or
more localized files. All files and folders, except digital
signatures and the configuration document , can be localized. For
example, a locale folder "/locales/ja" (Japanese) might contain an
HTML document translated into Japanese. Authoring guideline: Locale
folders need to be placed in the container for localized content (a
locale folder not in a container for
localized content will be treated as an arbitrary folder). Always
provide a start file at the root of the widget package , in case
the end-user's preferred language is not catered for by the widget.
7.1 Localization guidelines This section is non-normative. This
specification provides two means that authors can use to explicitly
localize the content of a widget: By placing localized file content
in locale folders , a process referred to as folder-based
localization . By explicitly marking XML elements in the
configuration document as localized, a process referred to as
element-based localization . Both forms of localization are
described below. Folder-based localization and element-based
localization work in conjunction with each other. Folder-based and
element-based localization rely on the user agent to match the
language ranges held by the user agent's locales to the appropriate
locale folders and/or localized XML elements in the widget's
configuration document . 7.2 Examples This section is
non-normative. This sections presents three examples of how widgets
can be localized, each example is intended to showcase how the
localization algorithm is intended to work. Simple Example This
example shows a widget that displays the days of the week based on
the language ranges held by the user agent's locales . If the user
agent is unable to match a language range to any locale folder ,
the widget displays /index.html at the root of the widget package .
/config.xml <widget xmlns="http://w3.org/ns/widgets">
<name>What day is it?</name> <description> This
widget highlights the current day of the week. </description>
</widget> /sp/index.html <!doctype html>
<title>¿Qué día es?</title> <script
src="/scripts/engine.js"></script> <body>
<p>Hoy es: lunes, martes, miércoles, jueves, viernes, sábado,
domingo weekdays.wgt index.html /*English*/ config.xml scripts
engine.js locales fr/ index.html /*French*/ es/ index.html
/*Spanish*/ pt/ index.html /*Portuguese*/ fi/ index.html
/*Finnish*/ it/ index.html /*Italian*/ Complex Example The
following is an example of a localized widget with multiple
localized icons , start files and configuration documents . Some
relevant things to note from the example: The Spanish version (
/locales/sp/ ) has its own localized icon. The Spanish ( locales/es
) and English ( locales/en/ ) versions of the widget use the
un-localized script in /scripts/engine.js folder. On the other
hand, the English-Australia ( en-au ) version uses a localized
script ( en-au/scripts/engine.js ). /config.xml <widget
xmlns="http://w3.org/ns/widgets"> <name xml:lang="ko">웃기는
고양이</name> <content src="cats.html"/> </widget>
/locales/en-au/cats.html <!doctype html> <title>G'day!
LOL Cats!</title> <script src="scripts/engine.js"> ...
/locales/es/gatos.html <!doctype html> <title>Gatos
Graciosos!</title> <script src="/scripts/engine.js">
... LOLcats.wgt cats.html /*written in Korean*/ config.xml icon.png
/*default icon*/ signature.xml /*not localizable*/ scripts/
engine.js /*default functionality*/ locales/ /*container for
localized content*/ en-au/ cats.html scripts/ engine.js /*custom
localized functionality*/ en/ cats.html /*international english
version*/ es/ gatos.html /*Spanish version*/ icon.png /*localized
icon*/ Fallback Behavior Example This specification allows authors
to place files and folders they don't wish to localize at the root
of the widget package. At runtime, if the user agent fails to find
a file in a locale folder , it will always search at the root of
the widget package for that missing file. The purpose of this
"fallback" model is to reduce then number of files that need to be
created to achieve localization of a widget package. The example
below demonstrates how a user agent attempts to locate a file that
is absent in a localized scenario: Firstly, the user agent will
search for served over HTTP, a
folder that matches the user agent's locale
as closely as possible for the desired file. If the file is absent,
the user agent will search for the absent file in any other sub
folder that is in the language range of the current locale folder.
If the above fails, the user agent will search for the absent file
at the root of the widget package. So, for example, assume the user
agent's locale is ' en-gb '. The user agent would fail to locate
'mast.png' so the next place it would look is in the ' en/ '
folder, where it would find the absent ' mast.png ' file. Now
consider the for various Chinese variants: ' zh-Hans-CN ', '
zh-Hans ', and ' zh ' below. In this case, to find find the '
flag.png ' file for Mainland Chinese in simplified script '
zh-Hans-CN ', the user agent would first look in ' zh-Hans-CN ',
followed by ' zh-Hans ', then in ' zh ' where the file is located.
To find the ' mast.png ' file, the user agent would look in '
zh-Hans-CN ', followed by ' zh-Hans ', followed ' zh ', and finally
at the root of the widget package where the absent file is actually
located. /index.html <!doctype html> <title>Patriotic
Boat</title> <script src="/scripts/engine.js">
</script> <body> <img src="flag.png"> <img
src="mast.png"> boat.wgt index.html mast.png flag.png scripts/
engine.js locales/ en-gb/ flag.png en/ mast.png zh-Hans-CN/
zh-Hans/ zh/ flag.png Conformance Checker Behavior A CC should
inform an author if they have used
deprecated, grandfathered, or redundant language tags from the IANA
Language Subtag Registry . Upon encountering any locale folders
named with a region or script subtag, a CC should must inform an author to avoid region or script subtags from the
IANA Language Subtag Registry . 7.3 Folder-based localization This
specification defines the concept of
folder-based localization , which is the process whereby an
author places files inside folders that are
named in a manner that conforms to a language tag as defined in the
[BCP47] specification. That is, by naming folders using values
derived from the IANA Language Subtag Registry such as " en-us ", "
en-gb ", and so on, but avoiding subtags marked as deprecated ,
grandfathered , or redundant in the IANA Language Subtag Registry .
These locale folders are then placed inside the container for
localized content . The container for localized content is a folder
at the root of the widget package whose folder-name
case-sensitively match the string ' locales '. A container for
localized content may contain zero or more locale folders . A
locale folder is a folder whose file name field matches
if the production
of locale-folder file-extensionand is a direct descendant of the container for
localized content (e.g., " /locales/en-us ", " /locales/fr ", etc).
A locale folder may contain zero or more arbitrary folders and/or
files. Authoring guideline: Authors need to avoid region, script or
other subtags except where they add useful distinguishing
information to a locale folder . In addition, avoid including empty
locale folders in a widget package (unless there is a good reason
to include them). An example of a widget that uses folder-based
localization: widget.wgt config.xml index.html fun.gif
locales/en/fun.gif locales/fr/french.html locales/fr/fun.gif
Authors can further facilitate the localization process by grouping
files into folder hierarchies made up of matching subtags ,
as is shown in the example below.
However, widget packages localized at any folder level (e.g. "
locales/zh/ ") needs to be fully functional as not a localized widget
. That is, authors cannot simply put shared
files into a language level folder , but need to put all files
needed into the language level folder for the widget to work (for
example, having " a.gif " in both the "/locales/zh-Hans/" folder
and "/locales/zh/" ). Note also that the user agent treats any
file extension or folder outside the container for localized content as
unlocalized content . For example, all English versions can share
the files " shared1.gif, shared2.gif ". widget.wgt index.html
config.xml locales/en/shared1.gif locales/en/shared2.gif
locales/en/a.gif locales/en-au/a.gif locales/en-us/a.gif
some/unlocalized.png This works at all sub-levels, so long as the
parent subtag matches the child subtags. So, for example, the " CN
" region below can make use of the localized files in the " zh-Hans
" folder level, the " zh " folder level, and the unlocalized files
at the root of the widget package. The user agent always
prioritizes files in sub-folders over files in locale folders
closer to the root of if the
widget package . In the example below,
assuming the widget's locale is " zh-hans-cn ", content in the "
zh-Hans-CN" locale folder would have a higher priority than content
in the zh-Hans locale folder , which in turn would have
lacks a higher
priority than content in the zh locale folder . The content in
the
.zh locale folder
file-extension would
have a higher priority than content at the root of the widget
package .
A configuration document
is an [XML] document that has a widget
element at
its root that is in the widget
namespace . A widget package must have
exactly one configuration document, which must
be located at the root of the
widget package .
Note: Please see Step 7 for details of how the elements of the configuration document are processed by a user agent.
A valid
configuration document file name is the string
config.xml
., to be treated as
case-sensitive.
A user agent must treat a valid configuration document file name case-sensitively.
Within a widget package, a configuration document must have a valid configuration document file name .
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 an example of a
configuration document :
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns = "http://www.w3.org/ns/widgets"
id = "http://example.org/exampleWidget"
version = "2.0 Beta"
height = "200"
width = "200"
viewmodes = "application fullscreen">
viewmodes = "application fullscreen">
<name short="Example 2.0">
The example Widget!
</name>
<feature name="http://example.com/camera">
<param name="autofocus" value="true"/>
</feature>
<preference name ="apikey"
value ="ea31ad3a23fd2f"
readonly ="true" />
<preference name = "apikey"
value = "ea31ad3a23fd2f"
readonly = "true" />
<description>
A sample widget to demonstrate some of the possibilities.
</description>
<author href="http://foo-bar.example.org/"
email="foo-bar@example.org">Foo Bar Corp</author>
<author href = "http://foo-bar.example.org/"
email = "foo-bar@example.org">Foo Bar Corp</author>
<icon src="icons/example.png"/>
<icon src="icons/boo.png"/>
<content src="index.html"/>
<content src="myWidget.html"/>
<license>
Example license (based on MIT License)
Copyright (c) 2008 The Foo Bar Corp.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</license>
</widget>
Note: Implementers are encouraged to expose relevant information provided by the configuration document to the user. Having "visual metadata" encourages authors to make full use of the configuration document format. See Step 6 for instructions on how to process a configuration document.
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 . For the sake of interoperability, extensions to the
configuration document are not recommended .
Example of extending the configuration document format:
<widget xmlns="http://www.w3.org/ns/widgets"
xmlns:ex="http://example.org/">
<icon src="idle.png" ex:role="inactive"/>
<icon src="big.png" ex:role="big"/>
<ex:datasource>{a:"b",c:"d"}</ex:datasource>
<content src="widget.html"/>
</widget>
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
rule rules
for how attributes are to be processed by a user agent or
conformance checker 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 version keyword attribute that
can only be used with a valid boolean value. A valid boolean
value is an arbitrary
a string (possibly empty) that denotes a software version identifier. This
specification does not mandate any specific format,
semantics, case-sensitively
matches true
or
special processing rule for
false
.Unless specified otherwise, the format of this attribute type. In other words, all
strings are valid for this attribute type within default behavior, which is used when the
constraints of [XML] attributes. The value of
this kind of attribute is retrieved
using the rule for getting omitted or
has a single attribute value
. Author Guidelines: For the purpose of this
specification, other than the
structure of version tags has no semantics;
they are just treated as arbitrary strings (e.g. '1.0'
two allowed values, is not greater than '2.0', but false
.The way a user
agent interprets a boolean attribute is simply different). However, for the sake
defined as part of consistency, one can choose to use an attribute's definition (see, for example, the
following [ABNF] : rec-version-tag = 1*2DIGIT
["." 1*2DIGIT [ "." 1*2DIGIT] [ ALPHA / SP / DIGIT] ] Example valid
version tags:
element's Version 1.0 Beta , 1.0 RC1 , 1.0-Build/1580 , Joey the
dog [5.1.2100] . Example of recommended version tags:
feature
1.0 , 1.10.1beta1 , 1.02.12rc1 .
attribute).Numeric attribute
required
A valid non-negative integer is a string
that consists of one of more code points in the range U+0030 DIGIT
ZERO (0) to U+0039 DIGIT NINE (9). For example, user agent must retrieve the
characters "2", "323", "23214", and so on.
The value of this kind of
a boolean attribute
is retrieved using the rule for getting a
single attribute value .
A keyword is a string that is reserved for the purpose of this specification. The
value of a keyword attribute is a keyword
that is one of a finite set specified in the attribute's definition
(e.g. the its:dir
attribute
defines ltr
, rtl
, lro
, or
rlo
as its only possible values). Authors
For keyword
attributes ,authors
must use keywords in the case given in this specification.
Implementations
User agents must
only perform literal comparisons on the
resulting value, keyword
attributes , and must not use
case insensitive case-insensitive comparisons. How the value of
this attribute is retrieved by a user
agent depends on the context in which is it used, so used: so, the
rule for hoe how to retrieve the value is given when this
attribute type is used. used in the specification.
An attribute defined as taking one or more keywords as values,
a value, which are separated by
space characters . The value of this kind of attribute is retrieved using
the rule for getting a list of keywords from an attribute
.
A valid boolean value is a string that
case-sensitively matches true or false . Unless specified
otherwise, the default behavior, which is used when the attribute
is omitted or has a value other than the two allowed values, is
false . The way a user agent interprets
a boolean attribute is defined as part of an attribute's definition
(see, for example, must retrieve the
feature element's required attribute).
The value of this kind of
a keyword list
attribute is retrieved using the
rule for
getting a single list of keywords from an attribute value .
An attribute whose value is defined as containing a valid media
type. A valid media type is string
that matches the production for valid-MIME-type
in the
following [ABNF] :
valid-MIME-type = type "/" subtype *(";" parameter)
The type
, subtype
, and parameter
tokens are defined in the [MIME] specification.
The A user
agent must
retrieve the value of this kind of
attribute is retrieved using the
rule for
getting a single attribute value .
The value of a numeric attribute
defined as is a
string containing a valid URI.
non-negative integer. A valid URI
non-negative integer is
one a
string that matches the URI token
consists of the
[URI] specification one or
more code points in the IRI token of range U+0030
DIGIT ZERO (0) to U+0039 DIGIT NINE (9). For example, the
characters "002", "323", "23214", and so on.
A user agent must retrieve the [RFC3987]
specification. The value of this kind
of a numeric attribute
is retrieved using the rule for getting a
single attribute value .
An attribute defined as containing a valid path. A valid path is one that matches the the production of a
or a
zip-rel-path
Zip-rel-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.zip-abs-path Zip-abs-path
A zip Zip absolute path is one that
case-insensitively matches the production of
in the
following [ABNF] :zip-abs-path
Zip-abs-path
Zip-abs-path = "/" Zip-rel-path
Note: A
is invalid in zip-abs-path Zip-abs-patha the file name filed 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 this kind
the [RFC3987] specification.
A user agent must retrieve the value for a IRI attribute using the rule for getting a single attribute value .
The value of a
version attribute is retrieved
an arbitrary string (possibly empty). This
specification does not mandate any specific format, semantics, or
special processing rule for the format of a version
attribute .A user agent
must allow any string, within the constraints allowed
for [XML]
attributes, as the value of a version
attribute .
A user agent must retrieve the value for a version attribute using the rule for getting a single attribute value .
This section describes the behavior and expected usage of other
relevant attributes that are
supported either by default as part of
the [XML] specification (as is the case with xml:lang ) or if the user agent
implements and the optional [ITS]
specification.
xml:lang
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 this kind of
an xml:lang
attribute is retrieved must be processed by a
user agent in accordance with the XML
. [XML]
specification.
A user agent must retrieve the value for an xml:lang
attribute using the rule for getting a single attribute value
.
its:dir
attribute
(
This feature is at risk )A keyword attribute defined as
containing a valid
its:dir
value (i.e., ltr
,
or rtl
, or lro
, or rlo
). To
use the its:dir
attribute, the
its
namespace (see [ITS] ) must be declared on the
element where it is used or somewhere in the element's ancestor
chain.
It is optional for authors to
use the its:dir
attribute
with any element.
A user agent must retrieve the value for an its:dir
attribute using the rule for getting a single attribute value
.
widget
ElementThe widget
element serves as a container for the
other elements. 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 valid URI IRI attribute that
denotes an identifier for the widget.
It is optional for authors to use
this attribute. the id
attribute with a widget
element.
version
A version attribute that specifies the version of the widget.
It is optional for authors to use
this attribute. the version
attribute with a widget
element.
height
A numeric attribute greater than
0
that indicates the preferred view port viewport height of the instantiated custom start
file in CSS
pixels [CSS21] . This value is only
applicable to particular view modes (e.g., floating and
application mode), , meaning that for certain view modes this value is
ignored . Which The view modes should that honor
the value of this the height
attribute
is are
defined in the the [Widgets-Views] specification.
It is optional for authors to use
this attribute. the height
attribute with a widget
element.
width
A numeric attribute greater than
0
that indicates the preferred view port viewport width of the instantiated custom start
file in CSS
pixels [CSS21] . This value is only
applicable to particular view modes (e.g., floating and
application mode), , meaning that for certain view modes this value is
ignored . Which The view modes should that honor
the value of this width
attribute is are defined in the
the [Widgets-Views] specification.
It is optional for authors to use
this attribute. the
attribute
with a xml:lang widthxml:lang widgetattribute.
It is optional for authors to use this attribute. element.
viewmodes
A keyword list attribute
that denotes the view
modes supported the widget.
The value
An author SHOULD should
be use one
or more of the following valid view modes
modes, as defined in the [Widgets-Views] specification:
application
, floating
,
fullscreen
, or mini
. In
addition, the , orall
keyword can be used by authors to denote that
all the valid view modes are supported by the widget..
The default value, which is used
a user agent must use when the
attribute is omitted absent or the
attribute has a value other than one of the valid view modes , is
floating
. The first item represents the author's
preferred view mode, followed by the next most preferred view mode
and so forth. It is optional for authors to
use this attribute. View port Viewport and
view mode are defined in
the [Widgets-Views] specification.
It is optional for authors to
use the viewmodes
attribute with a widget
element.
xml:lang
It is optional for authors to
use the xml:lang
attribute with a widget
element.
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
this attribute. the xml:lang
attribute with an name
element.
its:dir
It is optional for authors to use
this attribute. the its:dir
attribute
with an name
element.
short
A string that represents the short
a condensed name for a widget. Ideally, widget
(e.g., a name that could be used in context were only limited space
is available, such as underneath an icon).
It is optional for authors to
use the value short
attribute
with an name
element.
A CC should must
be shorter inform
an author if the value of the short
attribute is longer in length than the
contents text
content of the name
element. Otherwise,
the short attribute should not be used. It is optional for authors
to use this attribute.
The following example shows the usage of the name
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
The Ultimate Weather Widget
The Ultimate Weather Widget
</name>
<name short="Boletim" xml:lang="pt">
Boletim Metereológico
</name>
</widget>
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
this attribute. the xml:lang
attribute with an description
element.
its:dir
It is optional for authors to use
this attribute. 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
that whose
value represents a link
IRI that is
associated with the author (e.g. the
homepage of the author). associates
with himself or herself (e.g., a homepage, a profile on a social
network, etc.).
It is optional for authors to use
this attribute. the xml:lang
attribute with an author
element.
email
A string that represents an email address associated with the author.
It is optional for authors to use
this attribute. the
attribute
with an xml:lang emailxml:lang authorattribute.
It is optional for authors to use this attribute. element.
its:dir
It is optional for authors to use
this attribute. 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"
<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 URI
IRI or a valid path that points to a representation of a
software and/or content license.
When the href
attribute is present, used, the
user agent should allow provide users
the ability to view or otherwise link to the referenced
license.
If the href
attribute contains a valid path to a file within the widget package,
then the user agent should MUST use
the rule for
identifying the media type of a file to identify the media type of the file being referenced.
It is optional for authors to use
this attribute. the
attribute
with a xml:lang hreflicense
element.
xml:lang
It is optional for authors to use
this attribute. the xml:lang
attribute with a license
element.
its:dir
It is optional for authors to use
this attribute. 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. It
When an icon
element is
used, it is required for authors
to use this the src
attribute.
width
A numeric attribute greater than
0
that represents the width of the icon in CSS
pixels [CSS21] . This attribute The
width
is only applicable to graphic
formats that have no intrinsic width or height (e.g., SVG).
If the file pointed to by the src
attribute of an
icon
element is a supported
raster graphic, then the user agent will must ignore this
value.
If the file pointed to by the src
attribute of an icon
element is of a
supported
vector graphic format, then this value
the user agent must
be used. use this
value.
It is optional for authors to use
this attribute. the width
attribute of an icon
element.
height
A numeric attribute greater
than 0
that represents the height of the icon in
CSS
pixels [CSS21] .This .The height
attribute
is only applicable to graphic formats that have no intrinsic width
or height (e.g., SVG).
If the file pointed to by the src
attribute of the
icon
element is a supported
raster graphic, graphic format, then the user agent will must ignore this
value.
If the file pointed to by the src
attribute is a vector graphic format, then
this value must be used.
It is optional for authors to use
this attribute. the height
attribute of an icon
element.
xml:lang
It is optional for authors to
use the xml:lang
attribute with an icon
element.
This example shows the expected usage of the icon
element. The
example declares three icon elements, two of which are raster and
one of which is an [SVGTiny] file. The
raster graphics would be used for display contexts smaller than
256x256 pixels. Document order
of the elements is irrelevant.
<widget xmlns="http://www.w3.org/ns/widgets"> <icon src="icons/medium.png"/> <icon src="icons/big.svg" width="256" height="256"/> <icon src="icons/tiny.png"/><widget xmlns="http://www.w3.org/ns/widgets"> <icon src="icons/medium.png"/> <icon src="icons/big.svg" width="256" height="256"/> <icon src="icons/tiny.png"/> </widget>
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 instantiates
the widget.
widget
element.xml:lang
:content
Elementsrc
A path attribute that allows an
author to point to a file within the widget package . It
When a content
element
is used, it is required for
authors to use this the src
attribute.
type
A media type attribute that
indicates the media type of the file
referenced by the src
attribute. When the value is
absent, the user agent will assume the value text/html
.
It is optional for authors to use
this attribute. the type
attribute with a content
element.
charset encoding
A keyword attribute that
denotes the character set encoding of the file identified by the
src
attribute. The allowed
values are any name value is the "name" or "alias" of a character set any
"Character Set" listed in [IANA-Charsets] (a
.
A user agent are required must
to support [UTF-8]
, which has the " UTF-8
" name in
[IANA-Charsets] ;
it is optional for ). Itauthors a user agent
to use this attribute. support other character
encodings.
When the value of
is absent or in error , the user agent charset encodingwill 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
attribute to override the default
value of charset encodingthis 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 API) Application Programming Interface or video
decoder) that is not part of the standard specified set
provided by the Widgets 1.0 family of
specifications . The feature
element
serves as a standardized means to request the binding of an (IRI)
identifiable runtime component to a widget for use at
runtime. Using a feature
element denotes that, at runtime, a
widget may can attempt to access the feature identified by the feature
element's
name
attribute. How a user agent makes use
of features depends on the
user agent's security policy, hence activation and authorization
requirements for features are beyond the scope of this
specification.
A feature can may have zero or more
parameters associated
with it.
widget
element.param
elements.xml:lang
:feature
Elementname
A URI IRI attribute that
identifies a feature that may be needed by the widget at runtime (such as an
API). It API ).
When the feature
element
is declared, it is required for
authors to use this the name
attribute.
required
A boolean attribute that
indicates whether or not this feature
must be available to the widget at runtime.
In other words, the When set to true
,the
required
attribute denotes that a feature is absolutely needed by the widget to
function correctly, and without the availability of this feature the widget serves no useful purpose or
won't execute properly.
When set to false
,the
required
attribute denotes that a widget can function correctly
without the feature being
supported
or otherwise made available by the user
agent.
The default value that a user agent
must use when this
the required
attribute is absent is
true
, meaning that the feature must be made available to the widget by the widget user agent at
runtime.
It is optional for authors to use
this attribute. the required
attribute with an feature
element.
This example demonstrates a widget that would like to use a fictional geo-location API feature, but would still be able to function if the feature cannot be made available to the widget by the user agent.
<widget xmlns="http://www.w3.org/ns/widgets">
<feature name="http://example.org/api.geolocation"
required="false"/>
<feature name = "http://example.org/api/geolocation"
required = "false"/>
</widget>
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.
The A author
establishes the relationship of
between a parameter to a
and feature is
established by having a param
element as a direct child of a
feature
element in document order
.
A user agent must ignore any param
element outside the context of a feature
element
(outside the context of a feature
element, a
param
element does not represent anything and a
user agent must ignore it. has no
function or meaning).
feature
element.xml:lang
:param
Elementname
A string, which may be empty, that denotes
the name of this parameter . It
When a param
element is
declared, it is required for
authors to use this the name
attribute.
value
A string, which may be empty, that denotes
the value of this parameter . It
When a param
element is
used, it is required for authors
to use this the value
attribute.
This example demonstrates a widget that makes use of a fictional
geo-location feature where by its accuracy is set to "
low
" via a param
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<feature name="http://example.org/api.geolocation">
<param name="accuracy" value="low"/>
<param name="accuracy" value="low"/>
</feature>
</widget>
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 instantiated. Unless an end-user explicitly requests
that these values be reverted to the values as declared in the
configuration document, a initiated .
A user agent must not revert to these values on subsequent
initialization of the widget. User agents that support
supports the [Widgets-APIs]
specification must
expose any declared preference to the
author at runtime via scripting.
scripting in the manner described in
the [Widgets-APIs] specification. In addition, unless a preference
is
explicitly marked as read-only (via the readonly
attribute), it must be possible for authors to
override and delete these preference values at
runtime via the relevant methods defined in the [Widgets-APIs] specification.
widget
element.xml:lang
:preference
Elementname
A string that denotes the name of this preference . It
When a preference
element is used, it is required for authors to use this the name
attribute.
value
A string that denotes the value of this preference . The default value that a user agent must use for when
the value
attribute is
missing absent is null
(i.e., the data
value .null
,and not a string " null
").
It is optional for authors to use
this attribute. the value
attribute with a preference
element.
readonly
A boolean attribute indicating whether this preference can be overwritten at runtime.
The default value that a user agent
must use when this
the readonly
attribute is absent is
false
, meaning that the value can be overwritten at
runtime.
It is optional for authors to use
this attribute. the readonly
attribute
with a preference
element.
This example shows a widget where two preferences are set. The
second preference
is set as read only, "read only" via
the readonly
attribute, which means the values of
that preference cannot be changed at runtime.
<widget xmlns="http://www.w3.org/ns/widgets">
<preference name = "skin"
value = "alien"/>
<preference name = "api-key"
value = "f6d3a312f9d742"
readonly = "true"/>
</widget>
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
value s, 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 [XML] element in the configuration document has been
localized .
The following is an example of element
based element-based
localization:
<widget xmlns="http://www.w3.org/ns/widgets"> <name short="Weather"><widget xmlns="http://www.w3.org/ns/widgets"> <name short="Weather"> The Ultimate Weather Widget </name>
<name short="Boletim" xml:lang="pt"><name short="Boletim" xml:lang="pt"> Boletim Metereológico </name> </widget>
As part of their definition, the XML elements of the configuration document are marked as
being localizable via
xml:lang
with either
the word "yes" or "no".
If an element is marked as being localizable via xml:lang
with the word "no", it means that
the element is not localizable via element-based localization . In
such a case, the user agent must not attempt
to do any localization other words,
exclusion of an xml:lang
on an element indicates that that
element is unlocalized
content ,except in the
manner described in this section
regardless case whereby a parent
element uses xml:lang
(this
maintains consistency with the behavior of whether xml:lang
as
specified in the element contains
an [XML]
specification). Explicitly declaring
xml:lang
attribute. overrides
any xml:lang
value
inherited from a parent element.
For example, if the author uses the
xml:lang
attribute on the widget
element,
then all child elements inherit the value xml:lang. This means that
the first name
element below behaves as xml:lang="en"
had
been explicitly used. However, in the second name
element, the
declaration of xml:lang="pt"
overrides xml:lang="en" inherited from the
widget
element.
<widget xmlns="http://www.w3.org/ns/widgets"
xml:lang="en">
<name short="Weather">
Behaves as if xml:lang="en"
</name>
<name xml:lang="pt">
The declaration of xml:lang="pt" overrides
xml:lang="en" inherited from the widget element.
</name>
</widget>
If an element is marked as being localizable via xml:lang
with "yes", the specification always indicates if one
element is allowed per language or
whether elements
are grouped by language :
One element is allowed per language means
that only one element of a type is allowed to be used per language
(e.g., although many name
elements can be present in a configuration
document ,only one
name
element will
be selected by the user agent for the English language). During
processing ( Step
7 ), the user agent
must attempt to
only match the
first element, in document order ,that
matches a language range in the user agent's
agent locales and ignore any subsequent
repetitions of the element that contain a matching
xml:lang
value
(even if that element's content is different).
For example, assume the
user
agent locales only contains
the following language range: " en-us
" (English as
used in the manner specified
United States). As only one instance of
the description
element is allowed per language, in
Step 7 . the
following code the user agent would match the first
description
element but would ignore the second and third description
elements.
<widget xmlns="http://www.w3.org/ns/widgets">
<description xml:lang="en">
This element would be used.
</description>
<description xml:lang="en">
This element would be ignored.
</description>
8.16
Indicating
Text
Directionality
with
<description>
This element is unlocalized, and would be used if the user agent's
locale does not match any localized description elements.
</description>
</widget>
However, if the user agent
locales only contained "
", or did not match
any of the localized <its:span> *
elements, then the user agent would match the
third Although it is optional
for descriptiondescription
element above.
In the case whereby the author does not
use an xml:lang
attribute, and no element of a particular type with xml:lang
matches the user agent to
support locales [ITS] , it is , the
user agent recommended must
that authors use the <its:span> first
element to indicate the directionality of
text that unlocalized
content when needed. Directionality is
indicated by either using , in document order ,that
matches the element type being sought.
For example, now assume that the
user agent
locales only contains
the following language range: "
dir jpattribute,
with " (Japanese). As only one
instance of the description
element is allowed per language, in the following
valid code the
user will agent ignore the first
two description
elements, but would match the third
(unlocalized) description
element.
its:dir
<widget xmlns="http://www.w3.org/ns/widgets">
<description xml:lang="en">
This element would be ignored.
</description>
<description xml:lang="en">
This element would be ignored.
</description>
<description>
In this case, this unlocalized element would be used.
</description>
</widget>
Elements are grouped by language means
that multiples of an element are allowed per language (e.g.,
multiple icon
elements are allowed per language). During processing
( Step 7
), the user agent must match all elements with a particular name (e.g.,
icon
) having
an xml:lang
attribute value s,
that matches the language ranges of the
user agent
locales , as defined in
ITS: well as elements of that
particular name that are unlocalized
content .
For example, assume that the
user agent
locales contains the
following language ranges: "
" (Japanese and english). As multiple
instances of the ltr jp,en
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.Left to right text. icon rtl
<widget xmlns="http://www.w3.org/ns/widgets">
<icon xml:lang="en" src="icons/a.png"/>
<icon xml:lang="jp" src="icons/b.png"/>
<icon src="icons/c.png"/>
<icon src="icons/d.png"/>
Right
to
left
text.
</widget>
Now assume that the user agent
locales contains the
following language range: "
" (Japanese). In the following code, the user
agent would ignore the first lro jp
element, but
match the second, third, and fourth Left-to-right override.
icon rlo
elements.Right-to-left override.
icon
<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 optional non-normative. for
authors
This section presents three examples of how widgets can be localized, each example is intended to showcase how the localization algorithm is intended to work.
This example shows a
widget that displays the days of the week based on the language
ranges held by the user agent
locales .If the user agent is
unable to match a language range to use any locale folder ,the
widget displays /index.html
at
the root of the [ITS]
attributes. widget package
.
/config.xml
<widget xmlns="http://www.w3.org/ns/widgets">
<name>What day is it?</name>
<description>
<widget
xmlns="http://www.w3.org/ns/widgets"
xmlns:its="http://www.w3.org/2005/11/its">
<name>Yay for the
"<its:span dir="rtl"></its:span>" Widget</name>
<description its:dir="rtl"> </description>
This widget highlights the current day
of the week.
</description>
</widget>
/locale/es/index.html
<!doctype html> <title>¿Qué día es?</title> <script src="/scripts/engine.js"></script> <body> <p>Hoy es: lunes, martes, miércoles, jueves, viernes, sábado, domingo
</widget>
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:
its:dir /locales/es/
locales/es
)
and <its:span>
locales/en/
/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 SHOULD may
follow, in sequential order, responding accordingly if any of the
steps result in an error or if the specification asks for the user
agent to skip a step. The procedures for what to do when an error
is encountered are described as part of each step; however, there
are times when it will not be possible for the user agent to
recover from an error and it will be forced to treat the widget as
an invalid Zip archive (see
rule for
dealing with an invalid Zip archive ).
The steps for
processing a widget package and associated processing rules are written with more
concern for clarity than efficiency. As such, a user agents
agent may optimize
any of the parsing rules and the steps, or may
perform the steps in a different order, but the end result
must be indistinguishable from the result that
would be obtained by following the specification.
This section defines various processing rules on , which are a set
of common algorithms used in the by the steps for processing a
widget package rely on. .
The rule for extracting file data from a file entry is described in this section.
Given a path that matches a the file name
field of a file entry within
the zip
Zip archive , a user agent
must to decompress
(or otherwise extract) the file
data of file entry into its
original file representation. Exactly how to extract a file from a Zip archive is
beyond the scope of this specification. Instead, implementers
Implementers must
follow the [ZIP] specification's instructions on
how to extract a file for from the Zip
archive.
Note: For
efficiency, a Zip archive at the same
time. The user agent may
can extract specific files as they are needed for processing. Note: processing
rather than extracting all the files at once. As a security precaution, implementations
are discouraged from extracting file entries from un-trusted widgets directly onto
the file system. Instead, implementations should consider could use,
for example, a virtual file system or mapping to access files
inside a widget package
.
The rule for dealing with an invalid Zip archive is described in this section.
In the event that an implementation encounters an invalid Zip archive during the steps for processing a
widget package , the user agent must abort
all processing of the steps for processing a
widget package and .
In the case the UA is a CC, it should must inform
the end-user with an appropriate localized
error message. The wording of an appropriate localized error
message is left to author that
the discretion of implementers; however, its
presence Zip
archive is nonetheless recommended
. an invalid Zip
archive .
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 Zip
relative valid path to the file
entry being sought.
Let path-components be the result of
splitting path starts
with at each occurrence of a
U+002F SOLIDUS (e.g., " /style/master.css "),
meaning character, removing that
U+002F SOLIDUS character in the
process.
If the number
of items in path path-components is an
zip absolute path , then: Remove greater than two, then check if the first U+002F SOLIDUS from second item in path path-components and
search at exactly matches the
root of string
" locales
". If it does:
If the widget
package for a file entry whose third
item in file name field
path-components matches path . If none if found, contains any characters other than a U+002D HYPHEN-MINUS
("-") or characters the range %x61-71
,then
return null
and terminate this algorithm. (I.e., The third item in path-component can
only contain lower-case ASCII characters or zero or more
hyphens).
If a matching file entry is found, let
file be the result of applying rule for
extracting file data from a file entry to path
. If file is starts with a
processable file , then return file and
terminate this algorithm. If file U+002F SOLIDUS (e.g., " /style/master.css
"),
meaning that the path
is not a processable file an Zip absolute path , then return an error and terminate this algorithm.
remove the first U+002F SOLIDUS from
path.
For each lang-range in the user agent's
agent locales :
Let path be the concatenation of the string "
locales/
", the lang-range , a U+002F
SOLIDUS character, and the name of the
path (e.g., locales/en-us/cats.png
, where
" en-us
" is the lang-range and "
cats.png
" is the path ).
If path points to a file
entry within the widget
package , then return the
corresponding let file . be the result of applying the rule for extracting file data from a file
entry to path .
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's
agent locales have been
searched, then search for a file entry
whose file name field
matches path at from the root of the widget package :
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 U+0009, U+000A, U+000D, and U+0020 space
characters (in any order) with a single U+0020 SPACE
character.
In result , drop
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 U+0009, U+000A, U+000D, and U+0020 space
characters (in any order) with a single U+0020 SPACE
character.
In result , drop
remove any leading or trailing U+0020
SPACE character.
In result , chop
split the string at each occurrence of
a U+0020 character, dropping
removing that U+0020 character in the process.
The rule for
verifying a file entry is given in the following algorithm.
An unusable file entry is one where by any of
following conditions occur/apply (indicating that a condition is
met). If a user agent encounters an unusable file entry, it must
ignore the file entry: To ignore The
algorithm always returns a file entry
means that the user agent must act as if the said file does not
exist within the Zip archive . boolean
value.
For the file entry , check the
following data in the local file
header : .
If the value of the CRC-32 field (defined in the [ZIP] specification) fails a CRC-32 check. check, return
false
and terminate this algorithm.
The version needed to
extract is greater than 20
(meaning the
archive is using a feature unsupported
by this specification, such as Zip64). The
value of the compression method field is not one of the valid
compression methods ( 0 or Zip64),
return 8 false).
and terminate this algorithm.
The file name field
is an empty string. string, return false
and terminate
this algorithm.
The file name field
contains reserved 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 [DOM3Core] Element
to be
processed.
This feature is at risk . If the user agents agent supports [ITS] , and if the input element has the
dir
attribute from the [ITS]
namespace or any children with a valid its:dir
value , then
process input and its descendant text nodes in accordance to the [ITS] specification.
Return the value of the textContent
property for 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
Element
to be
processed.
Let result be the result of applying the Rule
rule for Getting
Text Content getting text
content to input .
In result , excluding any
U+0020 SPACE code points, convert any sequence of one or more
Unicode white space characters marked with the [Unicode] property "White_Space" into a single U+0020
SPACE.
Return result .
For example, the user agent would ignore
the author
and blink
elements, but
their Text
nodes would be extracted. The resulting
widget name would be "
The Awesome Super Dude Widget " and the resulting
widget short name would be "D
" D A
H U
":T": T
<widget xmlns="http://www.w3.org/ns/widgets">
<name short= "
D A H U T
">
The <blink>Awesome</blink>
<author email="dude@example.com">Super <blink>Dude</blink></author>
Widget</name>
</widget>
The rule for
parsing a non-negative integer are as given in the following
algorithm. When invoked, the algorithm must be
followed in the order given, aborting at the first step that
returns a value. This algorithm will either return zero, a positive
integer, or an error. A user agent must
ignore leading and trailing space characters .
There may be implementation-specific limits
on the range of integers allowed, and behavior outside such limits
is undefined. 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 are is given by
following algorithm. It is optional for user
agents to support any of
the media types listed in the
media type
identification table . The algorithm
always returns a string.
Note: This rule is only to be applied when explicitly instructed to by the specification (during Step 7 ).
file-extension
, attempt to match the
file-extension
to one
of the strings in the file-extension
, if the first bytes
of the file unknown/unknown
.file extension | |||
---|---|---|---|
.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 |
.svg | image/svg+xml | .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 are is given by the
following algorithm. It is optional for user
agents to support the
media types given in
the file identification
table below. The algorithm always returns
a string.
Note: This rule is
only to be applied when explicitly instructed to by the
specification (during Step 7 ). There are
situations where alternative means are defined by the specification
to identify the media type of a file (e.g., by the presence of
the content
element's type
attribute or
deriving the media type of a default start
file from the default start
files table ).
Let file be the file to be processed.
If file has a file-extension
, attempt to match the
file-extension
to one
in the first file
extensions column in the file identification table . If
there is a match, then return the media
type value.
If file extension is absent, the media type of a file must be determined by using the rules set forth in the [SNIFF] specification.
media type | |
---|---|
.html | text/html |
.htm | |
.css | text/css |
.js | application/javascript |
.xml | application/xml |
.txt | text/plain |
.wav | audio/x-wav |
.xhtml | |
.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 checking if confirming
that it is a Zip archive by
using applying the rule for determining
if a potential Zip archive is a Zip archive . A user agent will
acquire a potential Zip
archive from a data transfer protocol that either labels
resources with a media type (e.g.
[HTTP] ) or from a data transfer protocol that
does not label resources with a media type (e.g., BitTorrent, Bluetooth, etc.). BitTorrent or Bluetooth):
When attempting to acquire a potential Zip archive over some
protocol that labels resources with a media
type , a user agent must only attempt to
process resources labeled with the valid widget
media type ( application/widget
) ), regardless of
whether the resource contains a file extension or not. not, by applying
the rule for determining if a potential Zip archive is a Zip
archive . Unless the user agent supports legacy or proprietary media types, types , all
other media types are
in error and the user agent must treat the
potential Zip archive as an
invalid Zip archive .
If the result of the user agent applying
the rule for determining if a potential Zip archive is a Zip
archive is true
,meaning that
the potential Zip archive is
a Zip
archive ,then the user agent
must proceed to Step 2 .Otherwise, if an
error is returned, the user agent must treat the
potential
Zip archive as an invalid Zip
archive .
For example, in [HTTP] ,
where the Content-Type
header matches
application/widget
.
If the protocol used for acquisition of a potential Zip archive does not
provide, or otherwise include, a media
type , then a user agent may treat the
acquired potential Zip archive
as if it has been acquired from a protocol that does not label
resources with a media type . (see sub-section
below).
In this example, the media type of
the Content-Type
is not one supported by the user agent, so the user agent
would treat the potential
zip Zip
archive as an invalid Zip
archive :
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 a the resource regardless of the file extension
(including situations when the file extension is absent) by
applying the rule for determining
if a potential Zip archive is a Zip archive . Rule for Determining if a potential Zip archive is a Zip
archive It is optional for a user agent to acquire all the bytes of
a potential zip archive before applying the rule for determining if
a potential Zip archive is a Zip archive . A user agent may
apply If the rule for determining
if a potential Zip archive is a Zip archive once it has acquired the first four bytes of the
potential zip archive . The rule for determining if a potential Zip
archive is a Zip archive are as follows: If the first four bytes of
the potential Zip archive do not match the magic numbers for a Zip
archive ( return
,proceed
to Step 2 .
Otherwise, if an error was returned,
the user agent must treat the potential Zip archive as 50 4B 03 04 ) then a user agent must
treat the resource as an invalid Zip archive truea an invalid Zip
archive and proceed to Step 2 .
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 recommended , that a user agent must verify each file
entry by using applying the rule for verifying a file entry
before proceeding to step 3 .
If the result of applying the rule for
verifying a file entry is
false
,a CC must inform the
author.
In this Step, a user agent
must assume
set the following variables and default values as defined in the
table of configuration defaults at this point of processing. below.
When a null
value is assigned to a variable in the
table of configuration defaults table, an
implementation must treat the value as
null
(i.e., not as empty string and not as the text
string "null"
).
Variable | Type | Default Value | Overridden by | Description |
---|---|---|---|---|
author email | String | null |
Step 7 | The author element's
email
|
author href | null |
Step 7 | The author element's href |
|
author name | String | null |
Step 7 | The author |
feature list | List | null |
Step 7 | A list of features that correspond to features that were
feature feature element's
name
attribute, whether it is required, and any associated parameters |
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 |
start file encoding | String | UTF-8 |
Step 7 | The character encoding of the custom start file , corresponding to
either the content element's
attribute (if |
start file content-type | String | text/html |
Step 7 | The media type of the start content element's
type
attribute or to a media type derived from
the default start
|
File |
null |
Step 6 | The file |
|
null |
Step |
The description element in the configuration document |
||
widget |
null |
Step 7 | The
height attribute in the configuration document |
|
widget |
null |
Step 7 | The widget element's
attribute in the configuration document |
|
widget |
String | null |
Step 7 | 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 attribute in
the configuration document
|
widget |
null |
Step 7 | The element
in the configuration document
|
|
widget
|
null | Step 7 | The widget's |
|
widget short name | String | null |
Step 7 | The name
element's short attribute in the configuration document |
Variable | Type | Default Value | Overridden by | Description |
widget version | String | null |
Step 7 | The widget element's
version attribute in the configuration document |
widget width | null |
Step 7 | The widget element's
width attribute in the configuration document |
|
widget window modes | List of strings | floating |
Step 7 | The element's viewmodes
attribute in the configuration
document |
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 |
List of strings |
null |
Step 5 |
This step only applied applies to a user
agents agent that support supports the [Widgets-DigSig] specification. If the user
agent does not support
[Widgets-DigSig] , go to Step 5 .
The algorithm to locate digital signatures is defined in the
[Widgets-DigSig] specification, under
the section named Locating
and Processing Digital Signatures for the
Widget. .
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 lists
list be a comma-separated list that represents contains
the end-user's language ranges . Each item in
the unprocessed locales must be a
string shorter than eight characters,
in lowercase form, that conforms to the production of a
Language-Tag
, as defined in the [BCP47] specification. A string that conforms to the
production of a Language-Tag
is referred to as a
language range
[BCP47] (e.g. ' en-au
', which is
the range of English as spoken in Australia, and '
fr-ca
', which is the range of French as spoken in
Canada, etc.). A language range is composed of one or more subtags that are delimited by a U+002D HYPHEN-MINUS
(" ("
-
"). ").
The first item of the unprocessed locales must represent the user's most preferred language range (i.e., the language/region combination the user agent assumes the end-user most wants to see content in), followed by the next most preferred language range, and so forth.
For example, in an unprocessed locales
lists list that contains '
en-us,en,fr,es
', English as spoken in the United
States is preferred over English, and English is preferred over
French, and French is preferred over Spanish, and Spanish is
preferred over unlocalized
content .
For each range in the unprocessed unprocessed locales lists list :
If this range begins with the subtag ' *
' (e.g. "
" or just " *-US *-us*
"), or
is longer than eight characters, or
contains any space characters ,
skip all the steps in this algorithm below, and move onto the next
range .
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's
agent locales .
Remove the right most subtag from range (e.g., " zh-hans-cn " becomes " zh-hans ") and
append the resulting value to user agent's
agent locales . Continue
removing the right most subtag and adding the result to user agent's
agent locales until there are
no subtags left in range .
For example, if the
range was "zh-hans-cn", then the user agent
locales become "
zh-hans-cn,zh-hans,zh
".
Move onto the next range and go to step 1 in this algorithm.
Append the right most one. So, for example, value "
" fr,en-us,en,en-au,en,fr,en *would become "
fr,en-us,en,en-au ". Append the value "*" to the end of
user agent's agent
locales .
For example, an unprocessed locales
lists list that contains "
en-us,en-au,en,fr-ca,zh-hans-cn
", would decompose to " en-us,en,en-au,en,fr-ca,fr,zh-hans-cn,zh-hans,zh ", and
after step 4 is applied the would
result in a user
agent's agent locales would contain the following items: that contains "
".en-us,en,en-au,fr-ca,fr,zh-hans-cn,zh-hans,zh
en-us,en,en-au,en,en,fr-ca,fr,zh-hans-cn,zh-hans,zh,*
For example, an unprocessed locales
lists list that contains "
en-us,en,fr-ca,en,en-ca
" would
decompose to " en-us,en,en,fr-ca,fr,en,en-ca,en " "would result in step 3, and
after step 4 is applied the a
user agent's agent
locales would contain the following
items: that contains "
"."en-us,en,fr-ca,fr,en-ca" .
en-us,en,en,fr-ca,fr,en,en-ca,en,*
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 instantiation initialization and at runtime, and to select the
appropriate localized content (if any) that
must eventually to be presented
to the end-user. end user.
In this step, the user agent must make use
of the lookup algorithm, which is defined in section 3.4 of
[RFC4647] (part of [BCP47] ), conjunction to match
elements in the algorithm for
processing a configuration
document to the language ranges held by
the user agent's locales (if any). What to do when more then one
element of a type are matched given
below, this section firstly defines some terminology used by
the user agent depends on whether one element
is allowed per language or whether processing algorithm and describes how localized
elements are grouped by language : One
element is allowed per language : This means that only one element
of this type is allowed per language, so the user agent must only
use the first element, in document order , that matches a language
range in the user agent's locales and ignore any subsequent
repetitions of the element that contain a matching xml:lang value
(even if the content of any proceeding matching element is
different). processed.
The term in error is used in this Step
to mean that an element element, or attribute
attribute, or file
in a configuration document
is not conforming non-conforming to the rules of this specification.
How an element or an attribute is to be treated when it is in error
is always given when the term is used. During
the processing of a configuration document , an error condition can
ask used; but will generally
require the user agent to
ignore
any element, attribute, or file that is in error. To ignore
an object (e.g., a file or a DOM node).
This means that the a user agent must act as if
that object is not present. An element
the element, attribute, or an attribute is correct if it file that is not in
error . is not
present.
To associate means that two or more
bits pieces
of information are bound and stored together for the purpose of
later processing (e.g., the name of a feature , and if it is required
, and
any associated parameters ). How associated data is represented is
left up-to the implementation (e.g., a user agent could use an
array, or an object, or a hash map, etc.).
The term text node lookup
refers algorithm
is defined in section 3.4 of [RFC4647] (part of
[BCP47]
). It is used in this Step to
any Text node, including CDATASection nodes
(any Node with node type TEXT_NODE to
match localized content in
the configuration document to the language ranges held by the user agent
locales (if any).
A CC should process a
configuration document using the algorithm to process a configuration document
.However, where an element or
CDATA_SECTION_NODE ) as defined
attribute is in error, or invalid, the [DOM3Core] conformance
checker must
inform
specification. the author.
A CC may validate a configuration document against the Relax NG for the configuration document .
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 any of the following attributes are in
error or invalid , then the user agent must ignore those
attribute.
If the id
attribute is used, let id be
the result of applying the rule for getting a
single attribute value to the id
attribute. If
id is a valid URI 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 apply applying the
rule for
parsing a non-negative integer to the value of the attribute.
If the normalized height is not in
error and greater than 0
, let widget height be the value of
normalized height . .
If the attribute is in error and the user agent must ignore it.
If the width
attribute is used, then let
normalized width be the result of apply applying the
rule for
parsing a non-negative integer to the value of the attribute.
If the normalized width is not in
error and greater than 0
, let widget width be the value of
normalized width . .
If the attribute is in error and the user agent must ignore it.
If the viewmodes
attribute is used, let
viewmodes list be the result of applying the rule for getting a
list of keywords from an attribute . From the viewmode
list , remove any unsupported
items, or and any items that are not one of the valid view modes , or and any duplicated
items. Let widget window
modes be the value of viewmodes list .
If any other attribute, attribute declared in the widget
element, in any XML namespace, apart from
xml:lang
, is used, then
the attribute is in error the user agent
must ignore it. that
attribute.
If the widget
element does not contain any child
elements, then terminate this algorithm and go to Step 8 . Otherwise, continue
this algorithm.
Let element list be an empty list.
For each range in the user agent's
agent locales , starting from
the first and moving to the last:
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's
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 all 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 uri
IRI or a valid path , then the href
attribute is
in error and the user agent must ignore it.
If potential license href
is a valid uri
IRI , then associate license href with widget license href be the value
of potential license
href . Stop processing this element and
proceed to the next element in the elements
list .
If license href is a valid path , then let license file the result of applying the
rule for
finding a file within a widget package to license href .
If license file
is not a processable file , as
determined by applying the rule for identifying
the media type of a file , then stop Stop processing
this element and proceed to the next element
in the elements list . Otherwise, associate let
widget license
file with be the value of
widget license file .
icon
element:If the src
attribute of this icon
element is missing,
absent, then the user agent must ignore this element
and its attributes. Stop processing this element and
proceed to the next element in the elements
list .
Let path be the result of applying the rule for getting a
single attribute value to the src
attribute.
attribute of this icon
element. If path is not a valid path , then the user agent must ignore this element
and its attributes. Proceed to the next element in the
elements list .
Let file be the result of applying the rule for finding a file within a widget package to path . If file is in error, then the user agent must ignore this element and its attributes. Stop processing this element and proceed to the next element in the elements list .
If file is not a processable file , as determined by applying the rule for identifying the media type of an image , or already exists in the icons list, then the user agent must ignore this element. Stop processing this element and proceed to the next element in the elements list .
Otherwise,
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
uri 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-name 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 preference-name
name is an empty string, then
this element is in error and the
user agent must ignore
it. Stop processing this element and proceed to the next
element in the elements list . Otherwise, associate name with
preference .
Let preference-value
value be the value of the
the value
attribute.
Associate the preference-value value with the
preference-name derived above.
preference .
If a readonly
attribute is used, let preference-value readonly to
be the list
result of preferences . An access element: A user agent that does
not support applying the
[Widgets-Access] specification must
ignore rule for getting a single attribute value
this element. Stop processing this element
and proceed to the next
readonly
attribute. If element readonly
in is not a
valid boolean
value ,let the value of elements list
. Otherwise, if the user agent supports the [Widgets-Access] ,
refer to readonly
be the [Widgets-Access] specification for how to process this
element. An value '
update falseelement: A user
agent that does not support the [Widgets-Updates] specification
must ignore '. Associate this attribute. Stop processing this element and proceed
to the next element
readonly in with the
elements list preference
.
Add the user
agent supports preference and the [Widgets-Updates] ,
refer to associated name ,value and
readonly variables the [Widgets-Updates] list
of widget preferences specification for how to process this
element. .
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 missing,
absent, then the user agent must ignore this element
and its attributes. Stop processing this element and
proceed to the next element in the elements
list .
Let path be the result of applying the rule for getting a
single attribute value to the 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
content-type is a valid media type , then
check if the value of content type is supported as a start file by
the user agent. If the value of content-type
is
supported by the user agent, then let the
start file
content-type be the value of content type . If value of
content-type is invalid or
unsupported by the user agent, then a
user agent must treat the widget package as an invalid Zip archive .
If the
attribute is used, then let
charset encodingcontent-charset content-encoding be the result of applying
the rule for
getting a single attribute value to the value of the
attribute. If charset encodingcontent-charset content-encoding is supported by the user agent, then let the
start file encoding
be the value of the
attribute. If
charset
encodingcontent-charset 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 feature-name required-feature be
the result of applying the rule for getting a single attribute value
to the required
attribute. If required-feature is not a valid URI
boolean value , then let the
user agent must ignore this element, its
attributes, value of
required-feature be the value ' true
'.
If feature-name is not
a valid
IRI , and its children. Stop
processing required-feature is true
,then treat this element and proceed to the next widget as an invalid Zip
archive .
If element feature-name in
is not supported by the
user agent, and elements list . required-feature is true
,then treat this widget as an invalid Zip
archive .
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
feature it.
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 this Step 8 and go to
Step 9 .
When attempting to locate a default start
file ,a user agent must attempt to locate a file entry
whose file-name
matches one of the default start files based on the order they appear in the default start
files table (from top to bottom).
File names in the default start
files table must be treated by the
user agent case-sensitively.
null
or
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 its = "http://www.w3.org/2005/11/its/"
namespace local = ""
extension = ( attr.allowed | anyElement )*
anyElement = ( element * - widgets:* { any } | text )*
any = ( attribute * { text } | anyElement )*
attr.allowed = attribute * - (local:* | xml:lang | its:dir) { text }
attr.xmllang = attribute xml:lang { xsd:language }
attr.itsdir = attribute its:dir { "ltr" | "rtl" | "lro" | "rlo" }
data.positiveNumber = xsd:string { pattern="[1-9]\d*" }
data.boolean = ( string "true" | string "false" )
start = elem.widget
elem.widget = element widget {
attr.xmllang?,
attribute id { xsd:anyURI }?,
attribute version { text }?,
attribute height { data.positiveNumber }?,
attribute width { data.positiveNumber }?,
attribute viewmodes {
list {
( "application"
| "floating"
| "fullscreen"
| "mini"
| "all" )*
}
}?,
( elem.name*
& elem.description*
& elem.icon*
& elem.author?
& elem.license*
& elem.content?
& elem.feature*
& elem.preference*
& extension )
}
elem.name = element name {
attr.xmllang?,
attr.itsdir?,
attribute short { text }?,
extension
}
elem.description = element description {
attr.xmllang?,
attr.itsdir?,
extension
}
elem.icon = element icon {
attr.allowed*,
attribute src { xsd:anyURI },
attribute height { data.positiveNumber }?,
attribute width { data.positiveNumber }?,
empty
}
elem.author = element author {
attr.xmllang?,
attr.itsdir?,
attribute href { xsd:anyURI }?,
attribute email { xsd:string { pattern=".+@.+" } }?,
extension
}
elem.license = element license {
attr.xmllang?,
attr.itsdir?,
attribute href { xsd:anyURI }?,
extension
}
elem.content = element content {
attr.allowed*,
attribute src { xsd:anyURI },
attribute type { text }?,
attribute charset { text }?,
attribute encoding { text }?,
empty
}
elem.feature = element feature {
attribute name { xsd:anyURI },
attribute required { data.boolean }?,
( elem.param?
& extension )
}
elem.param = element param {
attribute name { text },
attribute value { text },
extension
}
elem.preference = element preference {
attr.xmllang?,
attribute name { text },
attribute value { text }?,
attribute readonly { data.boolean }?,
extension
}
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 Kapyaho,
Käpyaho, Jim Ley, Jon Ferraiolo, Jose
Manuel Cantera Fonseca, Josh Soref,
Jouni Hakala, Joey Bacalhau, Kevin Lawver, Kai Hendry, Krzysztof
Maczyński, Lachlan Hunt, Marc Silbey, Marcin
Hanclik, Mark Baker, Mikko Pohja, Mohamed Zergaoui, Olli
Immonen, Philipp Heltewig, Philip Taylor, Scott Wilson, Stephen Paul Weber, Tex Texin,Thomas Landspurg, Yang Wong, Zachary
Fitz-Walter.