<?xml version="1.0" encoding="utf-8"?>
<html>
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

Code Block
<ModulePrefs>

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

Panelcode


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

Panelcode


 <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

Code Block
<ModulePrefs>

attributes.

<ModulePrefs> attributes.

...

code

Attribute	Description
`title`	Optional string that provides the title of the gadget. This title is displayed in the gadget title bar on iGoogle. If this string contains basic.html and you are planning to submit your gadget to the iGoogle content directory, you should also provide a

...

directory_title

...

for directory display.

...

title_url

author

author_email

Code Block


Optional string that provides a URL that the gadget title links to. For example, you could link the title to a webpage related to the gadget. code
`description`	Optional string that describes the gadget.

Code Block
Optional string that lists the author of the gadget.

Code Block
Optional string that provides the gadget author's email address. 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 is interpreted as helensmith.feedback@gmail.com.

...

You can create a Gmail account here.

...

screenshot

thumbnail

Code Block


Optional string that gives the URL of a gadget screenshot. This must be an image 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.

Code Block
Optional string that gives the URL of a gadget thumbnail. This must be an image 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 thumbnails should be 120x60 pixels.

ModulePrefs/Require and ModulePrefs/Optional

The

...

<Require>

...

and

...

<Optional>

...

elements declare feature dependencies of the gadget.

Attributes:

Code Block"feature" – The name of the feature. Required

Examples:

Panelcode


 <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

Code Block
<Preload>

element instructs <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()

...

|http://wiki.opensocial.org/index.php?title=Introduction_to_makeRequest], which fetches data from a remote server.

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

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

You can preload the content at

...

http://www.example.com

...

by adding a

Code Block
<Preload>

<Preload> tag to your gadget's <ModulePrefs> section:

Code Block
<ModulePrefs>

section:

Panel

<ModulePrefs


 <ModulePrefs title="Demo Preloads" description="Demo Preloads">


  <Require feature="opensocial-0.9" />

Panel

<Preload



  <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

Code Block
<Preload>

<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.
Code Block"authz" – The authentication type to use for making this request. Valid values are Code Block"none" (default), Code Block"signed", and Code Block"oauth". Optional.

...

These attributes map to the authorization parameters in the

...

makeRequest()

...

query string:

oauth_service_name

gadgets.io.RequestParameters.OAUTH_SERVICE_NAME

.

oauth_token_name

gadgets.io.RequestParameters.OAUTH_TOKEN_NAME

.

oauth_request_token

OAUTH_REQUEST_TOKEN

parameter. This parameter is optional. Maps to

gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN

.

oauth_request_token_secret

gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET

.

code

gadgets.io.RequestParameters.SIGN_OWNER

.

sign_viewer

gadgets.io.RequestParameters.SIGN_VIEWER

.

views

Attribute

Description

Code Block

The nickname the gadget uses to refer to the OAuth

Code Block
<Service>

<Service> element from its XML spec. If unspecified, defaults to "". Maps to

Code Block

The nickname the gadget uses to refer to an OAuth token granting access to a particular resources. If unspecified, defaults to "". Gadgets can use multiple token names if they have access to multiple resources from the same service provider. For example, a gadget with access to a contact list and a calendar might use a token name of "contacts" to use the contact list token, and a contact list of "calendar" to use the calendar token. Maps to

Code Block

A service provider may be able to automatically provision a gadget with a request token that is preapproved for access to a resource. The gadget can use that token with the

Code Block

The secret corresponding to a preapproved request token. This parameter is optional. Maps to

Code Block

sign_owner

Boolean that indicates whether the owner must be authenticated. If unspecified, defaults to "true". Maps to

Code Block

Boolean that indicates whether the viewer must be authenticated. If unspecified, defaults to "true". Maps to

Code Block

A comma-separated list of the view names that trigger the specified preload.

Note that all of the

Code Block
<Preload>

<Preload> attributes also apply to #proxied_content proxied content.

ModulePrefs/Icon

The

Code Block
<Icon>

<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.
Code Block"type" – The MIME of the embedded icon text. Optional.

