This guide will help you build and manage gadgets within the iGoogle environment. It is meant for developers who have some general familiarity with iGoogle, the Gadgets API, and JavaScript. The guide also provides links to other resources relating to gadget development in iGoogle.
Each gadget container has a different development experience. This section describes the process of developing gadgets for use on iGoogle.
This guide uses the following terms to describe elements and topics related to the iGoogle development experience.
| Gadget | Third party code that uses the gadgets and OpenSocial APIs to extend the iGoogle experience. |
|---|---|
| Gadget definition | XML file that defines the gadget. Syntax is based on gadget XML, also known as the "gadget spec". |
| Gadget directory | Listing of available gadgets, ranked based on popularity and user feedback. |
| Left navigation | The list of links on the left hand side of iGoogle pages. The left navigation lists links to the canvas view for each gadget on a user's page. |
| Left navigation link | A link on the left navigation that opens a gadget's canvas page. |
| View | The location where a gadget is displayed. In iGoogle, gadgets can be displayed on either the canvas or home views. Both views are private. iGoogle does not allow users to see each other's gadgets. |
| Home view | The small view for a gadget, displayed with other gadgets. Shows all of your gadgets in their small display format. The home view is private, meaning that it is only visible to the logged in user. |
| Canvas view | The large view for a gadget, displayed alone without any other gadgets. The canvas view is private, meaning that is it only visible to the logged in user. |
| Friends | The OpenSocial API provides access to a user's network of friends. In iGoogle, you add friends using the Friends link in the left navigation. |
Before building gadgets for iGoogle it is useful to first familiarize yourself with the various features of gadgets and how they work together. A helpful guide is the Anatomy of an iGoogle Gadget document.
If this is your first gadget, follow the steps listed in the OpenSocial Tutorial to familiarize yourself with the OpenSocial API. This tutorial covers the steps needed to develop a simple gift-giving gadget using the OpenSocial API.
If you have an existing gadget you can enhance it to take advantage of some of the new features offered through the iGoogle sandbox, including:
If you do not have access to a server to store your gadget XML files, the Google Gadgets Editor (GGE) is a great tool to quickly edit and host gadgets. To create a quick "Hello World" gadget, make sure that you are logged in with a Google account (or else you cannot save your gadget) and modify the following gadget in GGE. For example, change the message "Hello, world!" to "Hello, iGoogle!":
Use File > Save As to save the file with the name "igoogle-sample.xml." Once you've done this, open your gadget's XML file by clicking on the filename in the top right-hand corner of the editor.
This opens the gadget XML in your browser. You'll need the URL of this file to install your gadget in the next section.
Gadgets need to run inside of a container in order to access social network data. iGoogle offers a developer sandbox where you can access the OpenSocial APIs and other new features. You can sign up for the sandbox here.
To add a new gadget:
You can also add gadgets through the developer gadget, once you've added the developer tools tab.
The iGoogle sandbox provides two different views for displaying your gadget. The first is the home view. In the home view, your gadget displays in a 3-column format along with any other gadgets you've added:
To see a gadget at its maximum size, you can display it in the canvas view by clicking its link under Home. By default, gadgets only display in their small format. For information on adding a canvas view to your gadget, see Views.
For example, here is a books gadget in the home view. It simply lists the user's reading list, the user's friends' books, and recommended books:
The book gadget's expanded canvas view offers a richer experience, with tabs, more detail about the user's books, and the user's reviews:
The home and canvas views in iGoogle are private, meaning that they cannot be viewed by anyone but the logged in user. This is a key distinction between iGoogle and some other social gadget containers, such as orkut.
To set up your sandbox development environment, log into the sandbox and add the developer gadget and add the Sandbox Profile Editor gadget.
The developer gadget acts a "command center" for all of the gadgets on your iGoogle page. In addition to listing all the gadgets that you're running, it lets you add, view, and manage gadgets. The developer gadget gives you features that you need if you're doing gadget development. For example, it lets you add gadgets that are "broken," which is useful when you are actively changing a gadget.
In the developer gadget you can click on individual gadget links to view their XML specifications. This is a good way to see how other gadgets are implemented.
One feature that helps you in developing gadgets is the Cached checkbox. By default, gadget specifications are cached. You should uncheck Cached for gadgets while you are working on them. This lets you see the latest version of your gadget instead of the cached version.
The Sandbox Profile Editor gadget lets you edit your iGoogle sandbox profile. Note that the only profile information that is accessible through the API is the user ID, name, location, and thumbnail URL. For more information, see Profile data.
Now that you've learned the basics for installing and updating gadgets, here are some tips and tricks to help you build gadgets that take advantage of the features of the iGoogle sandbox.
OpenSocial gadgets are a new type of gadget, based on gadgets technology, but extended to interact with social data retrieved from a website (also referred to as a container) that supports the OpenSocial API. iGoogle is an example of an OpenSocial container, and this section focuses on the development aspects of working with gadgets within the iGoogle environment.
A view is a location in a container where a gadget is displayed. Different views have different characteristics. For example, a container might have a view that shows gadgets in a small format, and a view that shows gadgets in full page format.
By default in the iGoogle sandbox, a gadget displays in home view mode ("small mode"), meaning that it appears in a column layout among other gadgets. To create a canvas ("big mode") view of your gadget, where the gadget expands horizontally to span the entire gadget area, you must define a <Content> section for the "canvas" view type, as follows:
<Content type="html" view="canvas">
Once you define a <Content> section for the canvas view, you
must also create a <Content> section to make the gadget display
properly in the home view. This can either be "default" or "home".
For more discussion of writing gadgets that support multiple <Content> sections,
see Multiple
Content Sections.
Here is a version of the Hello World gadget that defines <Content> section views for "home" and "canvas". Its width changes according to whether you display it in the home view or the canvas view.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Hello World!">
<Require feature="opensocial-0.8" />
</ModulePrefs>
<Content type="html" view="home">
<![CDATA[
Hello, small world!
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
Hello, big world!
]]>
</Content>
</Module>
Views are supported across OpenSocial containers, but each container may support a different set of views. For example, iGoogle has a small view called home, but the small view in orkut it is called profile.
Suppose you want to write a gadget that had the same display for home on iGoogle and profile on orkut. Instead of creating duplicate <Content> sections, you could concatenate the views for a single <Content> section, as follows:
<Content type="html" view="home,profile">
You can use this technique either across containers or within the same container. For example, gadgets that handle presentation logic for differently sized views in a single <Content> section can extend that support to the canvas page by declaring view="home,canvas".
In iGoogle, your gadget can be displayed in the canvas and home views. Both views are visible only to the logged-in user.
The easiest way to get the current view is to include the "views" feature in your gadget module preferences:
<ModulePrefs title="Views example"> <Require feature="views" /> </ModulePrefs>
When the views feature is included, you can obtain the current view by
calling the gadget.util.getCurrentView() function. This assigns a gadgets.views.View
object to the current_view variable. See Available views in iGoogle for a listing of
views that may be returned by this call.
The following example demonstrates getting the current view and conditionally executing code against the returned value:
function getViewName() {
return gadgets.views.getCurrentView().getName();
}
if (getViewName() == "canvas") {
/* Do canvas specific stuff here */
}
if (getViewName() == "home") {
/* Do home specific stuff here */
}
<Require
feature="views"> in the ModulePrefs section of your
gadget.Obtain the available View objects by calling
the gadgets.views.getSupportedViews() function.
var supported_views = gadgets.views.getSupportedViews();
The object returned by the getSupportedViews call contains
gadgets.views.View
objects representing all of the available views in iGoogle, indexed by view name.
The gadget's home view shows content and notifications that are the most interesting to the user. It’s a good place for summarizing content, and for providing a quick way for users to complete simple tasks.
The gadget's canvas view provides an expanded space to allow richer content and greater functionality. Take advantage of this view to engage users, show them what their friends are doing, and allow them to complete complex tasks.
<Require
feature="views"> in the ModulePrefs section of your
gadget.If you wish to provide links to other views, you need to pass a
gadgets.views.View object to the
gadgets.views.requestNavigateTo() method. You can choose to use one
of the objects returned by the getSupportedViews() call
described in the Available views in iGoogle. The
following code sample demonstrates this method:
function navigateTo(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
navigateTo("canvas");
};
/**
* When called, this method asks the container to switch to the home
*/
function gotoHome() {
navigateTo("home");
};
An alternative is to create a new View object manually, and
then use that to initiate navigation. The following code sample shows creating a new
gadgets.views.View object and
passing it to the gadgets.views.requestNavigateTo() method:
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view);
};
/**
* When called, this method asks the container to switch to the home
*/
function gotoHome() {
var home_view = new gadgets.views.View("home");
gadgets.views.requestNavigateTo(home_view);
};
Here is a complete example based on the "Hello World" gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs height="100" title="Navigation">
<Require feature="views" />
</ModulePrefs>
<Content type="html" view="home">
<![CDATA[
<div>Hello world Home view</div>
<script type="text/javascript">
function goToView(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
</script>
<a href="javascript:goToView('canvas')" >Go to canvas view</a><br><br>
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
<div>Hello world Canvas view</div>
<script type="text/javascript">
function goToView(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
</script>
<a href="javascript:goToView('home')" >Go to home view</a><br><br>
]]>
</Content>
</Module>
Note: In OpenSocial 0.8, there is no call to return your gadget's ID number. Store this value manually if you wish to use it in your gadget.
<Require
feature="views"> in the ModulePrefs section of your
gadget.If you are using the gadgets.views.requestNavigateTo() calls, you
may supply an optional parameter containing data to be passed to the new page.
The following code passes two variables: foo and
bar to the canvas surface of the current gadget:
function gotoCanvas(params) {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view, params);
};
var my_params = {
foo : 12345,
bar : "Bar value"
};
gotoCanvas(my_params);
In the canvas view, check for these values with the following code:
var prefs = gadgets.views.getParams(); var foo = prefs["foo"]; /* foo contains 12345 */ var bar = prefs["bar"]; /* bar contains "Bar value" */
In iGoogle, each gadget has a menu that includes a Share this gadget menu item. Share this gadget launches a popup that lets you select recipients from your list of iGoogle friends. You can also specify unlisted recipients by email address. This is the default mechanism for sharing gadgets.
But suppose you want to customize how your gadget gets shared. For example, maybe
you want to display a custom message, or modify the
list of potential recipients. You can customize gadget sharing by using the requestShareApp() method.
The requestShareApp() method takes the following parameters:
| Name | Type | Description |
|---|---|---|
recipients |
opensocial.IdSpec |
An IdSpec used to specify which people/groups to send the request to. Note that the maximum number of IDs that can be passed in is 50. Any IDs beyond that number are ignored. |
reason |
opensocial.Message |
The reason the user wants to share the gadget. This reason can be used by the container when prompting the user for permission to share the app. It may also be ignored. |
opt_callback |
Function |
The function to call once the request has been processed; either this callback
is called or the gadget is reloaded from scratch. The callback function
is not called until after the existing callstack has completed execution. The callback function is passed one parameter, an If the container does not support this method, the callback is called
with an |
opt_params |
opensocial.NavigationParameters |
The optional parameters indicating where to send a user when a request is
made, or when a request is accepted; options are of type NavigationParameters.DestinationType. |
Here is a simple example that illustrates how requestShareApp() works
in iGoogle. It's a gadget that has a button that lets users share the gadget with
their friends.

When users click the Share me! button, they see a popup that lets them specify the friends with whom they want to share the gadget.
Here is the code for the sample gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs height="325" title="requestShareApp Example" >
<Require feature="views" />
<Require feature="opensocial-0.8" />
</ModulePrefs>
<Content type="html" view="home, canvas">
<![CDATA[
<script type="text/javascript">
function shareApp() {
var recipient = null;
var reason = opensocial.newMessage('Install this gadget to help share the love.');
opensocial.requestShareApp(recipient, reason, function(response){
if (response != null && response.hadError()) {
alert('requestShareApp Error Code[' + response.getErrorCode() + '] Msg: ' + response.getErrorMessage());
} else if (response != null) {
alert ('requestShareApp OK, Data[' + gadgets.json.stringify(response.getData()) + ']');
} else {
alert('requestShareApp callback has null response');
} });
};
</script>
<div style="text-align: center">
<img src="http://gadget-doc-examples.googlecode.com/svn/trunk/images/Trevor.png" />
<br><br>
<input type="button" onclick="shareApp()" value="Share me!"/><br><br>
</div>
]]>
</Content>
</Module>
Note the following:
["name", "ID"],
where name is the contact's name, and ID is the OpenSocial ID. ["email-fragment", "-1"], where email-fragment is
the portion of the user's email before the "@".
ID is always -1 in this case. When you share a gadget with friends, how they receive the invitation depends on whether they have an iGoogle homepage:
Note: This feature is being deprecated. To create
gadgets that allow multiple users to share editable data, we recommend you use requestShareApp() in
conjunction with appdata.
You can use the shareable-prefs feature to make it possible for a gadget's user preferences to be edited by multiple users. Thus, users can share the gadget and see each other's edits. For example, family members could share a grocery list gadget, with each person adding his or her favorite items. User preference data is the part of the gadget state that is hosted by iGoogle. For more information about userprefs, see the Gadgets API Developers Guide.
To share a gadget's userprefs across multiple users, the gadget must include
the line <optional feature="shareable-prefs"/> in
the <ModulePrefs> section. For example, this
gadget uses the list
data type userpref to populate a grocery list.
Previously, gadgets installed in the iGoogle developer sandbox had implicit access to social data, with no way for users to opt-out without uninstalling the gadget. Now gadgets include a feature that allows users to explicitly grant or deny the gadget access to social data. Gadgets that access social data include the opensocial-x.x feature:
<Require feature="opensocial-0.8"/>
When users install gadgets that use social data (indicated by requiring the OpenSocial feature), they are prompted to give permission to access social data. If a gadget is released without social features and is upgraded, users will be prompted for access within the gadget when the new version is first rendered:

Users must grant permission before gadgets are allowed access to social data. Your gadget should have a graceful fallback if users deny access. Check out the Testing iGoogle State gadget for an example of determining whether or not the user has granted permission to access social data.
For a complete list of iGoogle states and how to handle them, refer to this blog post.
Updates are activities posted to a user's friends about actions that the user has made while interacting with an iGoogle gadget. The built-in Updates view displays a running list of all posted updates (activities), starting with the most recent.
Updates in iGoogle have the following characteristics:
<Name> <verb> <content>.
For example: Chris Smith shared <link>a news article
from nytimes</link>.This sample gadget lets you enter an update in a text box and then click Post Update to post it to the user's updates feed:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Post Updates" >
<Require feature="opensocial-0.8"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
// Post an activity and set its title to be the text the user entered in the
// text box.
function postUpdate(form) {
var text = form.inputbox.value;
var div = document.getElementById('content_div');
var params = {};
params[opensocial.Activity.Field.TITLE] = text;
var activity = opensocial.newActivity(params);
opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH);
div.innerHTML = "Update title is: " + activity.getField(opensocial.Activity.Field.TITLE);
}
</script>
<FORM NAME="myform" ACTION="" METHOD="GET">Add Update: <BR>
<INPUT TYPE="text" NAME="inputbox" VALUE=""><P>
<INPUT TYPE="button" NAME="button" Value="Post Update" onClick="postUpdate(this.form)">
</FORM>
<div id="content_div"></div>
]]>
</Content>
</Module>
The above example only accesses the TITLE field of the Activity object. iGoogle also supports these optional fields: BODY, MEDIA_ITEMS, STREAM_FAVICON_URL, and STREAM_URL.
The OpenSocial API provides access to information about iGoogle's users in the form of profile data. This section describes which profile fields are available in iGoogle. The iGoogle sandbox provides the Profile gadget for users to edit their profile data.
iGoogle lets you access the following fields for the current user, through a Person object:
getId()getDisplayName()getField(opensocial.Person.Field.THUMBNAIL_URL)
getField(opensocial.Person.Field.CURRENT_LOCATION)
iGoogle limits how much persistent data (appdata) an individual user instance can store (for more discussion of appdata, see The Persistence API). The limit is 10KB. If an attempted appdata write operation exceeds this quota, it will fail with a "quota exceeded" error.
Once you have designed, implemented, and tested your gadget, you may decide to submit it to Google to be published in the iGoogle content directory. This section lists the general steps you should follow in preparing any gadget to be published.
You can use the Gadget Checker to test your gadget before submitting it to the directory. The Gadget Checker includes the following features:
The following sections provide detailed guidelines for preparing your gadget to be submitted to the content directory.
The Reference lists all of the <ModulePrefs> attributes that you can use to provide "meta" information about your gadget. Here is the information you should include in your gadget spec:
helensmith.feedback+coolgadget@gmail.com in
your gadget spec. Gmail drops everything after the plus sign
(+), so this email address maps to helensmith.feedback@gmail.com.
You can create a Gmail account here. robots.txt.
PNG is the preferred format, though GIF and JPG are also acceptable.
Gadget screenshots should be 280 pixels wide. The height of
the screenshot should be the "natural" height of
the gadget when it's in use. This helps users understand how
much space a gadget will consume on their screen before they
add it to their page. The screenshot should not have any whitespace
above the gadget's blue header bar. Screenshots should show
your full gadget, including its title bar, but nothing else.
Alternatively, you can screenshot the gadget with the edit
window open. Screenshots should not be resized or
cropped. For quality and consistency, Google may take
its own screenshots of a given gadget.robots.txt.
PNG is the preferred format, though GIF and JPG
are also acceptable. Thumbnails should be 120x60 pixels.
They should not include title bars. If you want to be listed on the authors page, you can include these additional fields:
You can find more information here, and an example here.
Make sure you have coded your gadget in a way that minimizes any security risks.
You can use <Locale> tags under <ModulePrefs> to specify the locales supported by your gadget. For more information, see ModulePrefs/Locale in the gadgets XML reference.
To promote your gadget, consider putting an Add to Google button on it.
You can submit your gadget to Google here. See the FAQ for an explanation of how to find your gadget in the directory, and what determines its placement.
If you have submitted multiple versions of a gadget at different URLs and you want to designate one version as the official one, you can use the igoogle-legacy issue tracker to request the change.
You can use the gadget dashboard to see analytics on your gadgets and manage them.
The dashboard identifies your gadgets through the ModulePrefs author_email attribute:
<ModulePrefs title="My Gadget" author_email="my_username@gmail.com"> ... </ModulePrefs>
Be sure to include the author_email attribute in your gadgets.
To use the dashboard:
The first time you add a gadget with a new author email address, the dashboard sends you email at that address asking you to verify that you want to add the gadget. You only need to verify each email address once.
The dashboard displays the following information for each gadget you add:
| Label | Description |
|---|---|
| Title | The gadget's title. |
| Users worldwide | The number of unique users who loaded this gadget in the last 7 days. |
| Page views | The number of times this gadget has been loaded by users in the last 7 days. |
| Comments worldwide | The comments your gadget has received from users. |
| Status | Whether your gadget has been added to the iGoogle directory. If it has not been added, the dashboard gives you the option of adding it. |
You can create an "Add to Google" button and put it on your website to help users find your gadget.
To create an "Add to Google" button for your gadget, go to Add to Google and follow the instructions.
When you generate the HTML to add to your web page, it resembles the following:
<a href="http://fusion.google.com/add?source=atgs
&moduleurl=http%3A//gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/prefs-example.xml">
<img src="http://gmodules.com/ig/images/plus_google.gif" border="0" alt="Add to Google"></a>
The portion of the HTML snippet highlighted in red is the URL that actually adds the gadget to iGoogle. You can even paste this URL directly into the address field of a browser to add the gadget. You can also manually modify this URL to set initial values for userprefs, as described in the next section.
If you have a gadget that includes userprefs and you want to add the gadget with settings other than the defaults specified in the gadgets spec, you can append the new userpref settings to the "Add to Google" URL.
The syntax is as follows:
http://fusion.google.com/add?source=atgs&moduleurl=[GADGET_URL]&up_[PREF_NAME]=[PREF_VALUE]
Note that the [PREF_VALUE] must be properly URL-escaped.
To give a concrete example, the sample prefs gadget includes the following userprefs:
mycolor: the background color.myname: the name to use in the displaymyphoto: the URL for a photo you want to display in the gadget. mychoice: whether or not to display the specified photo. This is a boolean, so the value for the URL parameter is either 1 (show photo) or 0 (don't show photo). Userpref URL parameters are prefixed with up_. So in the "Add to Google" URL, these userprefs become up_mycolor, up_myname, up_myphoto, and up_mychoice. Suppose you want to set myname to "Trevor" and mycolor to orange. You would do this by appending the following to the URL:
&up_myname=Trevor&up_mycolor=Orange
Here is the full URL for adding the gadget with the background color set to orange, and the name set to "Trevor" (you may have to scroll right to see the full URL). Since the other userprefs (myphoto and mychoice) are not set through this URL, they retain their original default values as specified in the gadget spec.
http://fusion.google.com/add?source=atgs&moduleurl=http%3A//gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/prefs-example.xml&up_myname=Trevor&up_mycolor=Orange
Note: When you use this technique, note that userpref value can only contain the characters that are in [a-z0-9%. -]. In other words, the userpref value can include alphanumeric characters and also the characters for period (.) , space ( ), dash (-), and percent (%).
For a list of the languages and countries supported by iGoogle, go here. For more information on writing gadgets that can be easily localized for an international audience, see the Gadgets API Developers Guide.
To continue learning about the OpenSocial API, check out the additional documentation and materials hosted at the OpenSocial wiki.