Gadgets API Reference (v0.8)

This document describes the classes and methods in the gadgets.* namespace, some of which are feature-specific. For information on including features, see the Gadgets Specification.

Note: This API is not yet supported by the production instance of iGoogle, though it is available in the iGoogle sandbox. If you'd like to write a gadget for iGoogle, see the Gadgets API Reference.

Contents

• Type Conventions
• Core API
  • Prefs
  • io
    • AuthorizationType
    • ContentType
    • MethodType
    • ProxyUrlRequestParameters
    • RequestParameters
  • json
  • util
• Feature-Specific API
  • MiniMessage
  • Tab
  • TabSet
  • flash
  • pubsub
  • rpc
  • skins
    • Property
  • views
    • View
    • ViewType
  • window

Back to top

Type Conventions

This document uses the following conventions for types:

Array<T> or Array.<T>

An Array filled with only objects of type T. This convention is similar to Java generics.

Map<K, V> or Map.<K, V>

A JavaScript object with keys of type K that map to values of type V. Again, this convention is similar to Java generics. It's often used for opt_params variables.

static

A type marked with static class has no public or private constructor. In other words, the type is a namespace, not a class that can be instantiated to create objects. The fields and functions in such a type are also marked as static.

Boolean

A boolean value (not a Boolean object).

String

A string value (not a String object).

Back to top

Class gadgets.MiniMessage

SUMMARY DETAIL

MiniMessage class, used to create messages that will appear to the user within the gadget. Typical use cases:

• Status messages — loading, saving, etc.
• Promotional messages — new features, new gadget, etc.
• Debug/error messages — bad input, failed connection to server, etc.

Constructor Summary

gadgets.MiniMessage(opt_moduleId, opt_container)

Creates a MiniMessage.

Method Summary

HTMLElement createDismissibleMessage(message, opt_callback)

Creates a dismissible message with an [x] icon that allows users to dismiss the message.

HTMLElement createStaticMessage(message)

Creates a static message that can only be dismissed programmatically (by calling dismissMessage()).

HTMLElement createTimerMessage(message, seconds, opt_callback)

Creates a message that displays for the specified number of seconds.

dismissMessage(message)

Dismisses the specified message.

Constructor Detail

gadgets.MiniMessage

gadgets.MiniMessage(opt_moduleId, opt_container)

Creates a MiniMessage.

Parameters:
String opt_moduleId - Optional module ID
HTMLElement opt_container - Optional HTML container element where mini-messages will appear

Method Detail

createDismissibleMessage

HTMLElement createDismissibleMessage(message, opt_callback)

Creates a dismissible message with an [x] icon that allows users to dismiss the message. When the message is dismissed, it is removed from the DOM and the optional callback function, if defined, is called.

Parameters:
String, Object message - The message as an HTML string or DOM element
Function opt_callback - Optional callback function to be called when the message is dismissed

Returns:
HTMLElement HTML element of the created message

createStaticMessage

HTMLElement createStaticMessage(message)

Creates a static message that can only be dismissed programmatically (by calling dismissMessage()).

Parameters:
String, Object message - The message as an HTML string or DOM element

Returns:
HTMLElement HTML element of the created message

createTimerMessage

HTMLElement createTimerMessage(message, seconds, opt_callback)

Creates a message that displays for the specified number of seconds. When the timer expires, the message is dismissed and the optional callback function is executed.

Parameters:
String, Object message - The message as an HTML string or DOM element
number seconds - Number of seconds to wait before dismissing the message
Function opt_callback - Optional callback function to be called when the message is dismissed

Returns:
HTMLElement HTML element of the created message

dismissMessage

dismissMessage(message)

Dismisses the specified message.

Parameters:
HTMLElement message - HTML element of the message to remove

Back to top

Class gadgets.Prefs

SUMMARY DETAIL

Provides access to user preferences, module dimensions, and messages. Clients can access their preferences by constructing an instance of gadgets.Prefs and passing in their module ID. Example:

var prefs = new gadgets.Prefs();
var name = prefs.getString("name");
var lang = prefs.getLang();

Constructor Summary

gadgets.Prefs(opt_moduleId)

Creates a new Prefs object.

Method Summary

Array.<String> getArray(key)

Retrieves a preference as an array.

Boolean getBool(key)

Retrieves a preference as a boolean.

String getCountry()

Gets the current country, returned as ISO 3166-1 alpha-2 code.

Number getFloat(key)

Retrieves a preference as a floating-point value.

