Gadgets API Reference

This is the reference for the "legacy" gadgets API, based on the _IG_... namespace. It includes reference information for the gadget spec XML, and for the JavaScript core and feature-specific libraries.

Going forward, the gadgets API is being "renamespaced" into the gadgets.* JavaScript namespace, to provide a cleaner API to program against and support. Currently the new namespace is only supported in containers that also support the OpenSocial API. If you are developing gadgets for an OpenSocial container, see the gadgets.* Developers Guide. You can see the gadgets.* reference here. If you are interested in gaining a deeper understanding, you are also welcome to read the gadgets specification. Keep in mind that the new gadgets.* API is NOT yet supported everywhere. Go here for a list of containers that support the gadgets.* API.

Contents

1. XML Structure
   1. Gadget Preferences
   2. User Preferences
   3. Content Section
2. JavaScript Libraries
   1. Core JavaScript Library
   2. Feature-Specific JavaScript Libraries
3. Request Parameters

XML Structure

The following sections describe the structure and contents of the XML file used to specify a gadget.

Gadget Preferences

The <ModulePrefs> section in the XML file specifies characteristics of the gadget, such as title, author, preferred sizing, and so on. For example:

<Module>
  <ModulePrefs title="Developer Forum" 
    title_url="http://groups.google.com/group/Google-Gadgets-API" 
    height="200" 
    author="Jane Smith" 
    author_email="xxx@google.com"/> 
  <Content ...>
   ... content ...
  </Content> 
</Module>

The users of your gadget cannot change these attributes.

The following table lists the <ModulePrefs> attributes:

Using Libraries

To use certain gadget API features, such as dynamic height or storing state, you need to load the appropriate JavaScript library using the <Require> tag (inside <ModulePrefs>). The <Require> tag has one required attribute, feature, whose value specifies the feature library. For example:

<ModulePrefs 
  title="Set Userprefs Demo">
  <Require feature="dynamic-height"/>
  <Require feature="setprefs" /> 
</ModulePrefs> 

For more discussion of the feature libraries, see Feature-Specific JavaScript Libraries.

Specifying Locales

You can use <Locale> tags under <ModulePrefs> to specify the locales supported by your gadget. You can also use it to specify message bundles, as described in Internationalization.

For example, this snippet specifies two different locales:

<ModulePrefs ...>
  <Locale lang="en" country="us" />
  <Locale lang="ja" country="jp" />
</ModulePrefs>

The "lang" (language) and "country" attributes are both optional, but you must have at least one of them for each <Locale>. If you omit either attribute, the value is equivalent to "*" and "ALL". If you specify a country and no language, it is assumed that your gadget supports all languages associated with the country. Likewise, if you specify a language and no country, it is assumed that your gadget supports all countries associated with the language.

You can find the acceptable values you for "lang" and "country" here.

There are a few exceptions to the usual language rules:

• Simplified Chinese: lang="zh-cn" (typically for country="cn").
• Traditional Chinese: lang="zh-tw" (typically for country="tw" or "hk", Taiwan or Hong Kong, respectively).

The following table lists the <Locale> attributes:

If you don't specify a <Locale>, the default is assumed to be US + English only.

Specifying Compatibility Requirements

Not all gadgets can run in all environments. A gadget may require a particular browser or software. You can use the <MayRequire> tag to provide information about special requirements of your gadget. For example:

<ModulePrefs ...>
  <MayRequire type="plugin" value="quicktime"/>
  <MayRequire type="browser" value="firefox" min_version="1.06"/>
  <MayRequire type="platform" 
    value="windows"> This gadget uses a Windows API.
  </MayRequire>
</ModulePrefs>

The following table lists the <MayRequire> attributes:

User Preferences

Some gadgets need to give users a way of supplying user-specific information. For example, a weather gadget might require users to provide their postal codes. The user preferences (<UserPref>) section in the XML file describes the user input fields that are turned into user interface controls when the gadget runs.

