Copyright © 2008 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document defines a Zip-based packaging format, an XML-based configuration document, a processing model, as well as author requirements to help guide authors in the creation of conforming widgets. The packaging format acts as a container for files required by a widget. The configuration document is a simple XML-based language that authors can use to record metadata and configuration parameters about a widget. The processing model describes the expected behavior and means of error recovery for widget user agents while processing the packagiang format, configuration document, and other relevant resources, specifically for internationalized contexts.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This 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.
This document is produced by the Web Application Formats WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. Publication as a Working Draft 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, which is updated on a very regular basis. Please send comments to public-appformats@w3.org, the W3C's public email list for issues related to Web Application Formats. Archives of the list are available. A detailed list of changes from the previous version is also available from the W3C's CVS server.
Implementers should be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.
User agents that wish to extend this specification in any way are encouraged to discuss their extensions on a public forum, such as public-appformats so their extensions can be considered for standardization.
Widgets are a class of client-side web application for displaying and updating local or remote data, packaged in a way to allow a single download and installation on a client machine or device. Widgets typically run as stand-alone applications outside of a web browser, but it is possible to embed them into web pages. Examples range from simple clocks, stock tickers, news casters, games and weather forecasters, to complex applications that pull data from multiple sources to be "mashed-up" and presented to a user in some interesting and useful way (see [Widgets-Landscape] for more information).
For widgets, this specification defines:
The reader should be aware that this document is organized in to 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 special resources (such as icons), as well as what authors need to do to create conforming widgets (sections marked by the text "author requirement"). As such, the first half deliberately attempts not to describe aspects related to processing, which are left exclusively to the second half. The second half, which starts in section titled "Steps for Processing a Widget Resource", defines the steps required to process a widget as well as the expected behavior of a widget user agent as it processes the packaging format, the configuration document, and attempts to perform internationalization. The second half also deals with error handling in the event that a widget user agent encounters erroneous or missing resources, or erroneous DOM nodes in the configuration document. Wherever processing is relevant, sections in the first half of the document link to sections in the second half.
This specification is part the Widgets 1.0 family of specifications, which together standardize widgets as a whole. The Widgets 1.0: APIs and Events [Widgets-APIs] specification defines APIs to store preferences and capture events. The Widgets 1.0: Digital Signature [Widgets-Digsig] specification defines a means for widgets to be digitally signed using a custom profile of the XML-Signature Syntax and Processing Specification. The Widgets 1.0: Security Model [Widgets-Security] specification defines a security model that defines what a widget can or cannot do at runtime. The Widgets: 1.0: Automatic Updates [Widgets-Updates] specification defines a version control model that allows widgets to be kept up-to-date over HTTP.
The design goals and requirements for this specification are addressed in the Widgets 1.0 Requirements [Widgets-Reqs] document.
The following definitions are used globally throughout this specification. Please note that other definitions are given throughout this document and defined where they are used.
In this specification, a widget is understood to
be 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 mobile device
[Widgets-Landscape].
The space characters, for the purposes of this specification, are [Unicode] code points:
The control characters, for the purpose of this specification, are [Unicode] code points in the range U+0000 NUL to U+001F INFORMATION SEPARATOR 1, and character U+007F DELETE.
A file entry is the amalgamation of data held by a local file header, file data, and (optional) data descriptor [ZIP] for each physical file stored in a zip archive.
A widget resource is digitally signed if it
contains a file entry that conforms to the [Widgets-Digsig] specification (ie. a
conformant signature.xml file).
As well as sections marked as non-normative, all diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words must, must not, required, should, should not, recommended, may and optional in this specification are to be interpreted as described in [RFC2119].
This specification describes the conformance criteria for user agents (relevant to implementers) and various resource types (relevant to authors and authoring tool implementers).
There are three classes of products that can claim conformance to this specification:
Products that generate widget resources and/or allow authoring of configuration documents must not claim conformance to this specification, though they can claim to produce widget resources or configuration documents that themselves are conforming to this specification. Authoring tools and markup generators must generate conforming configuration documents and/or widget resources.
Products that check the conformance of widget resources or configuration documents must not claim conformance to this specification, though they can claim to verify that a widget resource or a configuration document is conforming to the relevant section(s) of this specification.
A widget user agent is a user agent that attempts to support this specification, as well as the [Widgets-APIs], [Widgets-Security], [Widgets-Digsig], and [Widgets-Updates] specifications.
A widget user agent must behave as described by this specification in order to claim conformance, even when faced with a non-conforming widget resource or a non-conforming configuration document.
In addition to this specification, a widget user agent must implement:
Note: In addition to supporting this specification, a widget user agent will typically support the following specifications.
A widget user agent is not required to implement or support any of the following aspects of the [ZIP] specification:
A valid zip archive is a byte-stream that conforms to the production of a .Zip file as defined by the Zip File Format Specification [ZIP], with the exclusion or support for the features and conditions specified below.
To conform to this specification, a zip archive must contain one or more file entries and must not be an invalid widget.
The root of the widget is the top most folder level of the Zip archive.
A folder is a file entry whose filename
field matches the production of folder in a valid zip
relative path (the last character is the file name field [ZIP] is a
U+002F SOLIDUS).
See "Step 2 -Verify the zip archive and its file entries" for instructions on how to process a zip archive.
The compression method is the compression algorithm or storage method used to store the file data of a file entry. The compression method that was used to store the file data of a file entry is identified by the numeric value derived from the compression method field [ZIP].
The valid compression methods for a file entry are:
8.0.Author requirements: File data must be compressed with either [Deflate] or stored [ZIP]. Using any other compression methods will result in an invalid widget.
The version needed to extract is a 2-byte sequence in the local file header of a file entry that indicate the minimum supported ZIP specification version needed to extract the file data [ZIP].
The value of the version
needed to extract of a file data that is stored must be 1.0
(0x100).
The value of the version needed to
extract of a file data that is compressed using [Deflate] must be 2.0
(0x200).
For the purpose of this specification, a zip relative path is the variable-length string derived from a file name field of a local file header from a file entry [ZIP].
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 (eg. images/bg.png), as opposed to storing an absolute path (eg. 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.
Author requirements: The zip relative path must be encoded as either [CP437] or
[UTF-8]. Encoding the file
name field using [UTF-8] is recommended. If the zip relative path is encoded using [UTF-8], then the general purpose bit 11 of
the local file header must be set to 1, otherwise it must be set to 0.
Author requirements: It is recommended that authors keep their path lengths below 255 characters.
Note: Having excessively long path names (eg. over 120 characters) can also result in interoperability issues on some operating systems.
A valid zip relative path is one that matches the
production of zip-rel-path in the
following [ABNF]:
zip-rel-path = [ *localized-folder ] [ *folder ] [ filename ] /
[localized-folder] [ *folder] / [ folder ]
localized-folder = Language-Tag delimiter
folder = filename delimiter
delimiter = U+002F
filename = 1*254( *basename [file-extension] )
basename = allowed-chars
file-extension = "." 1*allowed-chars
allowed-chars = cp437 / utf8-range
utf8-chars = ascii-range / U+0080 and beyond
cp437-chars = ascii-range / x80-FF;
ascii-chars = ALPHA / DIGIT / SP / "$" / "%" / "'" / "-" / "_" / "@"
/ "~" / "`" / "!" / "(" / ")" / "^" / "#" / "&" / "+"
/ "," / "." / "=" / "[" / "]"
ALPHA, DIGIT, and SP are defined in [ABNF] (but
essentially represent alphanumerical characters and the space
(0x20) character). Lanaguage-Tag is define in [RFC4646].
Note: Authors should be aware that, at the time of writing,
there are some interoperability issues with regards to using characters
outside the ascii-chars for file
an folder names in a Zip archive. If an author chooses to use cp437-chars or the UTF8-chars, they should thoroughly test
their widgets on various platforms prior to distribution; otherwise it is
suggested that authors restrict file and folder names to the ascii-chars.
Note for implementers: as this specification does not put a restriction on path length, implementers need to be prepared to deal with path lengths longer than 260 characters.
The following reserved characters must not appear
anywhere in a filename:
| Character | CP437 code points | Unicode code points |
|---|---|---|
| < | 0x3C | U+003C LESS-THAN SIGN |
| > | 0x3E | U+003E GREATER-THAN SIGN |
| : | 0x3A | U+003A COLON |
| " | 0x22 | U+0022 QUOTATION MARK |
| / | 0x2F | U+002F SOLIDUS |
| \ | 0x5C | U+005C REVERSE SOLIDUS |
| | | 0x7C | U+007C VERTICAL LINE |
| ? | 0x3F | U+003F QUESTION MARK |
| * | 0x2A | U+002A ASTERISK |
| ; | 0x3B | U+003B SEMICOLON |
Note to authors: It is recommend that authors avoid using
the following words as either a folder or a basename in a zip relative path as they
are reserved by some operating systems (case insensitive): CON, PRN, AUX,
NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2,
LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, CLOCKS$. For example, the
following names are ok: "CON-tact.txt",
"printer.lpt1", "DCOM1.pdf". However,
"com3.txt" "Lpt1", "CoM9.gif" would not be.
In addition, authors should also 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 hard drive. Authors should also avoid having the space character (SP) at the start or end of a file name. Authors should also take caution when using the "+" U+002B PLUS SIGN, as it might cause issues on some operating systems.
An invalid widget is a zip archive that is either corrupt, meaning that a CRC-32 has failed for a file entry, or meets any of the following conditions:
See Step 2 - Verify the zip archive and its file entries.
A widget resource is a byte-stream or file that is a valid zip archive.
A widget resource must contain a start file, and may contain a configuration document, one or more icons, and additional resources located either at the root of the archive or in sub-folders. In addition, a widget resource may be digitally signed.
The start file of a widget resource is the
resource that is used when the widget is instantiated. When a start file
is not explicitly declared via the content element or the content element's src attribute was in
error, the start file must be one of the default start files.
Authoring requirement: Authors must include at least one start file in a widget resource.
See "Step 1 - Acquire a Widget Resource Over HTTP or Local Storage" for instructions on how to process a widget resource.
A default start file is a start file that a widget user agent must attempt to locate when a the configuration
default's start file is
null.
Note: A widget user agent will attempt to locate a default
start file in a situation where by the content element is missing or the content element's src attribute was in
error.
The filename and MIME type each default start files is given by the
following table. The filenames should be considered case insensitive. A
widget user agent is only required to support the
text/html MIME type; support of other MIME types is optional.
| filename (case insensitive) | MIME type | Specification | support |
|---|---|---|---|
| index.html | text/html | [HTML] | required |
| index.htm | text/html | [HTML] | required |
See step X for instructions of how to find the default start file.
An icon is a resource that is used to represent the widget in various application contexts (eg. the icon that the user double-clicks to instantiate a widget, or an icon in a dock or task bar).
A default icon is an icon whose filename
case-insensitively matches a filename given in the first column of the default icons table below and whose MIME type matches
the MIME type given in the second column of the table. The default icon
must be located either at the root
of the widget or in a localized folder. A
widget user agent is required to support the
image/png and image/gif MIME types; support of
other MIME types is optional.
| filename | MIME type | Specification | Support |
|---|---|---|---|
| icon.png | image/png | [PNG] | required |
| icon.gif | image/gif | [GIF98][GIF87] | required |
| icon.svg | image/svg+xml | [SVG] | optional |
See Step X for rules for selecting a default icons in the presence of multiple default icons.
Note: If SVG is supported, a widget user agent will prioritize icon.svg.
A thumbnail is an image resource inside the
widget archive that represents the widget in a running state. The filename
of the thumbnail case-insensitively matches a filename given in the first
column of the default thumbnails table below and
whose MIME type matches the MIME type given in the second column of the
table. The thumbnail must be located either at the root of the widget or in a localized folder. A widget user agent is required to support the image/png and
image/gif MIME types; support of other MIME types is optional.
| filename | MIME type | Specification | Support |
|---|---|---|---|
| thumbnail.png | image/png | [PNG] | required |
| thumbnail.gif | image/gif | [GIF98][GIF87] | required |
Author requirement: it is recommended that authors use a screenshot of their widget in it's running state as the thumbnail.
See Step X for rules for selecting a thumbnail in the presence of multiple thumbnails.
The system locale is the end-user's preferred regional and language settings derived from the operating system or widget user agent (eg. Australia, Australian English).
A localized widget is a widget resource that contains one or more localized folders.
A localized folder is a file entry whose file
name field is a localized-folder that, after the
trailing U+002F SOLIDUS has been removed, matches a valid
language-tag as defined in [RFC4646] (eg.
en-gb). A widget resource may contain
zero or more localized folders. Localized folders may
contain zero or more sub-folders or resources.
Authoring requirements: Authors should avoid including empty localized folders in a widget resource.
A localized resource is a resource that may have had some aspect localized for use in an internationalized context (eg. a HTML document written in Japanese) and has been placed inside a localized folder. A widget resource may contain zero or more localized resources. All resources, except a digital signature, can be localized.
Author requirement: Authors can localize a widget by placing resources inside folders that follow the language-tag conventions set forth in [RFC4646]. Localized folders must be at the root of the widget of the widget resource (a localized folder not at the root of the widget (ie. a folder inside another folder) will be treated as a normal file entry). When an author follows these naming conventions, the widget user agent will automatically select the appropriate localized version of a widget's resources based on locale information derived from the operating environment. At runtime, the widget user agent will set the base URI of the start file to the localized folder (even if the start file does not reside inside the localized folder). Localizing a widget resource is optional and authors should always provide a start file at the root of the widget.
See "Step X " for the steps required to process a localized widget.
Author requirement: An author may localize an icon or thumbnail by placing the resource in a localized folder.
This section is informative.
Example of a localized widget with multiple localized icons, start files and configuration documents. All localized instance rely on the same un-localized script (engine.js):
/en-au/cats.html
<!doctype html>
<h1>G'day! LOL Cats!</h1>
<script src="/scripts/engine.js">
...
/es/gatos.html
<!doctype html>
<h1>Gatos Graciosos!</h1>
<script src="/scripts/engine.js">
...
The widget MIME Type is
application/widget.
Author requirement: Over the wire
(eg. over HTTP), a widget resource must be labeled
with an application/widget MIME type.
Note: Widget user agents can support other legacy/proprietary widget types, but they must remain conforming to this specification when dealing with widget resources.
The application/widget MIME type has not yet
been registered with IANA. This will happen when the specification reaches
Candidate Recommendation status.
The file extension .wgt is required for
a widget resource on systems where it is customary for file names to
include an extension that symbolizes the MIME type.
A valid file extension is the string
.wgt any case form.
Author requirement: It is recommended that a widget resource is served over HTTP
with the .wgt file extension in lowercase form.
A configuration document is an [XML] document that has a widget element at its root.
A config.xml file is the XML serialization of a
configuration document.
A valid configuration document file name is
config.xml, in any case form.
Author requirement: Configuration
documents can be placed at either the root of the
widget or in localized folders. Placing a
configuration document anywhere else within the widget resource will cause
the widget user agent to treat is as an arbritrary resource. Authors should only place configuration documents in localized
folders if the content of the configuration document has been localized.
It is recommended that authors always include a
configuration document at the root of the widget and that the
config.xml filename be in lowercase form regardless of where
it is stored within the widget resource.
The following is an example of a config.xml document:
<widget xmlns="http://www.w3.org/ns/widgets"
id="http://datadriven.com.au/exampleWidget"
version="2.0 Beta"
height="200"
width="200">
<name>The example widget!</name>
<update uri="http://www.bla.com/update.php"/>
<description>
A sample widget to demonstrate some of the possibilities.
</description>
<author url="http://foo-bar.example.org/"
email="foo-bar@example.org">Foo Bar Corporation</author>
<icon src="icons/example.png" />
<content src="index.html"/>
<access network="true"/>
<license>
Example license (based on MIT License)
Copyright (c) 2008 The Foo Bar Corp.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
</license>
</widget>
Note: Widget user agents are encouraged to expose relevant information provided by configuration document to the user. Having "visual metadata" encourages authors to make full use of the configuration document format.
See "Step 7 - Process the configuration document" for instructions on how to process a configuration document.
The configuration document namespace is
http://www.w3.org/ns/widgets [XMLNS].
Author requirements: Authors must
assign the configuration document namespace to the widget element. Authors should be aware that if
the namespace is missing, then then widget is an invalid widget and will be treated as such.
Vendors wishing to extend the configuration document format with their own XML elements and attributes (or those defined in other specifications) may do so by using a separate namespace [XMLNS]. This specification does not define a model for processing XML elements outside the configuration document namespace. For the sake of interoperability, extensions to the configuration document are not recommended.
Example of extending the configuration document format:
<widgets xmlns="http://www.w3.org/ns/widgets"
xmlns:ex="http://widgextension.org/">
<icon src="screenshot.png" ex:role="screenshot"/>
<icon src="big.png" ex:role="big"/>
<ex:datasource>{a:"b",c:"d"}</ex:datasource>
<content src="widget.html"/>
</widgets>
A valid non-negative float is a string that consists of one or more characters in the range U+0030 (0) to U+0039 (9) followed by a single U+002E FULL STOP (".") character and one or more characters in the range U+0030 (0) to U+0039 (9). (eg. 1.0, 243.23, 23.006).
A valid non-negative integer is a string that consists of one of more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). (eg. 2, 323, 23214).
A valid version-tag is a string that matches the
production for valid-version-tag in the following [ABNF]:
valid-version-tag = version-identifier*('.'version-identifier)
version-identifier = string
Version 1.0 Beta, 1.0 RC1,
1.0-Build1580, Happydog 5.1.2100Note: For the purpose of this specification, version tags have no significant semantics; they are just treated as arbitrary strings (eg. '1.0' is not greater than '2.0', but is simply different). This may change in future versions of this specification.
true
or false. The default behavior, which is used when the
attribute is omitted or has a value other than the two allowed values, is
false. Rules for exactly how a boolean attribute are to be
treated is given when the term is used.valid-MIME-type in the following ABNF:
valid-MIME-type = type "/" subtype *(";" parameter)
The type , subtype, and
parameter tokens are defined in [RFC2045].
path token of [RFC3986]. A path can be either absolute, maning that it is already resolved to the
root of the widget (eg. "/images/bg.png") or relative, meaning that it is resolved relative to the
location of the configuration document within the widget resource.widget ElementThe widget serves as a container for
the other elements; as such, it must be used.
name: zero or onedescription: zero or oneicon: zero or moreaccess: zero or oneauthor: zero or onelicense: zero or onecontent: zero or oneupdate: zero or oneidversionheight0 that controls the
initial height dimensions of the widget in CSS
pixels [CSS21]. When the value is missing, the
widget user agent will assume the value 300.width0 that controls the
initial width dimensions of the widget in CSS
pixels [CSS21]. When the value is missing, the
widget user agent will assume the value 150.modeNote: The width and
height attributes are only relevant to
widgets with a visual output.
name ElementThe name element represent the
human-readable name for a widget resource that can be used, for example,
in an application menu or in other contexts.
widget element.description ElementThe description element
represents a human-readable description of the widget.
widget element.author ElementAn author element represents a
person or an organization involved in the creation of the widget.
widget element.urlemailimglicense ElementThe license element represents an
end-user license agreement or a copyright statement.
widget element.icon ElementThe icon element represents an icon
for the widget. A widget user agent should expose an
icon in a way that it is visible to the end user.
widget element.srcwidth0 that represents the
width of the icon in CSS
pixels [CSS21]. If the resource pointed to by
the src is a supported raster graphic,
this value is ignored by the widget user agent. If the resource pointed
to by the src is a vector
graphic format, then this value will be used. This attribute is
only applicable to vector graphic formats.height0 that represents the
height of the icon in CSS
pixels [CSS21]. If the resource pointed to by
the src is a supported raster graphic,
this value is ignored by the widget user agent. If the resource pointed
to by the src is a vector graphic
format, then this value will be used. This attribute is only applicable
to vector graphic formats. Author requirement: Authors must not not use the width and height attributes for raster graphic formats
(as the values will be ignored).
access ElementThe access element indicates, through
its attributes, what kind of security permissions afforded to the widget
by the widget user agent. When the access element is absent, a widget user agent
must deny access to networked resources and to
plugins.
widget element.networkpluginsfilesNote: Widget user agents are not required to support, or otherwise implement, proprietary plugins.
Author requirements: If the access element is used, at least one of its
attributes must be used.
content ElementThe content element is used by an
author to declare which resource the widget user agent will use when it
instantiates the widget.
widget element.srctypesrc attribute. When the value is missing,
the widget user agent will assume the value text/html.update ElementThe update element point to a URI
where the widget user agent can check for the availability of a either a
update description or a widget resource.
widget element.urlAuthor requirements: If the access element is used, a full URI must be given.
requires ElementThe requires element is used by an
author to denote that, at runtime, a widget may require access to a
resource that is not part of the standard functionality provided by the Widgets 1.0 family of specifications. For example, it
can be used to denote that a widget requires access to a particular API
(eg. "urn:com.example.GPSApi" or
"http://datadriven.com.au/APIs/contacts"). When a requires
element is nested inside another element, it denotes a fallback
relationship, meaning that if the resource identified by the outtermost
element is unavailable, then the widget user agent will check for the
avilability of the resource identified by the child's element's uri attribute.
Note: the requires element is not a means to import javascript libraries or other resources available on the Web. The requires elements should be viewed as a standardized way to identify a required resource via an URI.
access element.uriAuthor requirements: If the requires element is used, a valid URI must be given.
The widget addressing scheme is used internally by the widget engine.
widget://[uuid]/index.html
The steps for processing a widget resource involve X steps that a widget user agent must follow in sequential order, responding accordingly if any of the steps result in an error. The procedures for what to do when an error is encountered are described in each section.
Note: the following steps and associated parsing rules are written with more concern for clarity than over efficiency. As such, user agents may optimize any of the steps (or may perform them in a different order) and parsing rules, so long as the end result is indistinguishable from the result that would be obtained by the following the specification.
In the event that a widget user agent encounters an invalid widget during the steps for processing a widget resource, the widget user agent must abort any processing and should inform the end-user with an appropriate localized error dialog (see example in the note below). The wording of appropriate localized error dialogs are left to the discretion of implementers, but their presence is nonetheless recommended.
Note: An example of an appropriate error message would be "Can't install this widget because it was created using an unsupported compression method."
When processing a widget, a widget user agent will decompress (or otherwise extract) the file data of file entry into its decompressed or unstored representation. To extract a file entry:
8, use the result of applying the [Deflate] algorithm to the file data field.
Otherwise, use the value of the file data field (see [ZIP] for full details on how to extract a file entry).Note: A widget user agent does not need to extract all the file entries in a zip archive at the same time. It may choose to only extract specific file entries as they are needed for processing.
Note: As a security precaution, implementations are discouraged from extracting file entries from untrusted widgets directly onto the file system. Instead, implementations should consider a virtual file system or mapping to access file entries inside a zip archive.
A widget user agent may acquire a widget resource over HTTP or from local storage (eg. from the user's hard drive).
If attempting to acquire a widget resource over HTTP, a widget user
agent must only attempt to process resources whose
Content-Type is application/widget (regardless
of the file extension).
Unless supporting a legacy or proprietary MIME type, all other
Content-type values are in error and the widget user agent
must treat the resource as an invalid widget.
When acquiring a widget resource from local storage, a widget user agent must process a resource regardless of the file extension (including situations when there is no file extension).
The widget user agent must verify the zip archive and its file entries.
In this example, the Content-Type is in error, so the
widget engine would not attempt to process the following
widget:
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
To verify that a zip archive and its file entries conform to this specification (and hence can be treated as a widget resource), a widget user agent must perform the following checks on a zip archive.
If any of these checks are true (indicating that a condition is met), then the zip archive is an invalid widget:
Next, for each file entry in the zip archive, the widget user agent must perform the the following checks. If any of these checks return true (indicating that a condition is met), then the zip archive is an invalid widget. For each file entry in the zip archive, check the following data from the local file header:
20 (meaning the archive is using a feature
unsupported by this specification, such as Zip64).0 or 8).null or is not an empty string or does not exactly match
"UTF8".Only once the above checks have been completed, a widget user agent must set the configuration defaults.
Widget user agents must assume the following configuration defaults:
| Variable | Type | default value | description |
|---|---|---|---|
| widget id | DOMString | null |
The identifier, corresponding to the widget element's id attribute in the
configuration document. |
| widget version | DOMString | null |
The widget's version, corresponding to the widget element's version attribute in the
configuration document. |
| widget name | DOMString | null |
The widget's name, corresponding to the name element in the configuration document. |
| widget width | integer | 100 |
The widget's width, corresponding to the
widget element's width
attribute in the configuration document. |
| widget height | integer | 100 |
The widget's height, corresponding to the
widget element's height
attribute in the configuration document. |
| allow plugins | boolean | false |
If the widget will be able to use plugins at runtime. |
| allow network | boolean | false |
If the widget will be able to access networked resources at runtime. |
| author name | DOMString | null |
The name of the author that created the widget, corresponding to the
content of the author element. |
| author email | DOMString | null |
The email of the author that created the widget, corresponding to
the author element's email attribute. |
| author url | URI | null |
The URL associated with the author that created the widget,
corresponding to the author
element's url attribute. |
| Start file | URI | null |
The start file for the widget, corresponding to either one of the default start files or the content element's src attribute. |
| content-type | DOMString | text/html |
The MIME type of the start file, corresponding to either one of the
default start files or the content element's type attribute. |
| widget locale | The system locale as an Language-Tag [RFC4646] (eg. en-us) |
||
| config file | DOMString | null |
The absolute URI to the configuration document for the widget. |
| icons | List | empty list | The icons of the widget as they correspond to the default icons and
to any occurrence of any correct icon element in the widget archive. |
| signed | DOMString | false |
If the widget contains a valid digital signature. Will only be set
to true if the signature is valid. |
| base URI | URI | null |
The absolute URI to the appropriate localized folder. |
| mode | DOMString | default |
|
Once the above configuration defaults have been set, a widget user agent must attempt to locate the digital signature.
The steps to locate the digital signature are as follows:
null.signature.xml' then:
null (meaning that no
signature was found), the go to "Step 7 - Locate the configuration
document".With the signature derived from Step 4, apply the Procedure
for Verifying a Digital Signature in the [Widgets-Digsig] specification. If the digital
signature is valid and verified, set signed to true.
Otherwise, treat this widget resource as an invalid
widget.
Before searching for the configuration document or the start file, the
widget user agent must check for the existence of file
entries in localized folders that suitably
matches the widget locale.
The steps for locating the base URI as follows:
null terminate this algorithm and attempt to locate the configuration document.null, search
the file entries whose file name
field begins with the concatenation of the potential
locale and a delimiter (eg.
en-us/).
en-us becomes
en) and repeat step 2 of the parent algorithm (ie. search
the file entries again for the new potential locale). (see section
4.3.2. Truncation of Language Tags in RFC)The configuration document, if it exists, must be located at either the root of the widget of a widget resource or in a localized folder.
The steps to locate the configuration document are as follows:
en-us/config.xml). If a match is made, set config
doc to be the filename field of the matching file entry.config.xml. If a
match is made, set config doc to be the filename
field.The config.xml file must be processed
as described in the following sub-sections. The purpose of processing the
configuration document is to override the configuration defaults (which are used during
instantiation (step X) and at runtime [Widgets-security]).
The main algorithm for processing a configuration document is given by the rules for processing a configuration document. However, that algorithm makes use of four additional processing rules:
The rules for processing a configuration document are given in the following algorithm.
In this section, the term in error is typically used to mean that an element or attribute in a configuration document is not conforming according to the rules of this specification. Rules for exactly how the an element or attribute are to be treated when it is in error is always given when the term is used. Typically the specification will say that the erroneous DOM nodes must be ignored, meaning the widget user agent will act as if erroneous nodes were absent.
A correct resource is a resource that has been verified as residing inside a widget resource and MIME type that is supported by the widget user agent.
An element or an attribute is correct if it is not in error.
A supported MIME Type is one that a widget
user agent is able to process or otherwise render. For icons, a widget user agent must apply rules for identifying the
content type of an image to acquire its MIME type and verify that it
is supported. For start files, a widget user agent must apply rules for identifying the
content type of a start file to acquire its MIME type and verify
that it is supported.
The term text node refers to any
Text node, including CDATASection nodes (any
Node with node type 3 or 4) as
defined in [DOM3Core].
config.xml as
a [DOM3Core] Document using a [XMLNS]-aware parser. If the document is not
well-formed [XML], then the widget resource is an invalid widget. (Although a document must be
well-formed, it does not necessarily need to be valid [XML]).documentElement of
doc.widget element, then treat this widget
resource as an invalid widget.widget element:If this element is not in the configuration document namespace, then treat this widget resource as an invalid widget.
For the widget element, if the height attribute is used, apply the rules for parsing a non-negative integer to its
value. If the value is not in error and
greater than 0, let widget
height be the value of the height attribute.
If the width attribute is used,
apply the rules for parsing a non-negative
integer to its value. If the value is not in
error and greater than 0, let widget width be the value of the width attribute.
If the id attribute is used, and it
is a valid uri, then let widget id be the value of the id attribute.
If the version attribute is
used, and it is a valid version-tag, then let
widget id be the value of the
id attribute.
name elementIf this is the first name element
encountered, then let widget name be
the result of applying the rules for getting text
content to this element.
description elementIf this is not the first description element, then the element
is in error and must be ignored.
If this is the first description element encountered, then
let widget description be the result of applying the rules for getting text content to this element.
author elementIf this is not the first author
element, then the element is in error and must be ignored.
If this is the first author
element encountered, then let widget author be the result
of applying the rules for getting text content
to this element.
If the url attribute is used, and
it is a valid uri, then let author url be the value of the url attribute.
If the email attribute is used,
then let author email be the value
of the email attribute.
license elementIf this is not the first license
element, then the element is in error and must be ignored. PRESERVE
WHITESPACE.
If this is the first license
element used, then let widget license be the result of
applying the rules for getting text content to
this element.
icon elementICONS SRC NEEDS TO BE RESOLVED AS A FULL URI. IF ITS NOT AN ABSOLUTE URI, THEN RESOLVE THE RELATIVE URI RELATIVE TO THE LOCATION OF THE LOCALIZATION FOLDER OR CONFIG.XML).
If it has a src attribute that is a
valid path that points to a correct resource and is not null when
the rules for identifying the content type of an
image are applied to it, then add the value of the src attribute to the list of icons
[/icons/myicon.png, images/bla.gif, etc]. If the src attribute is missing, then the element is
in error and must be ignored.
If the resource identified by the src attribute is missing, or corrupt, or in an
unsupported MIME type, then this element is in error and must be ignored.
content elementNEED TO RESOLVE SRC ATTRIBUTE TO FULL URI (BASED ON THE LOCATION OF THE COFIG DOC).
If this is not the first content
element, then the element is in error and must be ignored.
If this is the first content
element and it has a src attribute
that is a valid path, then let the start file be the value of the src attribute. If the src attribute is missing, or in error, then a widget user agent must treat the widget resource as an invalid widget.
If the type attribute was used, and
is a valid MIME type that is supported, then let the content-type
be the value of the type attribute.
If the MIME type is invalid, or unsupported by the widget user agent,
then a widget user agent must treat the widget
resource as an invalid widget.
access elementIf this is not the first access
element, then the element is in error and must be ignored.
If network attribute was used,
and it is a valid boolean value, then let
allow network be the value of the network attribute.
If plugins attribute was used,
and it is a valid boolean value, then let
allow plugins be the value of the plugins attribute.
Comment node, or a ProcessingInstruction
node, or a Text node that only contains space characters, or a CDATASection node
that only contains space characters, or anything
else:The rules for getting text content are as given in the following algorithm. The algorithm always returns a string, which may be empty.
Text nodes that only contain space characters, or CDATASection nodes
that only contain space characters, let
result be the concatenation the input's text nodes, in document
order, as a string:
Generally speaking, the processing model described in this section
involves walking through an element's children and concatenating all the
Text and CDATASection nodes into a single
string. This is functionally equivalent to invoking the getTextContent()
DOM3 Java interface on an element (part of the Node
interface), but with the any CR and LF characters removed. Subsequent
instances of a correct element will be ignored.
For example, the author and
blink elements would be ignored, but their Text
nodes would be extracted. The resulting widget
name would be "The Awesome Super Dude
Widget" (the second name
element is ignored):
<widget xmlns="http://www.w3.org/ns/widgets">
<name>
The <blink>Awesome</blink>
<author email="dude@example.com">Super <blink>Dude</blink></author>
Widget</name>
<name>This element will be ignored</name>
<content src="main.html"/>
</widget>
The rules for parsing a non-negative integer are as given in the following algorithm. When invoked, the steps must be followed in the order given, aborting at the first step that returns a value. This algorithm will either return zero, a positive integer, or an error. Leading spaces are ignored. Trailing spaces and any trailing garbage characters are ignored.
0.0, return
an error.0) ..
U+0039 (9), then return an error.0) .. U+0039
(9):
The rules for removing whitespace are as given in the following algorithm. As with the previous algorithms, when this one is invoked, the steps must be followed in the order given, aborting at the first step that returns a value. This algorithm returns a string with all space characters removed.
The rules for identifying the content type of an image are given by the following algorithm. Widget user agents are required to support the MIME types given in the table below.
null.| Bytes in Hexadecimal | MIME type | Comment | Defined by |
|---|---|---|---|
| 47 49 46 38 37 61 | image/gif | The string "GIF87a", a GIF
signature. |
[GIF87] |
| 47 49 46 38 39 61 | image/gif | The string "GIF89a", a GIF
signature. |
[GIF89] |
| 89 50 4E 47 0D 0A 1A 0A | image/png | The PNG signature. | [PNG] |
CHECK CHARACTER ENCODING, (UTF-X BOM PATTERN). FOR SVG, PARSE AND CHECK FOR THE SVG NAMESPACE.
The rules for identifying the content type of a start file are given by [HTML5]'s section on "Determining the type of a new resource in a browsing context".
If the start file is null, then try to find
one of the default start files in the base URI. If none is found, attempt
to find a default start file at the root of the
widget. If none is found then treat this widget resource as invalid widget.
If the start file is not null, check that it
is a correct resource and that it is a supported MIME Type
NEED TO DEFINE PREFERRED MATCHING ORDER.
Search for default icons that reside in the base URI. If any are found, add them to the icons list. If none are found, try to find default icons at the root of the widget.
If SVG is supported, then locate SVG first.
Note: Not sure how SVG is going to work as an icon format in regards to interactivity (eg. input events, javascript animation, network connections, etc). Send us feedback.
If a widget contains a localized folder that matches the widget locale, and the MIME type the
content-type is text/html, then widget user agent
must set the HTML base of the start file to the absolute URI the localized
folder.
If a widget contains a localized folder that matches the widget locale, and the MIME type the
content-type ends with +xml,
then widget user agent must set the [XML Base] of the
start file to the absolute URI the
localized folder.
To be written... this should be deferred to the security spec. I think we need a "core spec" that brings everything together.
A rendering context is a visual context on which graphical objects are rendered.
From the list of icons, select the icon that most closely fits the visual dimensions of the rendering context in CSS pixels. If the dimensions of the rendering context change, then the a widget user agent should attempt to find an icon from the list of icons that more accurately fits the new dimensions of the display context. Widget user agents may proportionally scale icons to fit the dimensions of a display context in which the icon is to be displayed. Widget user agents must not distort icons to fit a rendering context by proportionally scaling the icon.
HAVE A LOOK AT PRESERVING ASPECT RATIO IN SVG.
Search for default thumbnail that reside in the base URI. If any are found, add them to the icons list. If none are found, try to find default icons at the root of the widget.
This section is informative.
This section only applies to HTML user agents [HTML4] [XHTML].
Auto-discovery enables a user agent to identify and install a widget resource that is associated with an HTML page. When a page points to a widget resource, user agents should expose the presence of the widget resource 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 resource. In HTML, it may
be specified for the a, area
and link elements to create a hyperlink.
For example:
<a rel="widget" href="http://widgets.example.org/exampleWidget">The Example Widget</a>
This section is informative.
The following RelaxNG schema is a representation of the elements and attributes of the configuration document. Products that check the conformance of widget resources or configuration documents can use this schema to validate configurations documents.
# Widgets 1.0 (Working Draft) RELAX NG schema
default namespace = "http://www.w3.org/ns/widgets"
namespace xsd = "http://www.w3.org/2001/XMLSchema-datatypes"
xmllang.att = attribute xml:lang { xsd:language }
start = widget
widget = element widget {
xmllang.att?,
attribute id { text }?,
attribute version { text }?,
attribute height { xsd:string { pattern="[1-9]\d*" } }?,
attribute width { xsd:string { pattern="[1-9]\d*" } }?,
( name? &
description? &
icon* &
access? &
author? &
license? &
content? )
}
name = element name {
xmllang.att?,
text
}
description = element description {
xmllang.att?,
text
}
icon = element icon {
attribute src { xsd:anyURI },
empty
}
access = element access {
( attribute network { "true" | "false" } |
attribute plugins { "true" | "false" } |
( attribute network { "true" | "false" },
attribute plugins { "true" | "false" } ) ),
empty
}
author = element author {
xmllang.att?,
attribute url { xsd:anyURI }?,
attribute email { xsd:string { pattern=".*@.*" } }?,
text
}
license = element license {
xmllang.att?,
text
}
content = element content {
attribute src { xsd:anyURI | xsd:string { pattern="index\.(html|htm|xhtml|xht|xml|svg)" } },
attribute type { text }?,
empty
}
Special thanks go to Arve Bersvendsen, Anne van Kesteren and Charles McCathieNevile who helped edit the initial version of this specification. Special thanks also to David Håsäther for creating and maintaining the RelaxNG Schema for the configuration document.
Parts of this document reproduce text and behavior from the HTML5 specification and from the XBL 2.0 specification (as permitted by both specifications by their copyright).
Graphic icons used some examples of this specification were created by Yusuke Kamiyamane and are available for use under a Creative Commons Attribution 3.0 license.
The editor would also like to thank the following people for their contributions to this specification:
This section will be completed as the document matures.