Number getInt(key)

Retrieves a preference as an integer.

String getLang()

Gets the current language the gadget should use when rendering, returned as a ISO 639-1 language code.

String, Number getModuleId()

Gets the module ID for the current instance.

String getMsg(key)

Fetches an unformatted message.

String getString(key)

Retrieves a preference as a string.

set(key, val)

Stores a preference.

setArray(key, val)

Stores an array preference.

Constructor Detail

gadgets.Prefs

gadgets.Prefs(opt_moduleId)

Creates a new Prefs object.

Parameters:
String, Number opt_moduleId - An optional parameter specifying the module ID to create prefs for; if not provided, the default module ID is used

Method Detail

getArray

Array.<String> getArray(key)

Retrieves a preference as an array. UserPref values that were not declared as lists are treated as one-element arrays.

Parameters:
String key - The preference to fetch

Returns:
Array.<String> The preference; if not set, an empty array

getBool

Boolean getBool(key)

Retrieves a preference as a boolean.

Parameters:
String key - The preference to fetch

Returns:
Boolean The preference; if not set, false

getCountry

String getCountry()

Gets the current country, returned as ISO 3166-1 alpha-2 code.

Returns:
String The country for this module instance

getFloat

Number getFloat(key)

Retrieves a preference as a floating-point value.

Parameters:
String key - The preference to fetch

Returns:
Number The preference; if not set, 0

getInt

Number getInt(key)

Retrieves a preference as an integer.

Parameters:
String key - The preference to fetch

Returns:
Number The preference; if not set, 0

getLang

String getLang()

Gets the current language the gadget should use when rendering, returned as a ISO 639-1 language code.

Returns:
String The language for this module instance

getModuleId

String, Number getModuleId()

Gets the module ID for the current instance.

Returns:
String, Number The module ID for this module instance

getMsg

String getMsg(key)

Fetches an unformatted message.

Parameters:
String key - The message to fetch

Returns:
String The message

getString

String getString(key)

Retrieves a preference as a string.

Parameters:
String key - The preference to fetch

Returns:
String The preference; if not set, an empty string

set

set(key, val)

Stores a preference. To use this call, the gadget must require the feature setprefs.

Note: If the gadget needs to store an Array it should use setArray instead of this call.

Parameters:
String key - The pref to store
Object val - The values to store

setArray

setArray(key, val)

Stores an array preference. To use this call, the gadget must require the feature setprefs.

Parameters:
String key - The pref to store
Array val - The values to store

Back to top

Class gadgets.Tab

SUMMARY DETAIL

Tab class for gadgets. You create tabs using the TabSet addTab() method. To get Tab objects, use the TabSet getSelectedTab() or getTabs() methods.

See also: TabSet

Method Summary

Function getCallback()

Returns the callback function that is executed when the tab is selected.

HTMLElement getContentContainer()

Returns the HTML element where the tab content is rendered.

Number getIndex()

Returns the tab's index.

String getName()

Returns the label of the tab as a string (may contain HTML).

HTMLElement getNameContainer()

Returns the HTML element that contains the tab's label.

Method Detail

getCallback

Function getCallback()

Returns the callback function that is executed when the tab is selected.

Returns:
Function The callback function of the tab

getContentContainer

HTMLElement getContentContainer()

Returns the HTML element where the tab content is rendered.

Returns:
HTMLElement The HTML element of the content container

getIndex

Number getIndex()

Returns the tab's index.

Returns:
Number The tab's index

getName

String getName()

Returns the label of the tab as a string (may contain HTML).

Returns:
String The label of the tab

getNameContainer

HTMLElement getNameContainer()

Returns the HTML element that contains the tab's label.

Returns:
HTMLElement The HTML element of the tab's label

Back to top

Class gadgets.TabSet

SUMMARY DETAIL

A class gadgets can use to make tabs.

Constructor Summary

gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)

Creates a new TabSet object

Method Summary

String addTab(tabName, opt_params)

Adds a new tab based on the name-value pairs specified in opt_params.

alignTabs(align, opt_offset)

Sets the alignment of tabs.

displayTabs(display)

Shows or hides tabs and all associated content.

HTMLElement getHeaderContainer()

Returns the tab headers container element.

gadgets.Tab getSelectedTab()

Returns the currently selected tab object.

Array.<gadgets.Tab> getTabs()

Returns an array of all existing tab objects.

removeTab(tabIndex)

Removes a tab at tabIndex and all of its associated content.