The following table lists the <UserPref> attributes:

User preferences can be accessed from your gadget using the user preferences JavaScript API, for example:

<script type="text/javascript">
   var prefs = new _IG_Prefs();
   var someStringPref = prefs.getString("StringPrefName");
   var someIntPref = prefs.getInt("IntPrefName");
   var someBoolPref = prefs.getBool("BoolPrefName");
</script>

Enum Data Types

One of the values you can specify for the <UserPref> datatype attribute is enum. The enum data type is presented in the user interface as a menu of choices. You specify the contents of the menu using <EnumValue>.

For example, this <UserPref> lets users set the level of difficulty for a game. Each value that will appear in the menu (Easy, Medium, and Hard) is defined using an <EnumValue> tag.

<UserPref name="difficulty" 
     display_name="Difficulty"
     datatype="enum"
     default_value="4">
  <EnumValue value="3" display_value="Easy"/>
  <EnumValue value="4" display_value="Medium"/>
  <EnumValue value="5" display_value="Hard"/>
</UserPref>

The following table lists the <EnumValue> attributes:

Content Section

The <Content> section defines the type of content, and either holds the content itself or has a reference to external content. The <Content> section is where the gadget attributes and user preferences are combined with programming logic and formatting information to become a running gadget. For more discussion on content types, see Choosing a Content Type.

The following table lists the <Content> attributes:

JavaScript Libraries

This section describes the JavaScript functions supported by the gadgets API. For a discussion of the requirements of using the JavaScript libraries, see Using the JavaScript Libraries with Different Content Types.

There are two different types of JavaScript libraries in the gadgets API:

• Core JavaScript library
• Feature-specific JavaScript libraries

Core JavaScript Library

The core JavaScript library includes general functions that aren't related to a specific feature.

This table lists the userprefs constructor, and the functions you can call on a userprefs object once you have instantiated it:

This table lists the general purpose JavaScript methods that aren't specifically related to userprefs:

Feature-Specific JavaScript Libraries

The gadgets API includes the following feature libraries:

• setprefs
• dynamic-height
• settitle
• tabs
• drag
• grid
• minimessage
• analytics
• flash
• locked-domain

To use a particular feature library, you include it in your gadget spec using the <Require> tag (inside <ModulePrefs>). For example:

<ModulePrefs 
  title="My Tabbed Gadget">
  <Require feature="tabs"/>
</ModulePrefs> 

The feature libraries are described in more detail below.

setprefs Library

For a detailed discussion of using the setprefs library and examples, see Saving State.

To use the setprefs library, gadgets must include the following line under <ModulePrefs>:

<Require feature="setprefs"/>

The setprefs library includes the following function:

set(userpref, value)

This function is called on a (typically hidden) userprefs object. The userpref parameter specifies the name of the user preference, and the value parameter specifies the value that is being assigned to the user preference. For example:

var prefs = new _IG_Prefs();
prefs.set("score", 5000);			  

dynamic-height Library

For a detailed discussion of using the dynamic-height library and examples, see Managing Gadget Height.

To use the dynamic-height library, gadgets must include the following line under <ModulePrefs>:

<Require feature="dynamic-height" /> 

The dynamic-height library includes one function, which tells the gadget to resize itself:

_IG_AdjustIFrameHeight()

settitle Library

For a detailed discussion of using the settitle library and examples, see Setting a Gadget's Title.

To use the settitle library, gadgets must include the following line under <ModulePrefs>:

<Require feature="settitle" /> 

The settitle library includes the following constructors:

tabs Library

For a detailed discussion of using the tabs library and examples, see Tabs.

To use the tabs library, gadgets must include the following line under <ModulePrefs>:

<Require feature="tabs" /> 

This table lists the tabs constructor, and the functions you can call on a tabs object once you have instantiated it. A tabs object is the parent container that holds an array of individual tab objects.

tabs.addTab("Tab", { 
     contentContainer: _gel("domId"),
     callback: func, 
     tooltip: "Popup description" 
}); 

