Copyright
©
2012
2009
W3C
®
(
MIT
,
ERCIM
,
Keio
),
All
Rights
Reserved.
W3C
liability
,
trademark
and
document
use
rules
apply.
This
specification
updates
the
Widget
Packaging
and
XML
Configuration
,
and
addresses
some
errata
found
in
the
original
recommendation.
It
also
updates
the
name
of
the
specification,
to
be
more
in
vogue
with
industry
trends
towards
the
naming
of
this
class
of
application.
This
specification
standardizes
a
packaging
format
and
metadata
for
a
class
of
software
known
commonly
as
packaged
apps
or
widgets
.
Unlike
traditional
user
interface
widgets
(e.g.,
buttons,
input
boxes,
toolbars,
etc.),
widgets
as
specified
in
this
document
widgets.
Widgets
are
full-fledged
client-side
applications
that
are
authored
using
technologies
such
as
HTML
and
then
packaged
for
distribution.
Examples
range
from
simple
clocks,
stock
tickers,
news
casters,
games
and
weather
forecasters,
to
complex
applications
that
pull
data
from
multiple
sources
to
Web
standards,
but
whose
content
can
also
be
"mashed-up"
and
presented
to
a
user
in
some
interesting
and
useful
way.
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 specification is part of the Widgets 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
https://www.w3.org/TR/.
http://www.w3.org/TR/.
This
specification
is
obsolete
the
01
December
2009
Candidate
Recommendation
of
the
Widgets
Packaging
and
should
no
longer
be
used
as
Configuration
specification
(formally
called
"Widgets
1.0:
Packaging
and
Configuration").
W3C
publishes
a
basis
for
implementation.
Candidate
Recommendation
to
indicate
that
the
document
is
believed
to
be
stable
and
to
encourage
implementation
by
the
developer
community.
The
Widget
specifications
became
W3C
Recommendations
in
2012-2013.
They
were
designed
Web
Applications
(WebApps)
Working
Group
expects
to
enable
interactive
single
purpose
application
for
displaying
and/or
updating
local
data
or
data
on
request
that
the
Web,
packaged
Director
advance
this
document
to
Proposed
Recommendation
once
the
Working
Group
has
demonstrated
at
least
two
interoperable
implementations
(interoperable
meaning
at
least
two
implementations
that
pass
each
mandatory
test
in
a
way
the
[P&C-Test-Suite]
).
The
WebApps
Working
Group
expects
to
allow
a
single
download
show
these
implementations
as
part
of
an
Implementation
Report
and
installation
advance
to
Proposed
Recommendation
after
24
January
2010.
The
Last
Call
review
period
ended
on
19
November
2009,
for
which
a
user's
machine
or
mobile
device.
disposition
of
comments
is
available.
Since
2013,
Widgets
has
had
limited
deployment
and
its
usage
has
been
reduced
since
then.
Service
Workers
Implementation
feedback
based
on
any
aspect
of
this
specification
is
welcome
and
encouraged.
This
document
is
produced
by
the
Web
App
Manifest
Applications
WG
,
part
of
the
Rich
Web
Client
Activity
are
considered
in
the
W3C
Interaction
Domain
.
It
is
expected
that
this
document
will
progress
along
the
W3C's
Recommendation
track.
Publication
as
a
Candidate
Recommendation
does
not
imply
endorsement
by
the
W3C
Membership.
This
is
a
draft
document
and
may
be
updated,
replaced
or
obsoleted
by
other
documents
at
any
time.
It
is
inappropriate
to
provide
better
solutions
nowadays.
cite
this
document
as
other
than
work
in
progress.
For
purposes
of
This
document
was
produced
by
a
group
operating
under
the
5
February
2004
W3C
Patent
Policy
this
Obsolete
Recommendation
.
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
same
status
as
an
active
Recommendation;
it
retains
licensing
commitments
individual
believes
contains
Essential
Claim(s)
must
disclose
the
information
in
accordance
with
section
6
of
the
W3C
Patent
Policy
.
You
can
find
the
latest
Editor's
Draft
of
this
document
in
the
W3C's
CVS
repository
.
The
public
is
encouraged
to
send
comments
to
the
Web
Apps
Working
Group's
public
mailing
list
public-Webapps@w3.org
(
archive
).
See
W3C
mailing
list
and
remains
available
as
a
reference
for
old
implementations
but
archive
usage
guidelines
.
A
detailed
list
of
changes
from
the
previous
version
is
no
longer
recommended
for
future
implementation.
also
available
from
the
W3C's
CVS
server.
dir
widget
width
name
name
description
Element
author
Element
license
Element
icon
Element
content
Element
feature
Element
param
Element
preference
Element
span
its:span
application/widget
This section is non-normative.
Widgets
are
full-fledged
client-side
applications
that
are
authored
using
Web
standards
such
as
[HTML]
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
documented
in
the
Widgets
1.0
Requirements
[Widgets-Requirements]
[Widgets-Reqs]
document.
This document addresses the 25 requirements relating to " Packaging " and " Configuration Document " of the 30 April 2009 Working Draft of the Widgets 1.0: Requirements Document:
author
element.
license
element.
widget
element.
content
element.
icon
element,
default
icons
table
and
custom
icons
table
.
param
element
(used
in
conjunction
with
the
feature
element).
preference
element.
feature
element.
viewmodes
attribute
of
the
widget
element.
This section is non-normative.
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 . 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. Some text in this specification is non-normative. Non-normative text includes:
This section is non-normative,
Everything else in this specification is normative.
Defined terms appear as this sample defined term . Such terms are referenced as sample defined term , providing a link back to the term definition.
Words that denote a conformance clause or testable assertion use keywords from [RFC2119] : must , must not , should , recommended , may and optional . The keywords must , must not , should , recommended , may and optional in this specification are to be interpreted as described in [RFC2119] .
Variables
are
formatted
specially,
e.g.
variable
.
Code
is
also
specially
formatted,
such
as
code
.
Words in italics denote a formal definition given in an external specification.
This is an example. Examples are used to explain concepts or demonstrate how to use a feature. Examples are non-normative.
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 family of specifications , which together standardize widgets as a whole. The list of specifications that make up the Widgets Family of Specifications can be found on the Working Group's wiki.
There is only one class of product that can claim conformance to this specification: a user agent .
Note: Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the [P&C-Test-Suite] . Note, however, that passing all the tests in the test suite does not imply complete conformance to this specification; It only implies that the implementation conforms to aspects tested by the test suite (the test suite does not provide tests for any optional conformance clauses).
The following terms are used throughout this specification so they are gathered here for the readers convenience. The following list of terms is not exhaustive; other terms are defined throughout this specification.
Arbitrary
means
that
a
character,
or
text
string,
or
file-name
,
or
folder-name
is
not
reserved
for
the
purpose
of
this
specification.
An author is a person who created a widget package or an authoring tool that generated a widget package .
Initialization means a user agent procedurally stepping through the steps for processing a widget package .
A
language
tag
is
a
text
string
that
matches
the
production
of
a
Language-Tag
defined
in
the
[BCP47]
specifications
(see
the
IANA
Language
Subtag
Registry
for
an
authoritative
list
of
possible
values,
see
also
the
Maintenance
Agency
for
ISO
3166
country
codes
).
specifications.
A media type is defined in the [MIME] specification.
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
reserved
thing
reservation
is
given
when
the
term
is
used.
Supported means that a user agent implements a mentioned specification, or conformance clause, or is able to process or otherwise render mentioned media type .
Unsupported means the user agent does not implement a mentioned specification, or feature , or is unable to render or otherwise process a mentioned media type .
A
widget
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]
.
This section groups common sets of [Unicode] code points into definitions for the purpose processing in this specification.
The
space
characters
are
code
points
marked
in
the
[Unicode]
specification
with
the
property
"White_Space",
including,
but
not
limited
to
the
following
list
(see
[Unicode]
for
the
authoritive
list):
points:
The Unicode white space characters are code points marked in the [Unicode] specification with the property "White_Space", including:
The
Zip
forbidden
control
characters
are
code
points:
The forbidden characters are code points:
A
user
agent
is
an
implementation
of
this
specification
that
also
supports
[XML]
,
[XMLNS]
,
[UTF-8]
,
[Unicode]
,
[DOMCore]
[DOM3CORE]
,
[SNIFF]
,
and
[ZIP]
(see
optional
aspects
of
the
Zip
specification
).
In addition to widget packages , a user agent may support other legacy and proprietary application packaging formats.
It is optional for a user agent to support the optional aspects of the Zip specification .
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 Family of Specifications . The user agent described is this specification is only concerned with how to processes Zip archives and configuration documents .
The optional aspects of the Zip specification are as follows. These aspects represent general features defined in the [ZIP] specification that this specification does not make use of:
Compression or decompression algorithms other than [Deflate] and Stored .
Zip64 extensions.
Digital signature methods.
Decryption methods.
Patented aspects.
To
facilitate
the
localization
of
text
nodes
within
[XML]
elements
in
a
configuration
document
,
a
user
agent
may
support
the
Internationalization
Tag
Set's
(
[ITS]
)
its:span
element
and
the
its:dir
attribute.
It
is
optional
for
a
user
agent
to
support
other
[ITS]
elements
and
attributes.
Note:
Although
this
specification
defines
the
elements
of
the
configuration
document
in
which
its:span
element
and
the
its:dir
attribute
can
be
used,
the
specification
does
not
define
how
those
elements
are
to
be
interpreted
and
processed
by
a
user
agent.
If
a
user
agent
implements
its:span
and
its:dir
,
then
the
user
agent
must
do
so
in
conformance
with
the
processing
rules
defined
by
the
[ITS]
specification.
The Zip archive file format, defined in the [ZIP] specification, is the packaging format for .
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 or folder 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
the
user
agent
has
verified
as
conforming
to
the
production
of
a
.Zip
.Zip
file
as
defined
by
the
Zip
File
Format
Specification
[ZIP]
and
meets
the
requirements
of
this
specification
(See
(see
Step
2
1
).
The
magic
numbers
for
a
Zip
archive
is
the
byte
sequence:
50
4B
03
04
.
A compression method is the compression algorithm or storage method that was used to encode the file data of a file entry when the zip archive was created by the author. The compression method that encoded 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
The version needed to extract is the 2-byte sequence in the local file header of a file entry that indicates the minimum supported version of the [ZIP] specification needed to extract the file data .
The valid versions needed to extract values are as follows. Each value is assigned one or more meanings by the [ZIP] specification:
Default value specified in the [ZIP] specification.
The file data is compressed using [Deflate] , or the file data is a folder, or the file has been encrypted using traditional PKWARE encryption.
Note: If the Zip archive has been encrypted using traditional PKWARE encryption, then the user agent will treat the Zip archive as an invalid widget package in Step 2 .
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.
A
valid
Zip
relative
path
is
one
that
matches
the
production
of
Zip-rel-path
in
the
following
[ABNF]
:
Zip-rel-path = [locale-folder] *folder-name file-name /
[locale-folder] 1*folder-name
locale-folder = %x6C %x6F %x63 %x61 %x6C %x65 %x73
"/" lang-tag "/"
"/" language-range "/"
folder-name = file-name "/"
file-name = 1*allowed-char
allowed-char = safe-char / zip-UTF8-char
zip-UTF8-char = UTF8-2 / UTF8-3 / UTF8-4
= ALPHA / DIGIT / SP / "$" / "%" /
safe-char = ALPHA / DIGIT / SP / "$" / "%" /
"'" / "-" / "_" / "@" / "~" /
"(" / ")" / "&" / "+" / "," /
"=" / "[" / "]" / "."
UTF8-2 = %xC2-DF UTF8-tail
UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2( UTF8-tail ) /
%xED %x80-9F UTF8-tail / %xEE-EF 2( UTF8-tail )
UTF8-4 = %xF0 %x90-BF 2( UTF8-tail ) / %xF1-F3 3( UTF8-tail ) /
%xF4 %x80-8F 2( UTF8-tail )
UTF8-tail = %x80-BF
= 1*8(alphanum)
= %x61-7a
language-range = (1*8low-alpha / "*") *("-" (1*8alphanum / "*"))
alphanum = low-alpha / DIGIT
low-alpha = %x61-71
ALPHA
,
DIGIT
,
and
SP
are
defined
in
the
[ABNF]
specification
(but
essentially
represent
alphanumerical
characters
and
the
U+0020
SPACE
code
point
respectively).
This section is non-normative.
Some issues can arise with regards to character encodings of file names, the length of zip relative paths, and the use of certain strings as file names. This sections is intended to help authors avoid potential interoperability issues.
A widget package is a valid Zip archive that contains the following:
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.
During the steps for processing a widget package , certain error conditions can result in a Zip archive being treated as an invalid widget package . An invalid Widget package 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.
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 ).
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 ).
A
folder
is
a
file
entry
whose
file
name
field
matches
the
production
of
folder-name
in
a
valid
Zip
relative
path
(the
last
character
of
the
file
name
field
is
a
U+002F
SOLIDUS)
and
whose
version
needed
to
extract
is
2.0.
A processable file is a file that:
Exists within the mentioned widget package .
When
the
rule
for
verifying
a
file
entry
is
applied
to
the
file,
it
returns
true
.
Is of a media type supported by the user agent, determined applying the rule for identifying the media type of a file to the file in question.
The reserved file names table , below, contains a list of file names that are reserved for some purpose by this specification. The first column of the reserved file names table contains a case-sensitive list of file names. The second column of the table denotes the purpose for which the file name is reserved .
file name | Type | reserved for purpose |
---|---|---|
config.xml | file | Configuration document |
icon.png | file | Default icon |
icon.gif | file | Default icon |
icon.jpg | file | Default icon |
icon.ico | file | Default icon |
icon.svg | file | Default icon |
index.html | file | Default start file |
index.htm | file | Default start file |
index.svg | file | Default start file |
index.xhtml | file | Default start file |
index.xht | file | Default start file |
locales | folder | Container for localized content |
Files
named
using
the
naming
convention
conventions
for
distributor
signature
signatures
and
the
naming
convention
for
an
author
signature
,
as
defined
in
the
[Widgets-DigSig]
specification,
are
also
reserved
in
this
specification.
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.
A start file designates a file from the widget package to be loaded by the user agent when it instantiates the widget. This specification defines two kinds of start file: custom start file and default start file .
A
custom
start
file
is
a
processable
file
inside
the
widget
package
identified
by
a
content
element's
src
attribute.
A default start file is a reserved start file at the root of the widget package or at the root of a locale folder whose file name case-sensitively matches a file name given in the file name column of the default start files table , and whose media type matches the media type given in the media type column of the table.
It is optional for a user agent to support the media types listed in the default start files table .
If a user agent encounters a file matching a file name given in the file name column of the default start files table in an arbitrary folder , then user agent must treat that file as an arbitrary file.
For
example,
"
foo/bar/index.html
"
would
be
treated
as
an
arbitrary
file
.
file name | media type |
---|---|
index.htm | text/html |
index.html | text/html |
index.svg | image/svg+xml |
index.xhtml | application/xhtml+xml |
index.xht | application/xhtml+xml |
Note: See Step 8 for instructions on finding a default start file .
An
icon
is
a
file
that
is
used
to
represent
the
widget
in
various
application
contexts
(e.g.
the
icon
that
the
user
activates
actives
to
instantiate
a
widget,
or
an
icon
in
a
dock
or
task
bar
or
some
other
visual
context).
The
icon
is
intended
to
help
users
of
visual
browsers
to
recognize
the
widget
at
a
glance.
There
are
two
kinds
of
icons
defined
by
this
specification,
custom
icons
and
default
icons
.
A
custom
icon
is
an
icon
explicitly
declared
by
an
author
via
an
icon
element
in
a
configuration
document
.
A
custom
icon
can
be
located
at
the
root
of
the
widget
package
,
or
at
the
root
of
a
locale
folder
,
or
in
an
arbitrary
folder
.
A default icon is a reserved icon , either at the root of the widget package or at the root of a locale folder , whose file name case-sensitively and exactly matches a file name given in the file name column of the default icons table .
file name | media type |
---|---|
icon.svg | image/svg+xml |
icon.ico | image/vnd.microsoft.icon |
icon.png | image/png |
icon.gif | image/gif |
icon.jpg | image/jpeg |
It is optional for a user agent to support the media types listed in the default icons table .
The
valid
widget
media
type
is
the
string
application/widget
.
A
widget
file
extension
is
the
text
string
that
case-insensitively
matches
the
string
"
.wgt
"
(e.g.
.wgt
,
.WGt
,
.WgT
,
etc.
are
all
valid).
For
example
in
widget.WGT
,
the
".WGT
"
component
is
the
file
extension.
A
configuration
document
is
an
[XML]
document
that
has
a
widget
element
at
its
root
that
is
in
the
widget
namespace
.
A
widget
package
has
exactly
one
configuration
document
located
at
the
root
of
the
widget
package
.
Note: Please see Step 7 for details of how the elements of the configuration document are processed by a user agent.
A
valid
configuration
document
file
name
is
the
string
config.xml
.
It is optional for authors to use the attributes of elements.
A
user
agent
must
treat
any
file
in
an
arbitrary
folder
or
locale
folders
that
uses
the
file
name
config.xml
as
an
arbitrary
file.
The following is an example of a typical 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 = "fullscreen">
viewmodes = "widget">
<name short="Example 2.0">
The example Widget!
</name>
<feature name="http://example.com/camera">
<param name="autofocus" value="true"/>
<param name="autofocus" value="true"/>
</feature>
<preference name = "apikey"
value = "ea31ad3a23fd2f"
readonly = "true" />
<description>
A sample widget to demonstrate some of the possibilities.
</description>
<author href = "http://foo-bar.example.org/"
email = "foo-bar@example.org">Foo Bar Corp</author>
<icon src="icons/example.png"/>
<icon src="icons/boo.png"/>
<content src="myWidget.html"/>
<license>
Example license (based on MIT License)
Copyright (c) 2008 The Foo Bar Corp.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</license>
</widget>
Note: Implementers are encouraged to expose relevant information provided by the configuration document to the user. Having "visual metadata" encourages authors to make full use of the configuration document format. See Step 7 for instructions on how to process a configuration document.
The
widget
namespace
URI
for
a
configuration
document
is
http://www.w3.org/ns/widgets
[XMLNS]
.
This section is non-normative .
Implementers
or
authors
intending
to
extend
the
configuration
document
format
with
their
own
[XML]
elements
and
attributes
(or
those
defined
in
other
specifications)
can
do
so
by
using
a
separate
[XMLNS]
namespace.
This
specification
does
not
define
a
model
for
processing
[XML]
elements
outside
the
widget
namespace
(they
are
simply
ignored
during
processing).
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="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>
This section defines the different attribute types used in the configuration document and what constitutes valid values for those attribute types.
An attribute is invalid if its value does not conform to its said attribute type ; that is, if the value of the attribute is in error given the processing rules for that type of attribute.
A
boolean
attribute
is
a
keyword
attribute
that
can
only
be
used
with
a
valid
boolean
value.
A
valid
boolean
value
is
a
keyword
that
case-sensitively
matches
true
or
false
.
Unless
specified
otherwise,
the
default
behavior,
which
is
used
when
the
attribute
is
omitted
or
has
a
value
other
than
the
two
allowed
values,
is
false
.
The
way
a
user
agent
interprets
a
boolean
attribute
is
defined
as
part
of
an
attribute's
definition
(see,
for
example,
the
feature
element's
required
attribute).
A 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 in the case given in this specification.
An attribute defined as taking one or more keywords as a value, which are separated by space characters .
An
attribute
whose
value
is
defined
as
containing
a
valid
media
type.
A
valid
media
type
is
string
that
matches
the
production
for
valid-MIME-type
in
the
following
[ABNF]
:
valid-MIME-type
=
type
"/"
subtype
*(";"
parameter)
The
type
,
subtype
,
and
parameter
tokens
are
defined
in
the
[MIME]
specification.
The value of a numeric attribute is a string containing a valid non-negative integer. A valid non-negative integer is a string that consists of one or more code points in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). For example, the strings "002", "323", "23214", and so on.
An
attribute
defined
as
containing
a
valid
path.
A
valid
path
is
one
that
matches
the
production
of
a
Zip-rel-path
or
a
Zip-abs-path
.
A
Zip
absolute
path
is
one
that
case-insensitively
matches
the
production
of
Zip-abs-path
in
the
following
[ABNF]
:
Zip-abs-path = "/" Zip-rel-path
An
attribute
defined
as
containing
a
valid
IRI.
A
valid
IRI
is
one
that
matches
the
IRI
token
of
the
[IRI]
specification.
A
displayable-string
attribute
whose
The
value
of
a
version
attribute
is
any
arbitrary
string
value
(possibly
empty)
within
the
constraints
allowed
for
[XML]
attributes.
This
specification
does
not
mandate
any
specific
format,
semantics,
or
special
processing
rule
for
the
format
of
a
version
attribute
.
This
section
describes
the
behavior
and
expected
usage
of
other
relevant
attributes
that
are
part
of
the
[XML]
specification
and
this
specification.
In
this
specification,
these
attributes
are
referred
to
as
global
attributes
because
they
can
be
used
on
any
element
in
a
configuration
document
.
Although
global
attributes
can
be
used
on
any
element
in
this
specification,
they
sometimes
have
no
effect
on
the
element
on
which
they
are
used.
For
example,
applying
dir
attribute
on
an
icon
element
will
have
no
effect
on
the
icon
elements
or
any
of
its
attributes.
What
effect
specifying
a
global
attribute
has
on
an
elements
is
determined
by
Step
7
[ITS]
of
this
specification.
xml:lang
A
language
keyword
attribute
that
specifies,
through
defined
as
containing
a
language
tag
,
the
language
of
the
contents
and
attribute
values
of
XML
elements
(see
the
IANA
Language
Subtag
Registry
).
.
The
[XML]
specification
specifies
defines
the
xml:lang
attribute
and
its
influence
on
the
child
nodes.
dir
its:dir
A
keyword
attribute
used
to
specify
the
directionality
in
which
human-readable
text
is
to
be
represented
by
defined
as
containing
a
user
agent
(e.g.,
the
text
content
of
the
name
element,
the
description
element,
and
the
license
element).
The
directionality
set
by
the
dir
attribute
applies
to
the
text
content
and
any
displayable
string
attributes
of
the
element
where
it
is
used,
and
to
child
elements
in
its
content
unless
overridden
with
another
instance
of
dir
(i.e.,
in
this
specification,
the
valid
dir
attribute
only
affects
the
short
attribute
of
the
name
element
and
to
the
version
attribute
of
the
widget
its:dir
element).
The
possible
value
of
a
dir
attribute
is
one
of
the
valid
directional
indicators
:
(i.e.,
ltr
,
Left-to-right
text.
Request
that
the
Unicode
[BIDI]
algorithm
treat
characters
within
an
element
as
embedded
left-to-right.
rtl
,
Right-to-left
text.
Request
that
the
Unicode
[BIDI]
algorithm
treat
characters
within
an
element
as
embedded
right-to-left.
lro
,
or
Left-to-right
override.
Forces
the
Unicode
[BIDI]
algorithm
to
treat
characters
within
an
element
as
strong
left-to-right
characters.
rlo
Right-to-left
override.
Forces
the
Unicode
[BIDI]
algorithm
to
treat
characters
within
an
element
as
strong
right-to-left
characters.
).
widget
Element
The
widget
element
serves
as
a
container
for
the
other
elements
of
the
configuration
document
.
widget
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.
content
:
zero
or
one.
feature
:
zero
or
more.
preference
:
zero
or
more.
viewmodes
xml:lang
.
will
be
treated
as
if
xml:lang
had
not
been
inherited).
widget
Element
id
An IRI attribute that denotes an identifier for the widget.
version
A version attribute that specifies the version of the widget.
height
A
numeric
attribute
greater
than
0
that
indicates
the
preferred
viewport
height
of
the
instantiated
custom
start
file
in
CSS
pixels
[CSS]
[CSS21]
.
width
A
numeric
attribute
greater
than
0
that
indicates
the
preferred
viewport
width
of
the
instantiated
custom
start
file
in
CSS
pixels
[CSS]
[CSS21]
.
viewmodes
A
keyword
list
attribute
that
denotes
the
author's
preferred
view
mode,
followed
by
the
next
most
preferred
view
mode
and
so
forth.
When
the
attribute
is
missing,
or
is
left
empty,
it
implies
that
the
author
expects
the
user
agent
to
select
an
appropriate
viewmode
for
the
widget.
The
concept
of
a
viewport
Viewport
is
defined
in
[CSS]
,
but
is
essentially
a
window
or
other
viewing
area
on
the
screen
(see
section
9.1.1
The
viewport
of
[CSS]
).
The
concept
of
a
and
view
mode
is
are
defined
in
the
[View-Modes]
[Widgets-Views]
specification.
attribute
A
language
attribute
that
specifies,
through
a
language
tag
,
the
author's
preferred
locale
for
the
widget.
Its
intended
use
is
to
provide
a
fallback
in
case
the
user
agent
cannot
match
any
of
the
widget's
localized
content
xml:lang
to
the
user
agent
locales
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
=
"windowed
floating"/
id = "http://example.org/exampleWidget"
version = "2.0 Beta"
height = "200"
width = "200"
viewmodes = "application">
>
</widget>
name
Element
The
name
element
represents
the
full
human-readable
name
for
a
widget
that
is
used,
for
example,
in
an
application
menu
or
in
other
contexts.
widget
element.
xml:lang
:
name
Element
xml:lang
its:dir
short
A
displayable-string
attribute
intended
to
represent
string
that
represents
a
condensed
name
for
a
widget
(e.g.,
a
name
that
could
be
used
in
context
were
only
limited
space
is
available,
such
as
underneath
an
icon).
The
following
example
shows
the
usage
of
the
name
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
The Ultimate Weather Widget
</name>
<name short="Boletim" xml:lang="pt">
Boletim Metereológico
</name>
</widget>
description
Element
The
description
element
represents
a
human-readable
description
of
the
widget.
widget
element.
xml:lang
:
description
Element
xml:lang
attribute
value
are
encountered,
the
user
agent
will
ignore
all
but
its:dir
An example usage of the description element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name>Dahut Chaser</name>
<description>
Combining the latest weather info with your GPS position,
this widget alerts you of any significant dahut activity in your
area. When a big one walks by, the widget plots the best route on a map based
on the dahut's trajectory so you can chase it! With support for
built-in cameras, you can quickly upload all the Alpine action to
your blog or to the insane dahut chaser web site! Awesome!
</description>
</widget>
author
Element
An
author
element
represents
people
or
an
organization
attributed
with
the
creation
of
the
widget.
widget
element.
xml:lang
:
xml:lang
(if
any).
author
Element
href
An IRI attribute whose value represents an IRI that the author associates with himself or herself (e.g., a homepage, a profile on a social network, etc.).
email
A
string
attribute
that
represents
an
email
address
associated
with
the
author.
its:dir
The
following
example
shows
the
expected
usage
of
the
author
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name>Café Finder</name>
<author href = "http://dahut.example.org/developers/"
email = "cafefinder@example.org">
Mr. Jo and Julia Bacalhau
Joey and Princesa Bacalhau
</author>
</widget>
license
Element
The
license
element
represents
a
software
license
,
which
includes,
for
example,
a
usage
agreement,
redistribution
statement,
and/or
a
copyright
license
terms
under
which
the
content
of
the
widget
package
is
provided.
widget
element.
xml:lang
:
license
Element
href
A valid IRI or a valid path that points to a representation of a software and/or content license.
xml:lang
its:dir
This
example
shows
the
expected
usage
of
the
license
element's
href
attribute.
<widget xmlns="http://www.w3.org/ns/widgets">
<license href="http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231">
Distributed under the W3C Software License.
W3C Software 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>
...
3.3.1 Widgets can use any APIs or libraries, prescribed by anyone.
Widgets a are a free and open Web technology, so can be produced for free
and sold anywhere. Widgets can be written in JavaScript
so can run on any conforming engine (without the annoying restrictions of
C, C++, or Objective-C). You can even "cross-compile" them, if you want.
...
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
Element
The
icon
element
represents
a
custom
icon
for
the
widget.
widget
element.
xml:lang
:
icon
Element
src
A path attribute that points to a file inside the widget package.
width
A
numeric
attribute
greater
than
0
that
represents,
in
CSS
pixels
[CSS]
[CSS21]
,
the
author's
preferred
width
for
the
icon.
A
user
agent
may
ignore
this
value
when
changing
the
height
icon
to
fit
a
rendering
context
or
for
accessibility
reasons.
height
A
numeric
attribute
greater
than
0
that
represents,
in
CSS
pixels
[CSS]
[CSS21]
,
the
author's
preferred
height
for
the
icon.
A
user
agent
may
ignore
this
value
when
changing
the
height
icon
to
fit
a
rendering
context
or
for
accessibility
reasons.
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>
content
Element
The
content
element
is
used
by
an
author
to
declare
which
custom
start
file
the
user
agent
is
expected
to
use
when
it
instantiates
the
widget.
widget
element.
xml:lang
:
content
Element
src
A path attribute that allows an author to point to a file within the widget package .
type
A
media
type
attribute
that
indicates
the
media
type
of
the
file
referenced
by
the
src
attribute.
encoding
A
keyword
attribute
that
denotes
the
character
encoding
of
the
file
identified
by
the
src
attribute.
The
value
is
the
"name"
or
"alias"
of
any
"Character
Set"
listed
in
[IANA-Charsets]
.
The
default
encoding
is
[UTF-8]
,
which
has
the
name
"
UTF-8
"
in
the
[IANA-Charsets]
registry.
Aside from the default encoding , it is optional for a user agent to support other character encodings.
This
example
shows
the
expected
usage
of
the
content
element:
<widget xmlns="http://www.w3.org/ns/widgets">
<content src="myWidget.html"/>
</widget>
This
example
shows
the
content
element
being
used
with
a
encoding
attribute
to
override
the
default
value
of
the
encoding
attribute
(
UTF-8
)
with
the
GB2312
character
set,
which
the
author
has
used
to
encode
simplified
Chinese
characters:
<widget xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="zh-cn">古老瓷地图</name>
<name>Ancient Chinese Maps</name>
<content src="china-maps.html" encoding="GB2312"/>
</widget>
This
example
shows
the
content
element
being
used
with
a
type
attribute
to
instantiate
a
widget
created
with
a
proprietary
media
type
:
<widget xmlns="http://www.w3.org/ns/widgets">
<name>Location-Based Games Finder</name>
<content src="lbg-maps.swf" type="application/x-shockwave-flash"/>
<feature name="http://example.org/api.geolocation"
required="false"/>
</widget>
feature
Element
A
feature
is
a
URI
identifiable
runtime
component
(e.g.
an
Application
Programming
Interface
or
video
decoder).
The
act
of
a
an
author
requesting
the
availability
of
a
feature
through
a
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
is
referred
to
as
a
feature
request
.
The
feature
feature
element
denotes
that,
at
runtime,
a
widget
can
attempt
to
access
the
feature
identified
by
the
feature
element's
name
attribute.
How
a
user
agent
makes
use
of
features
depends
on
the
user
agent's
security
policy,
hence
activation
and
authorization
requirements
for
features
are
beyond
the
scope
of
this
specification.
A
feature
has
zero
or
more
parameters
associated
with
it.
widget
element.
param
elements.
xml:lang
:
feature
Element
name
An IRI attribute that identifies a feature that is needed by the widget at runtime (such as an API ).
required
A boolean attribute that indicates whether or not this feature has to be available to the widget at runtime.
When
set
to
true
,
the
required
attribute
denotes
that
a
feature
is
absolutely
needed
by
the
widget
to
function
correctly,
and
without
the
availability
of
this
feature
the
widget
serves
no
useful
purpose
or
won't
execute
properly.
When
set
to
false
,
the
required
attribute
denotes
that
a
widget
can
function
correctly
without
the
feature
being
supported
or
otherwise
made
available
by
the
user
agent.
This example demonstrates a widget that would like to use a fictional geo-location API feature, but would still be able to function if the feature cannot be made available to the widget by the user agent.
<widget xmlns="http://www.w3.org/ns/widgets">
<feature name = "http://example.org/api/geolocation"
required = "false"/>
</widget>
param
Element
The
param
element
defines
a
parameter
for
a
feature
.
A
parameter
is
a
name-value
pair
that
is
associated
with
the
corresponding
feature
for
which
the
parameter
is
declared
for.
A
author
establishes
the
relationship
between
a
parameter
and
feature
by
having
a
param
element
as
a
direct
child
of
a
feature
element
in
document
order
.
feature
element.
xml:lang
:
param
Element
name
A
string
attribute
that
denotes
the
name
of
this
parameter
.
value
A
string
attribute
that
denotes
the
value
of
this
parameter
.
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">
<feature name="http://example.org/api.geolocation">
<param name="accuracy" value="low"/>
</feature>
</widget>
preference
Element
The
preference
element
allows
authors
to
declare
one
or
more
preferences:
a
preference
is
a
persistently
stored
name-value
pair
that
is
associated
with
the
widget
the
first
time
the
widget
is
initiated.
Note: A user agent that supports the [Widgets-APIs] specification will expose any declared preference at runtime in the manner described in the [Widgets-APIs] specification.
widget
element.
xml:lang
:
preference
Element
name
A string that denotes the name of this preference .
value
A string that denotes the value of this preference .
readonly
A
boolean
attribute
indicating
whether
this
preference
can,
or
cannot,
be
overwritten
at
runtime
(e.g.,
via
an
author
script).
When
set
to
true
,
it
means
that
the
preference
cannot
be
overwritten.
When
set
to
false
,
it
means
that
the
preference
can
be
overwritten.
This
example
shows
a
widget
where
two
preferences
are
set.
The
second
preference
is
set
as
"read
only"
via
the
readonly
attribute,
which
means
the
values
of
that
preference
cannot
be
changed
at
runtime.
<widget xmlns="http://www.w3.org/ns/widgets">
<preference name = "skin"
value = "alien"/>
<!-- The preference below will be protected
from modification and deletion at runtime -->
<preference name = "api-key"
value = "f6d3a312f9d742"
readonly = "true"/>
</widget>
span
its:span
The
span
This
section
is
informative.
element
Internationalization , or i18n, is the design and development of a product, application or document content that enables 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.
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 .
Default
Unlocalized
content
is
content
included
in
the
widget
package
or
in
the
configuration
document
that
has
not
been
explicitly
localized
or
content
explicitly
indicated
by
the
author
to
be
used
as
default
content
via
the
defaultlocale
attribute
of
the
widget
element.
localized.
In
the
case
of
a
widget
package
,
package,
this
means
content
outside
the
container
for
localized
content
.
In
the
case
of
a
configuration
document
,
document,
this
means
any
element
without
an
explicitly
declared
or
inherited
xml:lang
attribute.
A localized file is any file that has been placed inside a locale folder (i.e., localized content that makes use of folder-based localization ). A widget package contains 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-range
ABNF
rule
of
this
language
tag
as
defined
in
the
[BCP47]
specification.
That
is,
by
naming
folders
in
lower-case
using
values
derived
from
the
IANA
Language
Subtag
Registry
such
as
"
en-us
",
"
en-gb
",
and
so
on,
but
avoiding
subtags
marked
as
deprecated
,
grandfathered
,
or
redundant
in
the
IANA
Language
Subtag
Registry
.
These
locale
folders
are
then
placed
inside
the
container
for
localized
content
.
The
container
for
localized
content
is
a
reserved
folder
at
the
root
of
the
widget
package
whose
folder-name
case-sensitively
matches
the
string
'
locales
'.
A
container
for
localized
content
contains
zero
or
more
locale
folders
.
A
locale
folder
is
a
folder
whose
file
name
field
matches
the
production
of
locale-folder
and
is
a
direct
descendant
of
the
container
for
localized
content
(e.g.,
"
/locales/en-us
",
"
/locales/fr
",
etc).
A
locale
folder
contains
zero
or
more
arbitrary
folders
and/or
files.
This
specification
defines
the
concept
of
element-based
localization
,
which
allows
authors
to
use
the
xml:lang
attribute
to
explicitly
indicate
that
an
[XML]
element
in
the
configuration
document
has
been
localized
.
The following is an example of element-based localization:
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
The Ultimate Weather Widget
</name>
<name short="Boletim" xml:lang="pt">
Boletim Metereológico
</name>
</widget>
Some
of
the
elements
in
the
widgets
namespace
are
defined
to
be
localizable
via
xml:lang
as
part
of
the
element's
definition
(with
either
"yes"
or
"no").
See,
for
example,
the
name
element.
When
"yes",
it
.
This
means
that
they
will
be
processed
in
a
specific
manner
if
they
have
an
author
can
utilize
xml:lang
to
achieve
element-based
localization
either
directly
value
(directly
or
indirectly
through
the
inheritance
of
the
value
of
xml:lang
.
How
element-based
localization
is
handled
is
specified
inheritance),
as
described
in
detail
in
Step
7
.
Note:
The
xml:lang
attribute
can
be
used
on
any
element
in
order
to
indicate
which
language
is
used
in
the
content
and
attribute
values
of
that
element.
As
specified
in
the
XML
Specification,
its
value
is
inherited,
such
that
if
an
element
has
an
xml:lang
attribute,
all
of
its
descendants
are
considered
to
be
in
that
language
as
well,
unless
they
specify
their
own
xml:lang
attribute.
Note
that
an
element
can
indicate
that
it
is
in
no
specific
language
by
setting
xml:lang
to
the
empty
string,
irrespective
of
whether
any
of
its
ancestors
has
an
xml:lang
attribute.
For
example,
if
an
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.
Finally,
the
last
name
element
overrides
xml:lang
with
an
empty
string,
so
that
element
will
be
treated
by
the
user
agent
as
default
unlocalized
content
.
<widget xmlns="http://www.w3.org/ns/widgets"
xml:lang="en">
<name short="I'm in english, though not explicitly marked as such!">
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>
</name>
<name xml:lang="">
The user agents will treat this as unlocalized content.
</name>
</widget>
If
an
element
is
marked
as
being
localizable
via
xml:lang
with
"yes",
the
specification
indicates
that
only
one
element
is
allowed
per
language
:
One
element
is
allowed
per
language
means
that
only
one
element
of
a
type
is
allowed
to
be
used
per
language
(e.g.,
although
many
name
elements
can
be
present
in
a
configuration
document
,
only
one
name
element
will
be
selected
by
the
user
agent
for
the
English
language).
During
processing
(
Step
7
),
the
user
agent
will
only
match
the
first
element,
in
document
order
,
that
matches
a
language
range
in
the
user
agent
locales
and
ignore
any
subsequent
repetitions
of
the
element
that
contain
a
matching
xml:lang
value
(even
if
that
element's
content
is
different).
For
example,
assume
the
user
agent
locales
only
contains
the
following
language
range:
"
en-us
"
(English
as
used
in
the
United
States).
As
only
one
instance
of
the
description
element
is
allowed
per
language,
in
the
following
code
the
user
agent
would
match
the
first
description
element
but
would
ignore
the
second
and
third
description
elements.
<widget xmlns="http://www.w3.org/ns/widgets">
<description xml:lang="en">
This element would be used.
</description>
<description xml:lang="en">
This element would be ignored because there is already
a description element that uses xml:lang="en".
</description>
<description>
This element is unlocalized, and would be used if the user agent's
locale does not match any localized description elements.
</description>
<description xml:lang="">
This element would be ignored because there is already an unlocalized
This element would be ignored because there is already an unlocalized
description element! Using xml:lang="" makes this element behave as if
it is unlocalized.
</description>
</widget>
However,
if
the
user
agent
locales
only
contained
"
*
",
or
did
not
match
any
of
the
localized
description
elements,
then
the
user
agent
would
match
the
third
description
element
above.
In
the
case
whereby
the
author
does
not
use
an
xml:lang
attribute,
and
no
element
of
a
particular
type
with
xml:lang
matches
the
user
agent
locales
,
the
user
agent
will
use
the
first
element
that
is
default
unlocalized
content
,
in
document
order
,
that
matches
the
element
type
being
sought.
For
example,
now
assume
that
the
user
agent
locales
only
contains
the
following
language
range:
"
jp
"
(Japanese).
As
only
one
instance
of
the
description
element
is
allowed
per
language,
in
the
following
code
the
user
will
agent
ignore
the
first
two
description
elements,
but
would
match
the
third
(unlocalized)
description
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<description xml:lang="en">
This element would be ignored.
</description>
<description xml:lang="en">
This element would be ignored.
</description>
<description>
In this case, this unlocalized element would be used.
</description>
</widget>
</widget>
This section is non-normative.
This section presents three examples of how widgets can be localized. Each example is intended to showcase how the localization algorithm is intended to work.
This
example
shows
a
widget
that
displays
the
days
of
the
week
based
on
the
language
ranges
held
by
the
user
agent
locales
.
If
the
user
agent
is
unable
to
match
a
language
range
to
any
locale
folder
,
the
widget
displays
/index.html
at
the
root
of
the
widget
package
.
config.xml
<widget xmlns="http://www.w3.org/ns/widgets">
<name>What day is it?</name>
<description>
This widget highlights the current day
of the week.
</description>
</widget>
locale/es/index.html
<!doctype html>
<title>¿Qué día es?</title>
<script src="scripts/dayfinder.js"></script>
<body>
<p>Hoy es: lunes, martes, miércoles,
jueves, viernes, sábado,
domingo
The following is an example of a localized widget with multiple localized icons , start files and configuration documents . Some relevant things to note from the example:
locales/es/
)
has
its
own
localized
icon.
locales/es
)
and
English
(
locales/en/
)
versions
of
the
widget
use
the
un-localized
script
in
/scripts/engine.js
folder.
en-au
)
version
uses
a
localized
script
(
en-au/scripts/engine.js
).
/config.xml
<widget xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="ko">웃기는 고양이</name>
<content src="cats.html"/>
</widget>
/locales/en-au/cats.html
<!doctype html>
<title>G'day! LOL Cats!</title>
<script src="scripts/engine.js">
...
/locales/es/cats.html
<!doctype html>
<title>Gatos Graciosos!</title>
<script src="scripts/engine.js">
...
This specification allows authors to place files and folders they don't wish to localize at the root of the widget package. At runtime, if the user agent fails to find a file in a locale folder , it will always search at the root of the widget package for that missing file. The purpose of this 'fallback' model is to reduce the number of files that need to be created in order to localize a widget package .
The
example
below
demonstrates
how
a
user
agent
attempts
to
locate
a
file
that
is
absent
in
a
localized
scenario.
Assume
the
user
agent's
locale
is
'
en-gb
'
and
the
zip
relative
path
being
sought
is
"
images/mast.png
":
Firstly,
the
user
agent
will
search
for
a
folder
that
matches
the
user
agent's
locale
as
closely
as
possible
for
the
desired
file.
In
this
case,
the
user
agent
would
attempt
to
locate
the
relative
path
'images/mast.png
'
in
'
/locales/en-gb/
',
but
would
fail.
Secondly,
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.
So
the
next
place
the
user
agent
would
look
is
in
the
'
en/
'
folder,
where
it
would
match
the
zip
relative
path
'
images/mast.png
'.
Lastly,
if
the
above
fails,
the
user
agent
will
search
for
the
absent
file
at
the
root
of
the
widget
package.
So,
if
the
user
agent's
locale
did
not
find
the
zip
relative
path
in
one
of
the
locale
folders,
then
'
images/mast.png
'
file
at
the
root
of
the
widget
would
be
matched
and
this
default
unlocalized
content
would
be
used.
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 follows in sequential order, responding accordingly if any of the steps result in an error or if the specification asks for the user agent to skip a step. The procedures for what to do when an error is encountered are described as part of each step; however, there are times when it will not be possible for the user agent to recover from an error and it will be forced to treat the widget as an invalid widget package .
In the event that a user agent encounters an invalid widget package during the steps for processing a widget package , a user agent must abort all processing of the steps for processing a widget package .
Note: A user agent can optimize steps for processing a widget package and associated processing rules , or perform the steps in a different order, but the end result needs to be indistinguishable from the result that would be obtained by following the specification.
This section defines various processing rules , which are algorithms used during the steps for processing a widget package .
The rule for verifying a zip archive is described in this section. The algorithm returns either true or an error.
This specification does not provide the technical details of how to actually perform the checks, for which implementers need to refer to the [ZIP] specification.
If the Zip archive is split into multiple files or spans multiple volumes , as defined in the [ZIP] specification, then return an error and terminate this algorithm.
If the Zip archive is encrypted, as defined in [Zip] , return an error and terminate this algorithm.
The rule for extracting file data from a file entry is as follows:
Let path be the zip relative path that identifies the file entry being sought.
Let file entry be the file entry identified by the path .
Let file be the result of decompressing (or extracting) the file data from file entry using [Zip] .
Return file .
Note: For efficiency, a user agent can extract specific files as they are needed for processing rather than extracting all the files at once. As a security precaution, implementations are discouraged from extracting file entries from un-trusted widgets directly onto the file system. Instead, implementations could use, for example, a virtual file system or mapping to access files inside a widget package .
The
rule
for
finding
a
file
within
a
widget
package
is
given
in
the
following
algorithm.
The
algorithm
returns
either
a
processable
file
,
null
,
or
an
error.
For the sake of comparison and matching, it is recommended that a user agent treat all Zip relative paths as [UTF-8] .
Note: This specification does not define how links in documents other than the configuration document are to be dereferenced. For handling links in other documents, such as (X)HTML, CSS, SVG, etc., please refer to the [Widgets-URI] specification.
Let path be the valid path to the file entry being sought by the user agent.
If
path
is
not
a
valid
path,
return
an
error
and
terminate
this
algorithm.
If
the
path
starts
with
a
U+002F
SOLIDUS
(e.g.,
"
/style/master.css
"),
then
remove
the
first
U+002F
SOLIDUS
from
path.
Let path-components be the result of splitting path at each occurrence of a U+002F SOLIDUS character, removing that U+002F SOLIDUS character in the process.
if
the
first
item
in
path-components
case-sensitively
matches
the
string
"
locales
",
then:
If
the
path-components
does
not
contain
a
second
item,
then
return
null
.
If
the
second
item
in
path-components
is
not
a
valid
language-range
,
then
return
null
and
terminate
this
algorithm.
Otherwise, continue.
For each lang-range in the user agent locales :
Let
path
be
the
concatenation
of
the
string
"
locales/
",
the
lang-range
,
a
U+002F
SOLIDUS
character,
and
the
path
(e.g.,
locales/en-us/cats.png
,
where
"
en-us
"
is
the
lang-range
and
"
cats.png
"
is
the
path
).
If path case-sensitively matches the file name field of a file entry within the widget package that is a folder , then return an error and terminate this algorithm.
If path case-sensitively matches the file name field of a file entry within the widget package that is a file , let file be the result of applying the rule for extracting file data from a file entry to path .
If file is a processable file , then return file and terminate this algorithm.
If the path points to a file entry that is not a processable file , then return an error and terminate this algorithm.
If every lang-range in the user agent locales have been searched, then search for a file entry whose file name field matches path from the root of the widget package :
If path points to a file entry within the widget package that is a folder , then return an error and terminate this algorithm.
If path points to a file entry within the widget package that is a file , let file be the result of applying the rule for extracting file data from a file entry to path .
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.
Otherwise,
return
null
.
The
rule
for
getting
a
single
attribute
value
is
given
in
the
following
algorithm.
The
algorithm
always
returns
either
a
string
or
a
localizable
string
,
string,
which
can
be
empty.
Let
attribute
be
the
attribute
to
be
processed.
Let
value
result
be
the
value
of
the
attribute
to
be
processed.
attribute.
In
value
result
,
replace
any
sequences
of
space
characters
(in
any
order)
with
a
single
U+0020
SPACE
character.
Remove
In
result
,
remove
any
leading
or
trailing
U+0020
SPACE
characters
from
value
.
If
the
attribute
is
not
a
displayable-string
attribute
,
then
let
result
be
a
string
that
contains
the
value
of
value
.
Otherwise,
if
and
only
if
the
attribute
is
a
displayable-string
attribute
:
Let
result
be
a
localizable
string
that
contains
the
value
of
value
.
Let
element
be
the
element
that
owns
attribute
.
Let
direction
be
the
result
of
applying
the
rule
for
determining
directionality
to
element
.
Associate
direction
with
result
.
Let
lang
be
the
language
tag
derived
from
having
processed
the
xml:lang
attribute
on
either
element
,
or
in
element
's
ancestor
chain
as
per
[XML]
.
If
xml:lang
was
not
used
anywhere
in
the
ancestor
chain,
then
let
lang
be
an
empty
string.
characters.
Associate
lang
with
result
.
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
of
strings
which
can
be
empty.
Let result be the value of the attribute to be processed.
In result , replace any sequences of space characters (in any order) with a single U+0020 SPACE character.
In result , remove any leading or trailing U+0020 SPACE character.
In result , split the string at each occurrence of a U+0020 character, removing that U+0020 character in the process.
The rule for verifying a file entry is given in the following algorithm. The algorithm always returns a boolean value.
For the file entry , check the following data in the local file header .
If
the
value
of
the
CRC-32
field
(defined
in
the
[ZIP]
specification)
fails
a
CRC-32
check,
return
false
and
terminate
this
algorithm.
The
file
name
field
is
an
empty
string,
return
false
and
terminate
this
algorithm.
The
file
name
field
contains
Zip
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
algorithm
always
returns
a
list
of
localizable
string
s,
string,
which
can
be
empty.
A
text
node
refers
to
any
Text
node,
including
CDATASection
nodes
(any
Node
with
node
type
TEXT_NODE
or
CDATA_SECTION_NODE
)
as
defined
in
the
[DOM3Core]
specification.
Let
input
be
the
Element
to
be
processed.
Let
bidi-text
be
an
empty
list
of
localizable
strings
.
If
the
user
agent
supports
[ITS]
,
and
if
the
input
element
has
no
child
nodes,
return
an
bidi-text
and
terminate
this
algorithm.
Let
lang-strings
be
an
empty
list
(it
will
hold
localizable
strings).
Let
lang
be
the
language
tag
derived
from
having
processed
the
attribute
xml:lang
dir
on
either
input
,
or
in
input
's
ancestor
chain
as
per
[XML]
.
If
xml:lang
was
not
used
anywhere
in
the
ancestor
chain,
then
let
lang
be
an
empty
string.
Let
direction
be
the
result
of
applying
from
the
rule
for
determining
directionality
[ITS]
to
input
.
Associate
lang
and
direction
namespace
or
any
children
with
bidi-text
.
For
each
child
node
of
input
:
If
child
node
is
not
an
a
valid
Element
its:dir
or
TextNode
,
move
onto
the
next
child
element
and
ignore
the
following
sub-steps.
If
the
child
node
is
an
Element
,
let
value
,
then
process
lstring
input
be
the
result
of
recursively
applying
the
rule
for
getting
and
its
descendant
text
content
nodes
using
this
current
child
element
as
in
accordance
to
the
argument.
[ITS]
specification.
If
the
child
node
is
a
text
node
,
then:
Create
a
new
localizable
string
called
lstring
,
using
Return
the
text
content
value
of
the
textContent
attribute
of
current
child
node
as
the
text
value,
direction
as
the
direction,
and
lang
as
the
language.
Append
lstring
to
the
lang-string
list.
Take
all
the
text
nodes,
in
order,
from
the
returned
localizable
string
and
associate
them
with
bidi-text
input
.
The rule for getting text content with normalized white space is given in the following algorithm. The algorithm always returns a string, which can be empty.
Let
input
be
the
Element
to
be
processed.
Let result be the result of applying the rule for getting text content to input .
In result , convert any sequence of one or more Unicode white space characters into a single U+0020 SPACE.
In result , remove any leading or trailing U+0020 SPACE character.
Return result .
For
example,
the
user
agent
would
ignore
the
author
and
blink
elements,
but
their
Text
nodes
would
be
extracted
(together
with
directional
and
language
information):
<widget xmlns="http://www.w3.org/ns/widgets"
xmlns:x="http://x.x.example/x" xml:lang="en">
<name>
The <blink xml:lang="en-us">Awesome</blink>
<author email="dude@example.com">Super <x:blink dir="rtl">Dude</x:blink></author>
Widget</name>
</widget>
extracted.
The
resulting
widget
name
would
be
"
The
Awesome
Super
Dude
Widget
"
(please
note
that
Dude
is
rendered
right-to-left).
":
<widget xmlns="http://www.w3.org/ns/widgets">
<name>
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 is given in the following algorithm. This algorithm returns the number zero, a positive integer, or an error.
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 first character 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 and terminate this algorithm. Otherwise, go to step 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
5
7
in
this
algorithm.
Return result .
The rule for identifying the media type of a file is given by the following algorithm. The algorithm always returns a string.
Note:
This
rule
is
only
to
be
applied
when
explicitly
instructed
to
by
the
specification
(e.g.,
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.
Let content-type be an empty string.
Let extension be an empty string.
Let
name
be
the
file-name
component
of
the
zip
relative
path
that
identifies
the
file
.
For
example,
the
name
for
"
some/zip/rel/path/hello.png
"
would
be
"
hello.png
".
If the first character of the name is a U+002E 'FULL STOP' character, and the file name contains no other U+002E 'FULL STOP' character, then go to step 10 of this algorithm.
For example, if the name is " .htaccess ", jump to step 10 and derive the media type using the [SNIFF] specification.
If
the
first
character
or
last
character
of
the
name
is
not
a
U+002E
'FULL
STOP'
character,
but
name
contains
one
or
more
U+002E
'FULL
STOP'
characters,
then
let
extension
be
the
sequence
of
characters
from
the
last
U+002E
'FULL
STOP'
(inclusive)
to
the
end
of
name
.
(if
any).
The value of extension for the file name " cat.html " would be ". html ". The value of extension for "...html" would be ".html". And the value of extension for "hello." would be an empty string.
If the first character of the name is a U+002E 'FULL STOP' character, and the file name contains another U+002E 'FULL STOP' character, then let extension be the sequence of characters from the last U+002E 'FULL STOP' (inclusive) to the end of name (if any).
For
example,
if
the
name
is
"
.myhidden.html
",
then
the
extension
would
be
"
.html
.html
".
If extension is an empty string, go to step 10 in this algorithm.
Check
that
each
character
in
the
extension
is
either
in
the
U+0041-U+005A
range
or
in
the
U+0061-U+007A
range
(ASCII
uppercase
and
lowercase
characters,
respectively)
or
in
the
U+0030-U+0039
range
(ASCII
numbers
0
to
9):
respectively):
If
any
character
in
the
extension
is
outside
the
U+0041-U+005A
range
or
and
the
U+0061-U+007A
range
or
the
U+0030-U+0039
range,
then
go
to
step
10
in
this
algorithm.
For example, if the extension is " .pñg ", the go to step 10 in this algorithm.
If
all
characters
in
the
extension
are
in
any
either
of
in
the
U+0041-U+005A
range
or
in
the
U+0061-U+007A
range
or
the
U+0030-U+0039
range
(e.g.,
"
Mp3
"),
range,
then
attempt
to
case-insensitive
match
the
value
of
extension
to
one
of
the
values
in
the
file
extension
column
in
the
file
identification
table
.
If
there
is
a
match,
then
return
let
content-type
be
the
corresponding
value
from
the
media
type
column.
Go to step 11.
Let content-type be the result of processing file through the [SNIFF] specification.
file extension | media type |
---|---|
.html | text/html |
.htm | text/html |
.css | text/css |
.js | application/javascript |
.xml | application/xml |
.txt | text/plain |
.wav | audio/x-wav |
.xhtml | application/xhtml+xml |
.xht | application/xhtml+xml |
.gif | image/gif |
.png | image/png |
.ico | image/vnd.microsoft.icon |
.svg | image/svg+xml |
.jpg | image/jpeg |
It is optional for a user agent to support the media types given in the file identification table .
The rule for determining if a potential Zip archive is a Zip archive is given by the following algorithm.
Let potential archive be the acquired resource.
Check
if
the
first
four
bytes
of
potential
archive
match
the
magic
numbers
for
a
Zip
archive
(
50
4B
03
04
).
If the first four bytes do not match the magic numbers for a Zip archive , then return an error.
Otherwise,
return
true
.
Note: A user agent can inspect the potential archive once it has acquired the first four bytes of the potential Zip archive or can wait until all the data of the potential Zip archive has been completely acquired.
Step 1 involves acquiring a potential Zip archive and confirming that it is a Zip archive by applying the rule for determining if a potential Zip archive is a Zip archive . A user agent will acquire a potential Zip archive from a data transfer protocol that either labels resources with a media type (e.g. [HTTP] ) or from a data transfer protocol that does not label resources with a media type (e.g., BitTorrent or Bluetooth).
It
is
recommended
that
a
user
agent
support
acquisition
of
a
potential
Zip
archive
from
a
protocol
that
labels
resources
with
a
media
type
(e.g.,
getting
a
widget
package
over
[HTTP]
).
If
a
user
agent
supports
acquisition
of
a
potential
Zip
archive
from
a
protocol
that
labels
resources
with
a
media
type,
then
the
a
user
agent
needs
to
must
process
resources
labeled
with
the
valid
widget
media
type
(
application/widget
),
regardless
of
whether
the
resource
contains
a
file
extension
or
not,
by
applying
the
rule
for
determining
if
a
potential
Zip
archive
is
a
Zip
archive
.
During the acquisition of a potential Zip archive labeled with a media type , unless the user agent supports legacy or proprietary media types , unsupported media types are in error and the user agent must treat the potential Zip archive as an invalid widget package .
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
widget
package
.
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 should treat the acquired potential Zip archive as if it has been acquired from a protocol that does not label resources with a media type .
In
this
example,
the
media
type
of
the
Content-Type
is
not
one
supported
by
the
user
agent,
so
the
user
agent
would
treat
the
potential
Zip
archive
as
an
invalid
widget
package
:
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
should
must
attempt
to
process
the
resource
regardless
of
the
file
extension
(including
situations
when
the
file
extension
is
absent)
by
applying
the
rule
for
determining
if
a
potential
Zip
archive
is
a
Zip
archive
.
If
the
rule
for
determining
if
a
potential
Zip
archive
is
a
Zip
archive
return
true
,
proceed
to
Step
2
.
Otherwise,
if
an
error
was
returned,
the
user
agent
must
treat
the
potential
Zip
archive
as
an
invalid
widget
package
.
To
verify
that
a
Zip
archive
and
its
file
entries
conform
to
this
specification,
a
user
agent
must
apply
the
rule
for
verifying
a
zip
archive
.
If
the
rule
for
verifying
a
zip
archive
returns
true
,
then
the
user
agent
must
go
to
Step
3
.
Otherwise,
if
the
rule
for
verifying
a
zip
archive
returns
an
error,
then
the
user
agent
must
treat
the
Zip
archive
as
an
invalid
widget
package
.
In Step 3 , a user agent must set the following variables and default values as defined in the table of configuration defaults .
Note:
When
a
null
value
is
assigned
to
a
variable
in
the
table
of
configuration
defaults
,
a
user
agent
needs
to
treats
the
value
as
null
(i.e.,
not
as
an
empty
string
and
not
as
the
text
string
"null"
).
Variable | Type | Default Value | Overridden in | Description |
---|---|---|---|---|
author email | String |
null
| Step 7 |
The
value
of
the
author
element's
email
attribute
(if
any).
|
author href | IRI |
null
| Step 7 |
The
value
of
the
author
element's
href
attribute
(if
any).
|
author name | String |
null
| Step 7 |
author
element
(if
any).
|
feature list | List |
null
| Step 7 |
A
list
of
features
that
correspond
to
features
that
were
requested
via
feature
elements
(if
any).
Each
item
in
the
list
corresponds
to
a
feature
element's
name
attribute,
whether
it
is
required,
and
any
associated
parameters
(if
any).
|
icons | List of file entries |
null
| Step 7 , Step 9 | The icons of the widget as they correspond to the default icons and to the occurrence of custom icons that are supported by the widget package (if any). |
start file encoding | String |
UTF-8
| Step 7 |
The
character
encoding
of
the
custom
start
file
,
corresponding
to
either
the
content
element's
encoding
attribute
(if
any),
or
the
default
encoding
.
|
start file content-type | String |
text/html
| Step 7 |
The
media
type
of
the
start
file
,
corresponding
to
the
content
element's
type
attribute
or
to
a
media
type
derived
from
the
default
start
files
table
.
|
widget config doc | File |
null
| Step 6 | The file that is the configuration document for the widget package . |
widget description | String |
null
| Step 7 |
The
text
content
of
the
description
element
in
the
configuration
document
.
|
widget height | positive number |
null
| Step 7 |
The
value
of
the
widget
element's
height
attribute
in
the
configuration
document
(if
any).
|
widget id | String |
null
| Step 7 |
The
value
of
the
|
widget license | String |
null
| Step 7 |
The
text
content
of
the
license
element
in
the
configuration
document
(if
any).
|
widget license file | File |
null
| Step 7 |
A
file
derived
if
the
value
of
the
license
element's
href
is
a
Zip
relative
path
to
a
file
within
the
widget
package
.
|
widget license href | IRI |
null
| Step 7 |
The
value
of
the
license
element's
href
attribute
in
the
configuration
document
(if
any).
|
widget name |
|
null
|
Step 7 |
The
text
content
of
the
name
element
in
the
configuration
document
(if
any).
|
widget preferences | List |
null
| Step 7 |
The
widget's
preferences
,
corresponding
to
the
Unless an end-user explicitly requests that these values be reverted to the values as declared in the configuration document , a user agent must not reset the value of the widget preferences variable on subsequent initializations of the widget. |
widget short name |
|
null
|
Step 7 |
The
value
of
the
name
element's
short
attribute
in
the
configuration
document
(if
any).
|
Variable | Type | Default Value | Overridden by | Description |
widget version |
|
null
|
Step 7 |
The
value
of
the
widget
element's
version
attribute
in
the
configuration
document
(if
any).
|
widget width | positive number |
null
| Step 7 |
The
value
of
the
widget
element's
width
attribute
in
the
configuration
document
(if
any).
|
widget window modes | List of strings |
null
| Step 7 |
The
value
of
the
widget
element's
viewmodes
attribute
in
the
configuration
document
(if
any).
|
widget start file | File entry |
null
| Step 7 , Step 8 |
The
start
file
for
the
widget
package
,
corresponding
to
either
one
of
the
default
start
files
table
or
the
file
identified
by
the
content
element's
src
attribute.
|
user agent locales |
List of strings |
null
| Step 5 | A list of language tags . |
If
the
user
agent
does
not
support
[Widgets-DigSig]
,
then
the
user
agent
must
skip
Step
4
and
go
to
Step
5
.
Otherwise,
the
user
agent
must
apply
the
algorithm
to
locate
digital
signatures,
which
is
defined
in
the
[Widgets-DigSig]
specification
under
the
section
named
Locating
signature
files
in
a
widget
package
and
Processing
Digital
Signatures
.
The end-user's language ranges represents the end-user's preferred languages and regional settings, which are derived from the operating system or directly from the user agent. As there are numerous ways a user agent can derive the end-user's preferred languages and regional settings, the means by which those values are derived are beyond the scope of this specification and left up to the implementation.
During
the
rule
for
deriving
algorithm
to
derive
the
user
agent
locales
defined
below,
the
user
agent
will
need
to
construct
a
list
unprocessed
locales
.
Each
item
in
the
unprocessed
locales
is
a
string
in
lowercase
form,
that
conforms
to
the
production
of
a
Language-Tag
,
as
defined
in
the
[BCP47]
specification.
A
string
that
conforms
to
the
production
of
a
Language-Tag
is
referred
to
as
a
language
range
[BCP47]
(e.g.
'
en-au
',
which
is
the
range
of
English
as
spoken
in
Australia,
and
'
fr-ca
',
which
is
the
range
of
French
as
spoken
in
Canada,
etc.).
A
language
range
is
composed
of
one
or
more
subtags
that
are
delimited
by
a
U+002D
HYPHEN-MINUS
("
-
").
The first item of the unprocessed locales represents the user's most preferred language range (i.e., the language/region combination the user agent assumes the end-user most wants to see content in), followed by the next most preferred language range, and so forth.
For
example,
in
an
unprocessed
locales
list
that
contains
'
en-us,en,fr,es
',
English
as
spoken
in
the
United
States
is
preferred
over
English,
and
English
is
preferred
over
French,
and
French
is
preferred
over
Spanish,
and
Spanish
is
preferred
over
default
unlocalized
content
.
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.
In
Step
5
,
the
user
agent
must
apply
the
rule
for
deriving
algorithm
to
derive
the
user
agent
locales
.
The algorithm to derive the user agent locales is as follows:
Let unprocessed locales list be a comma-separated list that contains the end-user's language ranges .
For each range in the unprocessed locales list :
If
this
range
begins
with
the
subtag
'
*
'
(e.g.
"
*-us
"
or
just
"
*
"),
or
contains
any
space
characters
,
skip
all
the
steps
in
this
algorithm
below,
and
move
onto
the
next
range
.
If
this
range
begins
with
the
subtag
"
i
"
or
the
range
is
marked
as
"deprecated"
in
the
IANA
Language
Subtag
Registry
,
skip
all
the
steps
in
this
algorithm
below,
and
move
onto
the
next
range
.
If
this
range
contains
any
subtag
'
*
',
remove
the
'
*
'
and
its
preceding
hyphen
(
U+002F
)
(e.g.,
'
en-*-us
'
becomes
'
en-us
').
While range contains subtags :
Add the value of the range to the user agent locales .
Remove the right most subtag from range and append the resulting value to user agent locales . Continue removing the right most subtag and adding the result to user agent locales until there are no subtags left in range .
For
example,
if
the
range
was
"
zh-hans-cn
",
then
the
user
agent
locales
become
"
zh-hans-cn,zh-hans,zh
".
Move onto the next range and go to step 1 in this algorithm.
Append
the
value
"
*
"
to
the
end
of
user
agent
locales
.
For
example,
an
unprocessed
locales
list
that
contains
"
en-us,en-au,en,fr-ca,zh-hans-cn
"
would
result
in
a
user
agent
locales
that
contains
"
en-us,en,en-au,en,en,fr-ca,fr,zh-hans-cn,zh-hans,zh,*
".
For
example,
an
unprocessed
locales
list
that
contains
"
en-us,en,fr-ca,en,en-ca
"
would
result
in
a
user
agent
locales
that
contains
"
en-us,en,en,fr-ca,fr,en,en-ca,en,*
".
This step involves searching within the Zip archive for a configuration document .
In Step 6 , a user agent must apply the algorithm to locate the configuration document .
The algorithm to locate the configuration document is as follows:
Search
at
the
root
of
the
widget
package
for
a
file
entry
whose
file
name
field
case-sensitively
matches
the
valid
configuration
document
file
name
(
config.xml
).
null
),
then
treat
the
Zip
archive
as
an
invalid
widget
package
.
The purpose of processing the configuration document is to override the values in the table of configuration defaults , which are used during initialization and at runtime, and to select the appropriate localized content (if any) to be presented to the end user.
In conjunction to the algorithm for processing a configuration document given below, this section firstly defines some terminology used by the processing algorithm and describes how localized elements are processed.
During Step 7 , a user agent must apply the algorithm to process a configuration document .
In the algorithm to process a configuration document , the term in error is used to mean that an element, or attribute, or file in a configuration document is non-conforming to the rules of this specification. How an element or an attribute is to be treated when it is in error is always given when the term is used; but will generally require the user agent to ignore any element, attribute, or file that is in error.
To ignore means to act as if the element, attribute, or file that is in error is absent (i.e., not declared or included by the author) in the widget package or configuration document. A user agent must , however, keep a record of all element types it has attempted to process even if they were ignored (this is to determine if the user agent has attempted to process an element of a given type already).
In the case the user agent is asked to ignore an [XML] element or node, a user agent must :
Stop processing the current element , ignoring all of the element 's attributes and child nodes (if any), and proceed to the next element in the elements list .
Make a record that it has attempted to process an element of that type.
In
the
following
example,
the
user
agent
ignores
both
content
elements.
The
user
agent
ignores
the
first
because
it
lacks
a
src
attribute.
The
user
agent
ignores
the
second
because
it
is
not
the
first
content
element
to
be
encountered
by
the
user
agent.
<widget xmlns="http://www.w3.org/ns/widgets">
<!-- User agent ignores the first, but records
that it has attempted to process a content element
<!-- User agent ignores the first, but records
that it has attempted to process a content element
-->
<content/>
<!-- The use agent knows that it has previously attempted
to process a content element, hence this content element
is ignored.
<!-- The use agent knows that it has previously attempted
to process a content element, hence this content element
is ignored.
-->
<content src="cats.html"/>
</widget>
To
associate
means
that
two
or
more
pieces
of
information
are
bound
and
stored
together
for
the
purpose
of
later
processing
(e.g.,
the
name
of
a
feature
,
and
if
it
is
required
,
and
any
associated
parameters
).
How
associated
data
is
represented
is
left
up-to
the
implementation
(e.g.,
a
user
agent
could
use
an
array,
an
object,
a
hash
map,
etc.).
The
lookup
algorithm
is
defined
in
section
3.4
of
[RFC4647]
(part
of
[BCP47]
.
).
It
is
used
in
this
Step
to
match
localized
content
in
the
configuration
document
to
the
language
ranges
held
by
the
user
agent
locales
(if
any).
The algorithm to process a configuration document is as follows:
Let
doc
be
the
result
of
loading
the
widget
config
doc
as
a
[DOMCore]
[DOM3Core]
Document
using
an
[XML]
parser
that
is
both
[XMLNS]
-aware
and
xml:lang
aware.
If doc is not namespace well-formed [XML] , then the user agent must terminate this algorithm and treat this widget package as an invalid widget package .
Let
root
element
be
the
documentElement
of
doc
.
If
the
root
element
is
not
a
widget
element
in
the
widget
namespace
,
then
the
user
agent
must
terminate
this
algorithm
and
treat
this
widget
package
as
an
invalid
widget
package
.
Otherwise,
the
element
is
a
widget
element:
If
the
id
attribute
is
used,
then
let
id
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
id
attribute.
If
id
is
a
valid
IRI
,
then
let
widget
id
be
the
value
of
the
id
.
If
the
id
is
not
a
valid
IRI
or
is
an
empty
string,
in
error
,
then
the
user
agent
must
ignore
the
attribute.
If
the
version
attribute
is
used,
then
let
version
value
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
version
attribute.
If
the
version
is
an
empty
string,
then
the
user
agent
must
ignore
the
attribute;
otherwise,
let
widget
version
be
the
value
of
version
value
.
If
the
height
attribute
is
used,
then
let
normalized
height
be
the
result
of
applying
the
rule
for
parsing
a
non-negative
integer
to
the
value
of
the
attribute.
If
the
normalized
height
is
not
in
error
and
greater
than
0
,
then
let
widget
height
be
the
value
of
normalized
height
.
If
the
height
attribute
is
in
error
,
then
the
user
agent
must
ignore
the
attribute.
If
the
width
attribute
is
used,
then
let
normalized
width
be
the
result
of
applying
the
rule
for
parsing
a
non-negative
integer
to
the
value
of
the
attribute.
If
the
normalized
width
is
not
in
error
and
greater
than
0
,
then
let
widget
width
be
the
value
of
normalized
width
.
If
the
width
attribute
is
in
error
,
then
the
user
agent
must
ignore
the
attribute.
If
the
viewmodes
attribute
is
used,
then
the
user
agent
must
let
viewmodes
list
be
the
result
of
applying
the
rule
for
getting
a
list
of
keywords
from
an
attribute
:
From the viewmode list , remove any unsupported items.
From the viewmode list , remove any duplicated items from right to left.
For
example,
viewmode
veiwmode
list
with
a
value
of
"
"
would
become
"
windowed
application
fullscreen
windowed
floating
application
widget
fullscreen
windowed
application
".
windowed
application
fullscreen
floating
widget
Let widget window modes be the value of viewmodes list .
If
the
widget
element
does
not
contain
any
child
elements,
then
the
user
agent
must
terminate
this
algorithm
and
go
to
Step
8
.
Otherwise, let element list be an empty list.
For each range in the user agent locales , starting from the first and moving to the last:
If
the
value
of
range
is
not
"*",
then
retaining
document
order
,
let
matching
elements
be
the
result
of
applying
lookup
to
the
child
elements
that
are
defined
as
being
localizable
via
xml:lang
(i.e.,
the
of
type
name
,
description
,
and
license
elements)
that
are
direct
descendants
descendents
of
the
root
element
and
whose
xml:lang
attribute
matches
the
current
range
.
Append
matching
elements
to
the
element
list
.
For example, consider the following configuration document.
<widget xmlns="http://www.w3.org/ns/widgets">
<name>El Widget!</name>
<name xml:lang="fr">Le Widget</name>
<name xml:lang="en">The Widget</name>
</widget>
For
a
use
agent
whose
user
agent
locales
contains
"
en,fr,*
",
the
matching
elements
would
be
in
the
following
order:
<name
xml:lang="en">The
Widget</name>
<name
xml:lang="fr">Le
Widget</name>
<name>El
Widget!</name>
For
a
use
agent
whose
user
agent
locales
contains
"
en,*
",
the
matching
elements
would
be
in
the
following
order:
<name
xml:lang="en">The
Widget</name>
<name>El
Widget!</name>
For
a
use
agent
whose
user
agent
locales
contains
"
jp,*
",
the
matching
elements
would
be
in
the
following
order:
<name>El
Widget!</name>
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
by
the
user
agent,
then
the
user
agent
must
ignore
this
element
.
If
this
is
the
first
name
element
encountered
by
the
user
agent,
then
the
user
agent
must
:
Record
that
an
attempt
has
been
made
by
the
user
agent
to
process
a
name
element.
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
by
the
user
agent,
then
the
user
agent
must
ignore
this
element
.
If
this
is
the
first
description
element
encountered
by
the
user
agent,
then
the
user
agent
must
:
Record
that
an
attempt
has
been
made
by
the
user
agent
to
process
a
description
element.
Let
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
by
the
user
agent,
then
the
user
agent
must
ignore
this
element
.
If
this
is
the
first
license
element
used,
then
the
user
agent
must
:
Record
that
an
attempt
has
been
made
by
the
user
agent
to
process
a
license
element.
Let license text be the result of applying the rule for getting text content to this element. Associate license text with widget license .
If
the
href
attribute
is
used,
then
let
potential
license
href
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
href
attribute.
If
potential
license
href
is
not
a
valid
IRI
or
a
valid
path
,
then
the
href
attribute
is
in
error
and
the
user
agent
must
ignore
the
attribute.
If potential license href is a valid IRI , then let widget license href be the value of potential license href .
If license href is a valid path , then let file be the result of applying the rule for finding a file within a widget package to license href .
If file is not a processable file , as determined by applying the rule for identifying the media type of a file , then ignore this element .
icon
element:
If
the
src
attribute
of
this
icon
element
is
absent,
then
the
user
agent
must
ignore
this
element
.
Let
path
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
src
attribute
of
this
icon
element.
If
path
is
not
a
valid
path
or
is
an
empty
string,
then
the
user
agent
must
ignore
this
element
.
Let file be the result of applying the rule for finding a file within a widget package to path . If file is not a processable file , as determined by applying the rule for identifying the media type of a file , or already exists in the icons list, then the user agent must ignore this element.
Otherwise,
If
the
height
attribute
is
used,
then
let
potential
height
be
the
result
of
applying
the
rule
for
parsing
a
non-negative
integer
to
the
attribute's
value.
If
the
potential
height
is
not
in
error
and
greater
than
0
,
then
associate
the
potential
height
with
file
.
Otherwise,
the
height
attribute
is
in
error
and
the
user
agent
must
ignore
the
attribute.
If
the
width
attribute
is
used,
then
let
potential
width
be
the
result
of
applying
the
rule
for
parsing
a
non-negative
integer
to
the
attribute's
value.
If
the
potential
width
is
not
in
error
and
greater
than
0
,
then
associate
the
potential
width
with
file
.
Otherwise,
the
width
attribute
is
in
error
and
the
user
agent
must
ignore
the
attribute.
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
by
the
user
agent,
then
the
user
agent
must
ignore
this
element
.
If
this
is
the
first
author
element
used,
then
the
user
agent
must
:
Record
that
an
attempt
has
been
made
by
the
user
agent
to
process
a
author
element.
If
the
href
attribute
is
used,
then
let
href-value
be
the
value
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
href
attribute.
If
href-value
is
a
valid
IRI
,
then
let
author
href
be
the
value
of
the
href
attribute.
Otherwise,
if
href-value
is
not
a
valid
IRI
,
then
ignore
the
href
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
of
the
preference
element
is
used,
but
the
name
attribute
is
absent,
then
this
preference
element
is
in
error
and
the
user
agent
must
ignore
this
element
.
Otherwise,
the
user
agent
must
:
Let
name
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
name
attribute.
If the name is an empty string, then this element is in error ; ignore this element .
If widget preferences already contains a preference whose name case-sensitively matches the value of name , then this element is in error ; ignore this element .
If name was not in error , let preference be an empty object.
Associate name with preference .
Let
value
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
attribute.
Associate value with preference .
If
a
readonly
attribute
is
used,
then
let
readonly
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
readonly
attribute.
If
readonly
is
not
a
valid
boolean
value
,
then
let
the
value
of
readonly
be
the
value
'
false
'.
Associate readonly with the preference .
Add the preference and the associated name , value and readonly variables the list of widget preferences .
content
element:
If
this
is
not
the
first
content
element
encountered
by
the
user
agent,
then
the
user
agent
must
ignore
this
element
.
If
this
is
the
first
content
element,
then
the
user
agent
must
:
Record
that
an
attempt
has
been
made
by
the
user
agent
to
process
a
content
element.
If
the
src
attribute
of
the
content
element
is
absent
or
an
empty
string,
then
the
user
agent
must
ignore
this
element
.
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 not a valid path , then the user agent must ignore this element .
If
path
is
a
valid
path
,
then
let
file
be
the
result
of
applying
the
rule
for
finding
a
file
within
a
widget
package
to
path
.
If
file
is
null
or
in
error,
then
the
user
agent
must
ignore
this
element
.
If
the
type
attribute
of
the
content
element
is
absent,
then
check
if
file
is
supported
by
the
user
agent
by
applying
the
rule
for
identifying
the
media
type
of
a
file
.
If
the
file
is
supported
,
then
let
the
widget
start
file
be
the
file
referenced
by
the
src
attribute
and
let
start
file
content-type
be
the
supported
media
type
as
was
derived
by
applying
the
rule
for
identifying
the
media
type
of
a
file
.
If
the
encoding
attribute
is
used,
then
let
content-encoding
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
of
the
encoding
attribute.
If
the
character
encoding
represented
by
the
value
of
content-encoding
is
supported
by
the
user
agent,
then
let
the
start
file
encoding
be
the
value
of
content-encoding
.
If
content-encoding
is
an
empty
string
or
unsupported
by
the
user
agent,
then
a
user
agent
must
ignore
the
encoding
attribute.
If
the
type
attribute
is
used,
then
let
content-type
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
of
the
type
attribute.
If
the
value
of
content-type
is
a
media
type
supported
by
the
user
agent,
then
let
the
start
file
content-type
be
the
value
of
content
type
.
If
value
of
content-type
is
invalid
or
unsupported
by
the
user
agent,
then
a
user
agent
must
treat
the
widget
package
as
an
invalid
widget
package
.
If
the
start
file
encoding
was
set
in
step
7
of
this
algorithm
as
a
result
of
processing
a
valid
and
supported
value
for
the
content
element's
encoding
attribute,
then
the
user
agent
must
skip
this
step
in
this
algorithm.
Otherwise,
if
the
value
of
content-type
is
a
media
type
supported
by
the
user
agent
and
if
content-type
contains
one
or
more
[MIME]
parameter
components
whose
purpose
is
to
declare
the
character
encoding
of
the
start
file
(e.g.,
the
value
"
text/html;charset=Windows-1252
",
where
charset
is
a
parameter
component
whose
purpose
is
to
declare
the
character
encoding
of
the
start
file),
then
let
start
file
encoding
be
the
value
of
the
last
supported
parameter
components
whose
purpose
is
to
declare
the
character
encoding
of
the
start
file
.
In the following example, the user agent would set the start file encoding to ISO-8859-1 and would ignore the charset parameter used in the type attribute.
<widget xmlns="http://www.w3.org/ns/widgets">
<content src = "start.php"
type = "text/html;charset=Windows-1252"
encoding
=
"ISO-8859-1"
/>
</widget>
In
the
following
example
the
user
agent
would
set
the
start
file
encoding
to
Windows-1252
,
if
the
user
agent
supports
that
character
encoding.
<widget xmlns="http://www.w3.org/ns/widgets">
<content src = "start.php"
type = "text/html;charset=Windows-1252"/>
</widget>
param
element:
If
this
param
element
is
not
a
direct
child
of
a
feature
element,
then
the
user
agent
must
ignore
this
param
element
.
Note: How a param element is to be processed when it is inside a feature element is defined below.
feature
element:
The user agent must process a feature element in the following manner:
If
Let
feature-name
be
the
name
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
of
this
the
feature
name
element
is
absent,
then
the
user
agent
must
ignore
this
element
.
Let
required-feature
be
the
value
true
.
attribute.
If
a
required
attribute
is
used,
then
let
potentialy-required-feature
required-feature
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
required
attribute.
If
the
value
of
potentialy-required-feature
required-feature
is
the
not
a
valid
boolean
value
"
false
",
,
then
let
the
value
of
required-feature
be
the
value
'
'.
false
true
If
feature-name
is
not
a
valid
IRI
,
and
required-feature
is
true
,
then
the
user
agent
must
treat
this
widget
as
an
invalid
widget
package
.
If
feature-name
is
not
supported
by
the
user
agent,
and
required-feature
is
true
,
then
the
user
agent
must
treat
this
widget
as
an
invalid
widget
package
.
If
feature-name
is
not
supported
by
the
user
agent,
and
required-feature
is
false
,
then
the
user
agent
must
ignore
this
element
.
Let
feature
be
an
object
that
represents
this
feature
.
Associate
the
value
of
required-feature
and
feature-name
with
the
feature
object.
feature-name
.
If
the
feature
element
contains
any
param
elements
as
direct
descendants,
then,
for
each
child
param
element
that
is
a
direct
descendants
descendent
of
this
feature
element,
starting
from
the
first
moving
to
the
last
in
document
order
:
If
either
the
a
value
attribute
is
used,
but
the
name
attribute
or
is
absent,
then
this
param
element
is
in
error
and
the
user
agent
must
ignore
this
element
.
If
a
attribute
is
value
name
missing,
used,
but
the
value
attribute
is
absent,
then
this
param
element
is
in
error
and
the
user
agent
must
ignore
this
element
.
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
this
element
.
Let
If,
and
only
if,
param-name
is
not
in
error
or
an
empty
string,
then
let
param-value
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
attribute.
L:et
param
be
an
object
that
represents
this
paramenter.
Associate
param-name
and
param-value
with
param
.
Associate
param
with
feature
feature-name
.
Append
feature
feature-name
,
and
any
associated
required-feature
,
and
associated
parameters
,
to
the
feature
list
.
If the user agent supports the element, then the user agent must process it in accordance with whatever specification defines that element (if any). Otherwise, the user agent must ignore the element.
If
widget
start
file
of
the
table
of
configuration
defaults
contains
a
file
(i.e.
widget
start
file
is
not
null
),
then
a
user
agent
must
skip
Step
8
and
go
to
Step
9
.
If widget start file does not contain a file , the user agent must apply the algorithm to locate a default start file .
The algorithm to locate a default start file is as follows:
For each file name in the default start files table (from top to bottom) that has a media type that is supported by the user agent:
Let potential-start-file be the result of applying the rule for finding a file within a widget package to file name .
If
potential-start-file
is
null
or
in
error
,
ignore
this
file
name
and
move
onto
the
next
file
name
in
the
default
start
files
table
.
If potential -start-file is a file , then:
Let widget start file be the value of potential- start-file .
Let start file content-type be the media type given in the media type column of the default start files table .
Terminate this algorithm and go to Step 9 .
If after searching for every file in the default start files table no default start file is found, then treat this widget as an invalid widget package .
This step describes how to locate the default icons .
In Step 9 , a user agent must apply the algorithm to locate the default icons .
The algorithm to locate the default icons is as follows:
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:
Let potential-icon be the result of applying the rule for finding a file within a widget package to file name .
If
the
following
conditions
are
all
true
,
then
append
the
value
of
potential-icon
to
the
icons
list
of
the
table
of
configuration
defaults
:
The value of potential-icon is a file .
The
potential-icon
is
a
processable
file
,
determined
by
the
media
type
given
in
the
media
type
column
of
the
default
icons
table
,
and
the
.
The
potential-icon
does
not
already
exist
in
the
icons
list
of
the
table
of
configuration
defaults
,
then
append
the
value
of
potential-icon
to
the
icons
list
of
the
table
of
configuration
defaults
.
Move onto the next file name in the default icons table .
application/widget
This
appendix
is
the
registers
a
new
MIME
media
type
registration
for
type,
"
application/widget
".
This
registration
has
been
approved
by
the
Internet
Assigned
Numbers
Authority
(
IANA
)
.
Registration
with
IANA
was
conducted
"
in
conformance
with
BCP
13
and
W3CRegMedia
.
This registration is for community review and was submitted to the IESG for review, approval, and registration with IANA .
application
None.
None.
Widget
packages
are
binary
data
and
thus
are
encoded
for
MIME
transmission.
As
a
widget
package
is
binary,
it
requires
encoding
on
transports
not
capable
of
handling
binary.
The
same
guidelines
that
apply
to
application/octet-stream
apply
to
widget
packages
(see
[MIME]
).
In addition to the security considerations specified for Zip files in the [Zip-MIME] registration, there are a number of security considerations that need to be taken into account when dealing with widget packages and configuration documents .
As the configuration document format is [XML] and will commonly be encoded using [Unicode] , the security considerations described in [XML-MIME] and [UTR36] apply. In addition, implementers need to 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.
The
configuration
document
allows
authors,
through
the
feature
element,
to
request
permission
to
enable
third-party
runtime
components
and
APIs.
As
these
features
are
outside
the
scope
of
this
specification,
significant
caution
needs
to
be
taken
when
granting
a
widget
the
capability
to
use
a
feature.
Features
themselves
define
their
own
security
considerations.
support . Specifically, implementers need to consider the security implications outlined in the [CSS-MIME] specification, the [ECMAScript-MIME] specification, and the [HTML-MIME] specification.
will generally contain ECMAscript, HTML, CSS files, and other media, which are executed in a sand boxed environment. As such, implementers need to be aware of the security implications for the types theyAs widget packages can contain content that is able to simultaneously interact with the local device and a remote host, implementers need to consider the privacy implications resulting from exposing private information to a remote host. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are advised to enable user awareness of information sharing, and to provide easy access to interfaces that enable revocation of permissions.
As this specification relies on the standardized heuristics for determining the content type of files defined in the [SNIFF] specification, implementers need to consider the security considerations discussed in the [SNIFF] specification.
As
this
specification
allows
for
the
declaration
of
IRIs
within
certain
elements
of
a
configuration
documents,
implementers
need
to
consider
the
security
considerations
discussed
in
the
[IRI]
specification.
Implementations
intending
to
display
IRIs
and
IDNA
addresses
found
in
the
configuration
document
are
strongly
encouraged
to
follow
the
security
advice
given
in
[UTR36]
.
This
could
include,
for
example,
behaving
as
if
the
dir
attribute
had
no
effect
on
any
IRI
attributes
,,
path
attributes
,
and
the
author
element's
email
attribute.
In
addition,
user
agents
need
to
be
careful
about
trusting
path
components
found
in
the
widget
package.
Such
path
components
might
be
interpreted
by
operating
systems
as
pointing
at
security
critical
files
outside
the
widget
environment
proper,
and
naive
unpacking
of
widget
packages
into
the
file
system
might
lead
to
undesirable
and
security
relevant
effects,
such
as
overwriting
of
system
files.
Some issues can arise with regards to character encodings of file names, the length of zip relative paths, and the use of certain strings as file names.
This specification does not put a restriction on the byte length of a Zip relative path , so a user agent should to be able to deal with Zip relative paths that have lengths longer than 250 bytes. As some operating systems have restrictions on how long a path length can be, authors need to keep the lengths of relative paths at less than 250 bytes. Unicode code points may require more than one byte to encode a character, which can result in a path whose length is less than 250 characters but whose size is greater than 250 bytes.
Authors
need
to
be
aware
that,
at
the
time
of
publication,
there
are
interoperability
issues
with
regards
to
using
characters
outside
the
safe-chars
range
for
file
or
folder
names
in
a
Zip
archive
when
using
Zipping
tools
bundled
with
operating
systems.
The
interoperability
issues
have
arisen
from
non-conforming
implementations
of
the
[ZIP]
specification
across
operating
systems:
very
few,
if
any,
correctly
support
encoding
file
names
in
Unicode.
In the case where the Zip relative path is encoded using [UTF-8] , the language encoding flag (EFS) needs to be set.
If
an
author
chooses
to
use
the
utf8-chars
,
they
need
to
thoroughly
test
their
widgets
on
various
platforms
prior
to
distribution;
otherwise
it
is
suggested
that
authors
restrict
file
and
folder
names
to
the
safe-chars
(characters
in
the
US-ASCII
range).
In
addition,
having
excessively
long
path
names
(e.g.
over
120
characters)
can
also
result
in
interoperability
issues
on
some
operating
systems.
Authors
need
to
avoid
using
Zip
forbidden
characters
when
naming
the
files
used
by
a
widget.
These
characters
are
reserved
to
maintain
interoperability
across
various
file
systems
and
with
[URI]
s.
Authors
need
to
avoid
using
the
following
words
as
either
a
folder
or
a
file-name
in
a
Zip
relative
path
as
they
are
reserved
by
some
operating
systems
(case-insensitive):
CON,
PRN,
AUX,
NUL,
COM1,
COM2,
COM3,
COM4,
COM5,
COM6,
COM7,
COM8,
COM9,
LPT1,
LPT2,
LPT3,
LPT4,
LPT5,
LPT6,
LPT7,
LPT8,
LPT9,
CLOCKS$.
For
example,
the
following
names
are
ok:
"CON-tact.txt",
"printer.lpt1",
"DCOM1.pdf".
However,
"com3.txt"
"Lpt1",
"CoM9.gif"
would
not
be.
In addition, authors need to avoid having a "." U+002E FULL STOP as the last character of a file or folder name as some operating systems will remove the character when the file is extracted from the Zip archive onto the device. Furthermore, avoid having the space character ( SP ) at the start or end of a file name; and take caution when using the "+" U+002B PLUS SIGN, as it might cause issues on some operating systems.
User agents that claim conformance to this specification.
50
4B
03
04
wgt
None.
Steven Pemberton, member-webapps@w3.org
Common.
None.
This section is non-normative.
This
section
only
applies
to
HTML
user
agents
[HTML]
[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>
Huge
thanks
to
everyone
who
contributed
their
time
and
sent
feedback
to
our
public
mailing,
particularly
the
i18n
WG.
mailing.
This
specification
would
not
exist
without
the
contribution
of
the
following
individuals:
your
contribution:
Aaron
Boodman,
Adam
Barth,
Addison
Phillips,
Alexander
Dreiling,
Andrew
Sledd,
Andrew
Welch,
Arun
Ranganathan,
Arthur
Barstow,
Bárbara
Barbosa
Neves,
Bil
Corry,
Brian
Wilson,
Bjoern
Hoehrmann,
Benoit
Suzanne,
Bert
Bos,
Boris
Zbarsky,
Bradford
Lassey,
Bryan
Sullivan,
Cameron
McCormack,
Cliff
Schmidt,
Claudio
Venezia,
Coach
Wei,
Corin
Edwards,
Cynthia
Shelly,
Cyril
Concolato,
Dan
Brickley,
Dan
Connolly,
Daniel
Silva,
David
Clarke,
Dean
Jackson,
David
Poehlman,
David
Pollington,
David
Rogers,
Dominique
Hazael-Massieux,
Doug
Schepers,
Ed
Voas,
Felix
Sasaki,
Francois
Daoust,
Frederick
Hirsch,
Gautam
Chandna,
Geir
Pedersen,
Gene
Vayngrib,
Gorm
Haug
Eriksen,
Guido
Grassel,
Guenter
Klas,
Hans
S.
Tømmerholt,
Hari
Kumar
G,
Henri
Sivonen,
Henry
Story,
Ian
Hickson,
Ivan
Demarino,
Jay
Sweeney,
Jean-Claude
Dufourd,
Jeff
Decker,
Jere
Käpyaho,
Jim
Ley,
Jo
Rabin,
Jon
Ferraiolo,
Jonas
Sicking,
Jose
Manuel
Cantera
Fonseca,
Josh
Soref,
Jouni
Hakala,
Joey
Bacalhau,
Julian
Reschke,
Kevin
Lawver,
Kai
Hendry,
Krzysztof
Maczyński,
Lachlan
Hunt,
Larry
Masinter,
Laurens
Holst,
Mark
Priestley,
Marc
Silbey,
Marcin
Hanclik,
Mark
Baker,
Martin
J.
Dürst,
Michael
Cooper,
Max
Froumentin,
Mikko
Pohja,
Mohamed
Zergaoui,
Ms2ger,
Najib
Tounsi,
Noah
Mendelsohn,
Oguz
Kupusoglu,
Ola
Andersson,
Olli
Immonen,
Paddy
Byers,
Paul
Libbrecht
,
Philipp
Heltewig,
Philip
Taylor,
Rainer
Hillebrand,
Robert
Sayre,
Rune
F.
Halvorsen,
Samuel
Santos,
Scott
Wilson,
Sean
Mullan,
Sigbjorn
Finne,
Simon
Pieters,
Stephen
Paul
Weber,
Stephen
Jolly,
Stephane
Sire,
Steven
Faulkner,
Thomas
Landspurg,
Thomas
Roessler,
Tiago
Neves,
William
Edney,
Yoan
Blanc,
Yves
Savourel.
Savoure.
Special
thanks
go
to
Arve
Bersvendsen,
Robin
Berjon,
Anne
van
Kesteren,
and
Charles
McCathieNevile
who
helped
edit
various
versions
of
this
specification.
Big
A
big
thanks
also
to
Richard
Tibbett.
Anne
van
Kesteren
for
being
such
a
great
supporter
of
this
work!
Special thanks also to David Håsäther for creating and maintaining the [Widgets-Relax NG Schema] for the configuration document format.
Parts
of
this
document
reproduce
text
and
behavior
from
the
[HTML]
[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 .
This specification is dedicated to the children of India.