setSelectedTab(tabIndex)

Selects the tab at tabIndex and fires the tab's callback function if it exists.

swapTabs(tabIndex1, tabIndex2)

Swaps the positions of tabs at tabIndex1 and tabIndex2.

Constructor Detail

gadgets.TabSet

gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)

Creates a new TabSet object

Parameters:
String opt_moduleId - Optional suffix for the ID of tab container
String opt_defaultTab - Optional tab name that specifies the name of of the tab that is selected after initialization; if this parameter is omitted, the first tab is selected by default
HTMLElement opt_container - The HTML element to contain the tabs; if omitted, a new div element is created and inserted at the very top

Method Detail

addTab

String addTab(tabName, opt_params)

Adds a new tab based on the name-value pairs specified in opt_params. The following properties are supported in opt_params:

contentContainer

An existing HTML element to be used as the tab content container. If omitted, the tabs library creates one.

callback

A callback function to be executed when the tab is selected.

tooltip

A tooltip description that pops up when user moves the mouse cursor over the tab.

index

The index at which to insert the tab. If omitted, the new tab is appended to the end.

Parameters:
String tabName - Label of the tab to create
Object opt_params - Optional parameter object

Returns:
String DOM id of the tab container

alignTabs

alignTabs(align, opt_offset)

Sets the alignment of tabs. Tabs are center-aligned by default.

Parameters:
String align - 'left', 'center', or 'right'
Number opt_offset - Optional parameter to set the number of pixels to offset tabs from the left or right edge; the default value is 3px

displayTabs

displayTabs(display)

Shows or hides tabs and all associated content.

Parameters:
Boolean display - True to show tabs; false to hide tabs

getHeaderContainer

HTMLElement getHeaderContainer()

Returns the tab headers container element.

Returns:
HTMLElement The tab headers container element

getSelectedTab

gadgets.Tab getSelectedTab()

Returns the currently selected tab object.

Returns:
gadgets.Tab The currently selected tab object

getTabs

Array.<gadgets.Tab> getTabs()

Returns an array of all existing tab objects.

Returns:
Array.<gadgets.Tab> Array of all existing tab objects

removeTab

removeTab(tabIndex)

Removes a tab at tabIndex and all of its associated content.

Parameters:
Number tabIndex - Index of the tab to remove

setSelectedTab

setSelectedTab(tabIndex)

Selects the tab at tabIndex and fires the tab's callback function if it exists. If the tab is already selected, the callback is not fired.

Parameters:
Number tabIndex - Index of the tab to select

swapTabs

swapTabs(tabIndex1, tabIndex2)

Swaps the positions of tabs at tabIndex1 and tabIndex2. The selected tab does not change, and no callback functions are called.

Parameters:
Number tabIndex1 - Index of the first tab to swap
Number tabIndex2 - Index of the secnod tab to swap

Back to top

Static Class gadgets.flash

SUMMARY DETAIL

Embeds Flash content in gadgets.

Method Summary

<static> Boolean embedCachedFlash()

Injects a cached Flash file into the DOM tree.

<static> Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)

Injects a Flash file into the DOM tree.

<static> Number getMajorVersion()

Detects Flash Player and its major version.

Method Detail

embedCachedFlash

<static> Boolean embedCachedFlash()

Injects a cached Flash file into the DOM tree. Accepts the same parameters as gadgets.flash.embedFlash does.

Returns:
Boolean Whether the function call completes successfully

embedFlash

<static> Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)

Injects a Flash file into the DOM tree.

Parameters:
String swfUrl - SWF URL
String, Object swfContainer - The ID or object reference of an existing HTML container element
Number swfVersion - Minimum Flash Player version required
Object opt_params - An optional object that may contain any valid HTML parameter; all attributes will be passed through to the Flash movie on creation

Returns:
Boolean Whether the function call completes successfully

getMajorVersion

<static> Number getMajorVersion()

Detects Flash Player and its major version.

Returns:
Number The major version of Flash Player or 0 if Flash is not supported

Back to top

Static Class gadgets.io

SUMMARY DETAIL

Provides remote content retrieval functions.

Method Summary

<static> String encodeValues(fields)

Converts an input object into a URL-encoded data string.

<static> String getProxyUrl(url, opt_params)

Gets the proxy version of the passed-in URL.

<static> makeRequest(url, callback, opt_params)

Fetches content from the provided URL and feeds that content into the callback function.

Method Detail

encodeValues

<static> String encodeValues(fields)

Converts an input object into a URL-encoded data string. (key=value&...)

Parameters:
Object fields - The post fields you wish to encode

Returns:
String The processed post data; this includes a trailing ampersand (&)

getProxyUrl

<static> String getProxyUrl(url, opt_params)

Gets the proxy version of the passed-in URL.

Parameters:
String url - The URL to get the proxy URL for
Map<String, String> opt_params - Additional optional parameters to pass to the request

Returns:
String The proxied version of the URL

makeRequest

<static> makeRequest(url, callback, opt_params)

Fetches content from the provided URL and feeds that content into the callback function. Example:

var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;
gadgets.io.makeRequest(url, callback, params);

Signed authorization

If opt_params[gadgets.io.RequestParameters.AUTHORIZATION] is set to gadgets.io.AuthorizationType.SIGNED, the container needs to vouch for the user's identity to the destination server. The container does this by doing the following:

1. Removing any request parameters with names that begin with oauth, xoauth, or opensocial (case insensitive).

2. Adding the following parameters to the request query string:

   opensocial_viewer_id

   Optional.
   The ID of the current viewer, which matches the getId() value on the viewer person object.

   opensocial_owner_id

   Required.
   The ID of the current owner, which matches the getId() value on the owner person object.

   opensocial_app_url

   Required.
   The URL of the application making the request. Containers may alias multiple application URLs to a single canonical application URL in the case where an application changes URLs.

   opensocial_instance_id

   Optional.
   An opaque identifier used to distinguish between multiple instances of the same application in a single container. If a container does not allow multiple instances of the same application to coexist, this parameter may be omitted. The combination of opensocial_app_url and opensocial_instance_id uniquely identify an instance of an application in a container.

   opensocial_app_id

   Optional.
   An opaque identifier for the application, unique to a particular container. Containers that wish to maintain backwards compatibility with the opensocial-0.7 specification may include this parameter.

   xoauth_public_key

   Optional.
   An opaque identifier for the public key used to sign the request. This parameter may be omitted by containers that do not use public keys to sign requests, or if the container arranges other means of key distribution with the target of the request.

3. Signing the resulting request according to section 9 of the OAuth specification.

Key management for gadgets.io.AuthorizationType.SIGNED

If a container uses public keys to sign requests, the container may choose to use either self-signed certificates or certificates signed by a well-known certificate authority. If a container does not distribute its OAuth signing key over HTTPS, it should use a certificate signed by a well-known certificate authority.

The commonName attribute of the certificate should match the hostname of the container server, and should also match the value of the oauth_consumer_key parameter specified in the request.

The container should make its public key available for download at a well-known location. The location https://container-hostname/opensocial/certificates/xoauth_public_keyvalue is recommended.

Recipients of signed requests must verify that the signature on the request is correct, and that the timestamp on the request is within a reasonable time window. A time window of 5 minutes before and after the current time is recommended.

Recipients of signed requests may use the oauth_consumer_key and xoauth_public_key parameters to automatically detect when a container deploys new certificates. If the container deploys certificates at a well-known location, the recipient may automatically download the new certificate. Recipients that automatically download new certificates should cache the resulting certificates.

If a container's certificate is not downloaded from https://container-hostname, the recipient should verify that the certificate is signed by a well-known certificate authority before trusting the certificate.

OAuth authorization

If opt_params[gadgets.io.RequestParameters.AUTHORIZATION] is set to gadgets.io.AuthorizationType.OAUTH, the container needs to use OAuth to gain access to the resource specified in the request. This may require that the gadget obtain the user's content by directing the user to the service provider to gain access.

Additional parameters

The following additional parameters may be specified in opt_params:

gadgets.io.RequestParameters.OAUTH_SERVICE_NAME

The nickname the gadget uses to refer to the OAuth <Service> element from its XML spec. If unspecified, defaults to "".

gadgets.io.RequestParameters.OAUTH_TOKEN_NAME

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.

gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN

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 OAUTH_REQUEST_TOKEN parameter. This parameter is optional.

gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET

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

If OAuth is used, the container should execute the OAuth protocol on behalf of the gadget. If the gadget has not registered a consumer key for use with this service provider, the container may choose to use a default RSA signing key corresponding to a well-known certificate to sign requests. If the container uses a default consumer key, it will include an additional OAuth parameter xoauth_app_url that identifies the gadget making the request.

The callback parameter

The makeRequest() callback parameter is passed a javascript object with several OAuth-specific fields in addition to the normal values returned by makeRequest():

