iGoogle Developer's Guide

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.

Contents

1. Getting familiar with gadgets in iGoogle
   1. iGoogle gadget terminology
   2. Anatomy of an iGoogle gadget
   3. Writing your first iGoogle gadget
   4. Using the Google Gadgets Editor to host your gadget
   5. Adding a gadget to iGoogle
   6. Viewing your gadget
   7. Setting up the development environment
2. Gadgets
   1. Views
   2. Concatenating views
   3. Determining the current gadget view
   4. Getting all available views
   5. Designing for the home view
   6. Designing for the canvas view
   7. Navigating to another view
   8. Obtaining the gadget's ID
   9. Passing data to your gadget through requestNavigateTo()
   10. Sharing user preferences
3. Updates
4. Profile data
5. Appdata limitations
6. Supported languages and countries
7. To learn more

Getting familiar with gadgets in iGoogle

Each gadget container has a different development experience. This section describes the process of developing gadgets for use on iGoogle.

iGoogle gadget terminology

This guide uses the following terms to describe elements and topics related to the iGoogle development experience.

Updates gadget	A gadget that displays a data feed that contains activities from one person.
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.

Anatomy of an iGoogle 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.

Writing your first iGoogle gadget

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.

Updating an existing iGoogle gadget

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:

• Views
• Friends
• Updates

Using the Google Gadgets Editor to host your gadget

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.

Adding a gadget to iGoogle

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:

1. Click the Personalize this page button. This takes you to the iGoogle directory. From the directory you can add an existing gadget, or you can add your own gadget.
2. To add your own gadget (for example, the "Hello World" gadget you created above), click the add feed or gadget link at the bottom of the left nav bar.
3. Type the URL for the gadget into the text field, and click Add.
4. Click the Back to iGoogle home link (upper left corner) to return to the sandbox and see the gadget you just added.

You can also add gadgets through the developer gadget, once you've added the developer tools tab.

Viewing your gadget

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.

Setting up the development environment

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:

• Developer gadget, to add gadgets and turn off caching.
• Sandbox Friends gadget, to add test friends in the sandbox.
• Sandbox Profile Editor gadget, to view and edit your sandbox profile.
• Updates gadget, to view a running list of all the user's posted activities, starting with the most recent.

Developer 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.

Sandbox Friends gadget

The Sandbox Friends gadget lets you manage your iGoogle sandbox friends.

Establishing someone as a sandbox friend is a two-part process. One person must issue an invitation, and the other person must accept it.

To view your invitations and invite others, click Invitations & Suggestions. This panel includes two lists:

• Friend Invitations -- Invitations others have sent you. If you accept an invitation, the person is added to your friends list.
• Friend Suggestions -- A selection of chat buddies who are not yet friends. If you click Ignore next to a person's name, the person is removed from the Friend Suggestions list.

To invite someone to be a friend, either click Add as friend next to a listed contact, or type a new email address in the text field. The email address must be associated with a Google account, or it will be silently dropped. Click Save changes to save changes you made in this panel. This step is important, because without it, any invitations you issued or accepted will not be processed.

Once you have accepted an invitation or had an invitation accepted, the person is added to your friends list. At this point the person becomes accessible through the OpenSocial API. See the tutorial for examples of working with friend data.

Sandbox Profile Editor gadget

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.

Updates gadget

The Updates gadget maintains a running list of all the user's posted activities, starting with the most recent.

For more discussion of updates, see Updates.

Gadgets

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.

Views

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.7" />
  </ModulePrefs>
  <Content type="html" view="home">
    <![CDATA[
      Hello, small world!
    ]]>  
  </Content>
  <Content type="html" view="canvas"> 
    <![CDATA[
      Hello, big world!
    ]]> 
  </Content>
</Module>

^New! Concatenating views

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".

Determining the current gadget view

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 */
}

Getting all available views

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.

Designing for the home view

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 friends' updates, and for providing a quick way for users to complete simple tasks.

• Remember that only the logged in user can see the home view. It is private.
• Gadgets should be flexible in width to accommodate various screen resolutions and maximize space efficiency.
• Recommended minimum width: 260 px (based on a 1024x768 resolution). Note that this is 40 px less due to the new left navigation.
• Height can vary. More concise gadgets tend to be more popular because users sacrifice less space for other gadgets.
• Users can access a gadget’s settings, remove a gadget, or go to canvas view by clicking buttons in a gadget's title bar.
  