Examples:

Panelcode


 <ModulePrefs title="My gadget">

<Icon>http


   <Icon>http://remote/favicon.

ico<

ico</Icon>


 </ModulePrefs>

Panel

<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 i18n.html Gadgets and Internationalization.

Attributes:

Code Block"lang" – The language associated with the locale. Optional. Code Block
"country" – The country associated with the locale. Optional.
Code Block""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 i18n.html Gadgets and Internationalization. Optional.code
"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 i18n.html Creating Bi-directional Gadgets. You can use the following substitution variables in conjunction with language_direction:
- __BIDI_START_EDGE__ No Format: The value is "left" when the gadget is in LTR-mode and "right" when the gadget is in RTL-mode. code
- __BIDI_END_EDGE__ No Format: The value is "right" when the gadget is in LTR-mode and "left" when the gadget is in RTL-mode.code
- __BIDI_DIR__ No Format: The value of this variable is "ltr" when the gadget is in LTR-mode and "rtl" when the gadget is in RTL-mode.code
- __BIDI_REVERSE_DIR__ No Format: 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:

Panelcode

<ModulePrefs>
<Locale


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

...

There are a few exceptions to the usual language rules:

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

...

A container-specific link. For example, this tag could be used to support new link types, such as gadgetsHelp and gadgetsSupport.

Attributes:

Code Block"rel" – A value that triggers a lifecycle event. Required.
Code Block"href" – A URL. Required. Code Block
"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

Code Block
href

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:

Panelcode


 <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 Code Block"invite", Code Block"gallery", and Code Block"external". Code Block
removeapp – IDs of users that have removed the appcode
app – Code Blockaction=\{enabled|disabled|approved\} reason=\{policy|quota|maintenance\} Code Block
invite – Code Blockid is people invited, Code Blockfrom_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.

...

This element identifies a single OAuth service configuration.

Attributes:

...