"oauthApprovalUrl"

If this value is specified, the user needs to visit an external page to approve the gadget's request to access data. Use of a pop-up window to direct the user to the external page is recommended. Once the user has approved access, the gadget can repeat the makeRequest call to retrieve the data.

"oauthError"

If this value is specified, it indicates an OAuth-related error occurred. The value will be one of a set of string constants that can be used for programmatically detecting errors. The constants are undefined for opensocial-0.8, but implementers should attempt to agree on a set of useful constant values for standardization in opensocial-0.9.

"oauthErrorText"

If this value is specified, it indicates an OAuth-related error occurred. The value is free-form text that can be used to provide debugging information for gadget developers.

Parameters:
String url - The URL where the content is located
Function callback - The function to call with the data from the URL once it is fetched
Map.<gadgets.io.RequestParameters, Object> opt_params - Additional request parameters or proxy request parameters

Back to top

Static Class gadgets.io.AuthorizationType

SUMMARY DETAIL

Used by RequestParameters.

Field Summary

<static> object NONE

No authorization.

<static> object OAUTH

The container will use OAuth for authentication.

<static> object SIGNED

The request will be signed by the container.

Field Detail

NONE

<static> object NONE

No authorization.

OAUTH

<static> object OAUTH

The container will use OAuth for authentication.

SIGNED

<static> object SIGNED

The request will be signed by the container.

Back to top

Static Class gadgets.io.ContentType

SUMMARY DETAIL

Used by RequestParameters.

Field Summary

<static> object DOM

Returns a DOM object; used for fetching XML.

<static> object FEED

Returns a JSON representation of an RSS or Atom feed.

<static> object JSON

Returns a JSON object.

<static> object TEXT

Returns text; used for fetching HTML.

Field Detail

DOM

<static> object DOM

Returns a DOM object; used for fetching XML.

FEED

<static> object FEED

Returns a JSON representation of an RSS or Atom feed.

JSON

<static> object JSON

Returns a JSON object.

TEXT

<static> object TEXT

Returns text; used for fetching HTML.

Back to top

Static Class gadgets.io.MethodType

SUMMARY DETAIL

Defines values for RequestParameters.METHOD.

Field Summary

<static> object DELETE

Container support for this method type is OPTIONAL.

<static> object GET

The default type.

<static> object HEAD

Container support for this method type is OPTIONAL.

<static> object POST

Container support for this method type is OPTIONAL.

<static> object PUT

Container support for this method type is OPTIONAL.

Field Detail

DELETE

<static> object DELETE

Container support for this method type is OPTIONAL.

GET

<static> object GET

The default type.

HEAD

<static> object HEAD

Container support for this method type is OPTIONAL.

POST

<static> object POST

Container support for this method type is OPTIONAL.

PUT

<static> object PUT

Container support for this method type is OPTIONAL.

Back to top

Static Class gadgets.io.ProxyUrlRequestParameters

SUMMARY DETAIL

Used by gadgets.io.getProxyUrl() method.

Field Summary

<static> object REFRESH_INTERVAL

Attempt to use content caching.

Field Detail

REFRESH_INTERVAL

<static> object REFRESH_INTERVAL

Attempt to use content caching. The Refresh Interval is the number of seconds we want to cache the given response. By default the HTTP headers will be respected. If there aren't any HTTP headers this value will default to 3600 (one hour). Note that Signed requests and objects with POST_DATA present will generally not be cached.

Back to top

Static Class gadgets.io.RequestParameters

SUMMARY DETAIL

Used by the gadgets.io.makeRequest() method.

Field Summary

<static> object AUTHORIZATION

The type of authentication to use when fetching the content; defaults to AuthorizationType.NONE.

<static> object CONTENT_TYPE

The type of content that lives at the URL; defaults to ContentType.TEXT.

<static> object GET_SUMMARIES

If the content is a feed, whether to fetch summaries for that feed; defaults to false.

<static> object HEADERS

The HTTP headers to send to the URL; defaults to null.

<static> object METHOD

The method to use when fetching content from the URL; defaults to MethodType.GET.

<static> object NUM_ENTRIES

If the content is a feed, the number of entries to fetch; defaults to 3.

<static> object POST_DATA

The data to send to the URL using the POST method; defaults to null.

Field Detail

AUTHORIZATION

<static> object AUTHORIZATION

The type of authentication to use when fetching the content; defaults to AuthorizationType.NONE. Specified as an AuthorizationType.

