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
document
also
defines
expected
behavior
for
conformance
checkers,
which
are
tools
that
aid
authors
in
verifying
that
Zip
archives
and
configuration
documents
conform
to
this
specification.
This specification is part of the Widgets 1.0 family of specifications , which together standardize widgets as a whole.
This
section
describes
the
status
of
this
document
at
the
time
of
its
publication.
Other
documents
may
supersede
this
document.
A
list
of
current
W3C
publications
and
the
latest
revision
of
this
technical
report
can
be
found
in
the
W3C
technical
reports
index
at
https://www.w3.org/TR/.
http://www.w3.org/TR/.
This
specification
is
obsolete
the
23
July
2009
Candidate
Recommendation
of
the
Widgets
1.0:
Packaging
and
should
no
longer
Configuration
specification.
W3C
publishes
a
Candidate
Recommendation
to
indicate
that
the
document
is
believed
to
be
used
as
stable
and
to
encourage
implementation
by
the
developer
community.
The
Web
Applications
(WebApps)
Working
Group
expects
to
request
that
the
Director
advance
this
document
to
Proposed
Recommendation
once
the
Working
Group
has
developed
a
basis
for
implementation.
comprehensive
Widgets
1.0:
Packaging
and
Configuration
test
suite
,
and
demonstrated
at
least
two
interoperable
implementations
(interoperable
meaning
at
least
two
implementations
that
pass
each
test
in
the
test
suite
).
The
WebApps
Working
Group
expects
to
show
these
implementations
by
October
2009.
The
Working
Group
does
not
plan
to
request
to
advance
to
Proposed
Recommendation
prior
to
01
November
2009.
The
Widget
specifications
became
W3C
Recommendations
Feedback
based
on
any
aspect
of
this
specification
is
welcome
and
encouraged.
However,
there
are
certain
features
in
2012-2013.
They
were
designed
to
enable
interactive
single
purpose
application
for
displaying
and/or
updating
local
data
the
specification
that
the
Working
Group
is
particularly
interested
in
getting
feedback
on:
these
are
marked
as
"feature
at
risk"
within
the
specification.
Whether
such
features
are
retained
or
data
dropped
by
the
Working
Group
when
the
document
progresses
to
Proposed
Recommendation
will
depend
on
the
Web,
packaged
feedback
received
from
implementers,
other
working
groups,
and
the
public.
This document is produced by the Web Applications WG , part of the Rich Web Client Activity in the W3C Interaction Domain . It is expected that this document will progress along the W3C's Recommendation track.
Publication
as
a
way
to
allow
Candidate
Recommendation
does
not
imply
endorsement
by
the
W3C
Membership.
This
is
a
single
download
draft
document
and
installation
on
a
user's
machine
may
be
updated,
replaced
or
mobile
device.
obsoleted
by
other
documents
at
any
time.
It
is
inappropriate
to
cite
this
document
as
other
than
work
in
progress.
Since
2013,
Widgets
has
had
limited
deployment
and
its
usage
has
been
reduced
since
then.
Service
Workers
This
document
was
produced
by
a
group
operating
under
the
5
February
2004
W3C
Patent
Policy
.
W3C
maintains
a
public
list
of
any
patent
disclosures
and
Web
App
Manifest
made
in
connection
with
the
deliverables
of
the
group;
that
page
also
includes
instructions
for
disclosing
a
patent.
An
individual
who
has
actual
knowledge
of
a
patent
which
the
individual
believes
contains
Essential
Claim(s)
are
considered
to
provide
better
solutions
nowadays.
For
purposes
must
disclose
the
information
in
accordance
with
section
6
of
the
W3C
Patent
Policy
this
Obsolete
Recommendation
.
You
can
find
the
latest
Editor's
Draft
has
of
this
document
in
the
same
status
as
an
active
Recommendation;
it
retains
licensing
commitments
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.
widget
Element
name
Element
description
Element
author
Element
license
Element
icon
Element
content
Element
feature
Element
param
Element
preference
Element
readonly
its:span
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
addressed
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
The
reader
should
be
aware
that
this
document
is
organized
into
two
halves,
but
not
explicitly
marked
as
such.
The
first
half
defines
the
various
aspects
of
what
constitutes
the
packaging
format
,
the
configuration
document
,
and
reserved
files,
such
as
default
icons
and
locale
folders
.
,
as
well
as
some
of
the
expected
behavior
of
conformance
checkers
,
which
are
implementations
that
check
the
conformance
of
a
Zip
archive
or
a
configuration
document
to
this
specification.
Where
possible,
the
first
half
avoids
describing
aspects
related
to
processing,
which
are
described
in
detail
in
the
second
half
of
the
document.
The
second
half,
which
starts
with
the
section
titled
"
Steps
for
Processing
a
widget
package
",
defines
the
steps
required
to
process
a
widget
package
as
well
as
the
expected
behavior
of
a
user
agent
as
it
processes
the
packaging
format
,
format,
the
configuration
document,
and
attempts
to
find
localized
content.
The
second
half
of
this
document
also
deals
with
error
handling
in
the
event
that
a
user
agent
encounters
unsupported
or
missing
files,
or
DOM
nodes
that
are
in
error
in
the
configuration
document.
Wherever
processing
is
relevant,
sections
in
the
first
half
of
the
document
link
to
sections
in
the
second
half
of
the
document.
This section is non-normative.
This
section
defines
the
typographical
conventions
used
by
this
specification.
Some
text
in
this
specification
is
non-normative.
Non-normative
text
includes:
sections
marked
with
the
text
This
section
is
non-normative
,
authoring
guidelines,
examples,
and
notes.
Everything
else
in
this
specification
is
normative.
Defined terms appear as this sample defined term . Such terms are referenced as sample defined term , providing a link back to the term definition.
Words
that
denote
a
conformance
clause
or
testable
assertion
use
keywords
from
[RFC2119]
:
must
,
must
not
,
required
,
should
,
should
not
,
recommended
,
may
and
optional
.
The
keywords
must
,
must
not
,
should
,
recommended
,
may
and
optional
in
this
specification
are
to
be
interpreted
as
described
in
[RFC2119]
.
Variables
are
formatted
specially,
e.g.
variable
.
Code
is
also
specially
formatted,
such
as
code
.
Words in italics denote a formal definition given in an external specification.
This is an example. Examples are used to explain concepts or demonstrate how to use a feature. Examples are non-normative.
ISSUE: This is an issue. It implies something that Working Group is trying to fix. Eventually, all these will disappear from the spec. Issues are non-normative.
Note: This is a note, it usually contains useful supplementary information in a non-normative form.
This section is non-normative.
This
specification
is
part
of
the
Widgets
1.0
family
of
specifications
,
which
together
standardize
widgets
as
a
whole.
whole:
The
list
Widgets
1.0:
APIs
and
Events
specification
defines
API
s
to
store
preferences
and
capture
events
(see
[Widgets-APIs]
).
The
Widgets
1.0:
Digital
Signature
specification
defines
a
means
for
widgets
to
be
digitally
signed
using
a
custom
profile
of
specifications
the
XML-Signature
Syntax
and
Processing
Specification
(see
[Widgets-DigSig]
).
The
Widgets:
1.0:
Updates
specification
defines
a
version
control
model
that
make
up
allows
widgets
to
be
kept
up-to-date
over
[HTTP]
(see
[Widgets-Updates]
).
The Widgets 1.0: Access Requests specification defines a means to request access to URI-identifiable resources (e.g. resources on the Web) (see [Widgets-Access] ).
The
Widgets
Family
1.0:
URI
Scheme
specification
which
defines
a
URI
scheme
for
use
inside
widgets
or
other
such
applications
of
Specifications
can
be
found
web
technology
that
do
not
run
on
the
Working
Group's
wiki.
Web
(see
[Widgets-URI]
).
There
The
key
words
must
,
must
not
,
required
,
should
,
should
not
,
recommended
,
may
and
optional
in
this
specification
[RFC2119]
.
Some
text
in
this
specification
is
only
one
class
non-normative.
Non-normative
text
includes:
This section is non-normative,
Everything else in this specification is normative.
Please
see
the
typographical
conventions
to
see
how
authoring
guidelines,
examples,
and
notes
of
product
this
specification
are
stylized.
This specification describes the conformance criteria for user agents (relevant to implementers) and various resource types (relevant to authors).
There
are
four
classes
of
products
that
can
claim
conformance
to
this
specification:
a
A user agent may support other legacy/proprietary widgets.
The
following
terms
definitions
are
used
throughout
this
specification
so
they
are
gathered
here
for
the
readers
convenience.
The
following
list
of
terms
is
not
exhaustive;
specification.
Please
note
that
other
terms
are
defined
given
throughout
this
specification.
Arbitrary
means
that
a
character,
or
text
string,
or
file-name
,
or
folder-name
is
not
reserved
for
the
purpose
of
this
specification.
document
and
defined
where
they
are
used.
An
author
is
a
person
who
created
a
widget
package
or
an
authoring
tool
that
generated
a
widget
package
.
package.
Initialization
A
media
type
means
a
user
agent
procedurally
stepping
through
is
defined
in
the
steps
for
processing
a
widget
package
.
[MIME]
specification
(see
in
particular
RFC2046
).
A
language
tag
is
a
text
string
that
matches
must
match
the
production
of
a
Language-Tag
defined
in
the
[BCP47]
specifications
(see
specifications.
It
is
optional
for
a
user
agent
to
validate
language
tags
against
the
IANA
Language
Subtag
Registry
for
an
authoritative
list
of
possible
values,
see
also
the
Maintenance
Agency
for
ISO
3166
country
codes
).
.
A
media
type
widget
is
defined
in
by
the
[MIME]
[Widgets-Landscape]
specification.
as
an
end-user's
conceptualization
of
an
interactive
single
purpose
application
for
displaying
and/or
updating
local
data
or
data
on
the
Web,
packaged
in
a
way
to
allow
a
single
download
and
installation
on
a
user's
machine,
mobile
phone,
or
Internet-enabled
device
.
Because
widgets
are
packaged,
they
can
be
shared
by
users
without
relying
on
[HTTP]
(i.e.,
users
can
share
widgets
over
non-HTTP
distribution
channels,
such
as
Bluetooth
or
a
USB
thumb
drive).
Reserved
means
that
a
character,
or
text
string,
or
file-name
,
or
folder-name
has
a
specified
purpose
and
semantics
in
this
specification
or
in
some
other
specification
or
system.
The
intended
purpose
for
any
reserved
thing
reservation
is
given
when
the
term
is
used.
Arbitrary
means
that
a
character,
or
text
string,
or
file-name
,
or
folder-name
is
not
reserved
for
the
purpose
of
this
specification.
Supported means that a user agent implements a mentioned specification, or conformance clause, or is able to process or otherwise render mentioned media type .
Unsupported means the user agent does not implement a mentioned specification, or feature , or is unable to render or otherwise process a mentioned media type .
A
widget
Initialization
is
defined
by
means
a
run
through
the
[Widgets-Landscape]
as
an
end-user's
conceptualization
of
an
interactive
single
purpose
application
steps
for
displaying
and/or
updating
local
data
or
data
on
the
Web,
packaged
in
a
way
to
allow
processing
a
single
download
and
widget
package
after
installation
on
of
a
user's
machine,
mobile
phone,
or
Internet-enabled
device
.
Because
widgets
are
packaged,
they
can
be
shared
by
users
without
relying
on
[HTTP]
.
widget.
The
space
characters
are
code
points
marked
in
the
[Unicode]
specification
with
the
property
"White_Space",
including,
but
not
limited
to
,
for
the
following
list
(see
purposes
of
this
specification,
are
[Unicode]
for
the
authoritive
list):
code
points:
The Unicode white space characters are [Unicode] code points marked in the [Unicode] specification (version 5.0.0) with the property "White_Space". Those code points include:
The
Zip
forbidden
control
characters
,
for
the
purpose
of
this
specification,
are
[Unicode]
code
points:
The following Unicode code points are referred to as the forbidden characters in this specification:
A
user
agent
is
an
implementation
of
this
specification
that
also
supports
[XML]
,
[XMLNS]
,
[UTF-8]
,
[Unicode]
,
[DOMCore]
,
[SNIFF]
,
and
[ZIP]
(see
optional
aspects
of
the
Zip
specification
).
In
addition
to
widget
packages
,
a
user
agent
may
support
other
legacy
and
proprietary
application
packaging
formats.
It
is
optional
for
a
user
agent
to
support
the
optional
aspects
of
the
Zip
specification
.
this
specification.
Note:
The
user
agent
described
in
this
specification
does
not
necessarily
denote
a
"
widget
user
agent
"
at
large:
that
is,
a
user
agent
that
implements
all
the
specifications,
and
dependencies,
defined
in
the
Widgets
1.0:
Family
of
Specifications
.
Specifications.
The
user
agent
described
is
this
specification
is
only
concerned
with
how
to
processes
Zip
archives
and
configuration
documents
.
A user agent must behave as described by this specification in order to claim conformance, even when faced with a non-conforming widget package or a non-conforming configuration document .
4.1
Note:
Optional
Aspects
Implementers
can
partially
check
their
level
of
conformance
to
this
specification
by
successfully
passing
the
Zip
Specification
test
cases
of
the
[P&C-Test-Suite]
Note,
however,
that
passing
all
the
tests
in
the
test
suite
does
not
imply
conformance
to
this
specification;
It
only
implies
that
the
implementation
conforms
to
aspects
tested
by
the
test
suite.
The
optional
aspects
of
A
user
agent
must
support
the
following
specifications:
A user agent may support the [Widgets-DigSig] specification, the [Widgets-Updates] specification, the [Widgets-Access] specification, and the [Widgets-APIs] specification.
A
user
agent
must
support
the
[ZIP]
specification.
However,
it
is
optional
for
user
agent
to
support
the
following
aspects
represent
general
features
defined
in
of
the
[ZIP]
specification
that
this
specification
does
not
make
use
of:
specification:
To
facilitate
the
localization
of
text
nodes
within
XML
elements
in
a
configuration
document
,
a
user
agent
may
support
the
Internationalization
Tag
Set's
(
[ITS]
)
its:span
element
and
the
its:dir
attribute.
It
is
optional
for
a
user
agent
to
support
other
ITS
elements
and
attributes.
Although
this
specification
defines
the
elements
of
the
configuration
document
in
which
its:span
element
and
the
its:dir
attribute
can
be
used
(below),
the
specification
does
not
define
how
they
are
to
be
interpreted
and
processed
by
a
user
agent.
If
a
user
agent
implements
its:span
and
its:dir
,
then
the
user
agent
must
do
so
in
conformance
to
the
processing
rules
defined
by
the
[ITS]
specification.
A conformance checker ( CC ) is a user agent that verifies whether a widget package and a configuration document conform to this specification. A CC checks the conformance of either a widget package or a configuration document by implementing the assertions made in sections labeled Conformance Checker Behavior throughout this document.
In those sections, this specification asks CCs to inform authors of conformance violations, which means they display advisory messages to authors in a manner that assists them in making their widgets valid and conforming. Wording of advisory messages is left to the discretion of implementers. It is optional for a CC to display all messages at once.
The
packaging
format
for
the
files
of
a
widget
is
the
Zip
archive
file
format,
format
as
defined
in
the
[ZIP]
specification,
is
the
packaging
file
format
for
widget
packages
.
specification.
A
file
entry
is
the
data
held
by
a
local
file
header
,
file
data
,
and
(optional)
data
descriptor
,
as
defined
in
the
[ZIP]
specification,
for
each
physical
file
or
folder
contained
in
a
Zip
archive
.
A
potential
Zip
archive
is
a
data
object
claiming
to
be
a
Zip
archive
,
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
must
conform
to
the
production
of
a
.Zip
.Zip
file
as
defined
by
the
Zip
File
Format
Specification
[ZIP]
,
with
the
exclusion
or
support
for
the
features
and
meets
conditions
defined
in
the
requirements
Zip
Support
section
of
this
specification
(See
specification.
Note:
Step
2
).
of
the
steps
for
processing
a
widget
package
describes
how
a
user
agent
verifies
that
a
Zip
archive
conforms
to
this
specification.
The
magic
numbers
for
a
Zip
archive
is
the
byte
sequence:
50
4B
03
04
.
To conform to this specification, a Zip archive must contain one or more file entries and must be a valid Zip archive .
Note: A valid Zip archive does not imply a conforming widget package . All valid Zip archives need to be further checked, using Step 2 , to see if they qualify as a widget package.
An invalid Zip archive is a condition whereby a Zip archive, or a file within the Zip archive, is deemed to be corrupt beyond recovery or is non-conforming to, or unsupported by, this specification in such a way that it would not be possible for the user agent to continue processing. During the steps for processing a widget package , certain error conditions can result in a Zip archive being treated as an invalid Zip archive .
Upon encountering an invalid Zip archive , a user agent must apply the rule for dealing with an invalid Zip archive .
A CC must inform the author that a Zip archive that is split into multiple files or spans multiple volumes , as defined in the [ZIP] specification, is an invalid Zip archive .
A
CC
must
inform
the
author
that
a
Zip
archive
that
is
encrypted,
which
is
denoted
by
bit
0
of
the
general
purpose
field
being
set
and
by
the
presence
of
archive
decryption
header
and
an
archive
extra
data
record
(all
three
of
which
are
defined
in
the
[ZIP]
specification),
is
an
invalid
Zip
archive
.
A CC must inform the author that a Zip archive that contains zero file entries is an invalid Zip archive .
A CC must inform the author that a Zip archive that contains only folders is an invalid Zip archive .
A
compression
method
is
the
compression
algorithm
or
storage
method
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
is
used
to
encode
the
file
data
of
a
file
entry
is
identified
by
the
numeric
value
derived
from
the
compression
method
field
defined
in
the
[ZIP]
specification.
The valid compression methods , as indicated by the compression method field , for a file entry are:
8
0
Of
the
valid
compression
methods,
[Deflate]
is
the
preferred
recommended
compression
method.
A CC must verify that each file entry uses one of the valid compression methods . If a CC encounters a file entry that uses a compression method that is not one of the valid compression methods , then the CC must inform the author to recompressed the file entry using one of the valid compression methods .
The version needed to extract is the 2-byte sequence in the local file header of a file entry that indicates the minimum supported version of the [ZIP] specification needed to extract the file data .
The valid versions needed to extract values are as follows. Each value is assigned one or more meanings by the [ZIP] specification:
Note:
If
the
Zip
archive
has
been
encrypted
using
traditional
PKWARE
encryption,
then
the
user
agent
will
treat
the
Zip
archive
as
an
invalid
widget
package
Zip
archive
in
Step
2
.
A CC must inform the author of any file entry with a value for version needed to extract does not match a valid versions needed to extract value (meaning that user agents could potentially ignore the file at run time).
A Zip relative path is the variable-length string derived from the file name field of the local file header of a file entry .
Note: A Zip relative path is said to be relative as it stores the string that represents file and folder names relative to where the Zip archive was created on a file system (e.g. images/bg.png ), as opposed to storing an absolute path (e.g. c:\images\bg.png ). The value of a Zip relative path will generally resemble the string value of a name of the file or folder(s) on the device on which the Zip archive was created, but with the exception of the path delimiter being a U+002F SOLIDUS "/" character. Note also that a Zip relative path is not a URI reference; Zip relative paths need to be converted to URI references before they can be used in context that make use of URIs.
The valid encodings for a Zip relative path are either [CP437] or [UTF-8] . It is recommended that the file name field be encoded using [UTF-8] .
For interoperability, manipulations of Zip relative paths must be performed on the string obtained by decoding the file name field using the appropriate encoding, and not on the bytes initially stored in the archive. For the sake of comparison and matching, it is recommended that a user agent treat all Zip-relative paths as [UTF-8] .
A
valid
Zip
relative
path
is
one
that
matches
the
production
of
Zip-rel-path
in
the
following
[ABNF]
:
Zip-rel-path = [ *folder-name ] file-name /
[ locale-folder ] 1*folder-name /
locale-folder [ *folder-name ] file-name
locale-folder = %x6c.%x6f.%x63.%x61.%x6c.%x65.%x73 ; "locales"
"/" folder-name
folder-name = file-name "/"
file-name = base-name [ file-extension ]
base-name = 1*allowed-char file-extension = "." 1*allowed-char allowed-char = safe-char / utf8-char safe-char = ALPHA / DIGIT / SP / "$" / "%"
/ "'" / "-" / "_" / "@"
/ "~" / "(" / ")" / "&" / "+"
/ "," / "." / "=" / "[" / "]"
utf8-char = %x80-D7FF / %xF900-FDCF / %xFDF0-FFEF
/ %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD
/ %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD
/ %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD
/ %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD
/ %xD0000-DFFFD / %xE1000-EFFFD
Note
that
ALPHA
,
DIGIT
,
and
SP
are
defined
in
the
[ABNF]
specification
(but
essentially
represent
alphanumerical
characters
and
the
U+0020
SPACE
code
point
respectively).
This
section
is
non-normative.
Some
issues
can
arise
with
regards
to
character
encodings
of
file
names,
specification
does
not
put
a
restriction
on
the
byte
length
of
zip
a
Zip
relative
paths,
and
the
use
of
certain
strings
as
file
names.
This
sections
is
intended
path
,
so
a
user
agent
must
be
able
to
help
authors
avoid
potential
interoperability
issues.
deal
with
path
lengths
longer
than
250
bytes.
A
This
section
is
non-normative.
CC
must
inform
the
author
about
any
file
entry
whose
file
name
field
does
not
match
the
production
of
a
Zip-rel-path
.
Authors
need
to
avoid
using
A
CC
must
inform
the
author
of
any
Zip
relative
path
whose
length
exceeds
120
characters.
A
user
agent
must
ignore
a
file
that
contain
forbidden
characters
when
naming
in
the
files
used
by
a
widget.
Zip
relative
path
.
Note: These characters are reserved to maintain interoperability across various file systems and with [URI] s.
A
CC
must
inform
the
author
of
the
presence
of
any
of
the
forbidden
characters
in
a
file-name
.
A
CC
should
inform
the
author
of
the
presence
of
a
U+0020
SPACE
character
at
the
start
or
end
of
a
file-name
.
A
CC
should
inform
the
author
of
the
presence
of
any
U+002E
FULL
STOP
at
the
end
of
a
file-name
.
A
CC
should
inform
the
author
of
any
base-name
that
case-insensitively
matches
any
of
the
following
strings:
CON
,
PRN
,
AUX
,
NUL
,
COM1
,
COM2
,
COM3
,
COM4
,
COM5
,
COM6
,
COM7
,
COM8
,
COM9
,
LPT1
,
LPT2
,
LPT3
,
LPT4
,
LPT5
,
LPT6
,
LPT7
,
LPT8
,
LPT9
,
CLOCKS$
.
A
CC
may
inform
the
author
of
the
presence
of
any
U+002B
PLUS
SIGN
in
a
file-name
.
A
widget
package
is
must
be
a
valid
Zip
archive
that
contains
the
following:
contains:
content
element's
src
attribute.
icon
element's
src
attribute.
Note: See step 1 - Acquire a Potential Zip Archive for instructions on how to process a widget package.
The root of the widget package is the top-most path level of the Zip archive . The root of the widget package contains files and folders , some of which are reserved (see reserved file names table and reserved folder names table ).
A file is the decompressed physical representation of a file entry (i.e., a file extracted into its physical form as it was prior to being added to the Zip archive ).
Note: Unlike [HTTP] resources, file entries within a Zip archive are not available in multiple representations, nor are files dynamically generated from URI query parameters when the user agent retrieves them from within a Zip archive.
A
folder
is
a
file
entry
whose
file
name
field
matches
must
match
the
production
of
folder-name
in
a
valid
Zip
relative
path
(the
last
character
of
the
file
name
field
is
a
U+002F
SOLIDUS)
and
whose
version
needed
to
extract
is
2.0.
File-extension
to
media-type
mapping
is
the
process
whereby
a
user
agent
maps
the
file-extension
of
a
file
to
a
media
type
.
A
processable
file
is
must
be
a
file
that:
true
.
The
reserved
file
names
table
,
below,
contains
a
list
of
file
names
that
are
reserved
for
some
purpose
by
this
specification.
The
first
column
of
the
reserved
file
names
table
table,
below,
contains
a
case-sensitive
list
of
file
names.
The
second
column
of
the
table
denotes
the
purpose
for
which
the
file
name
is
reserved
.
file name |
|
---|---|
config.xml |
|
icon.png |
|
icon.gif |
|
icon.jpg |
|
icon.ico |
|
icon.svg |
|
index.html |
|
index.htm |
|
index.svg |
|
index.xhtml |
|
index.xht |
|
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.
Authoring
Guideline:
Authors
The
reserved
folder
names
table
,
below,
contains
a
list
of
file
names
that
are
strongly
encourage
to
package
all
files,
except
the
reserved
files
and
the
container
for
localized
content,
within
some
purpose
by
this
specification.
The
first
column
of
the
reserved
file
names
table,
below,
contains
a
single
subdirectory
named,
for
instance,
after
case-sensitive
list
of
file
names.
The
second
column
of
the
widget.
This
is
to
avoid
unzipping
several
files
into
table
denotes
the
end-user's
current
working
directory.
Future
versions
of
this
specification
may
include
rules
for
locating
index.html
and
config.xml
within
such
directories.
For
example,
best-practice
purpose
for
packaging
a
widget
would
look
something
like
this:
which
the
file
name
is
reserved
.
folder name | reserved for purpose |
---|---|
locales |
|
A widget package contains a digital signature , and hence is digitally signed , if the widget package contains one or more files that conform to the [Widgets-DigSig] specification. The file naming convention for digital signatures files is defined in the [Widgets-DigSig] specification.
A user agent must prevent a browsing context of a widget from accessing (e.g., via scripts, CSS, HTML, etc.) the contents of a digital signature document unless an access control mechanism explicitly enables such access, e.g. via an access control policy. The definition of such a policy mechanism is beyond the scope this specification, but may be defined to allow access to all or parts of the signature documents, or deny any such access.
An exception is if a user agent that implements this specification also implements the optional [Widgets-DigSig] specification, in which case the user agent must make signature documents available only to the implementation of the [Widgets-DigSig] specification; the user agent must not make the digital signatures accessible to scripting or other content loading mechanisms, unless explicitly enabled by an access control mechanism.
A start file designates a file from the widget package to be loaded by the user agent when it instantiates the widget. This specification defines two kinds of start file: custom start file and default start file .
A
custom
start
file
is
a
processable
start
file
inside
the
widget
package
identified
by
via
a
content
element's
src
attribute.
The
custom
start
file
must
be
a
processable
file
inside
the
widget
package
,
determined
by
applying
the
rule
for
identifying
the
media
type
of
a
file
.
When
a
start
file
is
not
explicitly
declared
via
the
content
element,
then
start
file
will
be
one
of
the
default
start
files
.
A
default
start
file
is
a
reserved
start
file
at
the
root
of
the
widget
package
or
at
the
root
of
a
locale
folder
whose
file
name
case-sensitively
and
exactly
matches
a
file
name
given
in
the
file
name
column
of
the
default
start
files
table
,
and
whose
media
type
matches
the
media
type
given
in
the
media
type
column
of
the
table.
It
is
optional
for
a
user
agent
If
no
custom
start
file
to
support
has
been
declared,
a
default
start
file
must
appear
at
either
the
media
types
root
of
the
widget
package
listed
in
or
at
the
default
start
files
table
root
of
a
locale
folder
.
If
a
user
agent
encounters
a
file
matching
a
file
name
given
in
the
file
name
column
of
the
default
start
files
table
in
an
arbitrary
folder
,
then
the
user
agent
must
treat
that
file
as
an
arbitrary
file.
For
example,
"
foo/bar/index.html
"
would
be
treated
as
an
arbitrary
file
.
file name | media type |
---|---|
index.htm | text/html |
index.html | text/html |
index.svg | image/svg+xml |
index.xhtml | application/xhtml+xml |
index.xht | application/xhtml+xml |
It is optional for a user agent to support the media types listed in the default start files table .
Note: See Step 8 for instructions on finding a default start file .
A CC must verify that the widget package contains at least one start file by:
content
element
to
point
to
a
processable
file
within
the
widget
package
.If the widget package does not contain a start file , then the CC must inform the author.
An
icon
is
a
an
optional
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
of
the
configuration
document
.
A user agent must derive the media type of a custom icon by applying the rule for identifying the media type of an image .
A custom icon can be located either at the root of the widget package , or at the root of a locale folder , or in an arbitrary folder .
A
default
icon
is
a
reserved
icon
,
whose
file
name
case-sensitively
and
exactly
matches
a
file
name
given
in
the
file
name
column
of
the
default
icons
table
.
A
default
icon
must
be
located
either
at
the
root
of
the
widget
package
or
at
the
root
of
a
locale
folder
,
whose
file
name
case-sensitively
and
exactly
matches
.
A
user
agent
must
derive
the
media
type
of
a
file
name
given
in
default
icon
from
the
file
name
media
type
column
of
the
default
icons
table
.
A
user
agent
must
search
for
a
default
icon's
file-name
based
on
the
order
they
appear
in
the
default
icons
table
(from
top
to
bottom).
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
Implementations
that
support
the
use
of
[SVG]
as
an
icon
format
optional
may
display
declarative
animation.
However,
for
security
reasons,
a
user
agent
must
not
execute
scripts
or
interactivity
defined
within
an
[SVG]
icon
file.
Animation
and
interactivity
is
defined
as
the
set
of
features
intended
for
use
of
SVG
as
a
dynamic
image,
corresponding
to
support
the
[SVGTiny]
profile,
and
to
specific
feature
strings:
http://www.w3.org/TR/SVG11/feature#SVG-static
http://www.w3.org/Graphics/SVG/feature/1.2/#SVG-animated
If
no
default
icon
listed
has
been
included,
and
the
CC
determines
that
no
custom
icons
have
been
declared
in
the
configuration
document
,
a
CC
SHOULD
inform
the
author
that
it
is
desirable
to
include
a
default
icons
table
icon
.
If a CC encounters an icon in the [SVG] format, the CC may inform the author if the icon includes script or interactive functionality.
If a CC encounters an icon in a format other than [PNG] or [GIF89] or [GIF87] , then the CC should inform the author other formats might not be supported by all user agents.
If a CC encounters an icon in the [SVG] format, then the CC MAY inform the author if the icon does not conform to the [SVGTiny] specification.
The
valid
widget
media
type
is
the
string
application/widget
[MIME]
.
.
ISSUE:
The
application/widget
media
type
has
not
yet
been
registered
with
IANA
.
This
will
happen
when
the
specification
reaches
Candidate
Recommendation
status.
A CC MUST inform the author if a widget package is not being served from a remote location with the valid widget media type .
A
widget
file
extension
is
the
text
string
that
case-insensitively
matches
the
string
"
.wgt
"
any
case
form
(e.g.
.wgt
,
.WGt
,
.WgT
,
etc.
are
all
valid).
The
widget
file
extension
is
required
for
widget
packages
on
systems
where
it
is
customary
for
file
names
to
include
a
".WGT
file-extension
"
component
that
symbolizes
(or
is
the
file
extension.
associated
with)
a
media
type
.
For
when
a
widget
file
extension
package
is
required
for
widget
packages
on
systems
where
it
not
served
over
HTTP,
a
CC
must
inform
the
author
if
the
file-extension
is
customary
for
file
names
to
include
not
a
file
widget
extension
that
symbolizes
(or
is
associated
with)
or
if
the
widget
lacks
a
media
type
.
file-extension
.
A
configuration
document
is
an
[XML]
document
that
has
a
widget
element
at
its
root
that
is
in
the
widget
namespace
.
A
widget
package
has
must
have
exactly
one
configuration
document
document,
which
must
be
located
at
the
root
of
the
widget
package
.
Note: Please see Step 7 for details of how the elements of the configuration document are processed by a user agent.
A
valid
configuration
document
file
name
is
the
string
config.xml
.
A
user
agent
must
treat
any
a
valid
configuration
document
file
name
case-sensitively.
Within a widget package, a configuration document must have a valid configuration document file name .
A
user
agent
must
treat
files
in
an
arbitrary
folder
or
locale
folders
that
uses
use
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 = "application fullscreen">
<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"
<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>
email = "foo-bar@example.org">Foo Bar Corp</author>
<icon src="icons/example.png"/>
<icon src="icons/boo.png"/>
<content src="myWidget.html"/>
<icon src="icons/boo.png"/>
<content src="myWidget.html"/>
<license>
Example license (based on MIT License)
Copyright (c) 2008 The Foo Bar Corp.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</license>
</widget>
</license>
</widget>
Note:
Implementers
are
encouraged
to
expose
relevant
information
provided
by
the
configuration
document
to
the
user.
Having
"visual
metadata"
encourages
authors
to
make
full
use
of
the
configuration
document
format.
See
Step
7
6
for
instructions
on
how
to
process
a
configuration
document.
A
CC
must
inform
the
author
if
there
is
no
configuration
document
is
at
the
root
of
the
widget
package
.
A
CC
must
inform
the
author
the
file-name
element.
All
other
elements
and
their
respective
attributes
are
optional.
The
following
example
shows
of
the
smallest
possible
configuration
document
that
a
user
agent
will
be
able
to
process.
The
reason
to
include
this
sole
element
is
to
explicitly
inform
a
user
agent
or
conformance
checker
that
this
zip
file
attempts
to
conform
to
this
specification.
<!-- example of the smallest possible conforming configuration document -->
<widget
xmlns="http://www.w3.org/ns/widgets"/>
does
not
case-sensitively
match
the
string
"
config.xml
"
(that
is,
by
checking
for
the
configuration
document's
file-name
in
other
case
forms.).
The
widget
namespace
URI
for
a
configuration
document
is
http://www.w3.org/ns/widgets
[XMLNS]
.
A
CC
must
inform
the
author
if
the
configuration
document
is
lacking
the
widget
package
namespace
.
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
must
do
so
by
using
a
separate
[XMLNS]
namespace.
This
specification
does
not
define
a
model
for
processing
[XML]
elements
outside
the
widget
namespace
(they
are
simply
ignored
during
processing).
.
Example of extending the configuration document format:
<widget xmlns="http://www.w3.org/ns/widgets"
xmlns:ex="http://example.org/">
<icon src="idle.png" ex:role="inactive"/>
<icon src="big.png" ex:role="big"/>
<ex:datasource>{a:"b",c:"d"}</ex:datasource>
<content src="widget.html"/>
</widget>
</widget>
A
CC
must
inform
the
author
of
Attributes
the
presence
of
any
proprietary
extensions
to
the
configuration
document
outside
the
widget
namespace.
This section defines the different attribute types used in the configuration document and what constitutes valid values for those attribute types. Some general rules for how attributes are to be processed by a user agent are also given in this section.
A user agent should impose their own implementation-specific limits on the values of otherwise unconstrained attribute types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
An attribute is invalid if its value does not conform to its said attribute type ; that is, if the value of the attribute is in error given the processing rules for that type of attribute.
A
boolean
attribute
is
a
keyword
attribute
that
can
only
be
used
with
a
valid
boolean
value.
A
valid
boolean
value
is
a
keyword
string
that
case-sensitively
matches
true
or
false
.
Unless
specified
otherwise,
the
default
behavior,
which
is
used
when
the
attribute
is
omitted
or
has
a
value
other
than
the
two
allowed
values,
is
false
.
The
way
a
user
agent
interprets
a
boolean
attribute
is
defined
as
part
of
an
attribute's
definition
(see,
for
example,
the
feature
element's
required
attribute).
The
A
user
agent
must
retrieve
the
value
of
a
string
attribute
is
any
string
that
conforms
to
[XML]
as
a
valid
string
for
an
XML
attribute.
The
purpose
of
this
attribute
type
is
to
classify
strings
that
are
not
affected
by
the
dir
attribute,
such
as
the
email
boolean
attribute
(i.e.,
these
attributes
will
not
treated
as
displayable-strings
during
Step
7
).
Displayable-string
attribute
An
attribute
whose
primary
purpose
is
to
convey
human
readable
information,
such
as
using
the
name
element's
short
rule
for
getting
a
single
attribute
and
the
widget
element's
version
attribute.
value
.
A
keyword
is
a
string
that
is
reserved
for
the
purpose
of
this
specification.
The
value
of
a
keyword
attribute
is
a
keyword
that
is
one
of
a
finite
set
specified
in
the
attribute's
definition
(e.g.
the
its:dir
attribute
defines
ltr
,
rtl
,
lro
,
or
rlo
as
its
only
possible
values).
For keyword attributes , authors must use keywords in the case given in this specification.
User agents must only perform literal comparisons on keyword attributes , and must not use case-insensitive comparisons. How the value of this attribute is retrieved by a user agent depends on the context in which is it used: so, the rule for how to retrieve the value is given when this attribute type is used in the specification.
An attribute defined as taking one or more keywords as a value, which are separated by space characters .
A user agent must retrieve the value of a keyword list attribute using the rule for getting a list of keywords from an attribute .
An
attribute
whose
value
is
defined
as
containing
a
valid
media
type.
A
valid
media
type
is
string
that
matches
the
production
for
valid-MIME-type
in
the
following
[ABNF]
:
valid-MIME-type = type "/" subtype *(";" parameter)
The
type
,
subtype
,
and
parameter
tokens
are
defined
in
the
[MIME]
specification.
Language
attribute
An
attribute
whose
value
is
defined
as
containing
a
valid
language
tag
(see
A
user
agent
must
retrieve
the
IANA
Language
Subtag
Registry
for
an
authoritative
list
value
of
possible
values,
see
also
this
kind
of
attribute
using
the
Maintenance
Agency
rule
for
ISO
3166
country
codes
).
A
valid
language
tag
is
a
string
that
conforms
to
the
production
of
getting
a
Language-Tag
,
as
defined
in
the
[BCP47]
specification.
single
attribute
value
.
The
value
of
a
numeric
attribute
is
a
string
containing
a
valid
non-negative
integer.
A
valid
non-negative
integer
is
a
string
that
consists
of
one
or
more
code
points
in
the
range
U+0030
DIGIT
ZERO
(0)
to
U+0039
DIGIT
NINE
(9).
For
example,
the
strings
characters
"002",
"323",
"23214",
and
so
on.
A user agent must retrieve the value of a numeric attribute using the rule for getting a single attribute value .
An
attribute
defined
as
containing
a
valid
path.
A
valid
path
is
one
that
matches
the
production
of
a
Zip-rel-path
or
a
Zip-abs-path
.
A
valid
path
is
not
a
URI:
a
valid
path
.
Authoring
Guidelines:
represents
represent
a
hierarchical
path
to
a
file
inside
a
Zip
archive
,
which
must
exactly
matches
match
the
value
of
a
file
name
field
of
a
local
file
header
of
a
file
entry
.
This
means
that
valid
paths
need
must
not
be
URL
encoded.
A
Zip
absolute
path
is
one
that
case-insensitively
matches
the
production
of
Zip-abs-path
in
the
following
[ABNF]
:
Zip-abs-path = "/" Zip-rel-path
Note:
A
Zip-abs-path
is
invalid
in
the
file
name
field
of
a
file
entry
.
A user agent must retrieve the value for a path attribute using the rule for getting a single attribute value .
An
attribute
defined
as
containing
a
valid
IRI.
A
valid
IRI
is
one
that
matches
the
IRI
token
of
the
[IRI]
[RFC3987]
specification.
A
user
agent
must
retrieve
the
risk
of
confusion
between
IRIs
that
would
be
equivalent
if
dereferenced,
value
for
a
IRI
attribute
using
the
use
of
%-escaped
characters
in
feature
names
is
strongly
discouraged.
rule
for
getting
a
single
attribute
value
.
A
displayable-string
attribute
whose
The
value
of
a
version
attribute
is
any
an
arbitrary
string
value
(possibly
empty)
within
the
constraints
allowed
for
[XML]
attributes.
empty).
This
specification
does
not
mandate
any
specific
format,
semantics,
or
special
processing
rule
for
the
format
of
a
version
attribute
.
A
user
agent
must
allow
any
string,
within
the
constraints
allowed
for
[XML]
attributes,
as
the
value
of
a
version
attribute
.
A user agent must retrieve the value for a version attribute using the rule for getting a single attribute value .
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
contents
and
attribute
values
of
child
nodes.
elements.
The
value
of
an
attribute
must
be
Authoring
Guidelines:
Although
[BCP47]
xml:lang
recommends
that
language
tags
casefolded
in
a
particular
way
for
presentation,
case
has
no
meaning
in
a
language
tag.
As
processed
by
a
reminder
to
authors
that
user-agents
map
all
language
tags
to
lowercase,
all
examples
in
this
document
use
lowercase.
See
also
folder-based
localization
,
which
also
requires
authors
to
use
language
tags
user
agent
in
lowercase
form
as
accordance
with
the
names
of
folders.
[XML]
specification.
A
user
agent
must
retrieve
the
value
for
an
xml:lang
attribute
using
the
rule
for
getting
a
single
attribute
value
.
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.
Note:
For
security
reasons,
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
).
To
use
the
dir
its:dir
attribute
had
no
effect
on
any
IRI
attributes
,
path
attributes
,
and
attribute,
the
author
element's
email
attribute.
The
base
direction
of
a
dir
its
attribute
is
either
set
explicitly
by
the
nearest
parent
element
that
uses
the
dir
namespace
(see
[ITS]
attribute;
or,
in
the
absence
of
such
an
attribute,
)
must
be
declared
on
the
base
direction
element
where
it
is
inherited
from
the
default
direction
of
used
or
somewhere
in
the
document
,
which
is
left-to-right
("
ltr
").
element's
ancestor
chain.
The
following
example
demonstrates
It
is
optional
for
authors
to
use
the
attribute
dir
its:dir
being
applied
globally
to
a
configuration
document
.
with
any
element.
The
following
example
shows
A
user
agent
must
retrieve
the
value
for
an
attribute
dir
its:dir
applied
to
localized
content
.
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
Weather Application
</name>
<name short="" xml:lang="fa" dir="rtl">
آب و هوا برنامه
</name>
</widget>
The
following
example
shows
using
the
dir
rule
for
getting
a
single
attribute
used
with
mixed
language
content:
value
.
widget
Element
The
widget
element
serves
as
a
container
for
the
other
elements
of
the
configuration
document
.
name
:
zero
or
more
(
one
element
is
allowed
per
language
).
description
:
zero
or
more
(
one
element
is
allowed
per
language
).
author
:
zero
or
one.
license
:
zero
or
more
(
one
element
is
allowed
per
language
).
icon
:
zero
or
content
:
zero
or
one.
feature
:
zero
or
more.
preference
:
zero
or
more.
widget
Element
id
An
A
IRI
attribute
that
denotes
an
identifier
for
the
widget.
It
is
optional
for
authors
to
use
the
id
attribute
with
a
widget
element.
version
A version attribute that specifies the version of the widget.
It
is
optional
for
authors
to
use
the
version
attribute
with
a
widget
element.
height
A
numeric
attribute
greater
than
0
that
indicates
the
preferred
viewport
height
of
the
instantiated
custom
start
file
in
CSS
pixels
[CSS]
[CSS21]
.
This
value
is
only
applicable
to
particular
view
modes
,
meaning
that
for
certain
view
modes
this
value
is
ignored
.
The
view
modes
that
honor
the
value
of
the
attribute
are
defined
in
the
[Widgets-Views]
specification.
Authoring
Guidelines:
height
It
is
optional
for
authors
to
use
the
height
attribute
with
a
widget
element.
width
A
numeric
attribute
greater
than
0
that
indicates
the
preferred
viewport
width
of
the
instantiated
custom
start
file
in
CSS
pixels
[CSS]
[CSS21]
.
This
value
is
only
applicable
to
particular
view
modes
,
meaning
that
for
certain
view
modes
this
value
is
ignored
.
The
view
modes
that
honor
the
value
of
attribute
are
defined
in
the
[Widgets-Views]
specification.
Authoring
Guidelines:
width
It
is
optional
for
authors
to
use
the
width
attribute
with
a
widget
element.
viewmodes
A
keyword
list
attribute
that
denotes
the
author's
preferred
view
mode,
followed
by
modes
supported
the
next
most
preferred
widget.
An
author
should
use
one
or
more
of
the
following
valid
view
mode
and
so
forth.
When
modes,
as
defined
in
the
attribute
is
missing,
[Widgets-Views]
specification:
application
,
floating
,
fullscreen
,
or
is
left
empty,
it
implies
that
the
author
expects
mini
.
In
addition,
the
user
agent
all
keyword
can
be
used
by
authors
to
select
an
appropriate
viewmode
for
denote
that
all
the
valid
view
modes
are
supported
by
the
widget.
The
concept
of
default
value,
which
a
viewport
is
defined
in
[CSS]
,
but
user
agent
must
use
when
the
attribute
is
essentially
a
window
absent
or
other
viewing
area
on
the
screen
(see
section
9.1.1
The
viewport
attribute
has
a
value
other
than
one
of
[CSS]
).
the
valid
view
modes
,
is
floating
.
The
concept
of
a
first
item
represents
the
author's
preferred
view
mode,
followed
by
the
next
most
preferred
view
mode
and
so
forth.
Viewport
and
view
mode
is
are
defined
in
the
[View-Modes]
[Widgets-Views]
specification.
It
is
optional
for
authors
to
use
the
viewmodes
attribute
with
a
widget
element.
user
agent
locales
xml:lang
list
or
in
case
the
author
has
not
provided
any
unlocalized
content.
It
is
optional
for
authors
to
use
the
attribute
with
a
defaultlocale
xml:lang
widget
element.
The following example shows how the widget element can be used.
<widget xmlns="http://www.w3.org/ns/widgets"
id="http://example.org/exampleWidget"
version="2.0 Beta"
height="200"
width="200"
viewmodes="floating application">
<description>
An example of the possibilities.
</description>
</widget>
name
Element
The
name
element
represents
the
full
human-readable
name
for
a
widget
that
is
can
be
used,
for
example,
in
an
application
menu
or
in
other
contexts.
widget
element.
xml:lang
:
xml:lang
attribute
name
Element
xml:lang
It
is
optional
for
authors
to
use
the
xml:lang
attribute
with
an
name
element.
its:dir
It
is
optional
for
authors
to
use
the
attribute
with
an
short
its:dir
.
name
element.
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).
It
is
optional
for
authors
to
use
the
short
attribute
with
an
name
element.
A
CC
must
inform
an
author
if
the
value
of
the
short
attribute
is
longer
in
length
than
the
text
content
of
the
name
element.
The
following
example
shows
the
usage
of
the
name
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
The Ultimate Weather Widget
</name>
<name short="Boletim" xml:lang="pt">
Boletim Metereológico
</name>
</widget>
</widget>
description
Element
The
description
element
represents
a
human-readable
description
of
the
widget.
widget
element.
xml:lang
:
xml:lang
attribute
description
Element
xml:lang
attribute
value
are
encountered,
the
user
agent
will
ignore
all
but
It
is
optional
for
authors
to
use
the
matching
first
element.
See
Step
7
xml:lang
attribute
with
an
for
more
details.
description
element.
its:dir
It
is
optional
for
authors
to
use
the
its:dir
attribute
with
an
description
element.
An example usage of the description element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name>Tornado Chaser</name>
<description>
Combining the latest weather info with your GPS position,
this widget alerts you of any significant dahut activity in your
area. When a big one walks by, the widget plots the best route on a map based
on the dahut's trajectory so you can chase it! With support for
built-in cameras, you can quickly upload all the Alpine action to
your blog or to the insane dahut chaser web site! Awesome!
Combining the latest weather info with your GPS position,
this widget alerts you of any significant storm activity in your
area. When a big one hits, the widget plots the best route on a map based
on the storm's trajectory so you can chase it! With support for
built-in cameras, you can quickly upload all the meteorological action to
your blog or to the insane storm chaser web site! Awesome!
</description>
</widget>
</widget>
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
a
IRI
that
the
author
associates
with
himself
or
herself
(e.g.,
a
homepage,
a
profile
on
a
social
network,
etc.).
It
is
optional
for
authors
to
use
the
attribute
with
an
href
xml:lang
author
element.
email
A
string
attribute
that
represents
an
email
address
associated
with
the
author.
It
is
optional
for
authors
to
use
the
email
attribute
with
an
author
element.
its:dir
It
is
optional
for
authors
to
use
the
its:dir
attribute
with
an
author
element.
The
following
example
shows
the
expected
usage
of
the
author
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<name>Cup-a-Joe's Cafe Finder Widget</name>
<author href = "http://dahut.example.org/about/joe"
email = "joe@example.org">
Joey and Princesa Bacalhau
</author>
</widget>
</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
:
xml:lang
attribute
license
Element
href
A valid IRI or a valid path that points to a representation of a software and/or content license.
When
the
href
attribute
is
used,
the
user
agent
should
provide
users
the
ability
to
view
or
otherwise
link
to
the
referenced
license.
If
the
attribute
contains
a
valid
path
to
a
file
within
the
widget
package,
then
the
user
agent
MUST
use
the
rule
for
identifying
the
media
type
of
a
file
to
identify
the
media
type
of
the
file
being
referenced.
Authoring
Guidelines:
href
It
is
optional
for
authors
to
use
the
href
attribute
with
a
license
element.
xml:lang
It
is
optional
for
authors
to
use
the
xml:lang
attribute
with
a
license
element.
its:dir
It
is
optional
for
authors
to
use
the
its:dir
attribute
with
a
license
element.
This
example
shows
the
expected
usage
of
the
license
element's
href
attribute.
<widget xmlns="http://www.w3.org/ns/widgets">
<license href="http://creativecommons.org/licenses/by/3.0/">
Creative Commons Attribution License
</license>
</widget>
</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.
...
</license>
</widget>
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.
A
user
agent
should
expose
a
custom
icon
in
a
way
that
it
is
visible
to
the
end
user.
widget
element.
xml:lang
:
height
xml:lang
.
value
are
allowed.
icon
Element
src
A path attribute that points to a file inside the widget package.
When
an
icon
element
is
used,
it
is
required
for
authors
to
use
the
src
attribute.
width
A
numeric
attribute
greater
than
0
that
represents,
represents
the
width
of
the
icon
in
CSS
pixels
[CSS]
,
the
author's
preferred
[CSS21]
.
The
width
is
only
applicable
to
graphic
formats
that
have
no
intrinsic
width
or
height
(e.g.,
SVG).
for
If
the
file
pointed
to
by
the
src
attribute
of
an
icon
element
is
a
supported
raster
graphic,
then
the
icon.
A
user
agent
may
must
ignore
this
value
when
changing
value.
If
the
height
icon
file
pointed
to
fit
by
the
src
attribute
of
an
icon
element
is
of
a
rendering
context
or
for
accessibility
reasons.
supported
vector
graphic
format,
then
the
user
agent
must
use
this
value.
It
is
optional
for
authors
to
use
the
width
attribute
of
an
icon
element.
height
A
numeric
attribute
greater
than
0
that
represents,
represents
the
height
of
the
icon
in
CSS
pixels
[CSS]
,
the
author's
preferred
[CSS21]
.The
height
attribute
is
only
applicable
to
graphic
formats
that
have
no
intrinsic
width
or
height
(e.g.,
SVG).
for
If
the
file
pointed
to
by
the
src
attribute
of
the
icon
element
is
a
supported
raster
graphic
format,
then
the
icon.
A
user
agent
may
must
ignore
this
value
when
changing
value.
If
the
height
icon
file
pointed
to
fit
by
the
src
attribute
is
a
rendering
context
or
for
accessibility
reasons.
vector
graphic
format,
then
this
value
must
be
used.
It
is
optional
for
authors
to
use
the
height
attribute
of
an
icon
element.
xml:lang
It
is
optional
for
authors
to
use
the
xml:lang
attribute
with
an
icon
element.
This
example
shows
the
expected
usage
of
the
icon
element.
The
example
declares
three
icon
elements,
two
of
which
are
raster
and
one
of
which
is
an
[SVGTiny]
file.
The
raster
graphics
would
be
used
for
display
contexts
smaller
than
256x256
pixels.
Document
order
of
the
elements
is
irrelevant.
<widget xmlns="http://www.w3.org/ns/widgets">
<icon src="icons/medium.png"/>
<icon src="icons/big.svg" width="256" height="256"/>
<icon src="icons/tiny.png"/>
</widget>
This
example
shows
the
expected
usage
of
the
icon
element
with
the
xml:lang
attribute.
Note
that
unlocalized
icon
elements
will
also
be
used
by
the
user
agent.
<widget xmlns="http://www.w3.org/ns/widgets"> <icon src="icons/big_en.svg" xml:lang="en"/>
<icon src="icons/big_jp.svg" xml:lang="jp"/>
<icon src="icons/medium.png" xml:lang="en"/> <icon src="icons/medium.png" xml:lang="jp" />
<icon src="icons/tiny.png"/>
<icon src="icons/ultra-tiny.png"/>
</widget>
content
Element
The
content
element
is
used
by
an
author
to
declare
which
custom
start
file
the
user
agent
is
expected
to
will
use
when
it
instantiates
the
widget.
widget
element.
xml:lang
:
content
Element
src
A path attribute that allows an author to point to a file within the widget package .
When
a
content
element
is
used,
it
is
required
for
authors
to
use
the
src
attribute.
type
A
media
type
attribute
that
indicates
the
media
type
of
the
file
referenced
by
the
src
attribute.
When
the
value
is
absent,
the
user
agent
will
assume
the
value
text/html
.
It
is
optional
for
authors
to
use
the
type
attribute
with
a
content
element.
When
the
value
is
absent,
the
user
agent
will
assume
the
value
text/html
.
encoding
A
keyword
attribute
that
denotes
the
character
encoding
of
the
file
identified
by
the
src
attribute.
The
allowed
value
is
the
"name"
or
"alias"
of
any
"Character
Set"
listed
in
[IANA-Charsets]
.
A
user
agent
must
support
[UTF-8]
,
which
has
the
"
"
name
in
[IANA-Charsets]
;
it
is
optional
for
a
user
agent
to
support
other
character
encodings.
Authoring
Guidelines:
UTF-8
When
the
value
of
encoding
is
absent
or
in
error
,
the
user
agent
must
assume
the
default
encoding
which
is
the
value
UTF-8
.
It
is
optional
for
authors
to
use
the
encoding
attribute
with
a
content
element.
This
example
shows
the
expected
usage
of
the
content
element:
<widget xmlns="http://www.w3.org/ns/widgets">
<content src="myWidget.html"/>
</widget>
</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>
<name>Ancient Chinese Maps</name>
<content src="china-maps.html" encoding="GB2312"/>
</widget>
</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>
required="false"/>
</widget>
feature
Element
A
feature
is
a
URI
identifiable
runtime
component
(e.g.
an
Application
Programming
Interface
or
video
decoder).
The
act
decoder)
that
is
not
part
of
a
an
author
requesting
the
availability
specified
set
provided
by
the
Widgets
1.0
family
of
a
feature
through
a
feature
element
is
referred
to
as
a
feature
request
.
specifications
.
The
feature
element
serves
as
a
standardized
means
to
request
the
binding
of
an
IRI
(IRI)
identifiable
runtime
component
to
a
widget
for
use
at
runtime.
Using
a
feature
element
denotes
that,
at
runtime,
a
widget
can
attempt
to
access
the
feature
identified
by
the
feature
element's
name
attribute.
How
a
user
agent
makes
use
of
features
depends
on
the
user
agent's
security
policy,
hence
activation
and
authorization
requirements
for
features
are
beyond
the
scope
of
this
specification.
A
feature
has
may
have
zero
or
more
parameters
associated
with
it.
widget
element.
param
elements.
xml:lang
:
feature
Element
name
An
A
IRI
attribute
that
identifies
a
feature
that
is
may
be
needed
by
the
widget
at
runtime
(such
as
an
API
).
When
the
feature
element
is
declared,
it
is
required
for
authors
to
use
the
name
attribute.
required
A
boolean
attribute
that
indicates
whether
or
not
this
feature
has
to
must
be
available
to
the
widget
at
runtime.
When
set
to
true
,
the
required
attribute
denotes
that
a
feature
is
absolutely
needed
by
the
widget
to
function
correctly,
and
without
the
availability
of
this
feature
the
widget
serves
no
useful
purpose
or
won't
execute
properly.
When
set
to
false
,
the
required
attribute
denotes
that
a
widget
can
function
correctly
without
the
feature
being
supported
or
otherwise
made
available
by
the
user
agent.
The
default
value
that
a
user
agent
will
behave
as
if
must
use
when
the
required
attribute
had
been
set
to
is
absent
is
true
,
meaning
that
the
feature
must
be
made
available
to
the
widget
by
the
user
agent
at
runtime.
when
It
is
optional
for
authors
to
use
the
required
attribute
is
absent,
meaning
that
the
named
with
an
feature
element.
needs
to
be
available
at
runtime
or
the
widget
will
be
treated
as
an
invalid
widget
package
.
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>
</widget>
param
Element
The
param
element
defines
a
parameter
for
a
feature
.
A
parameter
is
a
name-value
pair
that
is
associated
a
user
agent
must
associate
with
the
corresponding
feature
for
which
the
parameter
is
declared
for.
A
author
establishes
the
relationship
between
a
parameter
and
feature
by
having
a
param
element
as
a
direct
child
of
a
feature
element
in
document
order
.
A
user
agent
must
ignore
any
param
element
outside
the
context
of
a
feature
element
(outside
the
context
of
a
feature
element,
a
param
element
has
no
function
or
meaning).
feature
element.
xml:lang
:
param
Element
name
A
string
attribute
string,
which
may
be
empty,
that
denotes
the
name
of
this
parameter
.
When
a
param
element
is
declared,
it
is
required
for
authors
to
use
the
name
attribute.
value
A
string
attribute
string,
which
may
be
empty,
that
denotes
the
value
of
this
parameter
.
When
a
param
element
is
used,
it
is
required
for
authors
to
use
the
value
attribute.
This
example
demonstrates
a
widget
that
makes
use
of
a
fictional
geo-location
feature
where
by
its
accuracy
is
set
to
"
low
"
via
a
param
element.
<widget xmlns="http://www.w3.org/ns/widgets">
<feature name="http://example.org/api.geolocation">
<param name="accuracy" value="low"/>
</feature>
</widget>
</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.
initiated
.
A
user
agent
that
supports
the
[Widgets-APIs]
specification
will
must
expose
any
declared
preference
to
the
author
at
runtime
via
scripting
in
the
manner
described
in
the
[Widgets-APIs]
specification.
In
addition,
unless
a
preference
is
explicitly
marked
as
read-only
(via
the
readonly
attribute),
it
must
be
possible
for
authors
to
override
and
delete
preference
values
at
runtime
via
the
relevant
methods
defined
in
the
[Widgets-APIs]
specification.
widget
element.
xml:lang
:
preference
Element
name
A string that denotes the name of this preference .
When
a
preference
element
is
used,
it
is
required
for
authors
to
use
the
name
attribute.
value
A
string
that
denotes
the
value
of
this
preference
.
The
default
value
that
a
user
agent
must
use
for
when
the
attribute
is
absent
is
Authoring
Guidelines:
value
null
(i.e.,
the
data
value
null
,
and
not
a
string
"
null
").
It
is
optional
for
authors
to
use
the
value
attribute
with
a
preference
element.
readonly
A
boolean
attribute
indicating
whether
this
preference
can,
or
cannot,
can
be
overwritten
at
runtime
(e.g.,
via
an
author
script).
When
set
to
true
,
it
means
runtime.
The
default
value
that
a
user
agent
must
use
when
the
preference
cannot
be
overwritten.
When
set
to
readonly
attribute
is
absent
is
false
,
it
means
meaning
that
the
preference
value
can
be
overwritten.
overwritten
at
runtime.
It
is
optional
for
authors
to
use
the
readonly
attribute
with
a
preference
element.
If
the
readonly
attribute
is
absent,
the
user
agent
will
act
as
if
the
readonly
attribute
had
been
set
to
false
(meaning
that
the
preference
can
be
overwritten
at
runtime).
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"
<preference name = "api-key"
value = "f6d3a312f9d742"
readonly = "true"/>
</widget>
</widget>
span
its:span
The
span
element
This
feature
is
a
wrapper
for
text
content;
on
its
own
it
serves
no
useful
function.
at
risk
.
It
Although
it
is
expected
optional
for
a
user
agent
to
support
[ITS]
,
it
is
recommended
that
authors
will
use
the
span
element
with
the
global
attributes
.
When
combined
with
the
element
dir
attribute,
the
span
its:span
can
to
indicate
the
textual
directionality
of
text
content.
In
other
words,
it
allows
authors
to
set
the
base
direction
for
the
Unicode
bidirectional
algorithm
[BIDI]
.
When
combined
with
content
when
needed.
Directionality
is
indicated
by
either
using
the
attribute,
with
one
of
the
xml:lang
dir
span
following
valid
its:dir
element
allows
the
author
to
indicate
the
particular
language
used
for
a
subset
of
text
content
within
another
element.
value
s,
as
defined
in
ITS:
ltr
rtl
lro
rlo
No,
meaning
that
declaring
xml:lang
It
is
optional
for
authors
to
use
any
of
the
[ITS]
attributes.
This example shows ITS being used to correctly set the directionality of text:
<widget
xmlns="http://www.w3.org/ns/widgets"
xmlns:its="http://www.w3.org/2005/11/its">
on
a
span
<name>Yay for the
"<its:span dir="rtl">متعة الأسماك!</its:span>" Widget</name>
<description its:dir="rtl">متعة الأسماك! </description>
</widget>
The
its:span
element
within
may
be
used
as
a
parent
child
element
(e.g.,
a
of
the
following
elements
of
the
configuration
document
.
In
addition,
the
name
its:dir
element)
will
not
affect
attribute
may
be
used
in
the
behavior
of
element-based
localization
(see
Example
following
elements
of
Usage
below
to
see
how
this
works).
the
configuration
document
:
xml:lang
name
Global
attributes
.
description
7.16.1
Example
of
Usage
span
author
license
If
the
its:span
element
is
used,
or
the
attribute
is
xml:lang
its:dir
set
to
an
empty
string
to
allow
it
to
be
used
as
default
content
used,
the
[ITS]
namespace
http://www.w3.org/2005/11/its/
)
must
be
declared
in
the
process
of
element-based
localization
:
configuration
document
.
Internationalization , or i18n, is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language. Localization refers to the adaptation of a product, application or document content to meet the language, cultural and other requirements of a specific target market (a "locale").
Note: See also the Web Services Internationalization Usage Scenarios and the Unicode Locale Data Markup Language for an informative discussion on the term locale.
A
Localized
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
element-based
localization
).
A
widget
package
contains
may
contain
zero
or
more
localized
files.
All
files
and
folders,
except
for
the
digital
signatures
and
the
configuration
document
,
can
be
localized
via
folder-based
localization
.
For
example,
a
locale
folder
"
locales/ja/
"
"/locales/ja"
(Japanese)
might
contain
an
HTML
document
translated
into
Japanese.
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
may
contain
zero
or
more
locale
folders
.
A
locale
folder
is
a
folder
whose
file
name
field
matches
the
production
of
locale-folder
and
is
a
direct
descendant
of
the
container
for
localized
content
(e.g.,
"
/locales/en-us
",
"
/locales/fr
",
etc).
A
locale
folder
contains
may
contain
zero
or
more
arbitrary
folders
and/or
files.
A CC should inform the author if there are empty locale folders in the widget package .
A
CC
should
inform
the
author
if
the
folder-name
of
any
folder
uses
deprecated,
grandfathered,
or
redundant
language
tags
from
the
IANA
Language
Subtag
Registry
.
A CC should inform the author to avoid region or script subtags from the IANA Language Subtag Registry for the names of folders.
This
specification
defines
the
concept
of
element-based
localization
,
which
allows
authors
to
use
the
xml:lang
attribute
to
explicitly
indicate
that
an
[XML]
element
in
the
configuration
document
has
been
localized
.
The following is an example of element-based localization:
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
The Ultimate Weather Widget
</name>
<name short="Boletim" xml:lang="pt">
Boletim Metereológico
</name>
</widget>
</widget>
Some
As
part
of
their
definition,
the
XML
elements
in
of
the
widgets
namespace
configuration
document
are
defined
to
be
marked
as
being
localizable
via
xml:lang
as
part
of
the
element's
definition
(with
with
either
the
word
"yes"
or
"no").
See,
for
example,
the
"no".
If
an
element
is
marked
as
being
localizable
via
name
xml:lang
element.
When
"yes",
with
the
word
"no",
it
means
that
an
author
can
utilize
xml:lang
to
achieve
the
element
is
not
localizable
via
element-based
localization
either
directly
or
indirectly
through
the
inheritance
of
the
value
.
In
other
words,
exclusion
of
an
xml:lang
on
.
How
element-based
localization
is
handled
is
specified
in
detail
in
Step
7
.
Note:
The
xml:lang
attribute
can
be
used
any
an
element
indicates
that
that
element
in
order
to
indicate
which
language
is
used
in
the
unlocalized
content
and
attribute
values
of
that
element.
As
specified
,
except
in
the
XML
Specification,
its
value
is
inherited,
such
that
if
an
case
whereby
a
parent
element
has
an
uses
xml:lang
(this
maintains
consistency
with
the
behavior
of
attribute,
all
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
as
specified
in
no
specific
language
by
setting
the
[XML]
specification).
Explicitly
declaring
xml:lang
to
the
empty
string,
irrespective
of
whether
overrides
any
of
its
ancestors
has
an
xml:lang
value
inherited
from
a
parent
element.
attribute.
For
example,
if
an
the
author
uses
the
xml:lang
attribute
on
the
widget
element,
then
all
child
elements
inherit
the
value
xml:lang.
This
means
that
the
first
name
element
below
behaves
as
xml:lang="en"
had
been
explicitly
used.
However,
in
the
second
name
element,
the
declaration
of
xml:lang="pt"
overrides
xml:lang="en"
inherited
from
the
widget
element.
Finally,
the
last
name
element
overrides
xml:lang
with
an
empty
string,
so
that
element
will
be
treated
by
the
user
agent
as
default
content
.
<widget xmlns="http://www.w3.org/ns/widgets"
xml:lang="en">
<name short="I'm in english, though not explicitly marked as such!">
<name short="Weather">
Behaves as if xml:lang="en"
</name>
<name xml:lang="pt">
The declaration of xml:lang="pt" overrides
xml:lang="en" inherited from the widget element.
</name>
<name xml:lang="">
</name>
</widget>
</widget>
If
an
element
is
marked
as
being
localizable
via
xml:lang
with
"yes",
the
specification
always
indicates
that
only
if
one
element
is
allowed
per
language
:
or
whether
elements
are
grouped
by
language
:
One
element
is
allowed
per
language
means
that
only
one
element
of
a
type
is
allowed
to
be
used
per
language
(e.g.,
although
many
name
elements
can
be
present
in
a
configuration
document
,
only
one
name
element
will
be
selected
by
the
user
agent
for
the
English
language).
During
processing
(
Step
7
),
the
user
agent
will
must
only
match
the
first
element,
in
document
order
,
that
matches
a
language
range
in
the
user
agent
locales
and
ignore
any
subsequent
repetitions
of
the
element
that
contain
a
matching
xml:lang
value
(even
if
that
element's
content
is
different).
For
example,
assume
the
user
agent
locales
only
contains
the
following
language
range:
"
en-us
"
(English
as
used
in
the
United
States).
As
only
one
instance
of
the
description
element
is
allowed
per
language,
in
the
following
code
the
user
agent
would
match
the
first
description
element
but
would
ignore
the
second
and
third
description
elements.
<widget xmlns="http://www.w3.org/ns/widgets">
<description xml:lang="en">
This element would be used.
</description>
<description xml:lang="en">
This element would be ignored because there is already
a description element that uses xml:lang="en".
This element would be ignored.
</description>
<description>
This element is unlocalized, and would be used if the user agent's
locale does not match any localized description elements.
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
description element! Using xml:lang="" makes this element behave as if
it is unlocalized.
</description>
</widget>
</widget>
However,
if
the
user
agent
locales
only
contained
"
*
",
or
did
not
match
any
of
the
localized
description
elements,
then
the
user
agent
would
match
the
third
description
element
above.
In
the
case
whereby
the
author
does
not
use
an
xml:lang
attribute,
and
no
element
of
a
particular
type
with
xml:lang
matches
the
user
agent
locales
,
the
user
agent
will
must
use
the
first
element
that
is
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>
Elements
are
grouped
by
language
means
that
multiples
of
an
element
are
allowed
per
language
(e.g.,
multiple
icon
elements
are
allowed
per
language).
During
processing
(
Step
7
),
the
user
agent
must
match
all
elements
with
a
particular
name
(e.g.,
icon
)
having
an
xml:lang
attribute
value
that
matches
the
language
ranges
of
the
user
agent
locales
,
as
well
as
elements
of
that
particular
name
that
are
unlocalized
content
.
For
example,
assume
that
the
user
agent
locales
contains
the
following
language
ranges:
"
jp,en
"
(Japanese
and
english).
As
multiple
instances
of
the
icon
element
are
allowed
per
language,
in
the
following
code
the
user
agent
match
all
the
following
icon
elements.
Note
that
unlocalized
content
elements
are
also
matched.
<widget xmlns="http://www.w3.org/ns/widgets">
<icon xml:lang="en" src="icons/a.png"/>
<icon xml:lang="jp" src="icons/b.png"/>
<icon src="icons/c.png"/>
<icon src="icons/d.png"/>
</widget>
Now
assume
that
the
user
agent
locales
contains
the
following
language
range:
"
jp
"
(Japanese).
In
the
following
code,
the
user
agent
would
ignore
the
first
icon
element,
but
match
the
second,
third,
and
fourth
icon
elements.
<widget xmlns="http://www.w3.org/ns/widgets">
<icon xml:lang="en" src="icons/a.png"/>
<icon xml:lang="jp" src="icons/b.png"/>
<icon src="icons/c.png"/>
<icon src="icons/d.png"/>
</widget>
This section is non-normative.
This
section
presents
three
examples
of
how
widgets
can
be
localized.
Each
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
/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>
</widget>
locale/es/index.html
/locale/es/index.html
<!doctype html>
<title>¿Qué día es?</title>
<script src="scripts/dayfinder.js"></script>
<script src="/scripts/engine.js"></script>
<body>
<p>Hoy es: lunes, martes, miércoles,
jueves, viernes, sábado,
<p>Hoy es: lunes, martes, miércoles,
jueves, viernes, sábado,
domingo
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/
/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>
</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">
...
<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
":
scenario:
So,
if
for
example,
assume
the
user
agent's
locale
did
not
find
is
'
en-gb
'.
The
user
agent
would
fail
to
locate
'mast.png'
so
the
zip
relative
path
next
place
it
would
look
is
in
one
of
the
locale
folders,
then
'
'
images/mast.png
en/
file
at
the
root
of
the
widget
would
be
matched
and
this
default
content
folder,
where
it
would
be
used.
find
the
absent
'
mast.png
'
file.
Now
consider
the
for
various
Chinese
variants:
'
zh-hans-cn
',
'
zh-hans
',
and
'
zh
'
below.
In
this
case,
to
find
the
'
flag.png
'
file
for
Mainland
Chinese
in
simplified
script
'
zh-hans-cn
',
the
user
agent
would
first
look
in
'
zh-hans-cn
',
followed
by
'
zh-hans
',
then
in
'
zh
'
where
the
file
is
located.
To
find
the
'
mast.png
'
file,
the
user
agent
would
look
in
'
zh-hans-cn
',
followed
by
'
zh-hans
',
followed
'
zh
',
and
finally
at
the
root
of
the
widget
package
where
the
absent
file
is
actually
located.
/index.html
<!doctype html>
<title>Patriotic Boat</title>
<script src="scripts/engine.js">
<script src="/scripts/engine.js">
</script>
<body>
<img src="flag.png">
<img
src="mast.png">
<img src="flag.png">
<img src="mast.png">
The
steps
for
processing
a
widget
package
involves
nine
steps
that
a
user
agent
follows
may
follow,
in
sequential
order,
responding
accordingly
if
any
of
the
steps
result
in
an
error
or
if
the
specification
asks
for
the
user
agent
to
skip
a
step.
The
procedures
for
what
to
do
when
an
error
is
encountered
are
described
as
part
of
each
step;
however,
there
are
times
when
it
will
not
be
possible
for
the
user
agent
to
recover
from
an
error
and
it
will
be
forced
to
treat
the
widget
as
an
invalid
widget
package
.
In
the
event
that
a
user
agent
encounters
Zip
archive
(see
rule
for
dealing
with
an
invalid
widget
package
Zip
archive
during
the
).
The
steps
for
processing
a
widget
package
,
a
user
agent
must
abort
all
and
associated
processing
of
the
steps
rules
are
written
with
more
concern
for
processing
clarity
than
efficiency.
As
such,
a
widget
package
.
Note:
A
user
agent
can
may
optimize
steps
for
processing
a
widget
package
and
associated
processing
any
of
the
parsing
rules
,
and
the
steps,
or
may
perform
the
steps
in
a
different
order,
but
the
end
result
needs
to
must
be
indistinguishable
from
the
result
that
would
be
obtained
by
following
the
specification.
This
section
defines
various
processing
rules
,
which
are
a
set
of
common
algorithms
used
during
in
the
by
the
steps
for
processing
a
widget
package
.
The
rule
for
extracting
file
data
from
a
file
entry
is
as
follows:
described
in
this
section.
Let
Given
a
path
be
the
zip
relative
path
that
identifies
matches
the
file
entry
being
sought.
Let
file
entry
name
field
be
the
of
a
file
entry
identified
by
the
path
.
Let
file
be
within
the
result
of
decompressing
Zip
archive
,
a
user
agent
must
decompress
(or
extracting)
otherwise
extract)
the
file
data
from
of
file
entry
using
into
its
original
file
representation.
Implementers
must
follow
the
[Zip]
.
Return
[ZIP]
specification's
instructions
on
how
to
extract
a
file
.
from
the
Zip
archive.
Note: For efficiency, a user agent can extract specific files as they are needed for processing rather than extracting all the files at once. As a security precaution, implementations are discouraged from extracting file entries from un-trusted widgets directly onto the file system. Instead, implementations could use, for example, a virtual file system or mapping to access files inside a widget package .
The rule for dealing with an invalid Zip archive is described in this section.
In the event that an implementation encounters an invalid Zip archive during the steps for processing a widget package , the user agent must abort all processing of the steps for processing a widget package .
In the case the UA is a CC, it must inform the author that the Zip archive is an invalid Zip archive .
The
rule
for
finding
a
file
within
a
widget
package
is
given
in
the
following
algorithm.
The
algorithm
returns
either
a
processable
file
,
null
,
or
an
error.
Note: This specification does not define how links in documents other than the configuration document are to be dereferenced. For handling links in other documents, such as (X)HTML, CSS, SVG, etc., please refer to the [Widgets-URI] specification.
Let
path
be
the
valid
path
to
the
file
entry
being
sought
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.
sought.
Let path-components be the result of splitting path at each occurrence of a U+002F SOLIDUS character, removing that U+002F SOLIDUS character in the process.
If
the
number
of
items
in
path-components
is
greater
than
two,
then
check
if
the
first
second
item
in
path-components
case-sensitively
exactly
matches
the
string
"
locales
",
then:
".
If
the
path-components
does
not
contain
a
second
item,
then
return
null
.
it
does:
If
the
second
third
item
in
path-components
is
not
contains
any
characters
other
than
a
valid
U+002D
HYPHEN-MINUS
("-")
or
characters
the
range
,
then
return
language-range
%x61-71
null
and
terminate
this
algorithm.
(I.e.,
The
third
item
in
path-component
can
only
contain
lower-case
ASCII
characters
or
zero
or
more
hyphens).
If
the
path
starts
with
a
U+002F
SOLIDUS
(e.g.,
"
/style/master.css
"),
meaning
that
the
path
is
an
Zip
absolute
path
,
then
remove
the
first
U+002F
SOLIDUS
from
path.
For each lang-range in the user agent locales :
Let
path
be
the
concatenation
of
the
string
"
locales/
",
the
lang-range
,
a
U+002F
SOLIDUS
character,
and
the
path
(e.g.,
locales/en-us/cats.png
,
where
"
en-us
"
is
the
lang-range
and
"
cats.png
"
is
the
path
).
If
path
case-sensitively
matches
the
file
name
field
of
points
to
a
file
entry
within
the
widget
package
that
is
a
folder
,
,
then
return
an
error
and
terminate
this
algorithm.
If
path
case-sensitively
matches
the
file
name
field
of
a
file
entry
within
the
widget
package
that
is
a
file
,
let
file
be
the
result
of
applying
the
rule
for
extracting
file
data
from
a
file
entry
to
path
.
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
matching
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
,
found,
let
file
be
the
result
of
applying
the
rule
for
extracting
file
data
from
a
file
entry
to
path
.
If file is a processable file , then return file and terminate this algorithm.
If
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
may
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.
character.
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
may
be
empty.
Let
result
be
the
value
of
the
attribute
to
be
processed.
attribute.
In result , replace any sequences of space characters (in any order) with a single U+0020 SPACE character.
In result , remove any leading or trailing U+0020 SPACE character.
In result , split the string at each occurrence of a U+0020 character, removing that U+0020 character in the process.
The rule for verifying a file entry is given in the following algorithm. The algorithm always returns a boolean value.
For the file entry , check the following data in the local file header .
If
the
value
of
the
CRC-32
field
(defined
in
the
[ZIP]
specification)
fails
a
CRC-32
check,
return
false
and
terminate
this
algorithm.
The
version
needed
to
extract
is
greater
than
20
(meaning
the
archive
is
using
a
feature
unsupported
by
this
specification,
such
as
Zip64),
return
false
and
terminate
this
algorithm.
The
file
name
field
is
an
empty
string,
return
false
and
terminate
this
algorithm.
The
file
name
field
contains
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
element
to
be
processed
must
be
interpreted
as
a
[DOM3Core]
Element
.
The
algorithm
always
returns
a
list
of
localizable
string
s,
string,
which
can
may
be
empty.
A
text
node
refers
to
any
Text
node,
including
CDATASection
nodes
(any
Node
with
node
type
TEXT_NODE
or
CDATA_SECTION_NODE
)
as
defined
in
the
[DOM3Core]
specification.
Let
input
be
the
Element
to
be
processed.
Let
bidi-text
be
an
empty
list
of
localizable
strings
.
If
input
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
xml:lang
attribute
on
either
input
,
or
in
input
's
ancestor
chain
as
per
[XML]
This
feature
is
at
risk
.
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
the
rule
for
determining
directionality
user
agent
supports
to
input
.
Associate
lang
[ITS]
,
and
direction
with
bidi-text
.
For
each
child
node
of
if
the
input
:
If
child
node
is
not
an
Element
or
TextNode
,
move
onto
the
next
child
element
and
ignore
the
following
sub-steps.
If
has
the
child
node
is
an
attribute
from
the
Element
,
let
lstring
be
the
result
of
recursively
applying
dir
rule
for
getting
text
content
[ITS]
using
this
current
child
element
as
the
argument.
If
the
child
node
is
namespace
or
any
children
with
a
text
node
valid
its:dir
value
,
then:
Create
a
new
localizable
string
called
lstring
,
using
the
text
content
of
the
current
child
node
as
the
text
value,
then
process
direction
input
as
the
direction,
and
lang
as
the
language.
Append
lstring
its
descendant
text
nodes
in
accordance
to
the
lang-string
list.
[ITS]
specification.
Take
all
Return
the
text
nodes,
in
order,
from
value
of
the
returned
localizable
string
and
associate
them
with
textContent
attribute
of
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
may
be
empty.
Let
input
be
the
Element
to
be
processed.
Let result be the result of applying the rule for getting text content to input .
In result , convert any sequence of one or more Unicode white space characters into a single U+0020 SPACE.
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).
and
the
resulting
widget
short
name
would
be
"
D
A
H
U
T
":
<widget xmlns="http://www.w3.org/ns/widgets">
<name short= "
D A H U T
">
The <blink>Awesome</blink>
<author email="dude@example.com">Super <blink>Dude</blink></author>
Widget</name>
</widget>
The
rule
for
parsing
a
non-negative
integer
is
are
as
given
in
the
following
algorithm.
This
When
invoked,
the
algorithm
returns
must
be
followed
in
the
number
order
given,
aborting
at
the
first
step
that
returns
a
value.
This
algorithm
will
either
return
zero,
a
positive
integer,
or
an
error.
There may be implementation-specific limits on the range of integers allowed, and behavior outside such limits is undefined by this specification.
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
the
start
of
the
string.
Let nextchar be the character in input at position .
If
the
nextchar
is
one
of
the
space
characters
,
increment
position
.
If
position
is
past
the
end
of
input
,
return
an
error
and
terminate
this
algorithm.
error.
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
an
image
is
given
by
the
following
algorithm.
It
is
optional
for
user
agents
to
support
any
of
the
media
types
listed
in
the
media
type
identification
table
.
The
algorithm
always
returns
a
string.
Note:
This
rule
is
only
to
be
applied
when
explicitly
instructed
to
by
the
specification
(e.g.,
during
(during
Step
7
).
There
are
situations
where
alternative
means
are
defined
by
the
specification
to
identify
the
media
type
of
a
file
(e.g.,
by
the
presence
of
the
content
element's
type
attribute
or
deriving
the
media
type
of
a
default
start
file
from
the
default
start
files
table
).
file-name
file-extension
component
of
the
zip
relative
path
that
identifies
,
attempt
to
match
the
file
file-extension
.
For
example,
the
name
for
"
some/zip/rel/path/hello.png
file-extension
,
if
the
first
unknown/unknown
.
file
| magic number | media type | comment about magic number |
---|---|---|---|
.gif |
47
49
46
38
37
61
| image/gif |
The
string
"
GIF87a
",
a
GIF
signature.
|
.gif |
47
49
46
38
39
61
| image/gif |
The
string
"
GIF89a
",
a
GIF
signature.
|
.png |
89
50
4E
47
0D
0A
1A
0A
| image/png | The PNG signature. |
.ico |
00
00
01
00
| image/vnd.microsoft.icon | A Windows Icon file format signature. |
.svg | image/svg+xml |
SVG
documents
cannot
be
file
extension
| |
.jpg |
FF
D8
| image/jpeg |
A
JPEG
SOI
marker
followed
by
the
first
byte
of
|
If
The
rule
for
identifying
the
first
character
media
type
of
a
file
is
given
by
the
name
following
algorithm.
It
is
a
U+002E
'FULL
STOP'
character,
and
optional
for
user
agents
to
support
the
media
types
given
in
the
file
name
contains
another
U+002E
'FULL
STOP'
character,
then
let
extension
identification
table
below.
The
algorithm
always
returns
a
string.
Note:
This
rule
is
only
to
be
applied
when
explicitly
instructed
to
by
the
sequence
of
characters
from
specification
(during
Step
7
).
There
are
situations
where
alternative
means
are
defined
by
the
last
U+002E
'FULL
STOP'
(inclusive)
specification
to
identify
the
end
media
type
of
name
(if
any).
For
example,
if
a
file
(e.g.,
by
the
name
is
"
.myhidden.html
",
then
presence
of
the
extension
would
be
"
element's
.html
content
".
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
type
attribute
or
in
deriving
the
U+0061-U+007A
range
(ASCII
uppercase
and
lowercase
characters,
respectively)
or
in
media
type
of
a
default
start
file
from
the
U+0030-U+0039
range
(ASCII
numbers
0
to
9):
default
start
files
table
).
If
any
character
in
the
extension
Let
file
is
outside
the
U+0041-U+005A
range
or
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
",
be
the
go
file
to
step
10
in
this
algorithm.
be
processed.
If
all
characters
in
the
extension
file
are
in
any
of
the
U+0041-U+005A
range
or
in
the
U+0061-U+007A
range
or
the
U+0030-U+0039
range
(e.g.,
"
has
a
,
attempt
to
Mp3
"),
then
file-extension
case-insensitive
match
the
value
of
extension
file-extension
to
one
of
the
values
in
the
file
extension
extensions
column
in
the
file
identification
table
.
If
there
is
a
match,
then
return
let
content-type
be
the
corresponding
value
from
the
media
type
column.
Go
to
step
11.
value.
Let
If
content-type
file
extension
be
is
absent,
the
result
media
type
of
processing
a
file
through
must
be
determined
by
using
the
rules
set
forth
in
the
[SNIFF]
specification.
file
|
media type |
---|---|
.html | text/html |
.htm | text/html |
.css | text/css |
.js | application/javascript |
.xml | application/xml |
.txt | text/plain |
.wav | audio/x-wav |
.xhtml | application/xhtml+xml |
.xht | application/xhtml+xml |
The rule for determining if a potential Zip archive is a Zip archive is given by the following algorithm.
50
4B
03
04
).
See
also
the
informative
note
below.
true
.
Note: A user agent can inspect the potential archive once it has acquired the first four bytes of the potential Zip archive or can wait until all the data of the potential Zip archive has been completely acquired.
Step
1
involves
acquiring
a
potential
Zip
archive
and
confirming
that
it
is
a
Zip
archive
by
applying
the
rule
for
determining
if
a
potential
Zip
archive
is
a
Zip
archive
.
A
user
agent
will
acquire
a
potential
Zip
archive
from
a
data
transfer
protocol
that
either
labels
resources
with
a
media
type
(e.g.
[HTTP]
)
or
from
a
data
transfer
protocol
that
does
not
label
resources
with
a
media
type
(e.g.,
BitTorrent
or
Bluetooth).
Bluetooth):
When
attempting
to
acquire
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
some
protocol
that
labels
resources
with
a
media
type,
then
the
type
,
a
user
agent
needs
must
only
attempt
to
process
resources
labeled
with
the
valid
widget
media
type
(
application/widget
),
regardless
of
whether
the
resource
contains
a
file
extension
or
not,
by
applying
the
rule
for
determining
if
a
potential
Zip
archive
is
a
Zip
archive
.
During
the
acquisition
of
a
potential
Zip
archive
labeled
with
a
media
type
,
unless
Unless
the
user
agent
supports
legacy
or
proprietary
media
types
,
unsupported
all
other
media
types
are
in
error
and
the
user
agent
must
treat
the
potential
Zip
archive
as
an
invalid
widget
package
Zip
archive
.
If
the
result
of
the
user
agent
applying
the
rule
for
determining
if
a
potential
Zip
archive
is
a
Zip
archive
is
true
,
meaning
that
the
potential
Zip
archive
is
a
Zip
archive
,
then
the
user
agent
must
proceed
to
Step
2
.
Otherwise,
if
an
error
is
returned,
the
user
agent
must
treat
the
potential
Zip
archive
as
an
invalid
widget
package
Zip
archive
.
For
example,
in
[HTTP]
,
where
the
Content-Type
header
matches
application/widget
.
If
the
protocol
used
for
acquisition
of
a
potential
Zip
archive
does
not
provide,
or
otherwise
include,
a
media
type
,
then
a
user
agent
should
may
treat
the
acquired
potential
Zip
archive
as
if
it
has
been
acquired
from
a
protocol
that
does
not
label
resources
with
a
media
type
.
(see
sub-section
below).
In
this
example,
the
media
type
of
the
Content-Type
is
not
one
supported
by
the
user
agent,
so
the
user
agent
would
treat
the
potential
Zip
archive
as
an
invalid
widget
package
Zip
archive
:
GET /foo.wgt HTTP/1.1
Host: www.example.com
Accept:
application/widget
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
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
Zip
archive
.
To
verify
that
a
Zip
archive
and
its
file
entries
conform
to
this
specification,
a
user
agent
must
apply
perform
the
rule
for
verifying
a
zip
archive
.
If
following
checks.
This
specification
does
not
provide
the
rule
for
verifying
a
zip
archive
returns
true
,
then
technical
details
of
how
to
actually
perform
the
user
agent
checks,
for
which
implementers
must
go
to
Step
3
.
Otherwise,
if
follow
the
rule
for
verifying
a
zip
archive
[ZIP]
returns
an
error,
then
specification.
The potential widget package can be considered verified only once the checks below have been completed.
If
any
of
the
following
conditions
are
met,
then
a
user
agent
must
treat
the
Zip
archive
as
an
invalid
widget
package
Zip
archive
:
The Zip archive is split into multiple files or spans multiple volumes , as defined in the [ZIP] specification.
The Zip archive is encrypted (which is denoted by bit 0 of the general purpose field being set and by the presence of archive decryption header and an archive extra data record , all three of which are defined in the [ZIP] specification).
The Zip archive contains zero file entries (i.e., the archive is empty).
The Zip archive contains only folders .
A
CC
must
verify
each
file
entry
by
applying
the
rule
for
verifying
a
file
entry
.
If
the
result
of
applying
the
rule
for
verifying
a
file
entry
is
false
,
a
CC
must
inform
the
author.
In
Step
3
,
this
Step,
a
user
agent
must
set
the
following
variables
and
default
values
as
defined
in
the
table
of
configuration
defaults
.
below.
When
a
null
value
is
assigned
to
a
variable
in
the
table
of
configuration
defaults
,
a
user
agent
needs
to
treats
table,
an
implementation
must
treat
the
value
as
null
(i.e.,
not
as
an
empty
string
and
not
as
the
text
string
"null"
).
Variable | Type | Default Value |
Overridden
|
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
element's
id
attribute
in
the
configuration
document
(if
any).
|
widget license | String |
null
| Step 7 |
The
text
content
of
the
license
element
in
the
configuration
document
(if
any).
|
widget license file | File |
null
| Step 7 |
A
file
derived
if
the
value
of
the
license
element's
href
is
a
Zip
relative
path
to
a
file
within
the
widget
package
.
|
widget license href | IRI | null | Step 7 |
The
value
of
the
license
element's
href
attribute
in
the
configuration
document
(if
any).
|
widget name |
|
null
|
Step 7 |
The
text
content
of
the
name
element
in
the
configuration
document
(if
any).
|
widget preferences | List | null | Step 7 |
The
widget's
preferences
,
corresponding
to
the
preference
elements
in
the
configuration
document
(if
any).
Unless
an
end-user
explicitly
requests
that
these
values
be
reverted
to
the
values
as
declared
in
the
configuration
|
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 |
floating
| Step 7 |
The
value
of
the
widget
element's
viewmodes
attribute
in
the
configuration
document
(if
any).
|
widget start file | File entry |
null
| Step 7 , Step 8 |
The
start
file
for
the
widget
package
,
corresponding
to
either
one
of
the
default
start
files
table
or
the
file
identified
by
the
content
element's
src
attribute.
|
user agent locales |
List of strings |
null
| Step 5 | A list of language tags . |
This
step
only
applies
to
a
user
agent
that
supports
the
[Widgets-DigSig]
specification.
If
the
user
agent
does
not
support
[Widgets-DigSig]
,
then
the
user
agent
must
skip
Step
4
and
go
to
Step
5
.
Otherwise,
the
user
agent
must
apply
the
The
algorithm
to
locate
digital
signatures,
which
signatures
is
defined
in
the
[Widgets-DigSig]
specification
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.
For
example,
the
rule
for
deriving
end-user
may
have
specified
her
preferred
languages
and
regional
settings
at
install
time
by
selecting
a
preferred
language,
or
languages
from
a
list,
or
a
list
of
preferred
languages
and
regional
settings
could
have
been
dynamically
derived
from
the
end-user's
geographical
location,
etc.
The
algorithm
to
derive
the
user
agent
locales
defined
below,
the
user
agent
will
need
to
construct
a
list
is
as
follows:
Let
unprocessed
locales
.
list
be
a
comma-separated
list
that
contains
the
end-user's
language
ranges
.
Each
item
in
the
unprocessed
locales
is
must
be
a
string
in
lowercase
form,
that
conforms
to
the
production
of
a
Language-Tag
,
as
defined
in
the
[BCP47]
specification.
A
string
that
conforms
to
the
production
of
a
Language-Tag
is
referred
to
as
a
language
range
[BCP47]
(e.g.
'
en-au
',
which
is
the
range
of
English
as
spoken
in
Australia,
and
'
fr-ca
',
which
is
the
range
of
French
as
spoken
in
Canada,
etc.).
A
language
range
is
composed
of
one
or
more
subtags
that
are
delimited
by
a
U+002D
HYPHEN-MINUS
("
-
").
The
first
item
of
the
unprocessed
locales
represents
must
represent
the
user's
most
preferred
language
range
(i.e.,
the
language/region
combination
the
user
agent
assumes
the
end-user
most
wants
to
see
content
in),
followed
by
the
next
most
preferred
language
range,
and
so
forth.
For
example,
in
an
unprocessed
locales
list
that
contains
'
en-us,en,fr,es
',
English
as
spoken
in
the
United
States
is
preferred
over
English,
and
English
is
preferred
over
French,
and
French
is
preferred
over
Spanish,
and
Spanish
is
preferred
over
default
unlocalized
content
.
For
example,
each
range
in
the
end-user
may
have
specified
her
preferred
languages
and
regional
settings
at
install
time
by
selecting
a
preferred
language,
unprocessed
locales
list
:
If
this
range
begins
with
the
subtag
'
*
'
(e.g.
"
*-us
"
or
languages
from
a
list,
just
"
*
"),
or
a
list
of
preferred
languages
contains
any
space
characters
,
skip
all
the
steps
in
this
algorithm
below,
and
regional
settings
could
have
been
dynamically
derived
from
move
onto
the
end-user's
geographical
location,
etc.
next
range
.
In
Step
5
,
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
must
apply
.
Remove
the
rule
for
deriving
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:
config.xml
).
null
),
then
a
user
agent
must
treat
the
Zip
archive
as
an
invalid
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.
In
the
algorithm
to
process
a
configuration
document
,
the
The
term
in
error
is
used
in
this
Step
to
mean
that
an
element,
or
attribute,
or
file
in
a
configuration
document
is
non-conforming
to
the
rules
of
this
specification.
How
an
element
or
an
attribute
is
to
be
treated
when
it
is
in
error
is
always
given
when
the
term
is
used;
but
will
generally
require
the
user
agent
to
ignore
any
element,
attribute,
or
file
that
is
in
error.
To
ignore
means
to
that
a
user
agent
must
act
as
if
the
element,
attribute,
or
file
that
is
in
error
is
absent
(i.e.,
not
declared
or
included
by
the
author)
in
the
widget
package
or
configuration
document.
A
user
agent
must
,
however,
keep
a
record
of
all
element
types
it
has
attempted
to
process
even
if
they
were
ignored
(this
is
to
determine
if
the
user
agent
has
attempted
to
process
an
element
of
a
given
type
already).
In
the
case
the
user
agent
is
asked
to
ignore
an
[XML]
element
or
node,
a
user
agent
must
:
Stop
processing
the
current
element
,
ignoring
all
of
the
element
's
attributes
and
child
nodes
(if
any),
and
proceed
to
the
next
element
in
the
elements
list
.
Make
a
record
that
it
has
attempted
to
process
an
element
of
that
type.
In
the
following
example,
the
user
agent
ignores
both
content
elements.
The
user
agent
ignores
the
first
because
it
lacks
a
src
attribute.
The
user
agent
ignores
the
second
because
it
is
not
the
first
content
element
to
be
encountered
by
the
user
agent.
present.
To
associate
means
that
two
or
more
pieces
of
information
are
bound
and
stored
together
for
the
purpose
of
later
processing
(e.g.,
the
name
of
a
feature
,
and
if
it
is
required
,
and
any
associated
parameters
).
How
associated
data
is
represented
is
left
up-to
the
implementation
(e.g.,
a
user
agent
could
use
an
array,
an
object,
a
hash
map,
etc.).
The
lookup
algorithm
is
defined
in
section
3.4
of
[RFC4647]
(part
of
[BCP47]
.
).
It
is
used
in
this
Step
to
to
match
localized
content
in
the
configuration
document
to
the
language
ranges
held
by
the
user
agent
locales
(if
any).
A
CC
should
process
a
configuration
document
using
the
algorithm
to
Process
process
a
Configuration
Document
configuration
document
.
However,
where
an
element
or
attribute
is
in
error,
or
invalid,
the
conformance
checker
must
inform
the
author.
A CC may validate a configuration document against the Relax NG for the configuration document .
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
a
[XMLNS]
-aware
and
xml:lang
aware.
parser.
If
doc
the
document
is
not
namespace
well-formed
[XML]
,
then
the
user
agent
must
terminate
this
algorithm
and
treat
this
widget
package
as
an
invalid
widget
package
Zip
archive
.
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
Zip
archive
.
Otherwise,
the
element
is
a
widget
element:
If
the
attribute
is
used,
defaultlocale
attribute
is
used,
then
let
default
locale
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
defaultlocale
attribute:
If
the
default
locale
is
in
error
or
an
empty
string
or
already
contained
by
the
user
agent
locales
list,
then
the
user
agent
must
ignore
the
defaultlocale
attribute.
If
potential
default
locale
is
a
valid
language
tag
and
the
user
agent
locales
does
not
contain
the
value
of
default
locale
,
the
user
agent
must
prepend
the
value
of
potential
default
locale
into
the
the
user
agent
locales
list
as
the
second-last
item
(i.e.,
at
position
length
-
1).
For
example,
if
the
default
locale
is
the
value
"
fr
",
and
the
user
agent
locales
contains
the
values
"
jp,us,*
",
then
the
user
agent
locales
list
becomes
"
jp,us,fr,*
".
For
example,
if
the
default
locale
is
the
value
"
en
",
and
the
user
agent
locales
only
contains
the
value
"
*
",
then
the
user
agent
locales
list
becomes
"
en,*
".
For
example,
if
the
default
locale
is
the
value
"
en
",
and
the
user
agent
locales
already
contains
the
values
"
en,*
",
then
the
user
agent
would
ignore
the
default
locale
because
it
is
already
contained
by
the
user
agent
locales
list.
If
the
id
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,
then
the
user
agent
must
ignore
the
attribute.
If
the
version
attribute
is
used,
then
let
widget
version
value
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
version
attribute.
If
the
version
is
an
empty
string,
then
the
user
agent
must
ignore
the
attribute;
otherwise,
let
widget
version
be
the
value
of
version
value
.
If
the
height
attribute
is
used,
then
let
normalized
height
be
the
result
of
applying
the
rule
for
parsing
a
non-negative
integer
to
the
value
of
the
attribute.
If
the
normalized
height
is
not
in
error
and
greater
than
0
,
then
let
widget
height
be
the
value
of
normalized
height
.
If
the
height
attribute
is
in
error
,
then
and
the
user
agent
must
ignore
the
attribute.
it.
If
the
width
attribute
is
used,
then
let
normalized
width
be
the
result
of
applying
the
rule
for
parsing
a
non-negative
integer
to
the
value
of
the
attribute.
If
the
normalized
width
is
not
in
error
and
greater
than
0
,
then
let
widget
width
be
the
value
of
normalized
width
.
If
the
width
attribute
is
in
error
,
then
and
the
user
agent
must
ignore
the
attribute.
it.
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
items,
and
any
duplicated
items
from
right
to
left.
For
example,
viewmode
list
with
a
value
that
are
not
one
of
"
windowed
fullscreen
windowed
floating
fullscreen
windowed
"
would
become
"
windowed
fullscreen
floating
".
the
valid
view
modes
,
and
any
duplicated
items.
Let
widget
window
modes
be
the
value
of
viewmodes
list
.
If
any
other
attribute
declared
in
the
widget
element,
in
any
XML
namespace,
apart
from
xml:lang
,
is
used,
then
ignore
that
attribute.
If
the
widget
element
does
not
contain
any
child
elements,
then
the
user
agent
must
terminate
this
algorithm
and
go
to
Step
8
.
Otherwise,
let
Let
element
list
be
an
empty
list.
For each range in the user agent locales , starting from the first and moving to the last:
If
the
value
of
range
is
not
"*",
then
retaining
document
order
,
let
Let
matching
elements
be
the
result
of
applying
lookup
to
the
child
elements
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
.
Document
order
must
be
retained
in
the
resulting
matching
elements
list.
Append matching elements to the element list .
For
each
range
in
the
context
of
this
specification,
user
agent
locales
,
starting
from
the
above
conformance
requirement
is
intended
first
and
moving
to
match
the
name
last:
Let
matching
elements
be
the
result
of
applying
lookup
to
the
child
elements
of
type
that
are
direct
descendents
of
the
root
element
and
whose
,
description
icon
,
license
xml:lang
elements.
However,
it
is
written
attribute
matches
the
current
range
.
Document
order
must
be
retained
in
an
abstract
manner
the
resulting
matching
elements
list.
If
matching
elements
is
not
empty,
append
matching
elements
to
provide
a
hook
for
future
specifications
that
want
element
list
and
continue
to
define
elements
that
also
support
being
localizable
via
xml:lang
.
step
8
in
this
algorithm.
If
matching
elements
is
empty,
continue
to
the
value
of
next
range
is
"*",
retaining
document
order
,
let
.
Let
unlocalized
elements
be
all
child
elements
that
are
direct
descendants
descendents
of
the
root
element
that
do
not
have
an
implicit
or
explicit
a
declared
xml:lang
attribute
(i.e.,
match
default
unlocalized
content
).
Append
unlocalized
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
Document
order
contains
"
en,fr,*
",
the
matching
elements
would
must
be
retained
in
the
following
order:
resulting
list.
For
a
use
agent
whose
user
agent
locales
contains
"
en,*
",
the
Append
matching
unlocalized
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,*
",
to
the
matching
elements
would
be
in
the
following
order:
element
list
.
For each element in the elements list , if the element is one of the following:
name
element:
If
this
is
not
the
first
name
element
encountered
by
the
user
agent,
encountered,
then
the
user
agent
must
ignore
the
element
and
its
child
nodes.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
If
this
is
the
first
name
element
encountered
by
the
user
agent,
then
the
user
agent
must
:
encountered,
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,
encountered,
then
the
user
agent
must
ignore
the
element
and
its
child
nodes.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
If
this
is
the
first
description
element
encountered
by
the
user
agent,
then
the
user
agent
must
:
Record
that
an
attempt
has
been
made
by
the
user
agent
to
process
a
description
element.
Let
encountered,
let
widget
description
be
the
result
of
applying
the
rule
for
getting
text
content
to
this
element.
license
element:
If
this
is
not
the
first
license
element
encountered
by
the
user
agent,
encountered,
then
the
user
agent
must
ignore
this
element,
its
attributes,
and
any
child
nodes.
Stop
processing
this
element
.
If
this
is
and
proceed
to
the
first
license
next
element
used,
then
the
user
agent
must
:
Record
that
an
attempt
has
been
made
by
in
the
user
agent
to
process
a
license
element.
elements
list
.
Let license text be the result of applying the rule for getting text content to this element. Associate license text with widget license .
If
the
href
attribute
is
used,
then
let
potential
license
href
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
href
attribute.
If
potential
license
href
is
not
a
valid
IRI
or
a
valid
path
,
then
the
href
attribute
is
in
error
and
the
user
agent
must
ignore
the
attribute.
it.
If
potential
license
href
is
a
valid
IRI
,
then
let
widget
license
href
be
the
value
of
potential
license
href
.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
If
license
href
is
a
valid
path
,
then
let
file
be
the
result
of
applying
the
rule
for
finding
a
file
within
a
widget
package
to
license
href
.
If
file
is
not
a
processable
file
,
as
determined
by
applying
the
rule
for
identifying
the
media
type
of
a
file
,
then
ignore
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
Otherwise,
let
widget
license
file
be
the
value
of
file
.
icon
element:
If
the
src
attribute
of
this
icon
element
is
absent,
then
the
user
agent
must
ignore
this
element
and
its
attributes.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
Let
path
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
src
attribute
of
this
icon
element.
If
path
is
not
a
valid
path
or
is
an
empty
string,
,
then
the
user
agent
must
ignore
this
element
and
its
attributes.
Proceed
to
the
next
element
in
the
elements
list
.
Let file be the result of applying the rule for finding a file within a widget package to path . If file is in error, then the user agent must ignore this element and its attributes. Stop processing this element and proceed to the next element in the elements list .
If
file
is
not
a
processable
file
,
as
determined
by
applying
the
rule
for
identifying
the
media
type
of
a
file
an
image
,
or
already
exists
in
the
icons
list,
then
the
user
agent
must
ignore
this
element.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
Otherwise,
If
the
height
attribute
is
used,
then
let
potential
height
be
the
result
of
applying
the
rule
for
parsing
a
non-negative
integer
to
the
attribute's
value.
If
the
potential
height
is
not
in
error
and
greater
than
0
,
then
associate
the
potential
height
with
file
.
Otherwise,
the
height
attribute
is
in
error
and
the
user
agent
must
ignore
the
attribute.
it.
If
the
width
attribute
is
used,
then
let
potential
width
be
the
result
of
applying
the
rule
for
parsing
a
non-negative
integer
to
the
attribute's
value.
If
the
potential
width
is
not
in
error
and
greater
than
0
,
then
associate
the
potential
width
with
file
.
Otherwise,
the
width
attribute
is
in
error
and
the
user
agent
must
ignore
the
attribute.
it.
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,
encountered,
then
the
user
agent
must
ignore
this
element
and
any
child
nodes.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
If
this
is
the
first
author
element
used,
then
the
user
agent
must
:
then:
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
the
user
agent
must
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
.
it.
Otherwise,
the
user
agent
must
:
Let preference be an empty object.
Let
name
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
name
attribute.
If
the
name
is
an
empty
string,
then
this
element
is
in
error
;
and
the
user
agent
must
ignore
it.
Stop
processing
this
element
.
If
widget
preferences
already
contains
a
preference
whose
name
case-sensitively
matches
and
proceed
to
the
value
of
name
,
then
this
next
element
is
in
error
;
ignore
this
the
element
elements
list
.
If
name
was
not
in
error
,
let
preference
be
an
empty
object.
Associate
Otherwise,
associate
name
with
preference
.
Let
value
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
of
the
value
attribute.
Associate
the
value
with
preference
.
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,
encountered,
then
the
user
agent
must
ignore
this
element
and
its
child
nodes.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
If
this
is
the
first
content
element,
then
the
user
agent
must
:
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,
absent,
then
the
user
agent
must
ignore
this
element
and
its
attributes.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
Let
path
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
of
the
src
attribute.
If
path
is
a
valid
path
,
then
let
file
be
the
result
of
applying
the
rule
for
finding
a
file
within
a
widget
package
to
path
.
If
file
path
is
null
or
in
error,
not
a
valid
path
,
then
the
a
user
agent
must
ignore
treat
the
widget
package
this
element
.
as
an
invalid
Zip
archive
.
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
attribute
is
used,
encoding
type
then
let
content-encoding
content-type
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
of
the
encoding
type
attribute.
If
the
character
encoding
represented
by
the
value
of
content-encoding
content-type
is
supported
by
the
user
agent,
then
let
the
start
file
encoding
content-type
be
the
value
of
content-encoding
content
type
.
If
value
of
content-encoding
content-type
is
an
empty
string
invalid
or
unsupported
by
the
user
agent,
then
a
user
agent
must
ignore
treat
the
encoding
widget
package
attribute.
as
an
invalid
Zip
archive
.
If
the
type
encoding
attribute
is
used,
then
let
content-type
content-encoding
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
of
the
type
encoding
attribute.
If
the
value
of
content-type
content-encoding
is
a
media
type
supported
by
the
user
agent,
then
let
the
start
file
content-type
encoding
be
the
value
of
content
type
.
the
encoding
attribute.
If
value
of
content-type
content-encoding
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
should
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
use
the
start
file),
then
let
start
file
default
encoding
(
be
the
value
of
the
last
supported
parameter
UTF-8
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.
<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.
).
param
feature
element:
If
this
param
element
is
not
a
direct
child
of
a
feature
required
element,
then
the
user
agent
must
ignore
attribute
of
this
param
element
.
Note:
How
a
param
element
is
to
be
processed
when
it
is
inside
a
feature
element
is
defined
below.
A
feature
element:
The
user
agent
must
process
a
feature
element
in
the
following
manner:
If
the
is
used,
but
no
name
attribute
of
this
feature
element
is
absent,
used,
then
the
user
agent
this
element,
its
attributes,
and
its
children
are
in
error
and
must
ignore
be
ignored
by
the
user
agent.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
Let
required-feature
feature-name
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
true
.
of
the
name
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
Let
feature-name
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
of
the
name
attribute.
Note:
This
specification
allows
feature
elements
with
the
same
name
attribute
value
to
be
declared
more
than
once.
Handling
of
duplicate
feature
requests
is
left
up
to
the
implementation
or
the
specification
that
defines
the
feature.
If
feature-name
is
not
a
valid
IRI
,
and
required-feature
is
true
,
then
the
user
agent
must
treat
this
widget
as
an
invalid
widget
package
Zip
archive
.
If
feature-name
is
not
supported
by
the
user
agent,
and
required-feature
is
true
,
then
the
user
agent
must
treat
this
widget
as
an
invalid
widget
package
Zip
archive
.
If
feature-name
is
not
supported
by
the
user
agent,
and
required-feature
is
false
,
then
the
user
agent
this
element,
its
attributes,
and
its
children
are
in
error
and
must
ignore
be
ignored
by
the
user
agent.
Stop
processing
this
element
and
proceed
to
the
next
element
in
the
elements
list
.
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
it.
Stop
processing
this
element
and
move
onto
the
next
value
param
param
element
(if
any).
If
a
name
attribute
is
missing,
used,
but
the
value
attribute
is
absent,
then
this
param
element
is
in
error
and
the
user
agent
must
ignore
it.
Stop
processing
this
param
element
.
and
move
onto
the
next
param
element
(if
any).
Let
param-name
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
name
attribute.
If
the
param-name
is
an
empty
string,
then
this
param
element
is
in
error
and
the
user
agent
must
ignore
it.
Stop
processing
this
param
element
.
and
move
onto
the
next
param
element
(if
any).
Let
If,
and
only
if,
param-name
is
not
in
error
or
an
empty
string,
let
param-value
be
the
result
of
applying
the
rule
for
getting
a
single
attribute
value
to
the
value
attribute.
L:et
If
the
param
param-value
be
is
an
object
that
represents
empty
string,
then
this
paramenter.
param
element
is
in
error
and
the
user
agent
must
ignore
it.
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
.
Comment
node,
or
a
ProcessingInstruction
node,
or
a
Text
node
that
only
contains
Unicode
white
space
characters
,
or
a
CDATASection
node
that
only
contains
Unicode
white
space
characters
,
or
a
param
element
that
is
not
a
direct
child
of
a
feature
element.
This
step
only
applies
if
a
custom
start
file
was
not
specified
in
the
configuration
document
(i.e.,
if
widget
start
file
of
the
table
of
configuration
defaults
contains
a
file
(i.e.
widget
start
file
is
not
null
),
then
a
in
which
case
the
user
agent
must
skip
Step
8
and
go
attempt
to
Step
9
find
a
default
start
file
.
If
widget
start
file
does
not
contain
contains
a
file
,
the
then
skip
Step
8
and
go
to
Step
9
.
When
attempting
to
locate
a
default
start
file
,
a
user
agent
must
apply
the
algorithm
attempt
to
locate
a
file
entry
whose
file-name
matches
one
of
the
default
start
file
.
The
algorithm
files
based
on
the
order
they
appear
in
the
default
start
files
table
(from
top
to
locate
a
bottom).
File
names
in
the
default
start
file
is
as
follows:
files
table
must
be
treated
by
the
user
agent
case-sensitively.
null
or
in
error
,
ignore
this
file
name
and
move
onto
the
next
file
name
in
the
default
start
files
table
.
This
step
describes
how
to
locate
the
default
icons
.
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:
true
,
then
add
the
value
of
potential-icon
to
the
icons
list
of
the
table
of
configuration
defaults
:This section is non-normative.
This
section
only
applies
to
HTML
user
agents
[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>
This section is non-normative.
This
table
lists
all
elements
The
following
is
the
Relax
NG
for
the
configuration
document
,
which
is
a
[RelaxNG]
schema
representation
of
the
elements,
and
respective
their
attributes,
as
well
as
child-parent
relationships,
that
make
up
the
language
of
the
configuration
document
format
defined
in
.
A
conformance
checker
may
use
this
specification.
Element
Description
Parent
Expected
Children
Attributes
Type
widget
The
root
element
schema
to
validate
elements
of
a
configuration
document
.
none.
name
description
author
license
icon
content
feature
preference
xml:lang
language
dir
keyword
id
IRI
version
version
height
numeric
width
numeric
viewmodes
Keyword
list
defaultlocale
language
name
The
name
of
the
widget.
widget
span
,
text
node
xml:lang
language
dir
keyword
short
displayable-string
description
Some
text
that
describes
within
the
purpose
limits
of
the
widget.
widget
span
text
node
xml:lang
language
dir
keyword
author
The
person
or
person
that
created
the
widget.
widget
span
text
node
xml:lang
language
dir
[RelaxNG]
specification.
# Widgets 1.0 (Working Draft) RELAX NG schema
keyworddefault namespace widgets = "http://www.w3.org/ns/widgets" namespace its = "http://www.w3.org/2005/11/its/" namespace local = "" extension = ( attr.allowed | anyElement )* anyElement = ( element * - widgets:* { any } | text )* any = ( attribute * { text } | anyElement )* attr.allowed = attribute * - (local:* | xml:lang | its:dir) { text } attr.xmllang = attribute xml:lang { xsd:language } attr.itsdir = attribute its:dir { "ltr" | "rtl" | "lro" | "rlo" }hrefdata.positiveNumber = xsd:string { pattern="[1-9]\d*" } data.boolean = ( string "true" | string "false" ) start = elem.widget elem.widget = element widget { attr.xmllang?, attribute id { xsd:anyURI }?, attribute version { text }?, attribute height { data.positiveNumber }?, attribute width { data.positiveNumber }?, attribute viewmodes { list { ( "application" | "floating" | "fullscreen" | "mini" | "all" )* } }?, ( elem.name* & elem.description* & elem.icon* & elem.author? & elem.license* & elem.content? & elem.feature* & elem.preference* & extension ) }IRIelem.name = element name { attr.xmllang?, attr.itsdir?, attribute short { text }?, extension } elem.description = element description { attr.xmllang?, attr.itsdir?, extension } elem.icon = element icon { attr.allowed*, attribute src { xsd:anyURI }, attribute height { data.positiveNumber }?, attribute width { data.positiveNumber }?, empty }stringelem.feature = element feature { attribute name { xsd:anyURI }, attribute required { data.boolean }?, ( elem.param? & extension ) } elem.param = element param { attribute name { text }, attribute value { text }, extension } elem.preference = element preference { attr.xmllang?, attribute name { text }, attribute value { text }?, attribute readonly { data.boolean }?, extension }license
Special thanks go to Arve Bersvendsen, Anne van Kesteren, Robin Berjon, and Charles McCathieNevile who helped edit various versions of this specification.
Special
thanks
also
to
David
Håsäther
The
license
under
which
for
creating
and
maintaining
the
widget
is
distributed.
widget
span
text
node
xml:lang
language
dir
keyword
href
IRI
or
path
icon
An
iconic
representation
of
RelaxNG
Schema
for
the
widget.
widget
none.
xml:lang
language
dir
keyword
src
path
width
numeric
height
numeric
content
The
means
to
point
configuration
document
format.
A
huge
thanks
to
the
"main
file"
of
a
widget;
serves
as
a
boot-strapping
mechanism.
widget
none.
xml:lang
language
dir
keyword
src
numeric
type
media
type
encoding
keyword
Sam
"
gsnedders
feature
"
Sneddon,
whose
Anolis
A
means
specification-generator
was
used
to
request
the
availability
of
a
feature
,
such
as
an
API,
that
would
not
normally
be
part
of
the
default
set
generate
this
document.
Parts
of
features
provided
by
this
document
reproduce
text
and
behavior
from
the
user
agent
at
runtime.
widget
param
.
xml:lang
language
dir
keyword
name
keyword
required
boolean
preference
[HTML5]
A
means
to
declare
a
name-value
pair
that
is
made
available
to
specification
and
from
the
widget
at
runtime.
widget
none.
xml:lang
language
dir
keyword
name
keyword
value
keyword
readonly
boolean
param
A
means
of
declaring
a
parameter
XBL
2.0
specification
that
can
be
(as
permitted
by
both
specifications
by
their
copyright
statements).
Graphic
icons
used
with
a
feature
.
feature
none.
xml:lang
language
dir
keyword
name
string
value
string
span
some
examples
of
this
specification
were
created
by
Yusuke
Kamiyamane
A
generic
text
container
which
is
mainly
used
and
are
available
for
internationalization
purposes.
name
description
author
use
under
a
Creative
Commons
Attribution
3.0
license
span
text
node
xml:lang
language
dir
keyword
Acknowledgements
Huge
thanks
to
everyone
who
contributed
their
time
and
sent
feedback
to
our
public
mailing,
particularly
the
i18n
WG.
.
This
specification
The
editors
would
not
exist
without
the
contribution
of
also
like
to
thank
the
following
individuals:
people
for
their
contributions
to
this
specification:
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.