Sidebar Gadgets

Greetings! Gmail is now a gadget container. This document will teach you how to write useful gadgets which run well and take full advantage of the gadget API.


This document assumes:


The parent web page, which has an iframe on it that contains your gadget. In this document, Gmail is the container. Other examples would be iGoogle or Google Calendar.
Content Type
Gadgets come in 2 flavors, type='html' and type='url'. The default is type='html', and it is strongly encouraged. Here is additional documentation.
A set of JavaScript functions which the container makes available to the gadgets. An example is setting the gadget's height with feature="dynamic-height". Gmail as a container supports many of them documented below.
A web page, which runs in an iframe on the parent containers. (Note - this is a simplified definition.)
Gadget Specification / Gadget Spec
An XML file which contains the gadget metadata and display data. Here is the reference.
Public Internet
A web page which anyone on the Internet can access. An intranet or your local hard drive is not on the public Internet.
A view is a location where a gadget is displayed. Gmail supports the DEFAULT and CANVAS views.
The user who is logged into Gmail, and thus is viewing your gadget.

Developing your gadget

  1. Make a gadget spec. (Use the Hello World sample to get started.)
  2. Publish the gadget spec to a location which is accessible on the public Internet. An intranet will not work. Your hard drive will not work. (Why? The Google servers will download the gadget. If they can't reach it, then Gmail can't display it.)
  3. Load the Gmail 'Add any gadget by URL' lab feature. In Gmail, click on the 'beaker' icon in the top right corner to load the Labs page. Find the 'Add any gadget by URL' lab feature, and click 'Enable'. Finally, at the top or bottom of the page, click the 'Save Changes' button.
  4. Ask Gmail to load the gadget. Go to the 'Gadgets' tab of 'Settings', enter your gadget URL in the 'Add a gadget by its URL' box, and click the 'Add' button.
  5. After clicking 'Add', the gadget will appear in the left navigation of Gmail.

Publicizing your gadget

Publicizing the gadget uses almost the same method as developing it.

You can prompt a user to add your gadget by instructing them on how to enable the 'Add any gadget by URL' lab feature, and providing them with the URL for your gadget.

Gadget features that Gmail supports

Gmail supports many gadget features. Here are some of them:

Feature Library Description Syntax
setprefs Sets the value of a user preference programmatically. See Gadgets API Reference: Saving State for more information. Note: Gmail currently does not provide any UI for a user to modify the preferences. <Require feature="setprefs"/>
dynamic-height Gives a gadget the ability to resize itself. See Gadgets API Reference: Managing Gadget Height for more information. <Require feature="dynamic-height"/>
settitle Sets a gadget's title programmatically. See Gadgets API Reference: Setting a Gadget's Title for more information. <Require feature="settitle"/>
locked-domain The locked-domain library isolates your gadgets from other gadgets running on the same page. You can only use this feature with type="html" gadgets. We suggest that you add this feature requirement to your gadget if your gadget stores sensitive private user data. <Require feature="locked-domain"/>
views Allows specifying the location in a container where a gadget is displayed. See gadgets.* Developer's Guide: Creating a User Interface for more information. Note: Gmail currently only supports the CANVAS and DEFAULT views. <Content type="html" view="canvas">
opensocial-0.8 Allows access to social networking functions from within gadgets. <Require feature="opensocial-0.8"/>
OAuth Authorization Allows making authenticated requests to third-party services via makeRequest(). For more information, see Writing OAuth Gadgets. <OAuth/>