CONTENT_TYPE

<static> object CONTENT_TYPE

The type of content that lives at the URL; defaults to ContentType.TEXT. Specified as a ContentType.

GET_SUMMARIES

<static> object GET_SUMMARIES

If the content is a feed, whether to fetch summaries for that feed; defaults to false. Specified as a Boolean.

HEADERS

<static> object HEADERS

The HTTP headers to send to the URL; defaults to null. Specified as a Map.<String,String>.

METHOD

<static> object METHOD

The method to use when fetching content from the URL; defaults to MethodType.GET. Valid values are specified by MethodType.

NUM_ENTRIES

<static> object NUM_ENTRIES

If the content is a feed, the number of entries to fetch; defaults to 3. Specified as a Number.

POST_DATA

<static> object POST_DATA

The data to send to the URL using the POST method; defaults to null. Specified as a String.

Back to top

Static Class gadgets.json

SUMMARY DETAIL

Provides operations for translating objects to and from JSON.

Method Summary

<static> Object parse(text)

Parses a JSON string, producing a JavaScript value.

<static> String stringify(v)

Converts a JavaScript value to a JSON string.

Method Detail

parse

<static> Object parse(text)

Parses a JSON string, producing a JavaScript value.

Parameters:
String text - The string to transform into an object — usually the result of a previous stringify call

Returns:
Object The object parsed from the passed in text; false if an error occurred

stringify

<static> String stringify(v)

Converts a JavaScript value to a JSON string.

Parameters:
Object v - The object to convert

Returns:
String The JSON equivalent

Back to top

Static Class gadgets.pubsub

SUMMARY DETAIL

Provides operations for publishing and subscribing to message channels.

Method Summary

<static> publish(channelName, message)

Publishes a string-type message to a channel.

<static> subscribe(channelName, callback)

Subscribes a gadget to a message channel.

<static> unsubscribe(channelName)

Unsubscribes the gadget from a message channel.

Method Detail

publish

<static> publish(channelName, message)

Publishes a string-type message to a channel.

Parameters:
String channelName - The name of the channel
String message - The message to publish

subscribe

<static> subscribe(channelName, callback)

Subscribes a gadget to a message channel.

Parameters:
String channelName - The name of the channel
Function callback - A function that will be called with the channel messages

unsubscribe

<static> unsubscribe(channelName)

Unsubscribes the gadget from a message channel.

Parameters:
String channelName - The name of the channel

Back to top

Static Class gadgets.rpc

SUMMARY DETAIL

Provides operations for making remote procedure calls for gadget-to-container, container-to-gadget, and gadget-to-gadget communication.

Method Summary

<static> call(targetId, serviceName, callback, var_args)

Calls an RPC service.

<static> register(serviceName, handler)

Registers an RPC service.

<static> registerDefault(handler)

Registers a default service handler to process all unknown remote procedure calls, which fail silently by default.

<static> unregister(serviceName)

Unregisters an RPC service.

<static> unregisterDefault()

Unregisters the default service handler.

Method Detail

call

<static> call(targetId, serviceName, callback, var_args)

Calls an RPC service.

Parameters:
String targetId - ID of the RPC service provider; empty if calling the parent container
String serviceName - Service name to call
Function, null callback - Callback function (if any) to process the return value of the RPC request
* var_args - Parameters for the RPC request

register

<static> register(serviceName, handler)

Registers an RPC service.

Parameters:
String serviceName - Service name to register
Function handler - Service handler

registerDefault

<static> registerDefault(handler)

Registers a default service handler to process all unknown remote procedure calls, which fail silently by default.

Parameters:
Function handler - Service handler

unregister

<static> unregister(serviceName)

Unregisters an RPC service.

Parameters:
String serviceName - Service name to unregister

unregisterDefault

<static> unregisterDefault()

Unregisters the default service handler. Future unknown remote procedure calls will fail silently.

Back to top

Static Class gadgets.skins

SUMMARY DETAIL

Provides operations for getting display information about the currently shown skin.

Method Summary

<static> String getProperty(propertyKey)

Fetches the display property mapped to the given key.

Method Detail

getProperty

<static> String getProperty(propertyKey)

Fetches the display property mapped to the given key.

Parameters:
String propertyKey - The key to get data for; keys are defined in gadgets.skins.Property

Returns:
String The data

Back to top

Static Class gadgets.skins.Property

SUMMARY DETAIL

