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 the iGoogle sandbox, you add friends using the Sandbox Friends gadget. |
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 tools tab.
The developer tools tab includes the following gadgets:
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 Friends gadget lets you add friends and manage your iGoogle contacts.
To get started, click Show and edit my friends list in the Sandbox Friends gadget. This displays the Contacts canvas view. The Contacts canvas view offers the following default groups for you to use as a starting point:
You can add people to existing groups, and you can also create new groups, as described in the following table under "Add a New Group."
To manage your iGoogle friends and contacts, you have the following options:
Here is a summary of the tasks you can perform in the Contacts canvas view:
| Task | How To |
|---|---|
| Add a New Group | Click the  button to add a new group. When prompted, type a name for the new group. |
| Add Contacts to a Group | Select My Contacts in the left column to display your contacts. In the middle column, select the people you want to add to a particular group. In the right-hand edit column, choose Groups > Add To > group-name. Alternatively, you can select the group and use the Add to this group text field. |
| Add a New Contact | Click the  button to add a new contact. This lets you add a new person from scratch--one that is not yet listed in your contacts or "Suggested Contacts." In the right-hand edit column, enter information for your new contact. This should minimally include an email address. When you are done, click Save. |
| Delete a Contact from a Group | Select the group. Select the contact. In the right-hand edit column, choose Groups > Remove From > group-name. |
| Edit an Existing Contact | In the left column, select a group that contains the contact you want to edit. In the middle column, select the contact. In the right-hand edit column, edit the persons information. When you are done, click Save. |
| Turn a Contact into a Friend | People in your Friends group have special significance in the OpenSocial API, because you can access them programmatically. To designate someone as a friend, add that person to the Friends group as described above under "Add Contacts to a Group." See the tutorial for examples of working with friend data. |
| Export Contacts | You can export your contacts to a file format that can be read by other tools. Click the Export link in the upper right corner, and choose the format you want to export to. |
| Import Contacts | You can import contacts from a CSV (comma-separated value) file. Click the Import link in the upper right corner, and browse to the file containing the contacts you want to import. |
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 the OpenSocial JavaScript Developers Guide.
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" */<sup class="changed">New!</sup>
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:
Here is the code for the gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs
title="Our Grocery List"
scrolling="true">
<optional feature="shareable-prefs"/>
</ModulePrefs>
<UserPref name="mylist"
display_name="Add items"
datatype="list" />
<Content type="html">
<![CDATA[
<div id="content_div" style='color: #CC0099; font-family: serif; font-size: 120%;'></div>
<script type="text/javascript">
// Get userprefs
var prefs = new gadgets.Prefs();
// Get the list
var items = prefs.getArray("mylist");
var html = "";
// If there are no items in the list yet, display message.
if (items.length == 0)
{
html += "Edit the userprefs to add items to the list.";
}
else {
for (var i = 0; i < items.length ; i++) {
var term = (items[i]);
html += term + "<br />";
}
}
document.getElementById("content_div").innerHTML = html;
</script>
]]>
</Content>
</Module>
Once you have added a gadget that supports shareable prefs to iGoogle, you can make it collaborative, as follows.
Step 1: Click the triangle on the gadget you want to share and choose Share this gadget.
Step 2: If you're a Gmail user, pick the friends you want to share with or type in their email addresses.
Step 3: Decide whether you want to let your friends edit your gadget content or just view it on their iGoogle page.
Click Send Invites. Your friends get an email from you inviting them to add the gadget it to their own iGoogle page.
Friends that you've authorized to edit the gadget can then modify the gadget's userprefs and publish their changes to all shared versions of the gadget.
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"/>
You can programmatically check for this as follows:
gadgets.util.hasFeature("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:
When OpenSocial gadgets are available to all iGoogle users, users must grant permission before gadgets are allowed access to social data. To ease development, sandbox gadgets are allowed access to social data by default, with the option for users to disable access.
If your gadget accesses social data, you should design it to have a graceful fallback if users deny access. For example, this gadget displays the message "You do not have permission to access social data " if the user turns off access to social data:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="ACL Example" >
<Require feature="opensocial-0.8"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<h3>Your Data</h3>
<div id="output">You do not have permission to access social data.</div>
<script type="text/javascript">
/**
* Request the OWNER.
*/
function requestData() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.OWNER), "owner");
req.send(showData);
};
/**
* Shows the response from the request for Person data.
*/
function showData(data) {
var owner = data.get("owner").getData();
var ownerOutput = document.getElementById("output");
showPerson(owner, ownerOutput);
}
/**
* Prints information about a person.
*/
function showPerson(person, div) {
var name = person.getDisplayName();
var thumb = person.getField(opensocial.Person.Field.THUMBNAIL_URL);
var html = '<img src="' + thumb + '"/>' + name;
div.innerHTML = html;
}
//Execute requestData when the page is done loading
gadgets.util.registerOnLoadHandler(requestData);
</script>
]]>
</Content>
</Module>
For information on working with permissions programmatically, see the OpenSocial Developers Guide.
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.
The iGoogle sandbox 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)
The iGoogle sandbox limits how much persistent data (appdata) an individual user instance can store (for more discussion of appdata, see the OpenSocial JavaScript Developers Guide). 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.
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 API home page.