This table lists the functions you can call on a individual tab object.

drag Library

For a detailed discussion of using the drag library and examples, see Drag.

To use the drag library, gadgets must include the following line under <ModulePrefs>:

<Require feature="drag" /> 

The drag library includes the following callback functions:

This table lists the drag constructor, and the functions you can call on a drag object once you have instantiated it. Sources and targets are HTML elements that have associated DOM ID's. Sources and targets also have drag ID's. If no drag ID is specified, the drag library uses the DOM ID as the drag ID.

Drag Properties

The drag library includes the properties listed below. You access these properties through a drag object. For example:

if (drag_obj.isDragging == true) {
     // do something
} 

This table lists read-only properties:

This table lists read-write properties. Changing these properties affects how dragging works. Do not change them during dragging:

grid Library

For a detailed discussion of using the grid library and examples, see Grid.

To use the grid library, gadgets must include the following line under <ModulePrefs>:

<Require feature="grid" /> 

The functions in the grid library are summarized below.

Grid Required Backend Functions

As part of using the grid library, you must implement the following backend functions:

Grid Backend Display Functions

By default, the grid library calls getNormalView() whenever it wants to display the contents of a cell. However, you may want the contents of a cell to react and be displayed differently based on how the user is dragging. For those cases, you can implement the following optional functions for your backend object.

Grid Backend Reaction Functions

The grid library provides the following functions to let your gadget respond to mouse clicking and dragging:

Grid Backend Callbacks

Backend callback functions are automatically created in your backend object. The grid library calls them as necessary, but you can also call them yourself, such as when your data is changing through a processes other than user dragging. The grid library includes the following backend callbacks:

Grid Object Properties

The grid library includes the grid object fields and functions listed below. You access these through a grid object. For example:

document.getElementById("summary").innerHTML = "In the grid " + mygrid.name + 
   " the HTML content of the source is " + mygrid.getCellValue(mygrid.source);

The fields and functions you can access through a grid object are as follows:

Advanced Backend Functions

If you override the dragHandler in the Grid object, sometimes the user will drag something that the Grid can't handle. In that case, it will attempt to call these functions in your backend object if they exist. See drag Library for details on how they work.

• _IGG_handleOnDragStart(object)
• _IGG_handleOnDragTargetHit(object)
• _IGG_handleOnDragTargetLost()
• _IGG_handleOnDragEnd(object, object)
• _IGG_handleOnDragClick(object)

MiniMessage Library

For a detailed discussion of using the MiniMessage library and examples, see MiniMessages.

To use the MiniMessage library, gadgets must include the following line under <ModulePrefs>:

<Require feature="minimessage" /> 

This table lists the MiniMessage constructor, and the functions you can call on a MiniMessage object once you have instantiated it:

analytics Library

For a detailed discussion of using the analytics library and examples, see Using Analytics.

To use the analytics library, gadgets must include the following line under <ModulePrefs>:

<Require feature="analytics" /> 

The analytics library includes the following function:

flash Library

For a detailed discussion of using the flash library and examples, see Flash.

To use the flash library, gadgets must include the following line under <ModulePrefs>:

<Require feature="flash" /> 

The flash library includes the following functions:

locked-domain Library

The locked-domain library isolates your gadgets from other gadgets running on the same page. You can only use this feature with type="html" gadgets.

To use the locked-domain library, gadgets must include the following line under <ModulePrefs>:

<Require feature="locked-domain"/>

We suggest that you add this feature requirement to your gadget if your gadget stores sensitive private user data. This feature is only supported on iGoogle. Other gadget containers may not support this feature and will reject your gadget.

Request Parameters

When the gadget URL is requested from iGoogle, parameters are appended to the request, which is a GET method. This only applies when your content type is set to "url"--see URL for more information. These parameters can be read by a gadget using JavaScript, or by a server-side web application. For an example, see URL.

The parameters that are passed are listed in the following table:

Back to top