All of the display values that can be fetched and used in the gadgets UI. These are the supported keys for the gadgets.skins.getProperty() method.

Field Summary

<static> object ANCHOR_COLOR

The color that anchor tags should use.

<static> object BG_COLOR

The color of the background of the gadget.

<static> object BG_IMAGE

An image to use in the background of the gadget.

<static> object FONT_COLOR

The color in which the main font should be rendered.

Field Detail

ANCHOR_COLOR

<static> object ANCHOR_COLOR

The color that anchor tags should use.

BG_COLOR

<static> object BG_COLOR

The color of the background of the gadget.

BG_IMAGE

<static> object BG_IMAGE

An image to use in the background of the gadget.

FONT_COLOR

<static> object FONT_COLOR

The color in which the main font should be rendered.

Back to top

Static Class gadgets.util

SUMMARY DETAIL

Provides general-purpose utility functions.

Method Summary

<static> String escapeString(str)

Escapes the input using HTML entities to make it safer.

<static> Object getFeatureParameters(feature)

Returns the value of parameters for this feature.

<static> Boolean hasFeature(feature)

Returns whether the specified feature is supported.

<static> registerOnLoadHandler(callback)

Registers an onload handler — a function that's executed when the gadget loads.

<static> String unescapeString(str)

Reverses escapeString

Method Detail

escapeString

<static> String escapeString(str)

