Gadgets Specification

First release: January 28, 2008

updated: May 27, 2008

Contents

1. Overview
2. Compliance: Gadget Server
   1. Gadget Rendering Request
   2. Gadget Metadata Request
   3. JavaScript Request
3. Core JavaScript API
4. Highly Recommended Features

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:

1. 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.
2. 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:

1. Fetch the gadget XML.
   1. This SHOULD consult a cache to minimize load on the gadget XML hosting server. The specific properties of caching are left to the implementation.
   2. 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.
   3. 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.
      1. HTTP-based request servers SHOULD support this via a URL parameter named nocache.
      2. 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.
2. Parse the gadget XML.
   1. 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.
3. Identify the Locale object corresponding to the request, and fetch messages specified by it.
   1. 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.
   2. Load the message bundle specified in the matched <Locale> element, if any.
      1. If the message attribute is specified, use it: load the bundle from the network using the provided URL.
      2. Otherwise use the <messagebundle> element that is a child of <Locale>, if present
4. 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.
   1. Process message bundle into __MSG_foo__ hangman variables.
      1. The bundle MUST conform to the message bundle XSD.
      2. For each message named foo with value bar, hangman expansion __MSG_foo__ = bar.
   2. For each provided User Pref with key foo and value bar, hangman expansion __UP_foo__ = bar.
   3. Hangman expansion __MODULE_ID__ = <provided module ID>.
      1. HTTP-based request servers SHOULD use the URL parameter named mid for this.
   4. 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".
   5. 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:
      1. Module.ModulePrefs attributes, Module.Content@href, Module.Content, UserPref@display_name, UserPref@default_value, and UserPref.EnumValue@display_value
5. Process gadget features, specified as <Require> or <Optional> in the gadget XML.
   1. 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.
      1. The message SHOULD list all requested features that could not be used because the container does not support them.
      2. The message MAY provide contact information for the gadget server administrator, along with a mechanism to request adding support for the feature.
   2. The server MUST support the following core JavaScript API, which applies to <Optional> features:

      gadgets.util.hasFeature(featureName)

      As indicated in the JsDoc, this method returns true if the server is able to satisfy 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.
   3. 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.
6. Output gadget content.
   1. For type HTML gadgets, the order is as follows:
      1. Standard HTML header, opening <html> tag and <body> tag. <head> information is optional. Gadgets run in browser quirks mode.
      2. Core gadgets JavaScript libraries, as specified here.
      3. Feature library initialization code, if needed.
      4. Processed gadget content, the result of steps #4 and possibly #5.
      5. A single call to gadgets.util.runOnLoadHandlers();
      6. Standard HTML closing tags.
   2. For type URL gadgets, the provided URL MUST have the following parameters added to it:
      1. up_<name>=<value> for each provided user preference.
      2. lang=<language> and country=<country>, from the provided request Locale.
      3. 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.
         1. The server SHOULD consolidate all libs into a single request to minimize the number of HTTP requests made by the client browser.

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:

1. Load and parse gadget XML as described in Gadget Rendering Request steps #1 and #2.
2. Process gadget features, specified as <Require> or <Optional> in the gadget XML.
   1. Emit an error message if a required feature is not supported.
   2. Otherwise, for each requested, supported feature with container-side JavaScript, enqueue this JavaScript to return to the client.
3. Construct URL to the corresponding Gadget Rendering Request, generated as follows:
   1. Initialize URL using a static prefix.
   2. Add parameter url=<url>, where <url> is URL of the requested gadget spec.
   3. Add user prefs parameters as described in Gadget Rendering Request 6.ii.a.
   4. Add locale parameters as described in Gadget Rendering Request 6.ii.b.
4. 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.

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: