My favorites ▼ | English ▼ | Sign in

Gadgets API

Gadgets.* Migration Guide

This document describes how to migrate a gadget from the legacy gadgets API to the gadgets.* API. The gadgets.* API is a re-namespaced version of the legacy API, so for many functions gadgets.* offers a drop-in replacement. The tables below list the legacy gadgets API functions and their gadgets.* equivalents, if available, or a recommendation of what to use if an equivalent does not exist.

Contents

  1. Core API
  2. Feature-specific API
  3. Notes for inlined gadgets

Core API

Convenience methods

Legacy gadgets.* or pure JS replacement Comments
_args gadgets.util.getUrlParameters
_esc encodeURIComponent
_gel document.getElementById
_gelstn none If you need to use _gelstn, you can include the following method definition in your code: 
function _gelstn(tag) {
  if (n === "*" && document.all) {
    return document.all;
  }
  return document.getElementsByTagName ?
         document.getElementsByTagName(n) : [];
}
_hesc none If you need to use _hesc, you can include the following method definition in your code: 
function _hesc(str) {
  // '<' and '>'
  str = str.replace(//g, ">");
  // '"' and '
  str = str.replace(/"/g, """).replace(/'/g, "'");

  return str;
}
_min none If you need to use _min, you can include the following method definition in your code: 
function _min(a, b) {
  return (a < b ? a : b);
}
_max none If you need to use _max, you can include the following method definition in your code: 
function _max(a, b) {
  return (a > b ? a : b);
}
_toggle none If you need to use _toggle, you can include the following method definition in your code: 
function _toggle(el) {
  el = document.getElementById(el);
  if (el !== null) {
    if (el.style.display.length === 0 || el.style.display === "block") {
      el.style.display = "none";
    } else if (el.style.display === "none") {
      el.style.display = "block";
    }
  }
}
Third-party libraries such as jQuery also offer a toggle feature.
_uc none If you need to use _uc, you can include the following method definition in your code: 
function _uc(value) {
  return value.toUpperCase();
}
However, the preferred solution is to rewrite any references to _uc to instead use the toUpperCase method, inline, directly on the string object.
_unesc decodeURIComponent

Prefs

Legacy gadgets.* or pure JS replacement Comments
_IG_Prefs gadgets.Prefs var prefs = new _IG_Prefs(); becomes var prefs = new gadgets.Prefs();, and the getter and setter methods on the prefs variable remain the same between the two API versions.

Fetch content

Legacy gadgets.* or pure JS replacement Comments
_IG_FetchContent gadgets.io.makeRequest The parameter ordering and available options are different between _IG_FetchContent and gadgets.io.makeRequest. To emulate the plain-text return format of _IG_FetchContent, you should pass in a params object as follows: 
var params = opt_params || {};
params["CONTENT_TYPE"] = gadgets.io.ContentType.TEXT;
gadgets.io.makeRequest(url, callback, params);
You can access data in the callback by reading the data property of the first argument (obj) passed to the callback: 
function callback(obj) {
  console.log(obj.data);
}
This differs from the legacy API, in which you would use obj directly. For more details on the arguments available for gadgets.io.makeRequest see the OpenSocial wiki. If you need to use _IG_FetchContent, you can include the following method definition in your code: 
function _IG_FetchContent(url, callback, opt_params) {
  var params = opt_params || {};
  params["CONTENT_TYPE"] = gadgets.io.ContentType.TEXT;
  
  gadgets.io.makeRequest(url, function(obj) {
    callback(obj.data);
  }, params);
}
_IG_FetchXmlContent gadgets.io.makeRequest The parameter ordering and available options are different between _IG_FetchXmlContent and gadgets.io.makeRequest. To emulate the XML return format of _IG_FetchXmlContent, you should pass in a params object as follows: 
var params = opt_params || {};
params["CONTENT_TYPE"] = gadgets.io.ContentType.DOM;
gadgets.io.makeRequest(url, callback, params);
You can access data in the callback by reading the data property of the first argument (obj) passed to the callback: 
function callback(obj) {
  console.log(obj.data);
}
This differs from the legacy API, in which you would use obj directly. For more details on the arguments available for gadgets.io.makeRequest see the OpenSocial wiki. If you need to use _IG_FetchXmlContent, you can include the following method definition in your code: 
function _IG_FetchXmlContent(url, callback, opt_params) {
  var params = opt_params || {};
  params["CONTENT_TYPE"] = gadgets.io.ContentType.DOM;
  
  gadgets.io.makeRequest(url, function(obj) {
    callback(obj.data);
  }, params);
}
_IG_FetchFeedAsJSON gadgets.io.makeRequest The parameter ordering and available options are different between _IG_FetchFeedAsJSON and gadgets.io.makeRequest. To emulate the JSON return format of _IG_FetchFeedAsJSON, you should pass in a params object as follows: 
var params = opt_params || {};
params["CONTENT_TYPE"] = gadgets.io.ContentType.FEED;
gadgets.io.makeRequest(url, callback, params);
You can access data in the callback by reading the data property of the first argument (obj) passed to the callback: 
function callback(obj) {
  console.log(obj.data);
}
This differs from the legacy API, in which you would use obj directly. For more details on the arguments available for gadgets.io.makeRequest see the OpenSocial wiki. If you need to use _IG_FetchFeedAsJSON, you can include the following method definition in your code: 
function _IG_FetchFeedAsJSON(url, callback, opt_params) {
  var params = opt_params || {};
  params["CONTENT_TYPE"] = gadgets.io.ContentType.FEED;
  
  gadgets.io.makeRequest(url, function(obj) {
    callback(obj.data);
  }, params);
}

Cache

Legacy gadgets.* or pure JS replacement Comments
_IG_GetCachedUrl gadgets.io.getProxyUrl
_IG_GetImage none If you need to use _IG_GetImage, you can include the following method definition in your code: 
function _IG_GetImage(url) {
  var img = document.createElement("img");
  img.src = gadgets.io.getProxyUrl(url);
  return img;
}
_IG_GetImageUrl gadgets.io.getProxyUrl

Other

Legacy gadgets.* or pure JS replacement Comments
_IG_RegisterOnloadHandler gadgets.util.registerOnLoadHandler This is equivalent to setting window.onload to the function passed to gadgets.util.registerOnLoadHandler.
_IG_Callback none If you need to use _IG_Callback, you can include the following method definition in your code: 
function _IG_Callback(callbackFunction, parameters) {
  var args = arguments;
  return function() {
    var combinedArgs = Array.prototype.slice.call(arguments);
    callbackFunction.apply(null,
      combinedArgs.concat(Array.prototype.slice.call(args,1)))
  }
}

Feature-specific API

dynamic-height

Legacy gadgets.* or pure JS replacement Comments
_IG_AdjustIFrameHeight gadgets.window.adjustHeight

settitle

Legacy gadgets.* or pure JS replacement Comments
_IG_SetTitle gadgets.window.setTitle

tabs

Legacy gadgets.* or pure JS replacement Comments
_IG_Tabs gadgets.TabSet var tabs = new _IG_Tabs(); becomes var tabs = new gadgets.TabSet();, and the methods on the tabs variable, as well as the methods on the individual gadgets.Tab objects that it comprises, remain the same between the two API versions.

drag

Legacy gadgets.* or pure JS replacement Comments
_IG_Drag none The drag library is not supported by gadgets.*. If you need drag functionality, it's recommended that you use a third-party UI library such as:

grid

Legacy gadgets.* or pure JS replacement Comments
_IG_Grid none The grid library is not supported by gadgets.*. If you need grid functionality, it's recommended that you use a third-party UI library such as:

minimessage

Legacy gadgets.* or pure JS replacement Comments
_IG_MiniMessage gadgets.MiniMessage var mini = new _IG_MiniMessage... becomes var mini = new gadgets.MiniMessage..., and the methods on the mini variable remain the same between the two API versions.

analytics

Legacy gadgets.* or pure JS replacement Comments
_IG_Analytics none The analytics feature is not part of the gadgets.* API, however, it remains supported in its current form.
_IG_GA none The com.google.gadgets.analytics feature is not part of the gadgets.* API, however, it remains supported in its current form.

flash

Legacy gadgets.* or pure JS replacement Comments
_IG_EmbedFlash gadgets.flash.embedFlash The parameter ordering is different between _IG_EmbedFlash and gadgets.flash.embedFlash., as the latter explicitly adds an argument for swf_version. If you need to use _IG_EmbedFlash as is, you can include the following method definition in your code: 
function _IG_EmbedFlash(swf_url, swf_container, opt_params) {
  return gadgets.flash.embedFlash(swf_url,
                                  swf_container,
                                  opt_params.swf_version,
                                  opt_params);
}
_IG_EmbedCachedFlash gadgets.flash.embedCachedFlash The parameter ordering is different between _IG_EmbedCachedFlash and gadgets.flash.embedCachedFlash., as the latter explicitly adds an argument for swf_version. If you need to use _IG_EmbedCachedFlash as is, you can include the following method definition in your code: 
function _IG_EmbedCachedFlash(swf_url, swf_container, opt_params) {
  return gadgets.flash.embedCachedFlash(swf_url,
                                        swf_container, 
                                        opt_params.swf_version,
                                        opt_params);
}
_IG_GetFlashMajorVersion gadgets.flash.getMajorVersion

Notes for inlined gadgets

If your legacy gadget also happens to be inlined, there are a few other changes to take into account when converting the gadget to gadgets.* (and type="html" or type="url").

CSS

Inlined gadget inherit their CSS from the iGoogle page. However, type="html" or type="url" gadgets are contained in their own frame and inherit no CSS. To maintain the look and feel of a generic iGoogle page, add the following CSS to your gadget:

body,div,ul,li,h1,h2,h3,h4,h5,h6,form,textarea,p,td {
  margin: 0;
  padding: 0;
}
img {
  border: 0;
}
ol,ul {
  list-style: none;
}
h1,h2,h3,h4,h5,h6 {
  font-size: 100%;
  font-weight: normal;
}
body {
  background-color: #fff;
  font:13px arial,sans-serif;
}
table {
  font-size: inherit;
}
img a,a img {
  background-color: transparent;
}
table td {
  font-size: 12px;
  vertical-align: top;
}

External Links

Gadgets that wish to direct the user to a third-party site should do so in a new window. All links should set target="_blank" in any href tags so that external links do not open inside of the gadget's iframe.

Height

Inlined gadgets will no longer grow and shrink, automatically, based on their content. Using the dynamic-height feature will be required to add this functionality. See "Managing Gadget Height" in the Developer's Guide for more details.