First release: January 28, 2008
updated: May 27, 2008
Contents
Overview
Gadgets are web-based software components based on HTML, CSS, and JavaScript. They allow developers to easily write useful web applications that work anywhere on the web without modification. They are defined using a declarative XML syntax that is processed by a gadget server into a format that allows them to be embedded into various contexts: standalone web pages, web applications, even other gadgets. A context into which a gadget is embedded is called a gadget container. The container is responsible for managing the gadgets' layout and controls, as well as for supporting various functionality on behalf of the gadget. A gadget may be a simple widget, a reusable component, or a full-blown application, possibly utilizing or communicating with other gadgets.
A gadget and its XML are synonymous. The gadget XML contains all information needed to identify and render a web application.
Metadata. Several pieces of metadata are specified by the gadget developer in the gadget XML, such as author information, gadget title, and description. This data gives hints to the gadget container on how to identify it, in addition to providing data to gadget directories, which are databases that help users find gadgets useful for their needs
Gadget Features. A list of all gadget features that are either required for the gadget to operate, or may optionally be utilized if available. Gadget features are the primary extensibility mechanism employed by gadgets. They often direct a gadget server to make new JavaScript APIs available to rendering code, but may also manipulate the gadget's contents, for example to add extended syntax. Examples of gadget features include OpenSocial (provides gadgets with a rich set of social APIs), dynamic-height (enables gadgets to resize themselves to an appropriate height), and tabs (a UI library facilitating tabular navigation).
User Preferences. These are key/value pairs that form the basis of gadget configuration and persistence. They are most often manipulable by users of the gadget, and are persisted on behalf of a user so that the gadget has access to them across multiple rendering requests. The gadget container is typically responsible for providing their persistence for this data and an interface to edit it.
Message Bundles. Message bundles allow developers to internationalize their gadgets simply by adding name/message mappings corresponding to whatever languages the developer chooses to support. These messages may be accessed programmatically through the core JavaScript APIs provided to all gadgets, or may be statically substituted into code using simple syntax.
Content. Provides the actual HTML, CSS, and JavaScript to be rendered by the gadget. Two delivery mechanisms are supported:
- Type HTML gadgets are the most prevalent, and are imbued with the most rich feature set. Code is provided directly in the gadget XML content section for rendering and control flow. This code simply assumes that functionality is available that has been requested from whatever gadget features were declared. In the case of optional-declared features, a simple feature-existence API can and should be consulted to ensure the capability is enabled. The code is processed by a gadget server and rendered in an IFRAME.
- Type URL gadgets only specify a base URL. A standard set of parameters are added to this URL by the gadget server, which renders the gadget in an IFRAME. The application to which the URL points must include a referenced JavaScript library using a <script> tag as it renders, to enable gadget APIs to be made available. Type URL gadgets can't take advantage of all features, notably features that manipulate HTML and JavaScript code directly. However, this gadget type has proven highly useful for turning existing web sites or applications into gadgets.
Multiple Content sections may be specified in gadget XML. Each is labeled with one or more optional view identifiers, which allow the gadget to behave or appear differently depending on the context in which it's rendered. This context is provided by the gadget container.
This document describes the gadget XML syntax and how it is processed by a compliant gadget server. In addition, it describes the core JavaScript APIs that must be made available to every gadget as it is rendered. While compliance can be attained by supporting only these core APIs, doing so severely limits a gadget server's usefulness. Gadget servers should support as many features as possible. Widely used, highly recommended features are listed at the end of this document.
Compliance: Gadget Server
To be gadgets-compliant, a server must be able to satisfy a Gadget Rendering Request and a JavaScript Request in the manner described. The server should be able to satisfy the Gadget Metadata Request in the manner described.
Gadget Rendering Request
The core gadget API, this translates gadget XML into content that can be rendered in a browser, typically in an IFRAME.
Inputs:
- Gadget XML, typically specified as a URL pointing to a file on the web.
- User prefs.
- Locale of the end user.
- (optional) IgnoreCache processing option.
- (optional) Module ID, an integer identifier for the gadget in a given container context. If not provided, this defaults top 0.
Outputs:
- HTML, CSS, and JavaScript.
Process:
- Fetch the gadget XML.
- This SHOULD consult a cache to minimize load on the gadget XML hosting server. The specific properties of caching are left to the implementation.
- The server may honor HTTP caching headers to provide developers with a way to balance the load their servers receive against the frequency with which they can reliably deploy updated content.
- The server SHOULD honor an IgnoreCache processing option. This
causes all built-in spec caches to be ignored, fetching the spec
directly from its canonical resource. This feature is very useful
while developing a gadget.
- HTTP-based request servers SHOULD support this via a URL
parameter named
nocache
. - The server MAY implement denial-of-service protection limiting the number fetches for a spec in a given period of time, as a courtesy to developers.
- HTTP-based request servers SHOULD support this via a URL
parameter named
- Parse the gadget XML.
- The XML MUST conform to the extended gadget spec XSD . This XSD represents all valid elements and attributes accepted by the legacy iGoogle gadget server (gmodules.com). However, some of these fields will be phased out. The canonical gadget spec XSD contains the subset of attributes that must be parsed and interpreted by the server. In other words, the parser MUST NOT reject gadget specs conforming to the extended spec, yet need not interpret more than the canonical spec.
- Identify the Locale object corresponding to the request, and fetch messages specified by it.
- The <Locale> element is selected from the gadget XML by matching to the declared language and/or country. If an element matches both, use it. Otherwise select a language-only match over a country-only match. If no such match exists and an element is defined without language or country attributes defined, use it.
- Load the message bundle specified in the matched <Locale> element, if any.
- If the message attribute is specified, use it: load the bundle from the network using the provided URL.
- Otherwise use the <messagebundle> element that is a child of <Locale>, if present
- Substitute "hangman variables" into supported gadget spec
fields. Hangman variables are of the form
__<TYPE>_<ID>__
, and are replaced with string values. There are four types of hangman variables, which are defined as follows.- Process message bundle into
__MSG_foo__
hangman variables.- The bundle MUST conform to the message bundle XSD.
- For each message named
foo
with valuebar
, hangman expansion__MSG_foo__ = bar
.
- For each provided User Pref with key
foo
and valuebar
, hangman expansion__UP_foo__ = bar
. - Hangman expansion
__MODULE_ID__ = <provided module ID>
.- HTTP-based request servers SHOULD use the URL parameter named
mid
for this.
- HTTP-based request servers SHOULD use the URL parameter named
- If a message bundle was found with language_direction = "rtl" ,
hangman expansions
__BIDI_START_EDGE__ = "right"
,__BIDI_END_EDGE__ = "left"
,__BIDI_DIR__ = "rtl"
,__BIDI_REVERSE_DIR__ = "ltr"
. Otherwise__BIDI_START_EDGE__ = "left"
,__BIDI_END_EDGE__ = "right"
,__BIDI_DIR__ = "ltr"
,__BIDI_REVERSE_DIR__ = "rtl"
. - Perform substitutions of each hangman expansion on all fields which get displayed to users. This currently includes, but is not limited to, the following fields:
Module.ModulePrefs attributes
,Module.Content@href
,Module.Content
,UserPref@display_name
,UserPref@default_value
, andUserPref.EnumValue@display_value
- Process message bundle into
- Process gadget features, specified as
<Require>
or<Optional>
in the gadget XML.- If one or more unsupported features are specified in a
<Require>
block, the server MUST emit a standard error message indicating that it cannot satisfy the rendering request.- The message SHOULD list all requested features that could not be used because the container does not support them.
- The message MAY provide contact information for the gadget server administrator, along with a mechanism to request adding support for the feature.
- The server MUST support the following core JavaScript API,
which applies to
<Optional>
features:gadgets.util.hasFeature(featureName)
featureName
, false otherwise. Gadget developers can use this functionality to enhance their gadgets if features are available without disabling their gadget if the features are missing. - The server MUST conform to the requirements specified by each requested feature in order to claim support for it. The particulars of this vary per feature, but include injecting JavaScript APIs into rendered output or the type URL-included libraries and manipulating type HTML content to support extended syntax.
- If one or more unsupported features are specified in a
- Output gadget content.
- For type HTML gadgets, the order is as follows:
- Standard HTML header, opening
<html>
tag and<body>
tag.<head>
information is optional. Gadgets run in browser quirks mode. - Core gadgets JavaScript libraries, as specified here.
- Feature library initialization code, if needed.
- Processed gadget content, the result of steps #4 and possibly #5.
- A single call to
gadgets.util.runOnLoadHandlers();
- Standard HTML closing tags.
- Standard HTML header, opening
- For type URL gadgets, the provided URL MUST have the following
parameters added to it:
up_<name>=<value>
for each provided user preference.lang=<language>
andcountry=<country>
, from the provided request Locale.libs=<jsLib>
, where<jsLib>
is a comma-separated list of URL path fragments relative to the server's JavaScript request handler path. These fragments are added to the JS path by the type URL target to load gadget API JavaScript into its execution context.- The server SHOULD consolidate all libs into a single request to minimize the number of HTTP requests made by the client browser.
- For type HTML gadgets, the order is as follows:
Gadget Metadata Request
This API tells a gadget container how to render a gadget on a page, and gives it the container-side JavaScript it needs to support the gadget's features.
Context (container-side JavaScript):
It is often the case that the gadget container's support is
required to satisfy gadget API requests due to the browser security
model. For example, the dynamic-height
feature allows a
gadget to request that it be resized to fit its contents,
particularly when it is in an IFRAME. Most often, the gadget
is rendered on a different domain than its container, so it cannot
modify the height itself. Rather, it makes an inter-domain
procedure call to its container requesting that it be resized. This
communication occurs through the core gadgets.rpc.*
APIs, which use
browser-specific techniques to pass messages between frames on
different domains located in the same browser context. The
container needs to be able to receive this request and respond
accordingly - this is the function of the container-side
JavaScript.
Sanitized Gadget Content Note:
Rather than a Gadget Rendering Request URL, the Gadget Metadata Request API may return a version of the gadget output sanitized for security. The Caja project provides this sanitization by rewriting HTML, CSS, and JavaScript through static analysis techniques to preclude unsafe DOM or cookie access to the gadget content, while maintaining expressiveness nearly equivalent to content running simply inside an IFRAME. This functionality is still experimental, however, so is not included in the core spec at this time.
Inputs:
- Same as for the Gadget Rendering Request.
Outputs:
- URL to a Gadget Rendering Request for the requested gadget.
- Reference(s) to container JavaScript needed to satisfy needed gadget API requests.
Process:
- Load and parse gadget XML as described in Gadget Rendering Request steps #1 and #2.
- Process gadget features, specified as
<Require>
or<Optional>
in the gadget XML.- Emit an error message if a required feature is not supported.
- Otherwise, for each requested, supported feature with container-side JavaScript, enqueue this JavaScript to return to the client.
- Construct URL to the corresponding Gadget Rendering Request, generated as follows:
- Return the enqueued container-side JavaScript and Gadget Rendering Request URL.
JavaScript Request
In order to satisfy type URL gadgets' JavaScript library loading requests, a server MUST provide an HTTP service for retrieving core and feature-linked JavaScript.
Input:
- Fixed path, computed by a static base URL combined with a path fragment as described in Gadget Rendering Request part 6.ii.c.
Output:
- JavaScript code corresponding to the API(s) required by the type URL gadget.
Core JavaScript API
All core APIs MUST be provided by the server in such a way as to conform to the Gadgets API Reference. Gadget developers should not have to request any of these features, as the container should provide them all automatically.
File | JsDoc |
---|---|
prefs.js | Documentation |
io.js | Documentation |
json.js | Documentation |
util.js | Documentation |
Highly Recommended Features
The vast majority of gadgets include one or more features. The more features a gadget server supports, the more gadgets it supports. Thus, each gadget server strongly SHOULD support as many such features as possible, especially the following features that have high usage rates. Each supplies a JavaScript API to be made available to the gadget. Features are listed with their name(s) and their associated API:
Feature | File | JsDoc |
---|---|---|
tabs | tabs.js | Documentation |
minimessage | minimessage.js | Documentation |
flash | flash.js | Documentation |
rpc | rpc.js | Documentation |
views | views.js | Documentation |
skins | skins.js | Documentation |
dynamic-height | dynamic-height.js | Documentation |
settitle | settitle.js | Documentation |