Escapes the input using HTML entities to make it safer. The following characters are affected:
• newline (\n, Unicode code point 10)
• carriage return (\r, Unicode 13)
• double quote (", Unicode 34)
• ampersand (&, Unicode 38)
• single quote (', Unicode 39)
• left angle bracket (<, Unicode 60)
• right angle bracket (>, Unicode 62)
• backslash (\, Unicode 92)
• line separator (Unicode 8232)
• paragraph separator (Unicode 8233)

Parameters:
String str - The string to escape

Returns:
String The escaped string

getFeatureParameters

<static> Object getFeatureParameters(feature)

Returns the value of parameters for this feature. A gadget specifies parameters using the <Param> subelement of the <Requires> or <Optional> element.

Parameters:
String feature - The feature to get parameters for

Returns:
Object The parameters for the given feature, or null

hasFeature

<static> Boolean hasFeature(feature)

Returns whether the specified feature is supported.

Parameters:
String feature - The feature to test for

Returns:
Boolean True if the feature is supported

registerOnLoadHandler

<static> registerOnLoadHandler(callback)

Registers an onload handler — a function that's executed when the gadget loads.

Parameters:
Function callback - The handler to run

unescapeString

<static> String unescapeString(str)

Reverses escapeString

Parameters:
String str - The string to unescape.

Returns:
String The unescaped string

Back to top

Static Class gadgets.views

SUMMARY DETAIL

Provides operations for dealing with views.

See also: gadgets.views.View

Method Summary

<static> String bind(urlTemplate, environment)

Binds a URL template with variables in the passed environment to produce a URL string.

<static> gadgets.views.View getCurrentView()

Returns the current view.

<static> Map.<String, String> getParams()

Returns the parameters passed into this gadget for this view.

<static> Map<gadgets.views.ViewType, String, gadgets.views.View> getSupportedViews()

Returns a map of all the supported views.

<static> requestNavigateTo(view, opt_params, opt_ownerId)

Attempts to navigate to this gadget in a different view.

Method Detail

bind

<static> String bind(urlTemplate, environment)

Binds a URL template with variables in the passed environment to produce a URL string.

See also: View.getUrlTemplate()

Parameters:
urlTemplate - A url template for a container view
environment - A set of named variables (for example, [OWNER | PATH | PARAMS | NAME]) of type string.

Returns:
String A URL string

getCurrentView

<static> gadgets.views.View getCurrentView()

Returns the current view.

Returns:
gadgets.views.View The current view

getParams

<static> Map.<String, String> getParams()

Returns the parameters passed into this gadget for this view. Does not include all URL parameters, only the ones passed into gadgets.views.requestNavigateTo.

Returns:
Map.<String, String> The parameter map

getSupportedViews

<static> Map<gadgets.views.ViewType, String, gadgets.views.View> getSupportedViews()

Returns a map of all the supported views. Keys each gadgets.view.View by its name.

Returns:
Map<gadgets.views.ViewType, String, gadgets.views.View> All supported views, keyed by their name attribute.

requestNavigateTo

<static> requestNavigateTo(view, opt_params, opt_ownerId)

Attempts to navigate to this gadget in a different view. If the container supports parameters will pass the optional parameters along to the gadget in the new view.

Parameters:
gadgets.views.View view - The view to navigate to
Map.<String, String> opt_params - Parameters to pass to the gadget after it has been navigated to on the surface
String opt_ownerId - The ID of the owner of the page to navigate to; defaults to the current owner

Back to top

Class gadgets.views.View

SUMMARY DETAIL

Base interface for all view objects.

Method Summary

String bind(environment)

Binds the view's URL template with variables in the passed environment to produce a URL string.

gadgets.views.ViewType, String getName()

Returns the name of this view.

String getUrlTemplate()

Returns a string URI template conforming to the IETF spec draft with variables for substitution.

boolean isOnlyVisibleGadget()

Returns true if the gadget is the only visible gadget in this view.

Method Detail

bind

String bind(environment)

Binds the view's URL template with variables in the passed environment to produce a URL string.

See also: getUrlTemplate()

Parameters:
environment - A set of named variables (for example, [OWNER | PATH | PARAMS | NAME]) of type string.

Returns:
String A URL string

getName

gadgets.views.ViewType, String getName()

Returns the name of this view.

Returns:
gadgets.views.ViewType, String The view name, usually specified as a gadgets.views.ViewType

getUrlTemplate

String getUrlTemplate()

Returns a string URI template conforming to the IETF spec draft with variables for substitution.

Four variables are supported:

name

The name or ID of the application

owner

The ID of the owner of the page

path

An array of path steps

params

Associative array or array[param1,value1,param2,value2,...]

Example

Here are two valid URL template strings:

http://container.com/{-list|/|name,owner,path}?{-join|&|params}
http://container.com/apps/{name}/{owner}{-prefix|/|path}{-opt|?os_|params}{-join|&os_|params} 

Here are some parameters:

{ 
  name : 'Wilma',
  owner : 'Betty',
  path : ['dino','car'], 
  params = { a : 'Barney', b : 'Fred'}
}

With those parameters, the two example URL template strings resolve to the following URLs:

http://container.com/Wilma/Betty/dino/car?a=Barney&b=Fred
http://container.com/apps/Wilma/Betty/dino/car?os_a=Barney&os_b=Fred

See also: bind()

Returns:
String A template that can be used to construct URLs that navigate to this view

isOnlyVisibleGadget

boolean isOnlyVisibleGadget()

Returns true if the gadget is the only visible gadget in this view. On a canvas page or in maximize mode this is most likely true; on a profile page or in dashboard mode, it is most likely false.

Returns:
boolean True if the gadget is the only visible gadget; otherwise, false

Back to top

Static Class gadgets.views.ViewType

SUMMARY DETAIL

Used by Views.

Field Summary

<static> object CANVAS

A view where the gadget is displayed in a very large mode.

<static> object HOME

A view where the gadget is displayed in a small area usually on a page with other gadgets.

<static> object PREVIEW

A demo view of the gadget.

<static> object PROFILE

A view where the gadget is displayed in a small area usually on a page with other gadgets.

Field Detail

CANVAS

<static> object CANVAS

A view where the gadget is displayed in a very large mode. It is typically the main content on the page. The viewer is not always the same as the owner.

HOME

<static> object HOME

A view where the gadget is displayed in a small area usually on a page with other gadgets. Typically the viewer is the same as the owner.

PREVIEW

<static> object PREVIEW

A demo view of the gadget. In this view the owner and viewer are not known.

PROFILE

<static> object PROFILE

A view where the gadget is displayed in a small area usually on a page with other gadgets. The viewer is not always the same as the owner.

Back to top

Static Class gadgets.window

SUMMARY DETAIL

Provides operations for getting information about and modifying the window the gadget is placed in.

Method Summary

<static> adjustHeight(opt_height)

Adjusts the gadget height.

<static> Object getViewportDimensions()

Detects the inner dimensions of a frame.

<static> setTitle(title)

Sets the gadget title.

Method Detail

adjustHeight

<static> adjustHeight(opt_height)

Adjusts the gadget height.

Parameters:
Number opt_height - An optional preferred height in pixels; If not specified, will attempt to fit the gadget to its content

getViewportDimensions

<static> Object getViewportDimensions()

Detects the inner dimensions of a frame. See http://www.quirksmode.org/dom/w3c_cssom.html for more information.

Returns:
Object An object with width and height properties

setTitle

<static> setTitle(title)

Sets the gadget title.

Parameters:
String title - The preferred title