"name" – The name of the service (for example, Code Block"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 [remote_content.html Code BlockmakeRequest() ].

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.
Code Block"method" – The HTTP verb to use for making the request. This parameter is optional. If unspecified, it defaults to POST.
Code Block"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.
- Code Block"auth-header" – OAuth parameters are passed in the Authorization header.
- Code Block"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

...

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:

name

display_name

is

is defined.

Must

contain

only

letters,

number

and

underscores,

i.e.

the

regular

expression

^[

| {code}

Attribute	Description

Code Block
Required "symbolic" name of the user preference; displayed to the user during editing if no
Code Block
No Format
`display_name` {code} \| Optional string to display alongside the user preferences in the edit window. Must be unique. \| \| {code}urlparam {code} \| Optional string to pass as the parameter name for content {code}	Optional string to display alongside the user preferences in the edit window. Must be unique.
`urlparam`	Optional string to pass as the parameter name for content `type="url"` {code}. \| \| {code}datatype {code} \| Optional string that indicates the data type of this attribute. Can be {code}string{code}, {code}bool{code}, {code}[#Enums enum]{code}, {code}hidden{code} (a string that is not visible or user editable), or {code}[fundamentals.html#list list]{code} (dynamic array generated from user input). The default is {code}string{code}. \| \| {code}required{code} \| Optional boolean argument ({code}true{code} or {code}false{code}) indicating whether this user preference is required. The default is {code}false{code}. \| \| {code}default_value {code} \| Optional string that indicates a user preference's default value. \| User preferences can be accessed from your gadget using the user preferences [[JavaScript_API_Reference \| JavaScript API\|]a-zA-Z0-9_]+$. Must be unique. ], for example:

...

.
`datatype`	Optional string that indicates the data type of this attribute. Can be `string`, `bool`, `#Enums enum`, `hidden` (a string that is not visible or user editable), or `fundamentals.html` (dynamic array generated from user input). The default is `string`.
`required`	Optional boolean argument (`true` or `false`) indicating whether this user preference is required. The default is `false`.
`default_value`	Optional string that indicates a user preference's default value.

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

Code Block


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

...

Code Blockdatatype 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.

Panelcode


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

value

display_value

is provided.

code

display_value

, the

value

is displayed in the user interface.

Attribute	Description

Code Block
Required string that provides a unique value. This value is displayed in the menu in the user preferences edit box unless a
Code Block
`display_value`	Optional string that is displayed in the menu in the user preferences edit box. If you do not specify a
Code Block
Code Block

Content Section

The

Code Block
<Content>

<Content> section defines the type of content, and either holds the content itself or has a reference to external content. The

Code Block
<Content>

<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

Code Block
<Content>

<Content> attributes:

type

html

and

url

. The default is

html

.

code

view

preferred_height

Attribute	Description

Code Block
Optional string that gives the type of the content. The possible values are
Code Block
Code Block
Code Block
`href`

Code Block
Optional string. OpenSocial gadgets only. Indicates in which view of the OpenSocial container the content should be displayed. An OpenSocial gadget can define multiple content sections, each of which can apply to a different view or views.

Code Block
The gadget's initial height, in pixels. code
`preferred_width`	The gadget's initial width, in pixels.

...

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

Code Block
<html>

,

Code Block
<head>

, and

Code Block
<body>

<html>, <head>, and <body> tags.

For example, this gadget uses proxied content for the

...

canvas

...

view, and inline content for the

...

home

...

view:

Panelcode


 <?xml version="1.0" encoding="UTF-8"?>

<Module>
<ModulePrefs


 <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

Code Block
<Preload>

<Preload> element. See #preload ModulePrefs-Preload for details.

...

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:

Panelcode

<ModulePrefs


 <ModulePrefs 
   title="My Tabbed Gadget">


   <Require feature="tabs"/>


 </ModulePrefs>

The

...

gadgets.*

...

API provides the following feature libraries:

Feature Library	Description	Syntax

...

...

setprefs

...

Sets the value of a user preference programmatically. See Saving State for more information

...

Code Block
<Require feature="setprefs"/>

|

[

Code Block
dynamic-height

...

.	`<Require feature="setprefs"/>`
`dynamic-height`	Gives a gadget the ability to resize itself. See Managing Gadget Height for more information.

...

<Require

...

feature="dynamic-height"/>

...

|

[

...

settitle

...

Sets a gadget's title programmatically. See Setting a Gadget's Title for more information.

...

<Require

...

feature="settitle"/>

...

|

[

...

tabs

...

Adds a tabbed interface to a gadget. See Tabs for more information

...

.	`<Require`

...

feature="tabs"/>

...

|

[

...

minimessage

...

Displays a dismissable, temporary message inside a gadget. See MiniMessages for more information.

...

<Require

...

feature="minimessage"/>

...

[

Code Block
flash

...

flash

...

Embeds a Flash movie (specifically, a

...

.swf

...

file) in a gadget. See Flash for more information.

...

<Require

...

feature="flash"/>

...

locked-domain

library isolates your gadgets from other gadgets running on the same page. You can only use this feature with

type="html"

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

<Require

feature="locked-domain"/>

Code Block


The
Code Block
Code Block

Code Block

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

Version	Old Version 1	New Version 2
Changes made by	Mark Halvorson	Jonathan Beri
Saved on	Oct 05, 2010	Jan 05, 2011

Versions Compared

Key

ModulePrefs Elements and Attributes

ModulePrefs

ModulePrefs/Require and ModulePrefs/Optional

ModulePrefs/Require/Param and ModulePrefs/Optional/Param

ModulePrefs/Preload

ModulePrefs/Icon

ModulePrefs/Locale

ModulePrefs/OAuth

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

ModulePrefs/OAuth/Service/Authorization

Enum Data Types

Content Section

Content Comparison

Versions Compared

Key

ModulePrefs Elements and Attributes

ModulePrefs

ModulePrefs/Require and ModulePrefs/Optional

ModulePrefs/Require/Param and ModulePrefs/Optional/Param

ModulePrefs/Preload

ModulePrefs/Icon

ModulePrefs/Locale

ModulePrefs/OAuth

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

ModulePrefs/OAuth/Service/Authorization

Enum Data Types

Content Section