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. Hosting your gadget
   5. Using the Google Gadgets Editor to host your gadget
   6. Adding a gadget to iGoogle
   7. Viewing your gadget
   8. 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()
3. Publishing gadgets to the iGoogle content directory
   1. Using the Gadget Checker to test your gadget
   2. Using the Gadget Dashboard
4. Creating an "Add to Google" button
   1. Setting userprefs in the "Add to Google" URL
5. Supported languages and countries

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.

Gadget	Third party code that uses the gadgets 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.

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.

Hosting your gadget

Your gadget must be publicly available on the web in order for iGoogle to access it. The source files of your gadget can be hosted on any reliable web host. A few options available from Google which work for gadget hosting are Google App Engine, Google Code Project Hosting, or the Google Gadgets Editor. The Google Gadgets Editor is a convenient way to try out gadgets and host them immediately.

If you're familiar with software development already, you can try using the OpenSocial Development Environment (OSDE) to build your gadget. OSDE works with the Eclipse IDE and is bundled with a Shindig server for local testing. OSDE can create gadgets for iGoogle or OpenSocial containers.

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 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!":

Note: Users have recently reported problems using Google Gadgets Editor in some browsers. Firefox is known to work well with GGE.

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

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 your iGoogle page and see the gadget you just added.

You can also add gadgets through the developer gadget.

Viewing your gadget

iGoogle 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 iGoogle page for development add the developer gadget.

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.

Gadgets

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

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

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

Publishing a gadget to the iGoogle content directory

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.

Using the Gadget Checker to test your gadget

You can use the Gadget Checker to test your gadget before submitting it to the directory. The Gadget Checker includes the following features:

• Gives you multiple ways to specify the gadget you want to test: URL, or the local file system.
• Tests the gadget for XML formatting and validity, HTML syntax, client-side latency, and unused features. Flags missing content such as metadata, images, scripts, message bundles, and stylesheets.

The following sections provide detailed guidelines for preparing your gadget to be submitted to the content directory.

Step 1: Provide complete metadata.

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:

• title: String that provides the title of the gadget.
• description: This attribute is important to let people know what your gadget does, particularly if it is not obvious.
• author: String that lists the author of the gadget.
• author_email: This is so that Google and users of your gadget can contact you. You can use any email system, but you should not use a personal email address because of spam. One approach is to use an email address of the form 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.
• screenshot: This is a string that gives the URL for a gadget screenshot. This must be a well-formed URL, not a relative URL. This image must be on a public web site that is not blocked by 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.
• thumbnail: Thumbnails are used in the content directory to give users a preview of a gadget. They should capture the main functionality of your gadget without showing it in its entirety. The value for this attribute is a string that gives the URL for a gadget thumbnail. This must be a well-formed URL, not a relative URL. This image must be on a public web site that is not blocked by 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.
• author_location: The author's geographical location, such as "Mountain View, CA, USA ".
• author_affiliation: Optional string such as "Google" that indicates the author's affiliation. This attribute is required for gadgets that are included in the content directory.
• title_url: You use this attribute to link your gadget title to an external HTML page. For example, if your gadget is a front end for a service, you can link the gadget title to that service's website.
• directory_title: Title that should be displayed for your gadget in the content directory (required if title contains user preference substitution variables).

If you want to be listed on the authors page, you can include these additional fields:

• author_photo: URL to a photo (70x100 PNG format preferred, but JPG/GIF are also supported).
• author_aboutme: A statement about yourself (try to keep to ~500 characters).
• author_link: A link to your website, blog, etc.
• author_quote: A quote you'd like to include (try to keep to ~300 characters).

You can find more information here, and an example here.

Step 2: Make sure that you have written a robust, secure gadget.

Make sure you have coded your gadget in a way that minimizes any security risks.

Step 3: Add any relevant locale information.

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.

Step 4: Make it easy for people to add your gadget.

To promote your gadget, consider placing an Add to Google button on your website.

Step 5: Submit your gadget to Google.

Once you're ready to submit your gadget, visit the Gadget Dashboard. If it's your first time using the Gadget Dashboard, you'll be asked for the Gadget URL immediately. Once you have some gadgets in the dashboard, you add more using the "Add gadget to dashboard" button near the top right of the list.

See the FAQ for an explanation of how to find your gadget in the directory, and what determines its placement.

Managing Submitted Gadgets

If you have submitted multiple versions of a gadget at different URLs and you want to designate one version as the official one use this form to request the change.

Using the Gadget Dashboard

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:

1. Sign into iGoogle.
2. Go to the dashboard.
3. Agree to the Terms and Conditions.
4. Once you're in the dashboard, use the add gadget to dashboard button to add gadgets.

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.

Creating an "Add to Google" button

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.

Setting userprefs in the "Add to Google " URL

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 display
• myphoto: 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 (%).

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.