This is the reference for the gadget spec XML (version 0.9). You can see the JavaScript reference here.

If you are interested in gaining a deeper understanding of the gadgets.* API, see the gadgets specification.

ModulePrefs Elements and Attributes

The {c{<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.

<ModulePrefs> serves as a container element for all metadata, features, and processing rules. For nested element descriptions, see their individual sections below. This section summarizes the elements and attributes in <ModulePrefs>. In the sections below, the level of nesting is indicated by slashes. For example, /ModulePrefs/Locale describes the <Locale> element that is nested inside the <ModulePrefs> element. This might appear in a gadget specification as follows:

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

ModulePrefs

The following table lists the <ModulePrefs> attributes that are supported in all containers. See your container documentation for any container-specific <ModulePrefs> attributes.

ModulePrefs/Require and ModulePrefs/Optional

The <Require> and <Optional> elements declare feature dependencies of the gadget.

Attributes:

• "feature" – The name of the feature. Required

Examples:

 <Require feature="dynamic-height"/>
 <Optional feature="shareable-prefs"/>

ModulePrefs/Require/Param and ModulePrefs/Optional/Param

These elements provide configuration parameters for a feature.

Attributes:

• "name" – The name of the parameter. Required.

ModulePrefs/Preload

The <Preload> element instructs the container to fetch data from a remote source during the gadget rendering process. This element is used in conjunction with makeRequest(), which fetches data from a remote server.

For example, suppose you have a request that looks like this:

 gadgets.io.makeRequest("http://www.example.com", response, params);

You can preload the content at http://www.example.com by adding a <Preload> tag to your gadget's <ModulePrefs> section:

 <ModulePrefs title="Demo Preloads" description="Demo Preloads">
  <Require feature="opensocial-0.9" />

  <Preload href="http://www.example.com" />
 </ModulePrefs>

When your gadget executes the makeRequest() call, this content is returned instantly, without needing to hit your server again.

You use <Preload> to reduce latency for gadgets that use makeRequest() to fetch data from remote servers. For more discussion of this topic, see Introduction to makeRequest.

Attributes:

• "href" – A URL specifiying the location of the data to prefetch. Required.
• "authz" – The authentication type to use for making this request. Valid values are "none" (default), "signed", and "oauth". Optional.

These attributes map to the authorization parameters in the makeRequest() query string:

Note that all of the <Preload> attributes also apply to #proxied_content proxied content.

ModulePrefs/Icon

The <Icon> element specifies a 16px x 16px image that containers can associate with a particular gadget (for example, the container might display the icon next to the gadget's name in the left nav bar).

The content of the <Icon> tag can be one of the following:

• An HTTP URL pointing to an image file on the web
• Inlined base64-encoded image data.

Attributes:

• "mode" – The encoding used for the icon when embedding an image. Currently, only base64 is supported. Optional.
• "type" – The MIME of the embedded icon text. Optional.

Examples:

 <ModulePrefs title="My gadget">
   <Icon>http://remote/favicon.ico</Icon>
 </ModulePrefs>
 
 <ModulePrefs title="My gadget">
   <Icon mode="base64" type="image/png">_base64 encoded data_</Icon>
 </ModulePrefs>

ModulePrefs/Locale

The <Locale> element specifies the locales supported by your gadget. You can also use it to specify message bundles, as described in Gadgets and Internationalization.

Attributes:

• "lang" – The language associated with the locale. Optional.
• "country" – The country associated with the locale. Optional.
• "messages" – A URL that points to a message bundle. Message bundles are XML files that contain the translated strings for a given locale. For more information, see Gadgets and Internationalization. Optional.
• "language_direction" – The direction of the gadget. Optional. Its value can either be "rtl" (right-to-left) or "ltr" (left-to-right). The default is "ltr". This attribute lets you create gadgets that support both left-to-right and right-to-left languages. For more discussion of this topic, see Creating Bi-directional Gadgets. You can use the following substitution variables in conjunction with language_direction:
  • _BIDI_START_EDGE_: The value is "left" when the gadget is in LTR-mode and "right" when the gadget is in RTL-mode.
  • _BIDI_END_EDGE_: The value is "right" when the gadget is in LTR-mode and "left" when the gadget is in RTL-mode.
  • _BIDI_DIR_: The value of this variable is "ltr" when the gadget is in LTR-mode and "rtl" when the gadget is in RTL-mode.
  • _BIDI_REVERSE_DIR_: The value of this variable is "rtl" when the gadget is in LTR-mode and "ltr" when the gadget is in RTL-mode.

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.

The valid values for language are ISO639-1 two-digit language codes, and for country they are ISO 3166-1 alpha-2 codes.

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

ModulePrefs/Link

A container-specific link. For example, this tag could be used to support new link types, such as <span id="eh740">gadgetsHelp</span> and <span id="eh741">gadgetsSupport</span>.

Attributes:

• "rel" – A value that triggers a lifecycle event. Required.
• "href" – A URL. Required.
• "method" – The method (POST or GET) by which the request should be send. The default is GET. Optional.

A container can optionally support sending lifecycle events to an application developer's site by sending relevant query-params to a URL endpoint. To receive these events you can use the <Link> tag.. Each <Link> tag has a rel and an href attribute. The href attribute denotes the endpont where event pings are sent. If the rel attribute is "opensocialevent" then all events are sent to that endpoint. If the rel attribute matches "opensocialevent.TYPE", then events of TYPE are sent to that endpoint. An optional method attribute can be set to POST or GET to specify how the request should be sent. The default is GET. Here are some examples:

 <link rel="event" href="http://www.example.com/pingme" method="POST/>
 <link rel="event.addapp" href="http://www.example.com/add" />
 <link rel="event.removeapp" href="http://www.example.com/remove" />

Most events have information about one or more opensocial ID values. These ID values are passed as one or more ID attributes. Note that a single ping can aggregate a number of events by specifying many ID values.

The following event types are defined:

• addapp – Users that have installed the app (ID). Optional "from" designates how the user added this app. Possible values are "invite", "gallery", and "external".
• removeapp – IDs of users that have removed the app
• app – action={enabled|disabled|approved} reason={policy|quota|maintenance}
• invite – id is people invited, from_id is the ID that sent the invitation.

ModulePrefs/OAuth

The <OAuth> element defines a gadget's use of the OAuth proxy. For more information about implement OAuth in gadgets, see oauth.html Writing OAuth Gadgets.

ModulePrefs/OAuth/Service

This element identifies a single OAuth service configuration.

Attributes:

• "name" – The name of the service (for example, "google"), used for referencing OAuth services at runtime. This parameter is optional, and if unspecified, defaults to "". Gadget developers specify which OAuth service they wish to use by passing the service name as a parameter to makeRequest() .

ModulePrefs/OAuth/Service/Request and ModulePrefs/OAuth/Service/Access

Represents the OAuth request token and access token URLs. See the OAuth spec and oauth.html Writing OAuth Gadgets for details.

Attributes:

• "url" – The URL for the endpoint.
• "method" – The HTTP verb to use for making the request. This parameter is optional. If unspecified, it defaults to POST.
• "param_location" – One of 3 possible locations in the request to the service where the OAuth parameters may be passed. You can use this value to specify the location of OAuth-related parameters. The possible values are:
  • "uri-query" – OAuth parameters are passed in the query string.
  • "auth-header" – OAuth parameters are passed in the Authorization header.
  • "post-body" – OAuth parameters are passed in the body of the POST request.

These values correspond to the options described in the OAuth spec. The default value is "auth-header".

ModulePrefs/OAuth/Service/Authorization

The OAuth authorization URL.

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_Reference, 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:

ModulePrefs/Content@href (Proxied Content)

Proxied content is a feature that applies to OpenSocial gadgets. It lets you specify HTML content by URL for a particular view. For more discussion of views, see Multiple Content Sections.

The target URL you specify for this feature should be valid HTML 4.01, XHTML 1.1, and so on. You should not specify an image or Flash URL, though you could wrap these things in HTML and then link to the HTML. Your target HTML content must include the <html>, <head>, and <body> tags.

For example, this gadget uses proxied content for the canvas view, and inline content for the home view:

 <?xml version="1.0" encoding="UTF-8"?>
 <Module>
   <ModulePrefs title="Proxied Content Example">
   </ModulePrefs>
   <Content view="canvas" 
    href="http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-09/mycontent.html">
   </Content>
   <Content view="home">
     <![CDATA[
       Hello, home view!
     ]]>
   </Content>
 </Module>

Proxied content uses the same attributes that apply to the <Preload> element. See #preload ModulePrefs-Preload for details.

JavaScript Reference

You can see the JavaScript Reference here.

Including Feature-Specific JavaScript Libraries

To create a gadget that uses a particular feature, such as tabs or a Flash movie, you must include the feature library in your gadget spec using the <Require> tag (inside <ModulePrefs>). For example:

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

The gadgets.* API provides the following feature libraries:

To see all of the methods supported by a given feature, see the JavaScript API Reference.