Designing for the canvas view

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.

• Remember only the logged in user can see the canvas view. Like the home view, it is private.
• Gadgets should be flexible in width to accommodate various screen resolutions and maximize space efficiency.
• Recommended minimum width: 800 px (based on a 1024x768 resolution).
• Height can vary. Unlike home view, in canvas view only one gadget is being shown so take advantage of the additional space.
• Note that old gadgets will continue to work in the home view. The home view is the default. To benefit from canvas view, we encourage developers to add a canvas view to their existing gadgets, as described in Views.

Navigating to another view

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>

Obtaining the gadget's ID

Note: In OpenSocial 0.7, there is no call to return your gadget's ID number. Store this value manually if you wish to use it in your gadget.

Passing data to your gadget through requestNavigateTo()

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>

^New! Sharing user preferences

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.

• If you pick View and edit my content, your friends can edit the gadget's userprefs. Their changes will be reflected in your version of the gadget and any other shared versions of the gadget.
• If you pick View my content, your friends cannot modify the gadget, not even their local copies. Only you can modify the gadget, and your changes will be pushed to all shared versions of the gadget.

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.

Updates

Updates are activities posted to a user's friends about actions that the user has made while interacting with an iGoogle gadget. The Updates gadget displays a running list of all posted updates (activities), starting with the most recent.

This sample gadget lets you enter an update in a text box and then click Post Update to post it. Once you post it, you can see it by clicking Refresh Now in the Updates gadget:

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Post Updates" >
    <Require feature="opensocial-0.7"/>
  </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.

For development purposes, the iGoogle sandbox supports the ability to call getActivities() and get all activities for the user. Later, getActivities() will only return activities for a particular gadget. 

To use this debugging feature, set up the optional parameters as follows:

var optParams = {};
optParams[opensocial.DataRequest.ActivityRequestFields.APP_ID] = '*';

The asterisk (*) is a wildcard that indicates that you want all activities.

iGoogle's updates policies

The following table shows which events will be shown in which locations:

Event type	Updates gadget
Native events
Gadget install and uninstall	Yes
Events from gadgets	Yes

To avoid gadgets spamming the Updates gadget, there will be a maximum number of updates it can post each day per user. To make development easier, the sandbox does not currently have this limitation. See our FAQ for details.

Profile data

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.

Supported fields

The iGoogle sandbox lets you access the following fields for the current user, through a Person object:

• ID -- getId()
• Name -- getDisplayName()
• Thumbnail URL -- getField(opensocial.Person.Field.THUMBNAIL_URL)
• Location -- getField(opensocial.Person.Field.CURRENT_LOCATION)

Here is an example that fetches the user and displays his or her thumbnail, name, ID, and location:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
 <ModulePrefs title="Profile Example" scrolling="true">
   <Require feature="opensocial-0.7"/>
 </ModulePrefs>
 <Content type="html">

 <![CDATA[

 <script type="text/javascript">

 /**
  * Request for viewer information.
  */
  function getData() {    
    var req = opensocial.newDataRequest();
    req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.VIEWER), 'viewer');
    req.send(onLoadViewer);
  };

 /**
  * Display the viewer's thumbnail, name, ID, and location.
  */
  function onLoadViewer(dataResponse) {
    var viewer = dataResponse.get('viewer').getData();
    var thumb = viewer.getField(opensocial.Person.Field.THUMBNAIL_URL);
    var loc = viewer.getField(opensocial.Person.Field.CURRENT_LOCATION);
    var address = loc.getField(opensocial.Address.Field.UNSTRUCTURED_ADDRESS);
    var html = "<img src=\"" + thumb + "\"/><br />";
    html += "The ID for " + viewer.getDisplayName() + " is " + viewer.getId()+"<br />"; 
    html += "The location for " + viewer.getDisplayName() + " is " + address;
    document.getElementById('message').innerHTML = html;
  };

  gadgets.util.registerOnLoadHandler(getData);

  </script>
  <div id="message"> </div>
  ]]>
  </Content>
</Module>

Appdata limitations

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.

^New! Supported languages and countries

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 learn more

To continue learning about the OpenSocial API, check out the additional documentation and materials hosted at the OpenSocial API home page.