Copyright © 2008 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document standardizes a Zip-based packaging format, an XML-based configuration document format and a series of steps that user agents follow when processing and verifying various aspects of widgets.The packaging format acts as a container for files used by a widget. The configuration document is an XML vocabulary that authors can use to declare metadata and configuration parameters for a widget. The steps for processing a widget resource describe the expected behavior and means of error handling for widget user agents while processing the packaging format, configuration document, and other relevant files. This document also defines conformance criteria and expected behavior for conformance checkers, which are tools that aid authors in verifying that Zip archives and configuration documents conform to this specification.
This document is part of the Widgets 1.0 Family of Specifications, which together standardize widgets.
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 is the 22 December 2008 Last Call Working Draft version of the "Widgets 1.0: Packaging and Configuration" specification. The Last Call period ends on 31 January 2009. This version reflects over of two years work addressing requirements 1 to 23 of the Widgets 1.0: Requirements document [Widgets-Reqs]. The requirements were addressed and specified through extensive research, and via consultation with W3C members and the public via the Working Group's mailing lists (WAF archive, WebApps archive). The purpose of this Last Call is to give external interested parties a final opportunity to publicly comment on how widgets should be packaged and configured before the Working Group makes a call for implementations. The Working Group's goal is to make sure that vendor's requirements for packaging and configuration have been effectively addressed and clearly specified.
This document is produced by the Web Applications 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. The public is encouraged to send comments to the Web Apps Working Group's public mailing list public-Webapps@w3.org (archive). See W3C mailing list and archive usage guidelines. A detailed list of changes from the previous version is also available from the W3C's CVS server.
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-Webapps so their extensions can be considered for standardization.
widget
Elementname
Elementdescription
Elementauthor
Elementlicense
Elementicon
Elementaccess
Elementcontent
Elementupdate
Elementfeature
Element<its:span>
Widgets are full-fledged client-side applications that are authored using Web standards. They are typically downloaded and installed on a client machine or device where they typically run as stand-alone applications outside of a Web browser. Examples range from simple clocks, stock tickers, news casters, games and weather forecasters, to complex applications that pull data from multiple sources to be "mashed-up" and presented to a user in some interesting and useful way (see [Widgets-Landscape] for more information). The runtime environment in which a widget runs is referred to as a widget user agent.
This section is non-normative.
The editor of this specification responds rapidly to all feedback and continuously makes corrections to this document. So, unless you are reading this document on the date of publication, it is extremely likely that this document has been superseded. Instead of reviewing this published draft, please review the latest editor's draft and make sure you cite the date of that draft in the feedback you send to the Web Apps Working Group's public mailing list public-Webapps@w3.org.
Please also be sure to check the mailing list archive to see if any issue you uncover has already been addressed. To help with cataloguing issues, prefix emails to the mailing list with the string [widgets]. Any and all feedback is welcomed.
This section is non-normative.
The design goals and requirements for this specification are addressed in the Widgets 1.0 Requirements [Widgets-Reqs] document. This document addresses the following requirements:
name
, description
, and
license
element.author
element.license
element.width
and height
attributes.content
element.icon
element and the default icons.access
element.feature
element.This section is non-normative.
The reader should be aware that this document is organized into two halves, but not explicitly marked as such. The first half defines the various aspects of what constitutes the packaging format, the configuration document, and reserved files, such as default icons and localized folders, as well as some of the expected behavior of conformance checkers, which are implementations that check the conformance of a Zip archive or a configuration document to this specification. Where possible, the first half avoids describing too many aspects related to processing, which are described in more detail in the second half of the document.
The second half, which starts in the 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 of this document also deals with error handling in the event that a widget user agent encounters unsupported or missing files, or erroneous [DOM3Core] nodes 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 specification should be read like all other specifications. First, it should be read cover-to-cover; multiple times. Then, it should be read backwards at least once. Then it should be read by picking random sections from the contents list and following all the cross-references.
This section is non-normative.
This specification is part of 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 following definitions are used globally throughout this specification. Please note that other terms are given throughout this document and defined where they are used.
An author is a person who creates a widget resource or an authoring tool that generates widget resources.
The [Widgets-Landscape] defines a widget 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 mobile device
.
Because widgets are packaged, they can be liberally shared by users without relying on
[HTTP] (i.e., users can share widgets over Bluetooth or through other
distribution channels).
Reserved means that a character, or text string, or a file that is
identified by a particular file-name
, has a specified purpose and meaning
in this specification or in some other specification or system. The reason why something is
reserved and how it must or must not be used is given when the term is used.
A character, or text string, or a file is arbitrary if it is not reserved.
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.
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 four 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 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 can claim conformance to this specification. They can also 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 implement 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.
Note: Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the [Widgets-Test-Suite]. Note, however, that passing all the tests in the test suite does not imply conformance to this specification; It only implies that the implementation conforms to aspects tested by the test suite.
This specification relies on several other specifications, some of which are file formats.
A specification is said to be supported by a widget user agent if the widget user agent attempts to implement that specification. In addition, a widget user agent is said to support a particular file format if it is able to process or render that file format.
In addition to this specification, a widget user agent must support the following specifications and file formats:
A widget user agent may also support the following file formats as icons:
To facilitate content localization in configuration documents, a widget
user agent should support the Internationalized Tag Set's
([ITS]) its:span
element and the its:dir
attribute. Support of other ITS elements and attributes is not
required.
Although this specification specifies the elements of the configuration document in
which <its:span>
and the its:dir
attribute can be used
(below), it does not define how they are to be interpreted and processed by a widget user
agent. If a widget user agent implements <its:span>
and
its:dir
, then the widget user agent must do so in
conformance to the processing rules defined by the ITS specification.
A widget user agent is not required to implement or support any of the following aspects of the [ZIP] specification:
A conformance checker (CC) is a user agent that verifies that a widget resource or a configuration document conforms to this specification.This specification defines the expected behavior of conformance checkers in sections marked as conformance checker behavior throughout this document.
This specification asks CCs to inform authors of conformance violations, which means they should display messages to authors in a human readable manner that would assist them in correcting problems. Wording of messages is left to the discretion of implementers.
A widget user agent may behave as a conformance checker.
The files of a widget are packaged using the [ZIP] file format (in other words, Zip is the packaging format for widgets).
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 potential Zip archive is a data object that has not been verified to be a valid Zip archive.
A valid Zip archive is a data object 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 defined in the Zip Support section. Step 2 of the Steps for Processing a Widget Resource describes how widget user agents verify that a Zip archive conforms to this specification.
The magic numbers for a Zip archive is the byte sequence: 50 4B 03 04
.
To conform to this specification, a Zip archive must contain one or more file entries and must not be an invalid widget.
The compression method is the compression algorithm or storage method used to encode the file data of a file entry. The compression method that is used to 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, as indicated by the compression method field, for a file entry are:
8
0
Author requirements: File data must be compressed with either [Deflate] or stored (no compression). Of the valid compression methods, [Deflate] is the recommended compression method. Using any other compression methods will result in an invalid widget.
A conformance checker must check that each file entry uses one of the valid compression methods. If a CC encounters a file entry that uses the Stored compression method, then it should inform the author that file entry should be recompressed with [Deflate]. If a CC encounters a compression method that is not a valid compression method, it must inform the author that the resource as an invalid widget.
The version needed to extract is the 2-byte sequence in the local file header of a file entry that indicates the minimum version supported version of the [ZIP] specification needed to extract the file data.
The valid versions needed to extract values are as follows. Each value is assigned one or more meanings by the [Zip] specification:
0x100
(equivalent to 1.0)0x200
(equivalent to 2.0)Note: If the Zip archive has been encrypted using traditional PKWARE encryption, then it will be treated as an invalid widget.
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 of a file entry.
The valid encodings for a Zip relative path are either [CP437] or [UTF-8]. It is recommended that the file name field be encoded using [UTF-8].
Author requirements: As stated in [Zip], the appropriate
encoding indicator must be used, meaning that if the Zip
relative path is encoded using [UTF-8], then general purpose bit
11 of the local file header must be set to 1
;
otherwise, it must be set to 0
.
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.
Author requirements: It is recommended that authors keep their path lengths below 255 bytes. Note that a character can require more than one byte to encode, making the length of the path in characters less than 255.
A valid Zip relative path is one that case-insensitively matches the production of
Zip-rel-path
in the following [ABNF]. Note that
ALPHA, DIGIT, and SP are defined in [ABNF]
(but essentially represent alphanumerical characters and the U+0020 SPACE character).
Language-Tag
is defined in [BCP47]. In addition,
reserved characters must not appear anywhere in the
file-name
.
Zip-rel-path = [ *localized-folder ] [ *folder-name ] [ file-name ] /
[ localized-folder ] [ *folder-name ] / [ folder-name ]
localized-folder = "locales" "/" Language-Tag "/"
folder-name = file-name "/"
file-name = 1*254( *base-name [ file-extension ] )
base-name = allowed-chars
file-extension = "." 1*allowed-chars
allowed-chars = cp437-chars / utf8-chars
utf8-chars = safe-chars / U+0080 and beyond
cp437-chars = safe-chars / x80-FF
safe-chars = ALPHA / DIGIT / SP / "$" / "%" / "'" / "-" / "_" / "@"
/ "~" / "!" / "(" / ")" / "^" / "&" / "+"
/ "," / "." / "=" / "[" / "]"
Note: Authors should be aware that, at the time of writing, there are
some interoperability issues with regards to using characters outside the
allowed-chars for file or 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 allowed-chars
(characters in the US-ASCII range).
This specification does not put a restriction on the byte length of Zip relative paths, a widget user agent should be prepared to deal with path lengths longer than 250 bytes.
A CC must inform the author about any file entry whose file name field is not a valid Zip relative path.
A CC must inform the author of any Zip relative paths whose length exceed 250 bytes, and should inform the author of any Zip relative path whose length exceeds 120 bytes.
Note: Having excessively long path names (e.g. over 120 characters) can also result in interoperability issues on some operating systems. Note that a character can require more than one byte to encode, making the length of the path in characters less than 255.
In addition to the control characters, the following characters are
reserved and must not appear anywhere in a
file-name
.
Note: These characters are reserved to maintain interoperability across various file systems and with generic [URI]s.
Representative Glyph | Unicode Character |
---|---|
< | U+003C LESS-THAN SIGN |
> | U+003E GREATER-THAN SIGN |
: | U+003A COLON |
" | U+0022 QUOTATION MARK |
/ | U+002F SOLIDUS |
\ | U+005C REVERSE SOLIDUS |
| | U+007C VERTICAL LINE |
? | U+003F QUESTION MARK |
* | U+002A ASTERISK |
Note to authors: It is recommended that authors avoid using the following
words as either a folder
or a
base-name
in a Zip relative path as they are reserved by some
operating systems (case insensitive): CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5,
COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, CLOCKS$.
For example, the following names are ok: "CON-tact.txt", "printer.lpt1", "DCOM1.pdf".
However, "com3.txt" "Lpt1", "CoM9.gif" would not be. In addition, authors should avoid
using 2 and 3 letters names for folders at the root of a widget resource.
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 device. 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.
A CC must inform an author of the presence of any of the
reserved characters or control characters in a
file-name
.
A CC should inform an author of the presence of a U+0020 SPACE
character at the start or end of a file-name
.
A CC should inform an author of the presence of any U+002E FULL
STOP at the end of a file-name
.
A CC should inform an author of any base-name
that case
insensitively matches any of the following strings: CON
, PRN
, AUX
, NUL
, COM1
, COM2
, COM3
,
COM4
, COM5
, COM6
, COM7
, COM8
, COM9
, LPT1
, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9,
CLOCKS$.
A CC may inform an author of the presence of any U+002B PLUS SIGN
in a file-name
.
A widget resource is a valid Zip archive that contains:
See step 1 - Acquire a Potential Zip Archive for instructions on how to process a widget resource.
During the steps for processing a widget resource, certain error conditions will result in a Zip archive being treated as an invalid widget. An invalid widget is a condition whereby a Zip archive, or a file within the Zip archive, is deemed to be corrupt beyond recovery or non-conforming to this specification.
See the section Dealing with Invalid Widgets for instructions on how a widget user agent must treat an invalid widget.
The root of the widget is the top-most folder level of the Zip archive. The root of the widget contains files and folders, some of which are reserved (see reserved file names).
A file is the decompressed representation of a file entry. Unlike [HTTP] resources, files within a Zip archive are not available in multiple representations, nor are they dynamically generated at runtime. Additionally, there is no notion of a [MIME] type within Zip (i.e., no Content-Type metadata), so widget user agents must use file extension to MIME mapping followed by content-type sniffing to determine the MIME type of a file.
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 [ZIP] is a
U+002F SOLIDUS) and whose version needed to extract is 0x200
. A folder may logically contain files or other
folders.
The base folder is the folder from which all relative paths are resolved.
File extension to MIME mapping is the process of mapping the file extension of a file to some MIME type.
Content-type sniffing is the process of determining the MIME type of a file by
examining its content. Examination of content involves examining the bytes of a file for
well-known patterns of byte sequences (e.g. the byte sequence EF BB BF
,
which identifies a text file as being encoded in [UTF-8]). Some of these
patterns have been registered with the Internet Assigned Numbers Authority (IANA), as part of a MIME type registration, under the
name magic numbers.
A processable file is a file that has been verified as residing inside a widget resource and that has a MIME type supported by the widget user agent.
The following table contains a list of base-name
s and possible file-extension
s that
when combined form file-name
s that are reserved for some purpose
by this specification. All reserved file name
s must be treated as
case insensitive.
base-name | file-extensions | Reserved for purpose |
---|---|---|
config | xml | Configuration Document |
signature[0..9 ] |
xml | Digital signature |
icon | png, gif, ico, svg | Default icon |
thumbnail | png, gif, ico, svg | Thumbnail |
The following table contains a list of folder-names
that are reserved for some purpose
by this specification. All reserved file names must be treated as case insensitive.
folder-name | reserved for purpose |
---|---|
locales/ | container of localized content |
A widget resource contains a digital signature, and hence is digitally signed, if it contains one or more files that conform to the [Widgets-DigSig] specification.
The naming convention for digital signatures is a string that case-insensitively matches the production of dig-sig-file-names
in the following ABNF:
dig-sig-file-names = "signature" *[0..9] ".xml"
Authors can localize the content of a widget by placing files inside folders that follow the Language Tag conventions set forth in [BCP47]; that is, by naming folders using values derived from the IANA Language Subtag Registry such as "en-us", "en-gb", and so on, but avoiding subtags marked as deprecated, grandfathered, or redundant. These localized folders are then placed inside the container for localized content (which is simply a folder called 'locales/' that sits at the root of the widget).
When an author places localized content in the container for localized content, the widget user agent will automatically select the appropriate localized version of a widget's files based on locale information derived from the system locale. The system locale is the end-user's preferred language and regional settings derived from the operating system or widget user agent (e.g. English, Australia).
Note: See also the Web Services Internationalization Usage Scenarios and the Unicode Locale Data Markup Language for an informative discussion on the term locale.
A localized widget is a widget resource that has a container for localized content, which contains one or more localized folders.
The container for localized content is a folder at the root of the widget whose the first five characters of the folder-name
case insensitively match the string 'locales/
'.
A localized folder is a folder whose file name
field matches localized-folder
. A widget resource may contain zero or more localized folders.
Localized folders may contain zero or more arbitrary
folders and/or files.
Author requirements: According to [BCP47], one should avoid region, script or other subtags except where they add useful distinguishing information to a localized folder. In addition, one should avoid including empty localized folders in a widget resource (unless there is a good reason to include them) as the a widget user agent will match them when it attempts to determine the base folder and widget locale.
A localized file is any resource that has been placed inside a localized folder. The contents of the resource may or may not be translated, localized, or altered for the given context. A widget resource may contain zero or more localized files. Any resource, except digital signatures, can be localized.
Note: A widget user agent will treat any localized digital signature as an arbitrary resource.
For example, a localized folder "/ja" (Japanese) might contain an HTML document translated into Japanese.
Author requirements: Localized folders must be at the root of the widget (a localized folder not at the root of the widget will be treated as an arbitrary folder). At runtime, the widget user agent will set the (HTML or XML) base 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 provide a start file at the root of the widget. Please be aware that if localization fails, and there is no default start file at the root of the widget, then the widget user agent will treat the widget resource as an invalid widget.
Note: See Step 6 - determine the base folder and widget locale for the algorithm to process a localized widget.
This section is non-normative.
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:
/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">
...
A CC should inform the author if they have used deprecated, grandfathered, or redundant language tags from the IANA Language Subtag Registry.
Upon encountering any localized folders named with a region or script subtag, a CC should inform the author to avoid region or script subtags.
The start file of a widget resource is a file that is used by
the widget user agent when the widget is instantiated. When a start file is not
explicitly declared via the content
element or the content
element's src
attribute is in error, the start file will be
one of the default start files.
A default start file is a start file that a widget user agent
will attempt to locate when the start file of the configuration
defaults is null
(i.e., when an author omitted the
content
element in the configuration document or the content
element is in error).
The file-name
and MIME type of the default start files is
given by the following table. A widget user agent is only required to
support the text/html
MIME type; support of other MIME types is optional.
A widget user agent will attempt to locate a file entry whose file-name
matches one of
the default start files based on the order they appear in the table below (from top to
bottom). File names must be treated as case
insensitive.
file-name | MIME type |
---|---|
index.htm | text/html |
index.html | text/html |
See step 9 for instructions for finding a default start file.
Author requirements: Always include at least one start file in a widget resource.
A CC must check that the widget resource contains at least one start file by:
If the widget does not contain a start file, or the start file is not one that is supported, then the CC must inform the author.
An icon is an optional file that is used to represent the widget in various application contexts (e.g. the icon that the user double-clicks to instantiate a widget, or an icon in a dock or task bar or some other visual context). There are two kinds of icons defined by this specification, custom icons and default icons.
An icon must be located either at the root of the widget or in a localized folder.
A custom icon is an icon explicitly declared to be used as an
icon by an author via an icon
element of the configuration
document. The MIME type of a custom icon is derived by the rules for identifying the MIME type of a file.
A default icon is an icon whose file-name case insensitively matches a file-name 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.
A default icon must be located either at the root of the widget or in a localized folder.
A widget user agent must search for a default icon's file-name
based on the order they appear in the default icons table below (from top to
bottom).
As indicated by the level of support column in the default icons table below, a widget
user agent is required to support the image/png
and
image/gif
MIME types; support of other MIME types is optional.
file-name | MIME type | Defined by | Level of Support |
---|---|---|---|
icon.svg | image/svg+xml | [SVGTiny] | optional |
icon.ico | image/vnd.microsoft.icon | [ICO] | optional |
icon.png | image/png | [PNG] | required |
icon.gif | image/gif | [GIF89][GIF87] | required |
If no default icon has been included, and the CC determines that no custom icons have been declared in the configuration document, a CC should inform the author that it is desirable, but optional, to include a default icon.
If a CC encounters an icon in a format either than [PNG] or [GIF89] or [GIF87], then the CC should inform the author that these formats might not be supported on all widget user agents.
A thumbnail is an optional file inside the widget resource that graphically represents the widget in a running state. The thumbnail must be located either at the root of the widget or in a localized folder.
To be treated as a thumbnail by the widget user agent, the file-name
of a file entry
must case insensitively match one of the
file-name
values given in the first column of the default thumbnails table
below. In addition, the MIME type must match the MIME type given in
the second column of the default thumbnails table below. A widget user agent will search
for a thumbnail's filename based on the order they appear in the table below (from top to
bottom).
file-name | MIME type |
---|---|
thumbnail.png | image/png |
thumbnail.gif | image/gif |
thumbnail.jpg | image/jpg |
Author requirement: it is recommended that authors use a screenshot of their widget in its running state as the thumbnail.
If a CC determines that the widget resource does not contain a thumbnail, it may inform the author that the inclusion of a thumbnail is desirable but, nonetheless, optional.
The widget MIME Type is application/widget
[MIME].
Author requirement: Over the wire (e.g. over HTTP), a widget resource
must be labeled with an application/widget
MIME type.
Failure to correctly label a widget resource will likely result in it being treated as an
invalid widget.
Note: Widget user agents can support other legacy/proprietary widget types, but they must remain conforming to this specification when dealing with widget resources.
Note: The application/widget
MIME type has
not yet been registered with IANA. This will happen
when the specification reaches Candidate Recommendation status.
A widget file extension is the string .wgt
in any case form
(e.g. my.wgt
, my.WGt
, my.WgT
, etc. are all
valid).
The file extension .wgt
is required for widget
resources on systems where it's customary for file names to include an extension that
symbolizes the MIME type.
Author requirement: As long as the widget resource is appropriately
labeled as a application/widget
when the widget resource is served over
HTTP, the widget file extension is not required.
A configuration document is an [XML] document that has a
widget
element at its root that is in the widget namespace.
A valid configuration document file name is config.xml
, in any
case form. Within a widget resource, a configuration document must
have a valid configuration document file name.
Configuration documents can exist either at the root of the widget or in a localized folder.
Note: Any configuration document not at the root of the widget or not in a localized folder will be treated by the widget user agent as an arbitrary resource.
Author requirement: 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, for constancy, that
the config.xml
filename be in lowercase form.
The following is an example of a config.xml
document:
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
identifier="http://datadriven.com.au/exampleWidget"
version="2.0 Beta"
height="200"
width="200">
<name>The example widget!</name>
<update href="http://www.bla.com/update.php"/>
<description>
A sample widget to demonstrate some of the possibilities.
</description>
<author href="http://foo-bar.example.org/"
email="foo-bar@example.org">Foo Bar Corp</author>
<icon src="icons/example.png"/>
<icon src="icons/boo.png"/>
<content src="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,
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</license>
</widget>
Note: Implementers are encouraged to expose relevant information provided by the configuration document to the user. Having "visual metadata" encourages authors to make full use of the configuration document format.
See "Step 7 for instructions on how to process a configuration document.
The widget namespace is http://www.w3.org/ns/widgets
[XMLNS].
Authoring requirements: Authors must assign the
widget namespace to the widget
element. Authors should be aware that, if the
namespace is missing then Zip archive will be treated as an invalid
widget.
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 widget namespace. For the sake of interoperability, extensions to the configuration document are not recommended.
Example of extending the configuration document format:
<widget xmlns="http://www.w3.org/ns/widgets"
xmlns:ex="http://widgextension.org/">
<icon src="idle.png" ex:role="inactive"/>
<icon src="big.png" ex:role="big"/>
<ex:datasource>{a:"b",c:"d"}</ex:datasource>
<content src="widget.html"/>
</widget>
This section defines the different attribute types used in the configuration document and what constitutes valid values for those attribute types. Some general rules for how attributes are to be processed by widget user agents and conformance checkers are also given in this section.
valid-version-tag
in the following
[ABNF]:
valid-version-tag = version-identifier *[ "." version-identifier ]
version-identifier = ALPHA / DIGIT / SP / "$" / "%" / "'" / "-" / "_"
/ "~" / "!" / "(" / ")" / "^" / "&" / "+" / "@"
/ "," / "=" / "[" / "]" / "/" / "\" / "*" / "?"
/ "|"/ ":"
Author Requirements: it is recommended that authors create version strings that conform to the following [ABNF]:
rec-version-tag = 1*2DIGIT ["." 1*2DIGIT [ "." 1*2DIGIT] [ ALPHA / SP / DIGIT]]
Version 1.0 Beta
, 1.0 RC1
, 1.0-Build/1580
,
Joey the dog [5.1.2100]
.1.0
, 1.10.1beta1
, 1.02.12rc1
.Note: For the purpose of this specification, version tags have no significant semantics; they are just treated as arbitrary strings (e.g. '1.0' is not greater than '2.0', but is simply different). This may change in future versions of this specification.
An attribute defined as containing a valid non-negative integer. 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). For example, the characters "2", "323", "23214", and so on.
An attribute defined as requiring a certain string value (e.g. apple
or
orange
). The values must be specified exactly, in the
case given in this specification, and with no leading or trailing space
characters. Implementations must only perform literal
comparisons, and must not use case
insensitive comparisons nor trim attribute values before comparison.
A keyword attribute that can only be used with a valid boolean value: a valid
boolean value is a string that case insensitively matches
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
. How a widget user agent is supposed to interpret a boolean attribute is described when the term is used.
An attribute defined as containing a valid MIME type. A valid MIME type is
one that matches the production for valid-MIME-type
in the following
[ABNF]:
valid-MIME-type = type "/" subtype *(";" parameter)
The type
, subtype
, and parameter
tokens are
defined in [RFC2045].
An attribute defined as containing a valid URI. A valid URI is one that matches the URI token of [URI] or the IRI token of [RFC3987].
An attribute defined as containing a valid path. A valid path is one that
matches the path
token of [URI]. A path can be either
absolute, meaning that it is already resolved to the root of the
widget (e.g. "/images/bg.png") or relative, meaning that it is resolved
relative to some folder in the widget resource.
This feature is at risk! A keyword attribute whose value is one of the following valid window modes: application
, floating
, fullscreen
, docked
.
xml:lang
attributeA keyword attribute defined as containing a basic language
range, defined in [BCP47], from the IANA Language Subtag
Registry.The [XML] specification defines the xml:lang
attribute and its influence on child elements that are XML text content. Widget user
agents are not required to validate language ranges against the
IANA Language Subtag
Registry.
Author requirements: Authors should avoid subtags from the IANA Language Subtag Registry marked as deprecated, grandfathered, or redundant.
its:dir
attributeA keyword attribute defined as containing a valid
its:dir
value (i.e., ltr
, or rtl
, or
lro
, or rlo
). To use the its:dir
attribute, the
its
namespace (see [ITS]) must be declared
on the element where it is used or somewhere in the element's ancestor chain.
widget
ElementThe widget
serves as a container for the other elements; as such, it
must be used.
name
: zero or one.description
: zero or one.icon
: zero or more.access
: zero or one.author
: zero or one.license
: zero or one.content
: zero or one.update
: zero or one.feature
: zero or more.id
version
height
0
that controls the initial height dimensions of
the instantiated widget in CSS pixels
[CSS21]. When the value is missing, the widget user agent will assume the
value 300
.width
0
that controls the initial width dimensions of
the instantiated widget in CSS pixels
[CSS21]. When the value is missing, the widget user agent will assume the
value 150
.mode
default
.xml:lang
Note: The width
and height
attributes are only
relevant to widgets with a visual output.
This section is non-normative.
The following example shows how the widget element can be used.
It also demonstrates the use of the xml:lang
attribute.
<widget xmlns="http://www.w3.org/ns/widgets"
id="http://datadriven.com.au/exampleWidget"
version="2.0 Beta"
height="200"
width="200"
xml:lang="pt">
<description>este é um exemplo das possibilidades!</description>
</widget>
name
ElementThe name
element represents a human-readable name for a widget resource
that can be used, for example, in an application menu or in other contexts.
widget
element.xml:lang
its:dir
its:dir
value.This section is non-normative.
The following example shows the usage of the name
element.
<widgets xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="pt">Boletim Metereológico</name>
</widget>
description
ElementThe description
element represents a human-readable description of the
widget.
widget
element.xml:lang
its:dir
its:dir
value.This section is non-normative.
An example usage of the description element.
<widgets xmlns="http://www.w3.org/ns/widgets">
<name>Tornado Chaser</name>
<description>
Combining the latest weather info with your GPS position,
this widget alerts you of any significant storm activity in your
area. When a big one hits, the widget plots the best route on a map based
on the storm's trajectory so you can chase it! With support for
built-in cameras, you can quickly upload all the meteorological action to
your blog or to the insane storm chaser web site! Awesome!
</description>
</widget>
author
ElementAn author
element represents people or an organization attributed with the
creation of the widget.
widget
element.href
email
xml:lang
its:dir
its:dir
value.This section is non-normative.
The following example shows the expected usage of the author element.
<widgets xmlns="http://www.w3.org/ns/widgets">
<name>Cup-a-Joe's Cafe Finder Widget</name>
<author href = "http://cup-a-joes-website-visit-us.com"
email = "joe@cup-a-joes-website-visit-us.com">
Joey and Princesa Bacalhau
</author>
</widget>
license
ElementThe license
element represents an end-user license agreement or a
copyright statement for the widget.
widget
element.href
href
attribute is present, the widget user agent should allow users the ability to view or otherwise access the referenced license.xml:lang
its:dir
its:dir
value.This section is non-normative.
This example shows the expected usage of the license
element's
href
attribute.
<widgets xmlns="http://www.w3.org/ns/widgets">
<license href="http://creativecommons.org/licenses/by/3.0/">
Creative Commons Attribution License
</license>
</widget>
This example shows the expected usage of the license
element when the
href
attribute is omitted.
<widgets xmlns="http://www.w3.org/ns/widgets">
<license>
Copyright (c) 2008 The Foo-Bar Corporation
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.
</license>
</widget>
icon
ElementThe icon
element represents a custom icon for the widget. A
widget user agent should expose a custom icon in a way
that it is visible to the end user.
widget
element.src
width
0
that represents the width of the icon in
CSS pixels
[CSS21]. This attribute is only applicable to graphic formats that have no intrinsic width or height (e.g., SVG). If the file pointed to by the src
is a supported
raster graphic, this value may be ignored by the widget user agent. If the file
pointed to by the src
is a vector graphic format, then this value will be
used. height
0
that represents the height of the icon in
CSS pixels
[CSS21].This attribute is only applicable to graphic formats that have no intrinsic width or height (e.g., SVG). If the file pointed to by the src
is a supported
raster graphic, this value may be ignored by the widget user agent. If the file
pointed to by the src
is a vector graphic format, then this value will be
used. Author requirement: Authors should not use
the width
and height
attributes for raster graphic formats (as
the values will be ignored).
This section is non-normative.
This example shows the expected usage of the icon
element. The example
declares three icon elements, two of which are raster and one of which is an [SVGTiny] file.
The raster graphics would be used for display contexts smaller than 256x256 pixels. Tree
order of the elements is irrelevant.
<widgets 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>
access
ElementThe access
element indicates, through its attributes, what kind of
security permissions are 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.network
plugins
Note: Widget user agents are not required to support, or otherwise implement, proprietary plugins.
Conformance checkers requirements: If the access
element
is used, at least one of its attributes must be used.
This section is non-normative.
This example shows the expected usage of the access
element. Assume the flash_version.html
file combines Adobe Flash and HTML content.
<widget
xmlns ="http://www.w3.org/ns/widgets"
width ="400"
height="500">
<name>Flight Tracker</name>
<access network="true" plugins="true"/>
<content src="flash_version.html"/>
</widget>
content
ElementThe content
element is used by an author to declare which start
file the widget user agent will use when it instantiates the widget.
widget
element.src
type
src
attribute. When the value is missing, the
widget user agent will assume the value text/html
.charset
src
attribute. The allowed values are any name of a character set
listed in [IANA-Charsets] (widget user agents are only required to support
UTF-8). When the value is missing, the widget user agent will assume the value
UTF-8
.This section is non-normative.
This example shows the expected usage of the content
element.
<widgets xmlns="http://www.w3.org/ns/widgets">
<content src="myWidget.html"/>
</widgets>
This example shows the content
element being used with a
charset
attribute to override the default value of this attribute
(UTF-8
) with the GB2312 character set, which the author has used to encode simplified Chinese characters.
<widgets xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="zh-cn">古老瓷地图</name>
<content src="china-maps.html" charset="GB2312"/>
</widgets>
This example shows the content
element being used with a
type
attribute to instantiate a widget created with a proprietary
MIME type.
<widgets xmlns="http://www.w3.org/ns/widgets">
<name>Location-Based Games Finder</name>
<content src="lbg-maps.swf" type="application/x-shockwave-flash"/>
<access network="true" plugins="true"/>
</widgets>
update
ElementThe update
element points, via the href
attribute, to an update description document (see [Widgets-Updates]). The update description document is processed by the widget user agent to check for the availability of an updated version of the widget.
widget
element.href
This section is non-normative.
This example shows the expected usage of the update
element.
<widget xmlns = "http://www.w3.org/ns/widgets"
id = "http://example.com/myWidget"
version = "1.0">
<update
href="http//example.com/update.php?widget=myWidget&version=1.0"/>
</widget>
feature
ElementThe feature
is used by an author to denote that, at runtime, a widget
may require access to a feature. A feature is a runtime
component (e.g. an API) that is not part of the standard set provided by the
Widgets 1.0 family of specifications.
When a feature
element is nested inside another feature element, it
denotes a fallback relationship: if the feature identified by the outermost
element is unavailable, then the widget user agent will check for the availability of the
feature identified by the child's element's name
attribute.
Note: the feature
element is not a means to import
javascript libraries or other resources available on the Web. The feature
element should be viewed as a standardized way to request the binding of an (URI)
identifiable runtime component to a widget for use at runtime.
widget
element or in the feature
element.feature
: Zero or one.name
required
feature
element must be available to the widget at runtime.This section is non-normative.
<widget xmlns="http://www.w3.org/ns/widgets">
<feature name="urn:proprietary.camera.api" required="true">
<!-- can't find it? use the alternative one -->
<feature name="http://w3.org/apis/camera"/>
</feature>
</widget>
Warning: Feature at risk! This specification
does not define the semantics of the window modes. We seek input regarding what, if anything,
should be specified in this spec versus what should be left as an implementation
detail. The widget
element's mode
attribute and associated window modes will be
dropped without substantial evidence that they are needed.
<its:span>
Although it is optional for a widget user agent to implement
[ITS], it is recommended that authors use the
<its:span>
element to indicate the directionality of arbitrary content
when needed. Directionality is indicated by either using the dir
attribute,
with one of the following valid its:dir
values, as defined in
ITS:
ltr
rtl
lro
rlo
For example,
<widget
xmlns="http://www.w3.org/ns/widgets"
xmlns:its="http://www.w3.org/2005/11/its">
<name>Yay for the
"<its:span dir="rtl">متعة الأسماك!</its:span>" Widget</name>
<description its:dir="rtl">متعة الأسماك! </description>
</widget>
The its:dir
attribute and the <its:span>
element can
be used as a child of the following elements of the configuration document:
Note: The following steps and associated parsing rules are written with more concern for clarity than efficiency. As such, user agents may optimize any of the parsing rules and the steps, or may perform the steps in a different order, so long as the end result is indistinguishable from the result that would be obtained by following the specification.
The steps for processing a widget resource involves ten 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 as part of each step; however, there are times when it will not be possible for the widget user agent to recover from an error and it will be forced to treat the widget as an invalid widget. What to do in a situation when a widget user agent encounters and invalid widget is described below.
Once a widget resource has been successfully processed, a widget user agent may install and instantiate the widget resource as described in [Widgets-Security].
This section describes what to do in the event a widget user agent needs to treat a Zip archive as an invalid widget.
In the event that an implementation encounters an invalid widget during the steps for processing a widget resource, the widget user agent must abort all processing of the steps for processing a widget resource and may inform the end-user with an appropriate localized error message (see example in the note below). The wording of an appropriate localized error message is left to the discretion of implementers; however, their presence is nonetheless recommended.
An example of an appropriate error dialog would be "This widget cannot be installed because it was created using an unsupported compression method."
When processing a widget resource, a widget user agent will have to decompress (or otherwise extract) the file data of file entry into its original representation. Specifying exactly how to extract file entries from a Zip archive is beyond the scope of this specification. Instead, implementers must follow the processing rules defined in the [ZIP] specification to extract file entries for Zip archive.
A widget user agent is not required to extract all the file entries in a Zip archive at the same time. It may extract specific file entries as they are needed for processing or rendering.
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 files inside a Zip archive.
Step 1 involves acquiring a potential Zip archive and checking if it is a Zip archive by using the rules for determining if a potential Zip archive is a Zip archive. A widget user agent will acquire a potential Zip archive from a data transfer protocol that either labels resources with a [MIME] type (e.g. [HTTP]) or from a data transfer protocol that does not label resources with a [MIME] type (e.g., BitTorrent, Bluetooth, etc.).
An implementation is not required to acquire all the bytes of a potential zip archive before applying the rules for determining if a potential Zip archive is a Zip archive. It may perform the check once it has acquired the first four bytes of the resource.
When attempting to acquire a potential Zip archive over some protocol that labels resources with a MIME type, a widget user agent must only attempt to process resources labeled with the widget MIME type (application/widget
) regardless of file extension or no file extension. Unless the widget user agent supports legacy or proprietary MIME types, all other MIME types are in error and the widget user agent must treat the potential Zip archive as an invalid widget.
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 MIME type, then a widget user agent may treat the acquired potential Zip archive as if it has been acquired from a protocol that does not label resources with a MIME type.
In this example, the Content-Type
is in error, so the widget user agent would not attempt to process the following potential Zip archive:
GET /foo.wgt HTTP/1.1
Host: www.example.com
Accept: application/widget
HTTP/1.1 200 OK
Date: Tue, 04 Sep 2007 00:00:38 GMT
Last-Modified: Mon, 03 Sep 2007 06:47:19 GMT
Content-Length: 1337
Content-Type: application/x-gadget
A widget user agent must attempt to process a resource regardless of the file extension (including situations when there is no file extension) by applying the rules for determining if a potential Zip archive is a Zip archive.
The rules for determining if a potential Zip archive is a Zip archive is as follows.
If the first four bytes of the potential Zip archive do not match the magic numbers for a Zip archive (50 4B 03 04
) then a widget user agent must treat the resource as an invalid widget. Otherwise, the widget user agent must treat the potential Zip archive as a Zip archive.
With the Zip archive, the widget user agent must verify the Zip archive and its file entries.
To verify that a Zip archive and its file entries conform to this specification, a widget user agent must perform the following checks. This specification does not provide the technical details of how to actually perform the checks. Instead, implementers must follow the [Zip] specification.
The potential widget resource can be considered verified only once the checks below have been completed.
If any of the following conditions occur/apply (indicating that a condition is met), then a widget user agent must treat the Zip archive is an invalid widget:
0
being set and by the presence
of archive decryption header and an archive extra data record
[ZIP]).Next, for each file entry in the Zip archive, the widget user agent must perform the following checks. If any of the following conditions occur/apply (indicating that a condition is met), then the widget user agent must treat the Zip archive as 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
).images/BG.png
' and 'iMaGeS/bG.pNg
' are considered canonically equivalent) A widget user agent must now set the configuration defaults (step 3).
Widget user agents must assume the following configuration defaults at this point of processing:
Variable | Type | Default Value | Overridden by | Description |
---|---|---|---|---|
signatures | File entry list | null |
Step 4 | The list of file entries that are digital signatures. |
signed | boolean | false |
Step 5 | The value indicates if the widget is digitally signed. Will only be set to true if a signature can be validated via [Widgets-DigSig]. |
base folder | DOMString | "" |
Step 6 | The base folder. |
wua-language list | List |
See description. | Step 6 | The user's system locale as a comma-separated list of basic language
ranges. The first item represents the user's
most preferred language range, followed by the next most preferred language and so forth.
For example, 'en,fr,es ', where English is preferred over French, and French is
preferred over Spanish, and Spanish is preferred over the widget user agent's default. Each language range must match the language-range production in [BCP47]. When generating this list, improperly formed ranges must be ignored. Widget user agents should, nevertheless,
attempt to populate the wua-language list with valid language subtags that
are well-formed (which can help with canonicalization and matching obsolete and
grandfathered subtags with a "preferred value"). |
widget locale | DOMString | null |
Step 6 | The locale under which the widget will be instantiated, as a language tag. |
widget config doc | File entry | null |
Step 7 | The file entry that is the configuration document for the widget resource. |
Variable | Type | Default Value | Overridden by | Description |
widget id | DOMString | null |
Step 8 | The identifier, corresponding to the widget element's id
attribute in the configuration document. |
widget version | DOMString | null |
Step 8 | The widget's version, corresponding to the widget element's version
attribute in the configuration document. |
widget width | integer | 300 |
Step 8 | The widget's visual width, corresponding to the widget element's
width attribute in the configuration document. |
widget height | integer | 150 |
Step 8 | The widget's visual height, corresponding to the widget element's
height attribute in the configuration document. |
widget window mode | DOMString | widget |
Step 8 | This feature is at risk! The window mode that corresponds to the widget element's mode attribute in the configuration document. |
widget name | DOMString | null |
Step 8 | The widget's name, corresponding to the name element in the
configuration document. |
widget description | DOMString | null |
Step 8 | The description given to the widget by the author, corresponding to the text content of the description element in the
configuration document. |
widget license | DOMString | null |
Step 8 | The software license assigned to the widget by the author, corresponding to the text content of the license element in the
configuration document. |
widget license href | URI | null |
Step 8 | The URI for a software license given to the widget by the author, corresponding href attribute of the license element in the
configuration document. |
access plugins | boolean | false |
Step 8 | If the widget will be able to use plugins at runtime, corresponding to the value of the access element's plugin attribute. |
access network | boolean | false |
Step 8 | If the widget will be able to access networked resources at runtime, corresponding to the value of the access element's network attribute. |
author name | DOMString | null |
Step 8 | The name of the author who created the widget, corresponding to the text content of the
author element. |
author email | DOMString | null |
Step 8 | The email of the author who created the widget, corresponding to the
author element's email attribute. |
author href | URI | null |
Step 8 | The URI associated with the author who created the widget, corresponding to the
author element's href attribute. |
widget start file | File entry | null |
Step 8, Step 9 | The start file for the widget resource, corresponding to either one of the default start files or the file identified by the content element's src attribute. |
start file content-type | DOMString | text/html |
Step 8 | The MIME type of the start file, corresponding to the content element's type attribute or to a default
start file. |
update href | URI | null |
Step 8 | The URI for where an update description can be downloaded, corresponding to the update element's href attribute. |
feature list | List | null |
Step 8 | A list of URIs that correspond to features that were requested, via feature elements, by the author and are supported by the widget user agent. Each item in the list corresponds to a feature element's name attribute. |
icons | List of file entries | null |
Step 8, Step 10 | 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 resource. |
start file encoding | DOMString | UTF-8 |
Step 8 | The character encoding of the start file, corresponding to the content element's charset attribute. |
widget thumbnail | File entry | null |
Step 10 | A file entry that corresponds to a default thumbnail. |
Once the above configuration defaults have been set, a widget user agent must attempt to locate digital signatures for the widget (step 4).
The algorithm to locate digital signatures for the widget is as follows:
signature001.xml
followed by signature9.xml
followed by signature.xml
). The following algorithm describes how to process the list of signatures created in step 4.
Note: How a widget user agent uses a digital signature is determined by the security policy implemented by that widget user agent. As such, this specification does not mandate processing rules dependent on the verification of one or more digital signature documents or on the revocation status obtained for the certificates associated with a verified digital signature document.
For each file entry in signatures, apply the Procedure for Verifying a Digital Signature Document in the [Widgets-DigSig] specification in the order they appear in the signatures list:
true
. Before attempting to locate the configuration document, the widget user agent must check for the existence of any localized folders that match the end-user's language preferences (as contained by the wua-language list).
This step makes use of the lookup mechanism as defined in section 3.4 of [RFC4647] (part of [BCP47]). The aim is to match, in order, one of the language ranges in the wua-language list to a localized folder in the widget resource.
The algorithm to determine the base folder and widget locale are as follows:
empty
', or null
,
or 'i-default
', or contains a single '*
', or is a sequence of
items that only contain the '*
' character, then terminate this algorithm and
attempt to locate the configuration document.*
', then terminate this algorithm
and attempt to locate the configuration document.*
', then skip this
range and, skipping all the steps below, repeat number 2 of this algorithm.*
', remove the
'*
' and its preceding hyphen (U+002F
) and continue (for
example, 'en-*-US
' becomes 'en-US
').localized/
' and the range (e.g. "en-us
" becomes "locales/en-us
"). locales/en-us
', then 'locales/en-us/anyfile
' would match),
locales/en
').For example, if the wua-language list is "en-AU" and a match is made on file entry whose name is "locales/En-Au/config.xml", then base folder would be ""locales/En-Au/", and the widget locale would be "en-au".
For example, if the wua-language list is "de-CH,fr-CH,it-CH" and folders included "locales/de", "locales/fr-FR" , and "locales/IT", then the folder "locales/de" would be matched, then base folder would be "locales/de" and the widget locale would be "de".
This step involves searching within the zip archive for a configuration document. The configuration document, if it exists, will be located at either the root of the widget or in a localized folder.
The algorithm to locate the configuration document is as follows:
config.xml
(e.g. locales/en-us/config.xml
).
If a match is made, set config doc to be this file entry.config.xml
. If a match is made, set
config doc to be this file entry.The config doc 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 and at runtime [Widgets-security]).
The main algorithm for processing a configuration document is given by the rules for processing a configuration document. To maintain interoperability across implementations, this step also makes use of the following rules for processing certain attribute types and files:
The rules for processing a configuration document are given in the following algorithm.
The term in error is typically used to mean that an element or attribute in a configuration document is not conforming to the rules of this specification. Rules for how an element or an attribute are to be treated when it is in error are always given when the term is used. Typically the specification will say that the erroneous DOM nodes must be ignored, meaning that the widget user agent must act as if those nodes were not present.
An element or an attribute is correct if it is not in error.
The term text node refers to any Text
node, including
CDATASection
nodes (any Node
with node type 3
or
4
) as defined in [DOM3Core].
Document
using a [XMLNS]-aware parser. The parser must support xml:lang
, and process any occurrence of the xml:lang attribute in accordance to the [XML] specification.documentElement
of
doc.widget
element in the widget
namespace, then treat this widget resource as an invalid widget.widget
element:If any one of the following attributes is in error or invalid, then that attribute must be ignored. All declared attributes must be processed.
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 version be the value of the
version
attribute.
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 mode
attribute is used, and it is a valid window mode, then let widget window mode be the value of the
mode
attribute. This feature is at risk!
If the widget element does not contain any child elements, then terminate this algorithm and go to step 9.
name
elementIf this is not the first name
element, then this element and its child nodes are in
error and must be ignored.
If 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 this element and its child nodes are 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 this element and its child nodes are in
error and must be ignored.
If this is the first author
element used, then:
let author name be the result of applying the rules for getting text content to this element.
If the href
attribute is used, and it is a valid uri, then
let author href be the value of the href
attribute. Otherwise, the attribute is in error and must be ignored.
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 this element and its child nodes are in
error and must be ignored.
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.
If the href
attribute is used, and it is a valid uri, then
let widget license href be the value of the href
attribute. However, if the attribute is in error then it must be ignored.
icon
elementIf the file identified by the src
attribute is missing, or not a valid path, or corrupt,
or is an unsupported MIME type, or already exists in the icons list, then this element is in error and must be ignored. Otherwise:
If the a src
attribute is a valid path that points
to a file, apply the rules for
identifying the MIME type of an image. If the MIME type is supported, then add the file entry identified by the value of
the src
attribute to the list of icons.
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
, make the value of the height
attribute a property of this file entry.
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
, make the value of the width
attribute a property of this file entry.
content
elementIf this is not the first content
element, then this element and its child nodes are in
error and must be ignored.
If this is the first content
element and it has a src
attribute that is a valid path that points
to a file, then check if the file is supported by the widget user agent by applying the rules for identifying the MIME type of a file. If the file is supported, let the widget start file be the file entry referenced by 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 is used and there is a correct src
attribute, and it is a valid MIME type
that is supported, then let the start file 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. Otherwise, the attribute is in error and must be ignored.
If the charset
attribute is used and there is a correct src
attribute, and it is an encoding that is supported by the widget user agent, then let the start file encoding be the value of the
charset
attribute. If the encoding is invalid, or unsupported by the widget
user agent, then a widget user agent may use the default encoding (UTF-8) or treat the widget as an invalid widget. Otherwise, the attribute is in error and must be ignored.
feature
elementIf the name
attribute is not a valid URI, then this element is in error and must be ignored.
If the name
attribute is a valid URI, then normalize the value of the name
attribute using [URI] normalization. If upon [URI] normalization the feature identified by the name
attribute is supported by the widget user agent, then add the normalized value of the name
attribute to the list of features. Otherwise, the attribute is in error and the element must be ignored.
access
elementIf this is not the first access
element, then this element and its child nodes are in
error and must be ignored.
If this is the first access
element and if the network
attribute is used, and it is a valid boolean
value, then let allow network be the value of the network
attribute. Otherwise, the attribute is in error and must be ignored.
If this is the first access
element and if the plugins
attribute is used, and it is a valid boolean
value, then let allow plugins be the value of the plugins
attribute. Otherwise, the attribute is in error and must be ignored.
update
elementIf this is not the first update
element, then this element and its child nodes are in
error and must be ignored.
If this is the first update
element used and the href
attribute is used, and it is a valid uri, then
let update href be the value of the href
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 given in the following algorithm. The algorithm always returns a string, which may be empty.
Let input be the element to be processed.
dir
attribute from the [ITS] namespace with a valid its:dir
value, then process its text nodes in accordance to the [ITS] specification.Text
nodes that only contain space characters,
or CDATASection
nodes that only contain space characters, let
result be the concatenation of 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 more or less equivalent to
invoking getTextContent()
DOM3 Java interface on an element (part of the Node
interface). 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" (carriage returns removed for legibility):
<widget xmlns="http://www.w3.org/ns/widgets">
<name>
The <blink>Awesome</blink>
<author email="dude@example.com">Super <blink>Dude</blink></author>
Widget</name>
</widget>
The 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 MIME 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, except for image/svg+xml, which is optional
.
unknown/unknown
.file extension | Magic Number | MIME type | Comment | Defined by |
---|---|---|---|---|
gif | 47 49 46 38 37 61 | image/gif | The string "GIF87a ", a GIF signature. |
[GIF87] |
gif | 47 49 46 38 39 61 | image/gif | The string "GIF89a ", a GIF signature. |
[GIF89] |
png | 89 50 4E 47 0D 0A 1A 0A | image/png | The PNG signature. | [PNG] |
ico | 00 00 01 00 | image/vnd.microsoft.icon | A 0 word following by a 1 word, a Windows Icon file format signature. | [ICO] |
svg | image/svg+xml | Widget user agents that support SVG should parse files in accordance to the [SVGTiny] specification. | [SVGTiny] |
The rules for identifying the MIME type of a file are given by the following algorithm. Widget user agents are required to support the MIME types given in the table below.
File Extensions | MIME Type | Defined by |
---|---|---|
html, htm | text/html | [HTML4] |
css | text/css | [CSS21] |
js | application/javascript | [ECMAScript] |
xml | application/xml | [XML] |
txt | text/plain | |
wav, wave | audio/x-wav |
This step involves finding and verifying the start file.
null
, terminate this algorithm and go to step 10.null
, then try to find one of the default
start files in the base folder. null
, check that it is a correct file of a supported MIME Type.A widget user agent must search for an icon's file name based on the order they appear in the default icons table (from top to bottom).
A widget user agent must search for a thumbnail's file name based on the order they appear in the default thumbnails table (from top to bottom).
This section is non-normative.
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://example.org/exampleWidget">The Example Widget</a>
This section is non-normative.
This schema may be out of date, we only update it prior to publication. You can get the latest draft from http://hasather.net/widgets/widgets.rnc.
The following is the RelaxNG schema 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 configuration documents.
# Widgets 1.0 (Working Draft) RELAX NG schema
# Latest draft at http://hasather.net/widgets/widgets.rnc
default namespace widgets = "http://www.w3.org/ns/widgets"
namespace its = "http://www.w3.org/2005/11/its"
namespace local = ""
start = elem.widget
elem.widget = element widget {
attr.xmllang?,
attribute id { xsd:anyURI }?,
attribute version { text }?,
attribute height { data.positiveNumber }?,
attribute width { data.positiveNumber }?,
attribute mode { "application" | "fullscreen" | "floating" | "docked" }?,
( elem.name?
& elem.description?
& elem.icon*
& elem.access?
& elem.author?
& elem.license?
& elem.content?
& elem.update?
& elem.feature*
& extension )
}
elem.name = element name {
attr.xmllang?,
attr.itsdir?,
extension
}
elem.description = element description {
attr.xmllang?,
attr.itsdir?,
extension
}
elem.icon = element icon {
attr.allowed*,
attribute src { xsd:anyURI },
attribute height { data.positiveNumber }?,
attribute width { data.positiveNumber }?,
empty
}
elem.access = element access {
attr.allowed*,
attribute network { data.boolean }?,
attribute plugins { data.boolean }?,
attribute files { data.boolean }?,
empty
}
elem.author = element author {
attr.xmllang?,
attr.itsdir?,
attribute href { xsd:anyURI }?,
attribute email { xsd:string { pattern=".+@.+" } }?,
extension
}
elem.license = element license {
attr.xmllang?,
attr.itsdir?,
attribute href { xsd:anyURI }?,
extension
}
elem.content = element content {
attr.allowed*,
attribute src { xsd:anyURI },
attribute type { text }?,
attribute charset { text }?,
empty
}
elem.update = element update {
attr.allowed*,
attribute href { xsd:anyURI }?,
empty
}
elem.feature = element feature {
attribute name { xsd:anyURI },
attribute required { data.boolean }?,
( elem.feature?
& extension )
}
extension = ( attr.allowed | anyElement )*
anyElement = ( element * - widgets:* { any } | text )*
any = ( attribute * { text } | anyElement )*
attr.allowed = attribute * - (local:* | xml:lang | its:dir) { text }
attr.xmllang = attribute xml:lang { xsd:language }
attr.itsdir = attribute its:dir { "ltr" | "rtl" | "lro" | "rlo" }
data.positiveNumber = xsd:string { pattern="[1-9]\d*" }
data.boolean = ( string "true" | string "false" )
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.
A huge thanks to Bárbara Barbosa Neves for her patience and for doing last minute proof-reads in the dead of night.
Parts of this document reproduce text and behavior from the HTML5 specification and from the XBL 2.0 specification (as permitted by both specifications by their copyright statements).
Graphic icons used some examples of this specification were created by Yusuke Kamiyamane and are available for use under a Creative Commons Attribution 3.0 license.
The editor would also like to thank the following people for their contributions to this specification: