Copyright
© © 2011
W3C ® ® ( MIT , ERCIM
, Keio ), All Rights Reserved.
W3C liability
, trademark
and document
use rules apply.
This specification standardizes a packaging format and metadata
for a class of software known as widgets . Unlike
traditional user interface widgets (e.g., buttons, input boxes,
toolbars, etc.), widgets as specified in this document 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 be "mashed-up" "mashed-up" and presented to a user in some
interesting and useful way.
The specification relies on PKWare's Zip specification as the archive format, XML as a configuration document format, and a series of steps that runtimes follow when processing and verifying various aspects of a package. The packaging format acts as a container for files used by a widget. The configuration document is an XML vocabulary that declares metadata and configuration parameters for a widget. The steps for processing a widget package describe the expected behavior and means of error handling for runtimes while processing the packaging format, configuration document, and other relevant files.
This specification is part of the Widgets family of specifications , which together standardize widgets as a whole.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
Publication as a Working Draft
Proposed Recommendation does not imply
endorsement by the W3C Membership. This is a draft document and may
be updated, replaced or obsoleted by other documents at any time.
It is inappropriate to cite this document as other than work in
progress. You can find the latest Editor's
Draft of this document in the W3C's CVS repository .
This is the 07 June 11 August 2011 Last Call
Working Draft Proposed
Recommendation of this specification. The The
Last Call period ends ended on 28 June 2011 .
The 2011. Since two independent
implementations already passed 100% of this specification's test
suite after the end of the Last Call period, there was no Candidate
Recommendation phase (see implementation report ).
No substantive changes were made as a result of the Last Call
review (see diff ).
The public is encouraged to send
comments to the WebApps Working Group's public mailing list list
public-webapps@w3.org
( ( archive
). See ) by
the 15 September
2011 .See W3C mailing list and archive usage
guidelines . A detailed list of changes
from the previous version is also available from the W3C's
CVS server. IMPORTANT: By the time the Last Call comment period
ends (June 28), the Working Group expects to have data that at
least two independent implementations pass 100% of this spec's test
suite . As such, if no substantive changes must be made as a result
of the Last Call review, we will not publish a Candidate
Recommendation for this spec and the next publication will be
Proposed Recommendation Advisory
Committee Representatives should consult their
questionnaires .
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.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
widget
Element and its
Attributes
id
Attributeversion
Attributeheight
Attributewidth
Attributeviewmodes
Attributedefaultlocale
attributedefaultlocale
attributename
Element and its
Attributes
description
Element
and its Attributes
author
Element and its Attributes
license
Element and
its Attributes
icon
Element and its
Attributes
content
Element and
its Attributes
feature
Element and
its Attributes
param
Element and its
Attributes
preference
Element
and its Attributes
span
Element and its
Attributes
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" "mashed-up" and presented to a user in some
interesting and useful way (see [Widgets-Landscape] for more
information).
This specification is intended to specify a part of the Web platform closely related to [HTML] .
This section is non-normative.
The design goals and requirements for this specification are documented in the [Widgets-Requirements] document.
This document addresses the 25 requirements relating to
" "
Packaging " " and " "
Configuration Document "
" of the 30 April 2009 Working Draft of
the Widgets Requirements Document:
author author
element.license license
element.widget widget
element.content content
element.icon icon
element, default icons table and custom icons table .param param
element (used in conjunction with
the feature feature
element).preference preference
element.feature feature
element.viewmodes
attribute of the widget widget
element.This section is non-normative.
This document is organized into two halves, but not explicitly marked as such. The first half defines the various aspects of what constitutes the packaging format , the configuration document , and reserved files, such as default icons and locale folders . Where possible, the first half avoids describing aspects related to processing, which are described in detail in the second half of the document.
The second half, which starts with the section titled
" "
Steps for
Processing a widget package ",
", defines the steps required to
process a widget package as well as the expected behavior of a user
agent as it processes the packaging
format , the configuration document, and attempts to find
localized content. The second half of this document also deals with
error handling in the event that a user agent encounters unsupported or missing files, or DOM nodes that are in error in the configuration document. Wherever
processing is relevant, sections in the first half of the document
link to sections in the second half of the document.
This section is non-normative.
This section defines the typographical conventions used by this specification. Some text in this specification is non-normative. Non-normative text includes:
This section is non-normative,
Everything else in this specification is normative.
Defined terms appear as this sample defined term . Such terms are referenced as sample defined term , providing a link back to the term definition.
Words that denote a conformance clause or testable assertion use keywords from [RFC2119] : must , must not , should , recommended , may and optional . The keywords must , must not , should , recommended , may and optional in this specification are to be interpreted as described in [RFC2119] .
Variables are formatted specially, e.g. variable .
Code is also specially formatted, such as code
.
Words in italics denote a formal definition given in an external specification.
This is an example. Examples are used to explain concepts or demonstrate how to use a feature. Examples are non-normative.
Note: This is a note, it usually contains useful supplementary information in a non-normative form.
This section is non-normative.
This specification is part of the Widgets family of specifications , which together standardize widgets as a whole. The list of specifications that make up the Widgets Family of Specifications can be found on the Working Group's wiki.
There is only one class of product that can claim conformance to this specification: a user agent .
Note: Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the [P&C-Test-Suite] . Note, however, that passing all the tests in the test suite does not imply complete conformance to this specification; It only implies that the implementation conforms to aspects tested by the test suite (the test suite does not provide tests for any optional conformance clauses).
The following terms are used throughout this specification so they are gathered here for the readers convenience. The following list of terms is not exhaustive; other terms are defined throughout this specification.
Arbitrary means that a character, or
text string, or file-name
, or ,
is not reserved for the purpose of this specification.folder-name folder-name
An author is a person who created a widget package or an authoring tool that generated a widget package .
Initialization means a user agent procedurally stepping through the steps for processing a widget package .
A language tag is
a text string that matches the production of a
Language-Tag
defined in the [BCP47] specifications (see the IANA
Language Subtag Registry for an authoritative list of possible
values, see also the
Maintenance Agency for ISO 3166 country codes ).
A media type is defined in the [MIME] specification.
Reserved means that a character, or
text string, or file-name
, or ,
has a specified purpose and
semantics in this specification or in some other specification or
system. The intended purpose for any reserved thing is given when
the term is used.folder-name folder-name
Supported means that a user agent implements a mentioned specification, or conformance clause, or is able to process or otherwise render mentioned media type .
Unsupported means the user agent does not implement a mentioned specification, or feature , or is unable to render or otherwise process a mentioned media type .
A widget is defined by
the [Widgets-Landscape] as an
end-user's conceptualization of an interactive single purpose
application for displaying and/or updating local data or data on
the Web, packaged in a way to allow a single download and
installation on a user's machine, mobile phone, or Internet-enabled
device
. Because widgets are packaged, they can be shared by
users without relying on [HTTP] .
This section groups common sets of [Unicode] code points into definitions for the purpose processing in this specification.
The space characters are code points:
The Unicode white space
characters are code points marked in the [Unicode] specification with the property
"White_Space", "White_Space", including (but not limited to - see
[Unicode] for the authoritive list):
The Zip forbidden characters are code points:
A user agent is an implementation of this specification that also supports [XML] , [XMLNS] , [UTF-8] , [Unicode] , [DOM3CORE] , [SNIFF] , and [ZIP] (see optional aspects of the Zip specification ).
In addition to widget packages , a user agent may support other legacy and proprietary application packaging formats.
It is optional for a user agent to support the optional aspects of the Zip specification .
Note: The user agent
described in this specification does not necessarily denote a
" "
widget user agent " " at large: that is,
a user agent that implements all the specifications, and
dependencies, defined in the Widgets Family of
Specifications . The user agent described is this specification
is only concerned with how to processes Zip archives and configuration documents .
The optional aspects of the Zip specification are as follows. These aspects represent general features defined in the [ZIP] specification that this specification does not make use of:
Compression or decompression algorithms other than [Deflate] and Stored .
Zip64 extensions.
Digital signature methods.
Decryption methods.
Patented aspects.
The Zip archive file format, defined in the [ZIP] specification, is the packaging format for widget packages .
A file entry is the data held by a local file header , file data , and (optional) data descriptor , as defined in the [ZIP] specification, for each physical file or folder contained in a Zip archive .
A potential Zip archive is a data object claiming to be a Zip archive , that has not been verified to be a valid Zip archive .
A valid Zip archive is a data
object that the user agent has verified as conforming to the
production of a .Zip .Zip file as defined by the
Zip File Format Specification [ZIP]
and meets
the requirements of this specification (See Step 2 ).
The magic numbers for
a Zip archive is the byte sequence: 50 4B 03 04
.
A compression method is the compression algorithm or storage method that was used to encode the file data of a file entry when the zip archive was created by the author. The compression method that encoded the file data of a file entry is identified by the numeric value derived from the compression method field defined in the [ZIP] specification.
The valid compression
methods , as indicated by the compression method field
, , for a file entry are:
8
0
The version needed to extract is the 2-byte sequence in the local file header of a file entry that indicates the minimum supported version of the [ZIP] specification needed to extract the file data .
The valid versions needed to extract values are as follows. Each value is assigned one or more meanings by the [ZIP] specification:
Default value specified in the [ZIP] specification.
The file data is compressed using [Deflate] , or the file data is a folder, or the file has been encrypted using traditional PKWARE encryption.
Note: If the Zip archive has been encrypted using traditional PKWARE encryption, then the user agent will treat the Zip archive as an invalid widget package in Step 2 .
A Zip relative path is the variable-length string derived from the file name field of the local file header of a file entry .
Note: A Zip relative
path is said to be relative as it stores the string that represents
file and folder names relative to where the Zip archive was created
on a file system (e.g. images/bg.png ), as opposed to
storing an absolute path (e.g. c:\images\bg.png ). The
value of a Zip relative path will generally resemble the string
value of a name of the file or folder(s) on the device on which the
Zip archive was created, but with the exception of the path
delimiter being a U+002F SOLIDUS "/"
"/" character. Note also that a Zip
relative path is not a URI reference; Zip relative paths need to be
converted to URI references before they can be used in context that
make use of URIs.
A valid Zip relative
path is one that matches the production of
in the following [ABNF] :Zip-rel-path Zip-rel-path
Zip-rel-path = [locale-folder] *folder-name file-name /
[locale-folder] 1*folder-name
locale-folder = %x6C %x6F %x63 %x61 %x6C %x65 %x73
"/" lang-tag "/"
= file-name "/"
"/" lang-tag "/"
folder-name = file-name "/"
file-name = 1*allowed-char
allowed-char = safe-char / zip-UTF8-char
zip-UTF8-char = UTF8-2 / UTF8-3 / UTF8-4
= ALPHA / DIGIT / SP / "$" / "%" /
"'" / "-" / "_" / "@" / "~" /
"(" / ")" / "&" / "+" / "," /
"=" / "[" / "]" / "."
safe-char = ALPHA / DIGIT / SP / "$" / "%" /
"'" / "-" / "_" / "@" / "~" /
"(" / ")" / "&" / "+" / "," /
"=" / "[" / "]" / "."
UTF8-2 = %xC2-DF UTF8-tail
UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2( UTF8-tail ) /
%xED %x80-9F UTF8-tail / %xEE-EF 2( UTF8-tail )
UTF8-4 = %xF0 %x90-BF 2( UTF8-tail ) / %xF1-F3 3( UTF8-tail ) /
%xF4 %x80-8F 2( UTF8-tail )
UTF8-tail = %x80-BF
= %x61-7a
lang-tag = primary-subtag *( "-" subtag )
primary-subtag = 1*8low-alpha
subtag = 1*8(alphanum)
alphanum = low-alpha / DIGIT
low-alpha = %x61-7a
ALPHA
,
DIGIT
, and
SP
are defined in
the [ABNF] specification (but essentially
represent alphanumerical characters and the U+0020 SPACE code point
respectively).
This section is non-normative.
Some issues can arise with regards to character encodings of file names, the length of zip relative paths, and the use of certain strings as file names. This sections is intended to help authors avoid potential interoperability issues.
A widget package is a valid Zip archive that contains the following:
One or more start
files , located at the root of the widget package and/or
at the root of locale folders or referenced by a
element's content content element's
srcsrc
attribute.
One configuration document , located at the root of the widget package .
Zero or more icons , either located at the root of the widget package and/or
at the root of locale folders or referenced by the
element's icon
icon element's
srcsrc
attribute.
Zero or more arbitrary files located either at the root of the widget package and/or in arbitrary folders or in locale folders .
Zero or more digital signatures located at the root of the widget package.
Note: See step 1 - Acquire a Potential Zip Archive for instructions on how to process a widget package.
During the steps for processing a widget package , certain error conditions can result in a Zip archive being treated as an invalid widget package . An invalid Widget package is a condition whereby a Zip archive, or a file within the Zip archive, is deemed to be corrupt beyond recovery or is non-conforming to, or unsupported by, this specification in such a way that it would not be possible for the user agent to continue processing.
The root of the widget package is the top-most path level of the Zip archive . The root of the widget package contains files and folders , some of which are reserved (see reserved file names table ).
A file is the decompressed physical representation of a file entry (i.e., a file extracted into its physical form as it was prior to being added to the Zip archive ).
A folder is a file
entry whose file name
field matches the production of folder-name
in a valid Zip relative path (the last
character of the file name
field is a U+002F SOLIDUS) and whose version needed to extract is
2.0.
A processable file is a file that:
Exists within the widget package .
When the rule for
verifying a file entry is applied to the file, it returns
true
.
Is of a media type supported by the user agent, determined applying the rule for identifying the media type of a file to the file in question.
The reserved file names table , below, contains a list of file names that are reserved for some purpose by this specification. The first column of the reserved file names table contains a case-sensitive list of file names. The second column of the table denotes the purpose for which the file name is reserved .
file name | Type | reserved for purpose |
---|---|---|
config.xml | file | Configuration document |
icon.png | file | Default icon |
icon.gif | file | Default icon |
icon.jpg | file | Default icon |
icon.ico | file | Default icon |
icon.svg | file | Default icon |
index.html | file | Default start file |
index.htm | file | Default start file |
index.svg | file | Default start file |
index.xhtml | file | Default start file |
index.xht | file | Default start file |
locales | folder | Container for localized content |
Files named using the naming conventions for distributor signatures and the naming convention for an author signature , as defined in the [Widgets-DigSig] specification, are also reserved in this specification.
A widget package contains a digital signature , and hence is digitally signed , if the widget package contains one or more files that conform to the [Widgets-DigSig] specification.
A start file designates a file from the widget package to be loaded by the user agent when it instantiates the widget. This specification defines two kinds of start file: custom start file and default start file .
A custom start file is a
processable file inside the
widget package identified by a
element's content
content element's
srcsrc
attribute.
A default start file is a reserved start file at the root of the widget package or at the root of a locale folder whose file name case-sensitively matches a file name given in the file name column of the default start files table , and whose media type matches the media type given in the media type column of the table.
It is optional for a user agent to support the media types listed in the default start files table .
If a user agent encounters a file matching a file name given in the file name column of the default start files table in an arbitrary folder , then user agent must treat that file as an arbitrary file.
For example, "
" foo/bar/index.html
" " would
be treated as an arbitrary file .
file name | media type |
---|---|
index.htm | text/html |
index.html | text/html |
index.svg | image/svg+xml |
index.xhtml | application/xhtml+xml |
index.xht | application/xhtml+xml |
Note: See Step 8 for instructions on finding a default start file .
An icon is a file that is used to represent the widget in various application contexts (e.g. the icon that the user activates 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
element in a configuration document . A custom icon can be located at the root of the widget package , or
at the root of a locale folder , or
in an arbitrary folder .icon
icon
A default icon is a reserved icon , either at the root of the widget package or at the root of a locale folder , whose file name case-sensitively and exactly matches a file name given in the file name column of the default icons table .
file name | media type |
---|---|
icon.svg | image/svg+xml |
icon.ico | image/vnd.microsoft.icon |
icon.png | image/png |
icon.gif | image/gif |
icon.jpg | image/jpeg |
It is optional for a user agent to support the media types listed in the default icons table .
The valid widget media
type is the string application/widget
.
A widget file extension is
the text string that case-insensitively matches the string
" "
.wgt
" " (e.g. .wgt
, .WGt
,
.WgT
, etc. are all valid).
For example in widget.WGT
, the
".WGT ".WGT"
" component is the file extension.
A configuration
document is an [XML] document that has a
element at its root that is in
the widget namespace . A widget
package has exactly one configuration document located at the
root of the widget
package .widget
widget
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
file in an arbitrary
folder or locale folders that uses the file name
config.xml
as an arbitrary
file.
The following is an example of a typical configuration document :
<?xml version="1.0" encoding="UTF-8"?> <widget xmlns = "http://www.w3.org/ns/widgets" id = "http://example.org/exampleWidget" version = "2.0 Beta" height = "200" width = "200" viewmodes = "fullscreen"><?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">
<name short="Example 2.0"><name short="Example 2.0"> The example Widget! </name><feature name="http://example.com/camera"> <param name="autofocus" value="true"/><feature name="http://example.com/camera"> <param name="autofocus" value="true"/> </feature><preference name = "apikey" value = "ea31ad3a23fd2f" readonly = "true" /><preference name = "apikey" value = "ea31ad3a23fd2f" readonly = "true" /> <description> A sample widget to demonstrate some of the possibilities. </description><author href = "http://foo-bar.example.org/" email = "foo-bar@example.org">Foo Bar Corp</author><author href = "http://foo-bar.example.org/" email = "foo-bar@example.org">Foo Bar Corp</author><icon src="icons/example.png"/> <icon src="icons/boo.png"/> <content src="myWidget.html"/><icon src="icons/example.png"/> <icon src="icons/boo.png"/> <content src="myWidget.html"/> <license> Example license (based on MIT License) Copyright (c) 2008 The Foo Bar Corp.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESSTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. </license> </widget>
Note: Implementers
are encouraged to expose relevant information provided by the
configuration document to
the user. Having "visual metadata"
"visual metadata" encourages authors to
make full use of the configuration document format. See Step 7 for
instructions on how to process a configuration document.
The widget namespace URI for a
configuration document is
http://www.w3.org/ns/widgets
[XMLNS] .
No provision is made for an explicit version number in this specification. If a future version of this specification requires explicit versioning of the document format, a different namespace will be used.
This section is non-normative .
Implementers or authors intending to extend the configuration document format with their own [XML] elements and attributes (or those defined in other specifications) can do so by using a separate [XMLNS] namespace. This specification does not define a model for processing [XML] elements outside the widget namespace (they are simply ignored during processing).
Example of extending the configuration document format:
<widget xmlns="http://www.w3.org/ns/widgets" > <icon src="idle.png" ex:role="inactive"/><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"/><content src="widget.html"/> </widget>
This section defines the different attribute types used in the configuration document and what constitutes valid values for those attribute types.
An attribute is invalid if its value does not conform to its said attribute type ; that is, if the value of the attribute is in error given the processing rules for that type of attribute.
A boolean attribute is a keyword
attribute that can only be used with a valid boolean value. A
valid boolean value is a
keyword that case-sensitively matches
true
or false
. Unless specified
otherwise, the default behavior, which is used when the attribute
is omitted or has a value other than the two allowed values, is
false
. The way a user agent interprets a boolean
attribute is defined as part of an attribute's definition (see, for
example, the
element's feature feature element's
requiredrequired
attribute).
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
attribute, such as the dir dir
attribute (i.e., these attributes will not treated as displayable-strings during
Step 7
).email email
An attribute whose primary purpose is to convey human readable
information, such as the
element's name name element's
shortshort
attribute and the widget element's
attribute.version version
A keyword is a string that is reserved for the purpose of this specification. The value of a keyword attribute is a keyword that is one of a finite set specified in the attribute's definition in the case given in this specification.
An attribute defined as taking one or more keywords as a value, which are separated by space characters .
An attribute whose value is defined as containing a valid media
type. A valid media type is string
that matches the production for
in the following
[ABNF] :valid-MIME-type valid-MIME-type
valid-MIME-type
=
type
"/"
"/"
subtype
*(";"
*(";"
parameter)
The type
, subtype
, and parameter
tokens are defined in
the [MIME] specification.
An attribute whose value is defined as containing a valid language tag (see the IANA
Language Subtag Registry for an authoritative list of possible
values, see also the
Maintenance Agency for ISO 3166 country codes ). A valid
language tag is a string that conforms to the production of a
Language-Tag
, as defined in the [BCP47] specification.
The value of a numeric attribute is a string containing a valid
non-negative integer. A valid
non-negative integer is a string that consists of one or more
code points in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE
(9). For example, the strings "002", "323",
"23214", "002", "323", "23214",
and so on.
An attribute defined as containing a valid path. A valid path is one that matches the production of
a
or a Zip-rel-path Zip-rel-pathZip-abs-path
.
An attribute defined as containing a valid IRI. A valid IRI is one that matches the
token of the [IRI] specification.IRI IRI
A displayable-string attribute whose value is any arbitrary string value (possibly empty) within the constraints allowed for [XML] attributes. This specification does not mandate any specific format, semantics, or special processing rule for the format of a version attribute .
This section describes the behavior and expected usage of other relevant attributes that are part of the [XML] specification and this specification. In this specification, these attributes are referred to as global attributes because they can be used on any element in a configuration document .
Although global attributes
can be used on any element in this specification, they sometimes
have no effect on the element on which they are used. For example,
applying
attribute on an dir dir
element will have no effect on the
icon icon
elements or any of its attributes.
What effect specifying a global attribute has on an elements is
determined by Step 7 of this
specification.icon
icon
xml:lang
AttributeA language attribute that
specifies, through a language tag , the
language of the contents and attribute values of XML elements (see
the IANA
Language Subtag Registry ). The [XML]
specification specifies the
attribute and its influence on
child nodes.xml:lang xml:lang
dir
AttributeA keyword attribute used to
specify the directionality in which human-readable text is to be
represented by a user agent (e.g., the text content of the
element, the name
name
element, and the
description
description
element). The directionality
set by the license
license
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 dir
(i.e., in this specification, the
dir dir
attribute only affects the dir dir
attribute of the short short
element and to the name name
attribute of the version version
element).widget widget
The possible value of a
attribute is one of the valid directional indicators
:dir
dir
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
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 the
attribute had no effect on any IRI attributes , path attributes , and the dir dir
element's author author element's
emailemail
attribute.
The base direction of a
attribute is either set explicitly
by the nearest parent element that uses the dir
dir
attribute; or, in the absence of
such an attribute, the base direction is inherited from the
default direction of
the document , which is left-to-right dir dir(" ("
").ltr ltr ").
The following example demonstrates the
attribute being applied globally to
a configuration document
.dir dir
<widget xmlns="http://www.w3.org/ns/widgets" dir="rtl" xml:lang="fa">
<name short="آب و هوا">
آب و هوا برنامه</name>
<description>
این نرم افزار به شما اجازه می دهد تا برای دیدن آب و هوا در منطقه محلی تان.
</description>
</widget>
The following example shows the
attribute applied to localized content .dir dir
<widget xmlns="http://www.w3.org/ns/widgets"><widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather"><name short="Weather"> Weather Application </name><name short="" xml:lang="fa" dir="rtl"><name short="آب و هوا" xml:lang="fa" dir="rtl"> آب و هوا برنامه </name> </widget>
The following example shows the
attribute used with mixed language
content:dir dir
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
<widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather">
Weather! a totally awesome application!
</name>
<name short="آب و هوا" xml:lang="fa" dir="rtl">
<span dir="ltr" xml:lang="en">Weather!</span> برنامه واقعا بزرگ
<name short="آب و هوا" xml:lang="fa" dir="rtl">
<span dir="ltr" xml:lang="en">Weather!</span> برنامه واقعا بزرگ
</name>
</widget>
widget
Element and its
AttributesThe
element serves as a container
for the other elements of the configuration document .widget widget
widget widget
element is the root element of a
configuration document
.name :
: zero or more ( one element is allowed per
language ).description
:
: zero or more ( one element is allowed per
language ).author :
: zero or one.license :
: zero or more ( one element is allowed per
language ).icon :
: zero or more.content :
: zero or one.feature :
: zero or more.preference
:
: zero or more.author , author
, preference
, preference
, icon ,
, and content content
will have no effect during
processing in Step 7 .id , id
,
version
, version
, height , height
, width , width
, viewmodes
.
.id
AttributeAn IRI attribute that denotes an identifier for the widget.
version
AttributeA version attribute that specifies the version of the widget.
height
AttributeA numeric attribute greater than
0
that indicates the preferred viewport height of the instantiated custom start file in
CSS pixels [CSS] .
width
AttributeA numeric attribute greater than
0
that indicates the preferred viewport width of the instantiated custom start file in
CSS pixels [CSS] .
viewmodes
AttributeA keyword list attribute that denotes the author's preferred view mode, followed by the next most preferred view mode and so forth. When the attribute is missing, or is left empty, it implies that the author expects the user agent to select an appropriate viewmode for the widget.
The concept of a viewport is defined in [CSS] , but is essentially a window or other viewing area on the screen (see section 9.1.1 The viewport of [CSS2] ). The concept of a view mode is defined in the [View-Modes] specification.
defaultlocale
attributeA language attribute that specifies, through a language tag , the author's preferred locale for the widget. Its intended use is to provide a fallback in case the user agent cannot match any of the widget's localized content to the user agent locales list or in case the author has not provided any unlocalized content.
The following example shows how the
element can be used.widget widget
<widget xmlns = "http://www.w3.org/ns/widgets" id = "http://example.org/exampleWidget" version = "2.0 Beta" height = "200" width = "200"<widget xmlns = "http://www.w3.org/ns/widgets" id = "http://example.org/exampleWidget" version = "2.0 Beta" height = "200" width = "200" viewmodes =
"windowed floating"/"windowed floating"/ >
defaultlocale
defaultlocale
attributeThe following example shows how the
element's widget widget element's
defaultlocaledefaultlocale
attribute can be
used:
<widget xmlns = "http://www.w3.org/ns/widgets" = "en-us"><widget xmlns = "http://www.w3.org/ns/widgets" defaultlocale = "en-us"><name short="Weather" xml:lang="en-us"><name short="Weather" xml:lang="en-us"> The Ultimate Weather Widget </name>
</widget><name short="Boletim" xml:lang="pt"> Boletim Metereológico<name short="Boletim" xml:lang="pt"> Boletim Metereológico </name>
name
Element and its
AttributesThe
element represents the full
human-readable name for a widget that is
used, for example, in an application menu or in other contexts.name
name
widget widget
element.span :
: zero or more.xml:lang :
:short .
.short
AttributeA displayable-string attribute intended to represent a condensed name for a widget (e.g., a name that could be used in context were only limited space is available, such as underneath an icon).
The following example shows the usage of the
element.name name
<widget xmlns="http://www.w3.org/ns/widgets"><widget xmlns="http://www.w3.org/ns/widgets">
<name short="Weather"><name short="Weather"> The Ultimate Weather Widget </name><name short="Boletim" xml:lang="pt"> Boletim Metereológico<name short="Boletim" xml:lang="pt"> Boletim Metereológico </name> </widget>
description
Element and
its AttributesThe
element represents a
human-readable description of the widget.description description
widget widget
element.span :
: zero or more.xml:lang :
:An example usage of the description element.
<widget xmlns="http://www.w3.org/ns/widgets"><widget xmlns="http://www.w3.org/ns/widgets"> <name>Dahut Chaser</name> <description> Combining the latest weather info with your GPS position, this widget alerts you of any significant dahut activity in your area. When a big one walks by, the widget plots the best route on a map based on the dahut's trajectory so you can chase it! With support for built-in cameras, you can quickly upload all the Alpine action to your blog or to the insane dahut chaser web site! Awesome! </description> </widget>
author
Element and its
AttributesAn
element represents people or an
organization attributed with the creation of the widget.author author
widget widget
element.span :
: zero or more.xml:lang :
:xml:lang xml:lang
(if any).href , href
,
email
.
.href
AttributeAn IRI attribute whose value represents an IRI that the author associates with himself or herself (e.g., a homepage, a profile on a social network, etc.).
email
AttributeA string attribute that represents an email address associated with the author.
The following example shows the expected usage of the
element.author
author
<widget xmlns="http://www.w3.org/ns/widgets"> <name>Café Finder</name> <author href = "http://dahut.example.org/developers/" email = "cafefinder@example.org"><widget xmlns="http://www.w3.org/ns/widgets"> <name>Café Finder</name> <author href = "http://dahut.example.org/developers/" email = "cafefinder@example.org"> Mr. Jo and Julia Bacalhau </author> </widget>
license
Element and its
AttributesThe
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.license license
widget widget
element.span :
: zero or more.xml:lang :
:href .
.href
AttributeA valid IRI or a valid path that points to a representation of a software and/or content license.
This example shows the expected usage of the
element's license license element's
hrefhref
attribute.
<widget xmlns="http://www.w3.org/ns/widgets"> <license href="http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231"><widget xmlns="http://www.w3.org/ns/widgets"> <license href="http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231"> Distributed under the W3C Software License. </license> </widget>
This example shows the expected usage of the
element when the license license
attribute is omitted.href href
<widget xmlns="http://www.w3.org/ns/widgets"><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.C, C++, or Objective-C). You can even "cross-compile" them, if you want. ... </license> </widget>
icon
Element and its
AttributesThe
element represents a custom icon for the widget.icon
icon
widget widget
element.xml:lang :
:src , src
,
width
, width
, height
.
.src
AttributeA path attribute that points to a file inside the widget package.
width
AttributeA numeric attribute greater than
0
that represents, in CSS
pixels [CSS2] , the author's preferred
width for the icon. A user agent may ignore
this value when changing the height icon to fit a rendering context
or for accessibility reasons.
height
AttributeA numeric attribute greater than
0
that represents, in CSS
pixels [CSS2] , the author's preferred
height for the icon. A user agent may ignore
this value when changing the height icon to fit a rendering context
or for accessibility reasons.
This example shows the expected usage of the
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.icon icon
<widget xmlns="http://www.w3.org/ns/widgets"> <icon src="icons/medium.png"/> <icon src="icons/big.svg" width="256" height="256"/> <icon src="icons/tiny.png"/><widget xmlns="http://www.w3.org/ns/widgets"> <icon src="icons/medium.png"/> <icon src="icons/big.svg" width="256" height="256"/> <icon src="icons/tiny.png"/> </widget>
content
Element and its
AttributesThe
element is used by an author to
declare which custom start file
the user agent is expected to use when it instantiates the
widget.content content
widget widget
element.xml:lang :
:src , src
,
type
, type
,
encoding .
.src
AttributeA path attribute that allows an author to point to a file within the widget package .
type
AttributeA media type attribute that
indicates the media type of the file
referenced by the src
attribute.
encoding
AttributeA keyword attribute that
denotes the character encoding of the file identified by the
attribute. The value is the src src"name"
"name" or "alias" "alias" of any
"Character Set" "Character Set" listed in [IANA-Charsets] .
The default encoding is
[UTF-8] , which has the name " "
" in the [IANA-Charsets] registry.UTF-8 UTF-8 "
Aside from the default encoding , it is optional for a user agent to support other character encodings.
This example shows the expected usage of the
element:content content
<widget xmlns="http://www.w3.org/ns/widgets"><widget xmlns="http://www.w3.org/ns/widgets"> <content src="myWidget.html"/> </widget>
This example shows the
element being used with a
content contentencoding
attribute to override the default value of
the encoding
attribute (
) with the GB2312 character set,
which the author has used to encode simplified Chinese
characters:UTF-8 UTF-8
<widget xmlns="http://www.w3.org/ns/widgets"> <name xml:lang="zh-cn">古老瓷地图</name><widget xmlns="http://www.w3.org/ns/widgets"> <name xml:lang="zh-cn">古老瓷地图</name> <name>Ancient Chinese Maps</name>
<content src="china-maps.html" encoding="GB2312"/> </widget>
This example shows the
element being used with a
content content
attribute to instantiate a widget
created with a proprietary media type
:type
type
<widget xmlns="http://www.w3.org/ns/widgets"><widget xmlns="http://www.w3.org/ns/widgets"> <name>Location-Based Games Finder</name>
<feature name="http://example.org/api.geolocation" required="false"/><content src="lbg-maps.swf" type="application/x-shockwave-flash"/> <feature name="http://example.org/api.geolocation" required="false"/> </widget>
feature
Element and its
AttributesA feature is a URI identifiable runtime
component (e.g. an Application Programming Interface or video
decoder). The act of a an author requesting the availability of a
feature through a
element is referred to as a
feature request . The feature feature
element serves as a
standardized means to request the binding of an IRI identifiable
runtime component to a widget for use at runtime. Using a
feature feature
element denotes that, at
runtime, a widget can attempt to access the feature identified by the feature
feature
element's feature feature element's
namename
attribute. How a user agent makes use of features depends on the user agent's security policy,
hence activation and authorization requirements for features are
beyond the scope of this specification. A feature has zero or more
parameters associated
with it.
widget widget
element.param param
elements.xml:lang :
:name , name
,
required .
.name
AttributeAn IRI attribute that identifies a feature that is needed by the widget at runtime (such as an API ).
required
AttributeA boolean attribute that indicates whether or not this feature has to be available to the widget at runtime.
When set to true
, the
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.required required
When set to false
, the
attribute denotes that a
widget can function correctly without the feature being supported or
otherwise made available by the user agent.required required
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 xmlns="http://www.w3.org/ns/widgets"> <feature name = "http://example.org/api/geolocation" required = "false"/> </widget>
param
Element and its
AttributesThe
element defines a parameter for a feature . A
parameter is a name-value pair that is
associated with the corresponding
feature for which the parameter is declared
for. A author establishes the relationship between a parameter and feature by having a param param
element as a direct child of a
param param
element in document order
.feature
feature
feature feature
element.xml:lang :
:name , name
, value .
.name
AttributeA string attribute that denotes the name of this parameter .
value
AttributeA string attribute that denotes the value of this parameter .
This example demonstrates a widget that makes use of a fictional
geo-location feature where by its accuracy is set to " " low
" " via a
element.param
param
<widget xmlns="http://www.w3.org/ns/widgets"> <feature name="http://example.org/api/geolocation"><widget xmlns="http://www.w3.org/ns/widgets"> <feature name="http://example.org/api/geolocation"> <param name="accuracy" value="low"/> </feature> </widget>
preference
Element and its
AttributesThe
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.preference preference
Note: A user agent that supports the [Widgets-APIs] specification will expose any declared preference at runtime in the manner described in the [Widgets-APIs] specification.
widget widget
element.xml:lang :
:name , name
, value
, value
, readonly .
.name
AttributeA string that denotes the name of this preference .
value
AttributeA string that denotes the value of this preference .
readonly
AttributeA boolean attribute indicating
whether this preference can, or cannot, be overwritten at runtime
(e.g., via an author script). When set to true
, it
means that the preference cannot be
overwritten. When set to false
, it means that the
preference can be overwritten.
This example shows a widget where two preferences are set. The
second
is set as preference preference"read only" "read
only" via the readonly
attribute, which means
the values of that preference cannot be changed at runtime.
<widget xmlns="http://www.w3.org/ns/widgets"> <preference name = "skin" value = "alien"/><widget xmlns="http://www.w3.org/ns/widgets"> <preference name = "skin" value = "alien"/> <!-- The preference below will be protected from modification and deletion at runtime -->
<preference name = "api-key" value = "f6d3a312f9d742" readonly = "true"/><preference name = "api-key" value = "f6d3a312f9d742" readonly = "true"/> </widget>
span
Element and its
AttributesThe
element is a wrapper for text
content; on its own it serves no useful function.span
span
It is expected that authors will use the
element with the global attributes . When combined with
the span span
attribute, the dir dir
element can 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 the
span span
attribute, the xml:lang xml:lang
element allows the author to
indicate the particular language used for a subset of text content
within another element.span span
name , name
, author , author
, license ,
, and/or description
description
element.xml:lang :
:No, meaning that declaring
on a xml:lang xml:lang
element within a parent element
(e.g., a span span
element) will not affect the
behavior of element-based
localization (see Example of Usage below to see how this
works).name name
This section is informative.
This example shows the
elements being used to indicate
directionality of text as well as language information. Note that
the span span
element's name
name element's
xml:langxml:lang
attribute is set to an empty
string to allow it to be used as default
content in the process of element-based localization
:
<widget
xmlns="http://www.w3.org/ns/widgets"
xml:lang="he" dir="rtl">
<name xml:lang="" dir="ltr">
<span xml:lang="en">GPS Weather!</span>
xmlns="http://www.w3.org/ns/widgets"
xml:lang="he" dir="rtl">
<name xml:lang="" dir="ltr">
<span xml:lang="en">GPS Weather!</span>
</name>
<description>
יישומון ה-
<span dir="ltr" xml:lang="en">GPS Weather!</span> מאפשר
<span dir="ltr" xml:lang="en">GPS Weather!</span> מאפשר
לך לבדוק את מזג הא
וויר בכל נקודת GPS ברחבי העולם.
</description>
<description xml:lang="" dir="ltr">
<span xml:lang="en">The GPS Weather! widget lets you check
<description xml:lang="" dir="ltr">
<span xml:lang="en">The GPS Weather! widget lets you check
the weather at any point around the world with GPS.</span>
</description>
</widget>
Internationalization , or
i18n, is the design and development of a product, application or
document content that enables localization for target audiences
that vary in culture, region, or language. Localization refers to the adaptation of a
product, application or document content to meet the language,
cultural and other requirements of a specific target market (a
"locale"). "locale").
Note: See also the Web Services Internationalization Usage Scenarios and the Unicode Locale Data Markup Language for an informative discussion on the term locale.
Localized content is content an author has explicitly localized : that is, a widget package that contains content localized using folder-based localization or a configuration document that contains content localized via element-based localization .
Default 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
element. In the case of a
widget package , this means content
outside the container
for localized content . In the case of a configuration document , this means
any element without an explicitly declared or inherited
widget widget
attribute.xml:lang xml:lang
A localized file is any file that has been placed inside a locale folder (i.e., localized content that makes use of folder-based localization ). A widget package contains zero or more localized files. All files and folders, except for the digital signatures and the configuration document , can be localized via folder-based localization .
For example, a locale folder " "
locales/ja/
" " (Japanese) might contain an HTML document
translated into Japanese.
In conjunction to mandating that user agents support [Unicode] , this specification provides the
attribute and dir dir
element as a markup-based means of
influencing the directionality for bidirectional Unicode text
[BIDI] . See the definitions of the
span span
attribute and dir dir
element for usage examples.span span
This specification provides two means that authors can use to explicitly localize the content of a widget:
By placing localized file content in locale folders , a process referred to as folder-based localization .
By explicitly marking XML elements in the configuration document as localized, a process referred to as element-based localization .
Both forms of localization are described below. Folder-based 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 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
case-sensitively matches the string ' folder-name folder-namelocales
'. A
container for localized content contains zero or more locale folders .
A locale folder is a folder whose file
name field matches the production of
and is a direct
descendant of the container for localized
content (e.g., locale-folder locale-folder" " /locales/en-us
", " ", "
/locales/fr
", ", etc). A locale
folder contains zero or more arbitrary
folders and/or files.
This specification defines the concept of element-based localization ,
which allows authors to use the
attribute to explicitly
indicate that an [XML] element in the configuration document has been
localized .xml:lang xml:lang
The following is an example of element-based localization:
<widget xmlns="http://www.w3.org/ns/widgets"> <name short="Weather"><widget xmlns="http://www.w3.org/ns/widgets"> <name short="Weather"> The Ultimate Weather Widget </name>
<name short="Boletim" xml:lang="pt"> Boletim Metereológico<name short="Boletim" xml:lang="pt"> Boletim Metereológico </name> </widget>
Some of the elements in the widgets namespace are defined to be
localizable via xml:lang
as part of the element's definition (with either "yes" "yes" or
"no"). "no"). See, for example, the
element. When name name"yes", "yes", it means
that an author can utilize xml:lang to achieve element-based
localization either directly or indirectly through the inheritance
of the value of xml:lang
. How element-based localization is
handled is specified in detail in Step 7 ..
Note: The xml:lang
attribute can be used on any element in order to indicate which
language is used in the content and attribute values of that
element. As specified in the XML Specification, its value is
inherited, such that if an element has an xml:lang attribute, all
of its descendants are considered to be in that language as well,
unless they specify their own
attribute. Note that an
element can indicate that it is in no specific language by setting
xml:lang xml:lang
to the empty string,
irrespective of whether any of its ancestors has an xml:lang
attribute.xml:lang xml:lang
For example, if an author uses the
attribute on the xml:lang xml:lang
element, then all child elements
inherit the value xml:lang. This means that the first widget widget
element below behaves as
name name
had been explicitly used.
However, in the second xml:lang="en" xml:lang="en"
element, the declaration of
name name
overrides xml:lang="pt" xml:lang="pt"
inherited from the
xml:lang="en" xml:lang="en"
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
widget
<widget xmlns="http://www.w3.org/ns/widgets" xml:lang="en"><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="I'm in english, though not explicitly marked as such!"> Behaves as if xml:lang="en" </name><name xml:lang="pt"> The declaration of xml:lang="pt" overrides xml:lang="en" inherited from the widget element.<name xml:lang="pt"> The declaration of xml:lang="pt" overrides xml:lang="en" inherited from the widget element. </name><name xml:lang=""><name xml:lang=""> The user agent will treat this as unlocalized content. </name> </widget>
If an element is marked as being localizable via
with xml:lang xml:lang"yes", "yes", the
specification indicates that only one element is allowed per
language :
One element is allowed per language means that only one element
of a type is allowed to be used per language (e.g., although many
elements can be present in a
configuration document ,
only one name
name
element will be selected by the
user agent for the English language). During processing ( Step 7 ), the user
agent will only match the first element, in document order
, that matches a language range in the user agent locales and ignore any subsequent repetitions of the element that
contain a matching name name
value (even if that element's
content is different).xml:lang
xml:lang
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
element is allowed per
language, in the following code the user agent would match the
first description description
element but would ignore the second and third description description
elements.description
description
<widget xmlns="http://www.w3.org/ns/widgets">
<widget xmlns="http://www.w3.org/ns/widgets">
<description xml:lang="en">
<description xml:lang="en">
This element would be used.
</description>
<description xml:lang="en">
<description xml:lang="en">
This element would be ignored because there is already
a description element that uses xml:lang="en".
a description element that uses xml:lang="en".
</description>
<description>
This element is unlocalized, and would be used if the user agent's
locale does not match any localized description elements.
</description>
<description xml:lang="">
<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
description element! Using xml:lang="" makes this element behave as if
it is unlocalized.
</description>
</widget>
However, if the user agent
locales only contained "
" *
", ", or did not match
any of the localized
elements, then the user
agent would match the third description description
element above.description
description
In the case whereby the author does not use an
attribute, and no element of a
particular type with xml:lang xml:lang
matches the user agent locales xml:lang
xml:lang, , the user agent will use the first
element that is default 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
element is allowed per
language, in the following code the user will agent ignore the first two description
description
elements, but would match
the third (unlocalized) description
description
element.description
description
<widget xmlns="http://www.w3.org/ns/widgets">
<widget xmlns="http://www.w3.org/ns/widgets">
<description xml:lang="en">
<description xml:lang="en">
This element would be ignored.
</description>
<description xml:lang="en">
<description xml:lang="en">
This element would be ignored.
</description>
<description>
In this case, this unlocalized element would be used.
</description>
</widget>
This section is non-normative.
This section presents three examples of how widgets can be localized. Each example is intended to showcase how the localization algorithm is intended to work.
This example shows a widget that displays
the days of the week based on the language ranges held by the
user agent locales
. . If the user agent is unable
to match a language range to any locale
folder , the widget displays /index.html
at the
root of the widget
package .
config.xml
<widget xmlns="http://www.w3.org/ns/widgets">
<name>What day is it?</name>
<description>
This widget highlights the current day
of the week.
</description>
</widget>
locale/es/index.html
<!doctype html>
<title>¿Qué día es?</title>
<script src="scripts/dayfinder.js"></script>
<title>¿Qué día es?</title>
<script src="scripts/dayfinder.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/
) has its own
localized icon.locales/es
) and English (
locales/en/
) versions of the widget use the
un-localized script in /scripts/engine.js
folder.en-au
)
version uses a localized script (
en-au/scripts/engine.js
)./config.xml
<widget xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="ko">웃기는 고양이</name>
<content src="cats.html"/>
</widget>
/locales/en-au/cats.html
<!doctype html>
<title>G'day! LOL Cats!</title>
<script src="scripts/engine.js">
<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
": ":
Firstly, the user agent will search for a folder that matches
the user agent's locale as closely as possible for the desired
file. In this case, the user agent would attempt to locate the
relative path 'images/mast.png
' in '
/locales/en-gb/
', but would fail.
Secondly, if the file is absent, the user agent will search for
the absent file in any other sub-folder that is in the language
range of the current locale folder. So the next place the user
agent would look is in the ' en/
' folder, where it
would match the zip relative path ' images/mast.png
'.
Lastly, if the above fails, the user agent will search for the
absent file at the root of the widget package. So, if the user
agent's locale did not find the zip relative path in one of the
locale folders, then ' images/mast.png
' file at the
root of the widget would be matched and this default content would be used.
Now consider the for various Chinese variants: '
zh-hans-cn
', ' zh-hans
', and '
zh
' below. In this case, to find the '
flag.png
' file for Mainland Chinese in simplified
script ' zh-hans-cn
', the user agent would first look
in ' zh-hans-cn
', followed by ' zh-hans
', then in ' zh
' where the file is located.
To find the ' mast.png
' file, the user agent would
look in ' zh-hans-cn
', followed by '
zh-hans
', followed ' zh
', and finally
at the root of the widget package where the absent file is actually
located.
/index.html
<!doctype html>
<title>Patriotic Boat</title>
<script src="scripts/engine.js">
<script src="scripts/engine.js">
</script>
<body>
<img src="flag.png">
<img src="flag.png">
<img
src="mast.png">
src="mast.png">
The steps for processing a widget package involves nine steps that a user agent follows in sequential order, responding accordingly if any of the steps result in an error or if the specification asks for the user agent to skip a step. The procedures for what to do when an error is encountered are described as part of each step; however, there are times when it will not be possible for the user agent to recover from an error and it will be forced to treat the widget as an invalid widget package .
In the event that a user agent encounters an invalid widget package during the steps for processing a widget package , a user agent must abort all processing of the steps for processing a widget package .
Note: A user agent can optimize steps for processing a widget package and associated processing rules , or perform the steps in a different order, but the end result needs to be indistinguishable from the result that would be obtained by following the specification.
This section defines various processing rules , which are algorithms used during the steps for processing a widget package .
These algorithm makes use of a few special concepts defined below:
Any Text
node, including CDATASection
nodes (any Node
with node type TEXT_NODE
or CDATA_SECTION_NODE
) as defined in the [DOM3Core] specification. For example, the worlds
"hello world!" "hello world!" in the following
element: name name<name>hello
world!</name>
.
A data structure containing a sequence of one or more strings, each having some associated directional information and language information (if any). The purpose of an localizable string is to assist user agent in correctly applying the Unicode [BIDI] algorithm when displaying text.
For example, the string "Internationalization "Internationalization نشاط
التدويل! Activity." Activity." The string contains both Arabic and
English that mixes left-to-right text, right-to-left text, and a
directionality-neutral punctuation mark that could not be correctly
displayed without directional information.
null
A special symbol to indicate that a value has no data. For
example, "let "let x be
" or null null ""if
"if y is empty, then return
".null null ".
Note: Note: Although
languages such as ECMA Script and Java support
as a native value type, there are
some programming languages that have no notion of null null
or where null is problematic (e.g.
C++). Implementations in these languages need to substitute a
language-specific value or symbol which is functionally equivalent
to null nullnull
, or if no equivalent exists, to have no
value at all. For example, the value 0 may represent
,
for the height of a widget, since
the height of a widget is defined as a non-negative integer greater
than 0. In such a case, 0 could be treated as if it were
null nullnull
..
The rule for verifying a zip archive is described in this section. The algorithm returns either true or an error.
This specification does not provide the technical details of how to actually perform the checks, for which implementers need to refer to the [ZIP] specification.
If the Zip archive is split into multiple files or spans multiple volumes , as defined in the [ZIP] specification, then return an error and terminate this algorithm.
If the Zip archive is encrypted, as defined in [Zip] , return an error and terminate this algorithm.
The rule for extracting file data from a file entry is as follows:
Let path be the zip relative path that identifies the file entry being sought.
Let file entry be the file entry identified by the path .
Let file file be the result of
decompressing (or extracting) the file
data from from file
entry using [Zip] .
Return file . .
Note: For efficiency, a user agent can extract specific files as they are needed for processing rather than extracting all the files at once. As a security precaution, implementations are discouraged from extracting file entries from un-trusted widgets directly onto the file system. Instead, implementations could use, for example, a virtual file system or mapping to access files inside a widget package .
The rule for
finding a file within a widget package is given in the
following algorithm. The algorithm returns either a processable file , null
, or an
error.,
For the sake of comparison and matching, it is recommended that a user agent treat all Zip relative paths as [UTF-8] .
Note: This specification does not define how links in documents other than the configuration document are to be dereferenced. For handling links in other documents, such as (X)HTML, CSS, SVG, etc., please refer to the [Widgets-URI] specification.
Let path be the path to the file entry being sought by the user agent.
If path is not a valid path, return an error and terminate this algorithm.
If the path starts with a U+002F SOLIDUS (e.g.,
" "
/style/master.css
"),
"), then remove the first U+002F
SOLIDUS from path.
Let path-components be the result of splitting path at each occurrence of a U+002F SOLIDUS character, removing that U+002F SOLIDUS character in the process.
if the first item in path-components case-sensitively
matches the string " " locales
", ", then:
For each lang-range in the user agent locales : :
Let path be the concatenation of the string
" "
locales/
", ", the lang-range , a U+002F SOLIDUS
character, and the path (e.g.,
locales/en-us/cats.png
, where " " en-us
" " is the
lang-range and " " cats.png
" " is the
path ).
If path case-sensitively matches the file name field of a file entry within the widget package that is a folder , then return an error and terminate this algorithm.
If path case-sensitively matches the file name field of a file entry within the widget package that is a file , let file
file be the
result of applying the rule for
extracting file data from a file entry to path .
If file is a processable file , then return file and terminate this algorithm.
If the path points to a file entry that is not a processable file , then return an error and terminate this algorithm.
If every lang-range in the user agent locales have been searched, then search for a file entry whose file name field matches path from the root of the widget package :
If path points to a file entry within the widget package that is a folder , then return an error and terminate this algorithm.
If path points to a file
entry within the widget
package that is a file , let
file 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 determining directionality is given in the following algorithm. The algorithm always returns one of the valid directional indicators as a string.
Let element be the element to be processed.
If element is the root element of the configuration document :
If it does not contain a
attribute, return dir
dir" "
" and terminate this algorithm.ltr ltr "
if it does contain a
attribute, and the value of the
attribute case-sensitively matches one of the valid directional indicators ,
return the value of the attribute and terminate this algorithm. if
the value does not case-sensitively matches one of the valid directional indicators ,
return the dir
dir" "
" and
terminate this algorithm.ltr ltr "
If element does not contain a
attribute, recursively apply
rule for
determining directionality to the direct parent element of
element and return the result.dir dir
If element contains a
attribute, let direction
be the result of applying the rule for getting a
single attribute value to the dir dirdir dir attribute of element
:
If direction case-sensitively matches one of the valid directional indicators , return direction .
If direction did not case-sensitively match one of the valid directional indicators , apply the rule for determining directionality to the direct parent element of element and return the result .
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 , which can be empty.
Let attribute be the attribute to be processed.
Let value be the value of the attribute to be processed.
In value , replace any sequences of space characters (in any order) with a single U+0020 SPACE character.
In value , remove any leading or trailing U+0020 SPACE characters.
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
attribute on either
element , or in element 's ancestor chain as
per [XML] . If xml:lang xml:langxml:lang xml:lang was not used anywhere in the
ancestor chain, then let lang be an empty string.
Associate lang with result .
The rule for getting a list of keywords from an attribute is given by the following algorithm. The algorithm takes a string as input, and returns a list of strings which can be empty.
Let result be the value of the attribute to be processed.
In result , replace any sequences of space characters (in any order) with a single U+0020 SPACE character.
In result , remove any leading or trailing U+0020 SPACE character.
In result , split the string at each occurrence of a U+0020 character, removing that U+0020 character in the process.
The rule for verifying a file entry is given in the following algorithm. The algorithm always returns a boolean value.
For the file entry , check the
following data in the local file
header . .
If the value of the CRC-32 field (defined
in the [ZIP] specification) fails a CRC-32
check, return false
and terminate this algorithm.
The file name field is
an empty string, return false
and terminate this
algorithm.
The file name field
contains Zip forbidden
characters , return false
and terminate this
algorithm.
The file name field is
a sequence exclusively composed of (one or more) space characters or a mixed sequence of
space characters and U+002E FULL
STOP (".") (".") (e.g. " . . "), " . . "), return
false
and terminate this algorithm.
The file name field is
an invalid Zip relative path ,
return false
and terminate this algorithm.
true
.The rule for getting text content is given in the following algorithm. The algorithm always returns a localizable string , which can be empty.
Let input be the Element
to be
processed.
Let bidi-text be an empty localizable string .
If input has no child nodes, return an bidi-text and terminate this algorithm.
Let lang be the language
tag derived from having processed the
attribute on either
input , or in input 's ancestor chain as per
[XML] . If xml:lang xml:langxml:lang 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 to input .
For each child node of input :
If the current child node is a text node , the associate direction and lang with the current child node.
If the current child node is an Element
,
recursively apply the rule for getting text
content :
Associate lang and direction with bidi-text.
For example, the following configuration document:
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" dir="rtl" xml:lang="fr"> <name dir="rlo"> <span xml:lang="jp">Hello <span dir="rtl"><span dir="rlo"/>backwards</span></span> </name> </widget>
When the rule for getting text content is applied could be logically represented as pseudo code:
{dir: rlo,
lang: fr,
textNodes:
[{data: "Hello ",
direction: "rlo",
lang: "jp"},
{data: "backwards",
direction: "rtl",
lang: "jp"}]
}
The rule for getting text content with normalized white space is given in the following algorithm. The algorithm always returns a string, which can be empty.
Let input be the Element
to be
processed.
Let result be the result of applying the rule for getting text content to input .
In result , convert any sequence of one or more Unicode white space characters into a single U+0020 SPACE.
In result , remove any leading or trailing U+0020 SPACE character.
Return result .
For example, the user agent would ignore
the
and author
authorblink
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>
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>
The resulting widget name
would be " " The Awesome Super Dude Widget "
" (please note that Dude
is
rendered right-to-left).
The rule for parsing a non-negative integer is given in the following algorithm. This algorithm returns the number zero, a positive integer, or an error.
Let input be the string being parsed.
Let result have the value 0
.
If the length of input is 0
,
return an error.
Let position be a pointer into input , initially pointing at first character of the string.
Let nextchar be the character in input at position .
If the nextchar is one of the space characters , increment position . If position is past the end of input , return an error and terminate this algorithm. Otherwise, go to step 5 in this algorithm.
If the nextchar is not one of U+0030 ( 0
) .. U+0039 ( 9
), then return result .
If the nextchar is one of U+0030 ( 0
)
.. U+0039 ( 9
):
Multiply result by ten.
Add the value of the nextchar to result .
Increment position .
If position is not past the end of input , go to 5 in this algorithm.
Return result .
The rule for identifying the media type of a file is given by the following algorithm. The algorithm always returns a string.
Note: This rule is
only to be applied when explicitly instructed to by the
specification (e.g., during Step 7 ). There
are situations where alternative means are defined by the
specification to identify the media type of a file (e.g., by the
presence of the
element's content content element's
typetype
attribute or deriving the media type of a default start file from the default start files table ).
Let file be the file to be processed.
Let content-type be an empty string.
Let extension be an empty string.
Let name be the
component of the zip relative path that identifies the
file file-name file-name.
.
For example, the name for " "
some/zip/rel/path/hello.png
" " would be
" "
hello.png
". ".
If the first character of the name is a U+002E 'FULL STOP' character, and the file name contains no other U+002E 'FULL STOP' character, then go to step 10 of this algorithm.
For example, if the name is " "
.htaccess ", ", jump to step 10 and derive the media type using
the [SNIFF] specification.
If the first character or last character of the name is not a U+002E 'FULL STOP' character, but name contains one or more U+002E 'FULL STOP' characters, then let extension be the sequence of characters from the last U+002E 'FULL STOP' (inclusive) to the end of name .
The value of extension for the file
name " "
cat.html " " would be ".
". html html ".
". The value of extension for
"...html" "...html" would be ".html". ".html". And
the value of extension for "hello." "hello."
would be an empty string.
If the first character of the name is a U+002E 'FULL STOP' character, and the file name contains another U+002E 'FULL STOP' character, then let extension be the sequence of characters from the last U+002E 'FULL STOP' (inclusive) to the end of name (if any).
For example, if the name is
" "
.myhidden.html ",
", then the extension would be
" .html "
.html ". ".
If extension is an empty string, go to step 10 in this algorithm.
Check that each character in the extension is either in the U+0041-U+005A range or in the U+0061-U+007A range (ASCII uppercase and lowercase characters, respectively) or in the U+0030-U+0039 range (ASCII numbers 0 to 9):
If any character in the extension 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 "
.pñg ", ", the go to step 10 in this algorithm.
If all characters in the extension 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., "
" Mp3
"), "), then attempt
to case-insensitive match the value of extension to one
of the values in the file extension column in the file identification table . If
there is a match, then return let content-type be the
corresponding value from the media type
column.
Go to step 11.
Let content-type be the result of processing
file file through the [SNIFF] specification.
file extension | media type |
---|---|
.html | text/html |
.htm | text/html |
.css | text/css |
.js | application/javascript |
.xml | application/xml |
.txt | text/plain |
.wav | audio/x-wav |
.xhtml | application/xhtml+xml |
.xht | application/xhtml+xml |
.gif | image/gif |
.png | image/png |
.ico | image/vnd.microsoft.icon |
.svg | image/svg+xml |
.jpg | image/jpeg |
.mp3 | audio/mpeg |
It is optional for a user agent to support the media types given in the file identification table .
The rule for deriving the user agent locales is as follows:
Let unprocessed locales list be a comma-separated list that contains the end-user's language ranges .
For each range in the unprocessed locales list :
If this range begins with the subtag ' *
' (e.g. " " *-us
" " or just
" "
*
"), "), or contains any space characters , skip all the steps in
this algorithm below, and move onto the next range .
If this range begins with the subtag "
" i
" " or the
range is marked as "deprecated" "deprecated" in the IANA
Language Subtag Registry , skip all the steps in this algorithm
below, and move onto the next range .
If this range contains any subtag ' *
', remove the '
*
' and its preceding hyphen ( U+002F
)
(e.g., ' en-*-us
' becomes ' en-us
').
While range contains subtags :
Add the value of the range to the user agent locales . .
Remove the right most subtag from range and append the resulting
value to user agent locales
. . Continue removing the right
most subtag and adding the
result to user agent
locales until there are no subtags
left in range .
For example, if the range was
" "
zh-hans-cn
", ", then the user agent locales become
" "
zh-hans-cn,zh-hans,zh
".
".
Move onto the next range and go to step 1 in this algorithm.
Append the value " " *
"
" to the end of user agent locales . .
For example, an unprocessed locales
list that contains " " en-us,en-au,en,fr-ca,zh-hans-cn
" " would
result in a user agent
locales that contains "
"
en-us,en,en-au,en,en,fr-ca,fr,zh-hans-cn,zh-hans,zh,*
". ".
For example, an unprocessed locales
list that contains " " en-us,en,fr-ca,en,en-ca
" " would result in a
user agent locales
that contains " " en-us,en,en,fr-ca,fr,en,en-ca,en,*
". ".
The rule for determining if a potential Zip archive is a Zip archive is given by the following algorithm.
Let potential archive be the acquired resource.
Check if the first four bytes of potential archive
match the magic numbers
for a Zip archive ( 50 4B 03 04
).
If the first four bytes do not match the magic numbers for a Zip archive , then return an error.
Otherwise, return true
.
Note: A user agent can inspect the potential archive once it has acquired the first four bytes of the potential Zip archive or can wait until all the data of the potential Zip archive has been completely acquired.
Step 1 involves acquiring a potential Zip archive and confirming that it is a Zip archive by applying the rule for determining if a potential Zip archive is a Zip archive . A user agent will acquire a potential Zip archive from a data transfer protocol that either labels resources with a media type (e.g. [HTTP] ) or from a data transfer protocol that does not label resources with a media type (e.g., BitTorrent or Bluetooth).
It is recommended that a
user agent support
acquisition
of a potential Zip archive from a protocol that labels resources
with a media type (e.g., getting a widget package over [HTTP] ). If a user agent supports acquisition of a potential Zip archive
from a protocol that labels resources with a media type, then the
user agent needs 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 the user agent supports legacy or proprietary media types , unsupported media types are in error and the user agent must treat the potential
Zip archive as an invalid
widget package .
If the result of the user agent applying the
rule for determining if a potential Zip archive is a Zip
archive is true
, meaning that the potential Zip archive is a Zip archive , then the user agent must proceed
to Step 2 . Otherwise,
if an error is returned, the user agent must treat the
potential Zip archive as an
invalid widget package
.
For example, in [HTTP] ,
where the Content-Type
header matches
application/widget
.
If the protocol used for acquisition of a potential Zip archive does not provide, or otherwise include, a media type , then a user agent should treat the acquired potential Zip archive as if it has been acquired from a protocol that does not label resources with a media type .
In this example, the media type of
the Content-Type
is not one supported by the user agent, so the user agent
would treat the potential Zip
archive as an invalid
widget package :
GET /foo.wgt HTTP/1.1
Host: www.example.com
Accept:
application/widget
HTTP/1.1 200 OK
Date: Tue, 04 Sep 2007 00:00:38 GMT
Last-Modified: Mon, 03 Sep 2007 06:47:19 GMT
Content-Length: 1337
Content-Type:
application/x-gadget
When acquiring a potential Zip archive that
has not been labeled with a media type (e.g., from a file system),
a user agent
should attempt to process the resource
regardless of the file extension (including situations when the
file extension is absent) by applying the
rule for determining if a potential Zip archive is a Zip
archive . If the
rule for determining if a potential Zip archive is a Zip
archive return true
, proceed to Step 2 . Otherwise, if an
error was returned, the user agent must treat the
potential Zip archive as an
invalid widget package
.
To verify that a Zip
archive and its file
entries conform to this specification, a user agent must apply
the rule for
verifying a zip archive . If the rule for verifying a zip
archive returns true
, then the user agent must go to Step 3 . Otherwise, if
the rule for
verifying a zip archive returns an error, then the user agent must treat the Zip archive
as an invalid widget
package .
In Step 3 , a user agent must set the following variables and default values as defined in the table of configuration defaults .
Note: When a
value is assigned to a variable in
the table of
configuration defaults , a user agent needs to treats the value
as null null
(i.e., not as
an empty string and not as the text string null null
)."null" "null"
Variable | Type | Overridden in | Description |
---|---|---|---|
author email | String | Step 7 | The value of the element's email
attribute (if any). |
author href | IRI | Step 7 | The value of the element's href attribute (if any). |
author name | String | Step 7 | The text content of the element (if any). |
feature list | List | Step 7 | A list of features that correspond to features that were
requested via elements (if any). Each item in
the list corresponds to a element's name attribute, whether it is required,
and any associated parameters (if any). |
icons | List of file entries | 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 | Step 7 | The character encoding of the custom start file , corresponding to
either the element's encoding attribute (if any), or the
default encoding . |
start file content-type | String | Step 7 | The media type of the start file , corresponding to the element's type
attribute or to a media type derived from the default start files table . |
widget config doc | File | Step 6 | The file that is the configuration document for the widget package . |
widget description | String | Step 7 | The text content of the element in the configuration document . |
widget height | positive number | Step 7 | The value of the element's height attribute in the configuration document (if
any). |
widget id | String | Step 7 |
The value of the |
widget license | String | Step 7 | The text content of the element in the configuration document (if
any). |
widget license file | File | Step 7 | A file derived if the value of the
element's href
is a Zip relative path to a file
within the widget package . |
widget license href | IRI | Step 7 | The value of the element's href
attribute in the configuration
document (if any). |
widget name | Localizable String | Step 7 | The text content of the element in the configuration document (if
any). |
widget preferences | List | Step 7 |
The widget's preferences , corresponding to the Unless an end-user explicitly requests that these values be reverted to the values as declared in the configuration document , a user agent must not reset the value of the widget preferences variable on subsequent initializations of the widget. |
widget short name | Localizable String | Step 7 | The value of the element's short
attribute in the configuration
document (if any). |
Variable | Type | Overridden by | Description |
widget version | Localizable String | Step 7 | The value of the element's version attribute in the configuration document (if
any). |
widget width | positive number | Step 7 | The value of the element's width attribute in the configuration document (if
any). |
widget window modes | List of strings | Step 7 | The value of the element's viewmodes
attribute in the configuration
document (if any). |
widget start file | File entry | 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
element's src
attribute. |
user agent locales |
List of strings |
Step 5 | A list of language tags . |
If the user agent does not support [Widgets-DigSig] , then the user agent must skip Step 4 and go to Step 5 . Otherwise, the user agent must apply the algorithm to locate digital signatures, which is defined in the [Widgets-DigSig] specification under the section named Locating and Processing Digital Signatures .
The end-user's language ranges represents the end-user's preferred languages and regional settings, which are derived from the operating system or directly from the user agent. As there are numerous ways a user agent can derive the end-user's preferred languages and regional settings, the means by which those values are derived are beyond the scope of this specification and left up to the implementation.
During the rule for deriving the
user agent locales defined below, the user agent
will need to construct a list unprocessed locales . Each
item in the unprocessed locales is a string in lowercase
form, that conforms to the production of a
Language-Tag
, as defined in the [BCP47] specification. A string that conforms to the
production of a Language-Tag
is referred to as a
language range
[BCP47] (e.g. ' en-au
', which is
the range of English as spoken in Australia, and '
fr-ca
', which is the range of French as spoken in
Canada, etc.). A language range is composed of one or more subtags that are delimited by a U+002D HYPHEN-MINUS
(" ("
-
"). ").
The first item of the unprocessed locales represents the user's most preferred language range (i.e., the language/region combination the user agent assumes the end-user most wants to see content in), followed by the next most preferred language range, and so forth.
For example, in an unprocessed locales
list that contains ' en-us,en,fr,es
', English
as spoken in the United States is preferred over English, and
English is preferred over French, and French is preferred over
Spanish, and Spanish is preferred over default content .
For example, the end-user may have specified her preferred languages and regional settings at install time by selecting a preferred language, or languages from a list, or a list of preferred languages and regional settings could have been dynamically derived from the end-user's geographical location, etc.
In Step 5 , the user agent must apply the rule for deriving the user agent locales .
This step involves searching within the Zip archive for a configuration document .
In Step 6 , a user agent must apply the algorithm to locate the configuration document .
The algorithm to locate the configuration document is as follows:
Search at the root of the
widget package for a file entry whose
file name field
case-sensitively matches the valid configuration
document file name ( config.xml
).
null null
), then treat the Zip archive as an invalid widget package .The purpose of processing the configuration document is to override the values in the table of configuration defaults , which are used during initialization and at runtime, and to select the appropriate localized content (if any) to be presented to the end user.
In conjunction to the algorithm for processing a configuration document given below, this section firstly defines some terminology used by the processing algorithm and describes how localized elements are processed.
During Step 7 , a user agent must apply the algorithm to process a configuration document .
In the algorithm to process a configuration document , the term in error is used to mean that an element, or attribute, or file in a configuration document is non-conforming to the rules of this specification. How an element or an attribute is to be treated when it is in error is always given when the term is used; but will generally require the user agent to ignore any element, attribute, or file that is in error.
To ignore means to act as if the element, attribute, or file that is in error is absent (i.e., not declared or included by the author) in the widget package or configuration document. A user agent must , however, keep a record of all element types it has attempted to process even if they were ignored (this is to determine if the user agent has attempted to process an element of a given type already).
In the case the user agent is asked to ignore an [XML] element or node, a user agent must :
Stop processing the current element , ignoring all of the element 's attributes and child nodes (if any), and proceed to the next element in the elements list .
Make a record that it has attempted to process an element of that type.
In the following example, the user agent ignores both
elements. The user agent
ignores the first because it lacks a content
content
attribute. The user agent ignores the second because it is not the
first content element to be encountered by the user agent.src src
<widget xmlns="http://www.w3.org/ns/widgets">
<!-- User agent ignores the first, but records
that it has attempted to process a content element
-->
<content/>
<!-- The use agent knows that it has previously attempted
to process a content element, hence this content element
is ignored.
-->
<content src="cats.html"/>
<content src="cats.html"/>
</widget>
To associate means that two or more
pieces of information are bound and stored together for the purpose
of later processing (e.g., the name of a feature , and if it is required
, and any associated parameters ). How associated
data is represented is left up-to the implementation (e.g., a user
agent could use an array, an object, a hash map, etc.).,
The lookup algorithm is defined in [BCP47] (see RFC 5646 ). It is used in this Step to match localized content in the configuration document to the language ranges held by the user agent locales (if any).
The algorithm to process a configuration document is as follows:
Let doc be the result of loading the widget config doc as a [DOM3Core] Document
using an [XML] parser that is both [XMLNS]
-aware and
aware.xml:lang xml:lang
If doc is not namespace well-formed [XML] , then the user agent must terminate this algorithm and treat this widget package as an invalid widget package .
Let root element be the documentElement
of doc .
If the root element is not a
element in the widget namespace , then the user agent must terminate this algorithm and treat this widget package as an invalid widget package .widget
widget
Otherwise, the element is a
element:widget widget
If the 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
attribute is used,
then let id be the result of applying the rule for getting a
single attribute value to the id
attribute. If
id is a valid IRI , then let
widget
id be the value of the id . If the
id is in error , then the
user agent must ignore the attribute.
If the version
attribute is
used, then let version value be the result of applying
the rule for
getting a single attribute value to the version
attribute. If the version is an empty string, then the
user agent must ignore the attribute;
otherwise, let widget
version be the value of version value .
If the height
attribute is used,
then let normalized height be the result of applying the
rule for
parsing a non-negative integer to the value of the attribute.
If the normalized height is not in
error and greater than 0
, then let widget height be the value of
normalized height . If the height
attribute
is in error , then the user agent must ignore the attribute.
If the width
attribute is used,
then let normalized width be the result of applying the
rule for
parsing a non-negative integer to the value of the attribute.
If the normalized width is not in
error and greater than 0
, then let widget width be the value of
normalized width . If the width
attribute
is in error , then the user agent must ignore the attribute.
If the viewmodes
attribute is
used, then the user
agent must let viewmodes list be
the result of applying the rule for
getting a list of keywords from an attribute :
From the viewmode list , remove any unsupported items.
From the viewmode list , remove any duplicated items from right to left.
For example, viewmode list with a
value of " " windowed fullscreen windowed floating
fullscreen windowed
"
" would become " " windowed
fullscreen floating
".
".
Let widget window modes be the value of viewmodes list .
If the
element does not contain any
child elements, then the user agent must terminate
this algorithm and go to Step 8 .widget widget
Otherwise, let element list be an empty list.
For each range in the user agent locales , , starting from the first and moving to
the last:
If the value of range is not "*", "*", then
retaining document order
, let matching elements be the result of applying
lookup to the child elements that are defined
as being localizable via
xml:lang
that are direct descendents of the
root element and whose
attribute matches the current
range . Append matching elements to the
element list xml:lang xml:lang. .
Note: In the context
of this specification, the above conformance requirement is
intended to match the
, name , namedescription
, and ,
elements. However, it is
written in an abstract manner to provide a hook for future
specifications that want to define elements that also support being
localizable via xml:lang
.license license
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>
<name xml:lang="fr">Le Widget</name>
<name xml:lang="en">The Widget</name>
</widget>
For a use agent whose user
agent locales contains "
" en,fr,*
", ", the
matching elements would be in the following order:
<name xml:lang="en">The
xml:lang="en">The
Widget</name>
<name xml:lang="fr">Le
xml:lang="fr">Le
Widget</name>
<name>El Widget!</name>
For a use agent whose user
agent locales contains "
" en,*
", ", the
matching elements would be in the following order:
<name xml:lang="en">The
xml:lang="en">The
Widget</name>
<name>El Widget!</name>
For a use agent whose user
agent locales contains "
" jp,*
", ", the
matching elements would be in the following order:
<name>El Widget!</name>
For each element in the elements list , if the element is one of the following:
name
name
element:If this is not the first
element encountered by the user
agent, then the user
agent must ignore
this element .name name
If this is the first
element encountered by the user
agent, then the user
agent must :name name
Record that an attempt has been made by the user agent to
process a
element.name name
Let widget name be the result of applying the rule for getting text content with normalized white space to this element.
If the
attribute is used, then let
widget short name be
the result of applying the rule for getting a
single attribute value to the short short
attribute.short short
description description
element:If this is not the first
element encountered by the
user agent, then the user
agent must ignore
this element .description
description
If this is the first
element encountered by the
user agent, then the user
agent must :description
description
Record that an attempt has been made by the user agent to
process a
element.description description
let widget description be the result of applying the rule for getting text content to this element.
license license
element:If this is not the first
element encountered by the user
agent, then the user
agent must ignore
this element .license license
If this is the first
element used, then the
user agent must :license license
Record that an attempt has been made by the user agent to
process a
element.license license
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
attribute is used, then let
potential license href be the result of applying the
rule for
getting a single attribute value to the href href
attribute.href href
If potential license href is not a valid IRI or a valid
path , then the
attribute is in error and the user agent must ignore the attribute.href href
If potential license href is a valid IRI , then let widget license href be the value of potential license href .
If license href
is a valid path , then let file be the result of applying the rule for
finding a file within a widget package to license href . .
If file is not a processable file , as determined by applying the rule for identifying the media type of a file , then ignore this element .
Otherwise, let widget license
file file be the value of file . .
icon
icon
element:If the
attribute of this src src
element is absent, then the
user agent must ignore this element
.icon icon
Let path be the result of applying
the rule for
getting a single attribute value to the
attribute of this src src
element. If path is not a valid path or is an empty string, then the
user agent must ignore this element
.icon icon
Let file be the result of
applying the rule for
finding a file within a widget package to path . If
file is not a processable file , as determined by
applying the rule for
identifying the media type of a file , or already exists in the
icons icons list, then
the user agent
must ignore this
element.
Otherwise,
If the
attribute is used, then let
potential height heightheight
be the result of applying
the rule for
parsing a non-negative integer to the attribute's value. If the
potential height
is not in error and greater than 0
, then
associate the potential
height
with file .
Otherwise, the
attribute is in error and the user agent must ignore the attribute.height height
If the
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 width width0
, then associate the potential width with
file . Otherwise, the
attribute is in error and the user agent must ignore the attribute.width width
Add file and any associated potential width and/or
potential height to the list of icons . .
author author
element:If this is not the first
element encountered by the user
agent, then the user
agent must ignore
this element .author author
If this is the first
element used, then the user agent must :author author
Record that an attempt has been made by the user agent to
process a
element.author author
If the
attribute is used, then let
href-value be the value of applying the rule for getting a
single attribute value to the href href
attribute.href href
If href-value is a valid IRI
, then let author href be the
value of the
attribute. Otherwise, if
href-value is not a valid IRI ,
then ignore the href href
attribute.href href
If the
attribute is used, then let
author
email be the result of applying the rule for getting a
single attribute value to the email email
attribute.email email
Let author name be the result of applying the rule for getting text content with normalized white space to this element.
preference preference
element:If a
attribute of the value value
element is used, but the
preference
preference
attribute is absent, then this
name
name
element is in error and the user agent must ignore this element . Otherwise, the user
agent must :preference preference
Let name be the result of applying the rule for getting a
single attribute value to the
attribute.name name
If the name is an empty string, then this element is in error ; ignore this element .
If widget preferences already contains a preference whose name case-sensitively matches the value of name , then this element is in error ; ignore this element .
If name was not in error ,
let preference preference be
an empty object.
Associate name with preference .
.
Let value be the result of applying the rule for getting a
single attribute value to the
attribute.value value
Associate value with
preference . .
If a
attribute is used, then let
readonly be the result of applying the rule for getting a
single attribute value to the readonly readonly
attribute. If
readonly is not a valid
boolean value , then let the value of readonly be
the value ' readonly readonlyfalse
'.
Associate readonly with the
preference . .
Add the preference preference and
the associated
name , value and readonly
variables the list of widget
preferences . .
content content
element:If this is not the first
element encountered by the user
agent, then the user
agent must ignore
this element .content content
If this is the first
element, then the user agent must :content content
Record that an attempt has been made by the user agent to
process a
element.content content
If the
attribute of the src src
element is absent or an empty
string, then the user
agent must ignore
this element .content content
Let path be the result of applying the rule for getting a
single attribute value to the value of the src
attribute.
If path is not a valid path , then the user agent must ignore this element .
If path is a valid path , then let file be
the result of applying the rule for
finding a file within a widget package to path . If
file file is
is
or in error, then the user agent must ignore this element
.null null
If the
attribute of the type type
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 content content
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 .src src
If the
attribute is used, then let
content-encoding be the result of applying the rule for getting a
single attribute value to the value of the
encoding encodingencoding
attribute. If the character encoding
represented by the value of content-encoding is supported by the user agent, then let the
start file encoding
be the value of content-encoding . If
content-encoding is an empty string or unsupported by the user agent, then a user agent must ignore the
attribute.encoding encoding
If the
attribute is used, then let
content-type be the result of applying the rule for getting a
single attribute value to the value of the type type
attribute. If the value of content-type is a media type supported
by the user agent, then let the start file content-type be the
value of content type
type type. . If value of
content-type is invalid or
unsupported by the user agent, then a
user agent must treat the widget
package as an invalid
widget package .
If the start file encoding was set in
step 7 of this algorithm as a result of processing a valid and
supported value for the
element's content content element's
encodingencoding
attribute, then the user agent must skip this step in this algorithm. Otherwise, if the
value of content-type is a media
type supported by the user agent and
if content-type contains one or more [MIME]
components whose purpose is
to declare the character encoding of the start file (e.g., the value parameter parameter" "
text/html;charset=Windows-1252 ", ", where
charset is a parameter component whose purpose is to
declare the character encoding of the start file), then let
start file encoding
be the value of the last supported
components whose purpose is
to declare the character encoding of the start file .parameter
parameter
In the following example, the user agent would set the start file encoding to ISO-8859-1 and would ignore the charset parameter used in the type attribute.
<widget xmlns="http://www.w3.org/ns/widgets">
<content src = "start.php"
type = "text/html;charset=Windows-1252"
encoding
=
"ISO-8859-1"
"ISO-8859-1"
/>
</widget>
In the following example the user agent would set the
start file encoding
to Windows-1252
, if the user agent supports that character
encoding.
<widget xmlns="http://www.w3.org/ns/widgets">
<content src = "start.php"
type = "text/html;charset=Windows-1252"/>
</widget>
param param
element:If this param
element is not a direct child of a
element, then the user agent must ignore this feature
feature
element .param param
Note: How a param element is to be processed when it is inside a feature element is defined below.
feature feature
element:The user agent must process a feature element in the following manner:
If the
attribute of this name name
element is absent, then the
user agent must ignore this element
.feature feature
Let feature-name be the result of applying the
rule for
getting a single attribute value to the value of the
attribute.name
name
Note: This
specification allows
elements with the same
feature feature
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.name
name
If a
attribute is used, then let
required-feature be the result of applying the rule for getting a
single attribute value to the required required
attribute. If the required required
attribute is not used or if
required-feature is not a valid boolean value , then let the value
of required-feature be the value ' required requiredtrue
'.
If feature-name is not a valid IRI , and required-feature is
true
, then the user agent must treat this
widget as an invalid widget
package .
If
feature-name is not a valid IRI
, and required-feature is false
, then the
user agent must ignore this element.
If feature-name is not supported by the user agent, and
required-feature is true
, then the
user agent must treat this widget as an invalid widget package .
If feature-name is not supported by the user agent, and
required-feature is false
, then the
user agent must ignore this element
.
Associate the value of required-feature with feature-name .
If the
element contains any
feature feature
elements as direct descendants,
then, for each child param
param
element that is a direct
descendent of this param param
element, starting from the
first moving to the last in document order
:feature feature
If a
attribute is used, but the
value value
attribute is absent, then this name name
element is in
error and the user
agent must ignore
this element .param param
If a
attribute is used, but the
name namevalue
attribute is absent, then this
element is in
error and the user
agent must ignore
this element .param param
Let param-name be the result of
applying the rule for getting a
single attribute value to the
attribute. If the param-name is an empty string, then
this name name
element is in
error and the user
agent must ignore
this element .param
param
If, and only if, param-name is not in error or an empty string, then let
param-value be the result of applying the rule for getting a
single attribute value to the
attribute.value value
Associate param-name and param-value with feature-name .
Append feature-name , and any associated
required-feature , and associated parameters , to the feature list . .
If the user agent supports the element, then the user agent must process it in accordance with whatever specification defines that element (if any). Otherwise, the user agent must ignore the element.
If widget
start file of the table of configuration
defaults contains a file (i.e.
widget start file is
not
), then a
user agent must skip Step
8 and go to Step
9 .null null
If widget start file does not contain a file , the user agent must apply the algorithm to locate a default start file .
The algorithm to locate a default start file is as follows:
For each file name in the default start files table (from top to bottom) that has a media type that is supported by the user agent:
Let potential-start-file be the result of applying the rule for finding a file within a widget package to file name .
If potential-start-file is
or in
error , ignore this file name
and move onto the next file name in the default start files table .null null
If potential -start-file is a file , then:
Let widget start file be the value of potential- start-file .
Let start file content-type be the media type given in the media type column of the default start files table .
Terminate this algorithm and go to Step 9 .
If after searching for every file in the default start files table no default start file is found, then treat this widget as an invalid widget package .
This step describes how to locate the default icons .
In Step 9 , a user agent must apply the algorithm to locate the default icons .
The algorithm to locate the default icons is as follows:
For each file name in the default icons table (from top to bottom) that has a media type that is supported by the user agent:
Let potential-icon be the result of applying the rule for finding a file within a widget package to file name .
If the potential-icon is a processable file , determined by the
media type given in the media type
column of the default icons
table , and the potential-icon does not already
exist in the icons icons list of the
table of configuration
defaults , then append the value of potential-icon
to the icons icons list of the
table of configuration
defaults .
Move onto the next file name in the default icons table .
application/widget
This appendix is the MIME media type registration for
" "
application/widget
".
". This registration has been approved
by the Internet Assigned Numbers Authority ( IANA ) .
Registration with IANA was conducted in conformance with BCP 13 and W3CRegMedia .
application
widget widget
None.
None.
Widget packages are binary data and thus are encoded for MIME
transmission. As a widget package is binary, it requires encoding
on transports not capable of handling binary. The same guidelines
that apply to application/octet-stream
apply to widget
packages (see [MIME] ).
In addition to the security considerations specified for Zip files in the [Zip-MIME] registration, there are a number of security considerations that need to be taken into account when dealing with widget packages and configuration documents .
As the configuration document format is [XML] and will commonly be encoded using [Unicode] , the security considerations described in [XML-MIME] and [UTR36] apply. In addition, implementers need to impose their own implementation-specific limits on the values of otherwise unconstrained attribute types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
The configuration document allows authors, through the
element, to request permission
to enable third-party runtime components and APIs. As these
features are outside the scope of this specification, significant
caution needs to be taken when granting a widget the capability to
use a feature. Features themselves define their own security
considerations.feature
feature
support . Specifically, implementers need to consider the security implications outlined in the [CSS-MIME] specification, the [ECMAScript-MIME] specification, and the [HTML-MIME] specification.
will generally contain ECMAscript, HTML, CSS files, and other media, which are executed in a sand boxed environment. As such, implementers need to be aware of the security implications for the types theyAs widget packages can contain content that is able to simultaneously interact with the local device and a remote host, implementers need to consider the privacy implications resulting from exposing private information to a remote host. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are advised to enable user awareness of information sharing, and to provide easy access to interfaces that enable revocation of permissions.
As this specification relies on the standardized heuristics for determining the content type of files defined in the [SNIFF] specification, implementers need to consider the security considerations discussed in the [SNIFF] specification.
As this specification allows for the declaration of IRIs within
certain elements of a configuration documents, implementers need to
consider the security considerations discussed in the [IRI] specification. Implementations intending to
display IRIs and
IDNA addresses
found in the configuration
document are strongly encouraged to follow the security advice
given in [UTR36] . This could include, for
example, behaving as if the
attribute had no effect on any
IRI attributes , path attributes , and
the dir
dir
element's author
author element's
emailemail
attribute.
In addition, user agents need to be careful about trusting path components found in the widget package. Such path components might be interpreted by operating systems as pointing at security critical files outside the widget environment proper, and naive unpacking of widget packages into the file system might lead to undesirable and security relevant effects, such as overwriting of system files.
Some issues can arise with regards to character encodings of file names, the length of zip relative paths, and the use of certain strings as file names.
This specification does not put a restriction on the byte length of a Zip relative path , so a user agent should to be able to deal with Zip relative paths that have lengths longer than 250 bytes. As some operating systems have restrictions on how long a path length can be, authors need to keep the lengths of relative paths at less than 250 bytes. Unicode code points may require more than one byte to encode a character, which can result in a path whose length is less than 250 characters but whose size is greater than 250 bytes.
Authors need to be aware that, at the time of publication, there
are interoperability issues with regards to using characters
outside the safe-chars
range for file or folder names
in a Zip archive when using Zipping tools bundled with operating
systems. The interoperability issues have arisen from
non-conforming implementations of the [ZIP]
specification across operating systems: very few, if any, correctly
support encoding file names in Unicode.
In the case where the Zip relative path is encoded using [UTF-8] , the language encoding flag (EFS) needs to be set.
If an author chooses to use the utf8-chars
, they
need to thoroughly test their widgets on various platforms prior to
distribution; otherwise it is suggested that authors restrict file
and folder names to the safe-chars
(characters in the
US-ASCII range). In addition, having excessively long path names
(e.g. over 120 characters) can also result in interoperability
issues on some operating systems.
Authors need to avoid using Zip forbidden characters when naming the files used by a widget. These characters are reserved to maintain interoperability across various file systems and with [URI] s.
Authors need to avoid using the following words as either a
folder
or a file-name
in a Zip relative path as they are reserved by
some operating systems (case-insensitive): CON, PRN, AUX, NUL,
COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2,
LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, CLOCKS$. For example, the
following names are ok: "CON-tact.txt",
"printer.lpt1", "DCOM1.pdf". "CON-tact.txt", "printer.lpt1", "DCOM1.pdf".
However, "com3.txt" "Lpt1", "CoM9.gif"
"com3.txt" "Lpt1", "CoM9.gif" would not
be.
In addition, authors need to avoid having a "." "." U+002E FULL
STOP as the last character of a file or folder name as some
operating systems will remove the character when the file is
extracted from the Zip archive onto the device. Furthermore, avoid
having the space character ( SP ) at the start or
end of a file name; and take caution when using the "+" "+" U+002B PLUS
SIGN, as it might cause issues on some operating systems.
User agents that claim conformance to this specification.
50 4B 03 04
wgt
None.
Steven Pemberton, member-webapps@w3.org
Common.
None.
This section is non-normative.
This section only applies to HTML user agents [HTML] [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"><a rel="widget" href="http://example.org/exampleWidget"> The Example Widget </a>
This section is non-normative.
This table lists all elements and respective attributes, as well as child-parent relationships, that make up the language of the configuration document format defined in this specification.
Element | Description | Parent | Expected Children | Attributes | Type |
---|---|---|---|---|---|
|
The root element of a configuration document . | none. |
|
|
language |
|
keyword | ||||
|
IRI | ||||
|
version | ||||
|
numeric | ||||
|
numeric | ||||
|
Keyword list | ||||
|
language | ||||
|
The name of the widget. |
|
|
language | |
|
keyword | ||||
|
displayable-string | ||||
|
Some text that describes the purpose of the widget. |
|
|
language | |
|
keyword | ||||
|
The person or person that created the widget. |
|
|
language | |
|
keyword | ||||
|
IRI | ||||
|
string | ||||
|
The license under which the widget is distributed. |
|
|
language | |
|
keyword | ||||
|
IRI or path | ||||
|
An iconic representation of the widget. |
|
none. |
|
language |
|
keyword | ||||
|
path | ||||
|
numeric | ||||
|
numeric | ||||
|
The means to point to the |
|
none. |
|
language |
|
keyword | ||||
|
numeric | ||||
|
media type | ||||
|
keyword | ||||
|
A means to request the availability of a feature , such as an API, that would not normally be part of the default set of features provided by the user agent at runtime. |
|
|
|
language |
|
keyword | ||||
|
keyword | ||||
|
boolean | ||||
|
A means to declare a name-value pair that is made available to the widget at runtime. |
|
none. |
|
language |
|
keyword | ||||
|
keyword | ||||
|
keyword | ||||
|
boolean | ||||
|
A means of declaring a parameter that can be used with a feature . |
|
none. |
|
language |
|
keyword | ||||
|
string | ||||
|
string | ||||
|
A generic text container which is mainly used for internationalization purposes. |
|
|
language | |
|
keyword |
Huge thanks to everyone who contributed their time and sent feedback to our public mailing, particularly the i18n WG.
This specification would not exist without the contribution of the following individuals:
Aaron Boodman, Adam Barth, Addison Phillips, Alexander Dreiling,
Andrew Sledd, Andrew Welch, Arun Ranganathan, Arthur Barstow,
Bárbara 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, Tømmerholt, Hari Kumar G, Henri Sivonen, Henry
Story, Ian Hickson, Ivan Demarino, Jay Sweeney, Jean-Claude
Dufourd, Jeff Decker, Jere Käpyaho,
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, 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.
Special thanks go to Arve Bersvendsen, Robin Berjon, and Charles McCathieNevile who helped edit various versions of this specification.
A big thanks to Anne van Kesteren for being such a great supporter of this work! Also, huge thanks to the folks at Apple, specially Maciej Stachowiak, who contributed immensely to make all the widgets specs free and open!
Special thanks also to David
Håsäther Håsäther for creating and maintaining the
[Widgets-Relax NG Schema]
for the configuration document format.
Parts of this document reproduce text and behavior from the [HTML] specification and from the XBL 2.0 specification (as permitted by both specifications by their copyright statements).
Graphic icons used some examples of this specification were created by Yusuke Kamiyamane and are available for use under a Creative Commons Attribution 3.0 license .
This specification is dedicated to the children of India.