Gadgets JavaScript Reference

Stay organized with collections Save and categorize content based on your preferences.

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.

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

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. 
<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.
    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()
    Returns:
      Object  An object with width and height properties

setTitle

<static> setTitle(title)
    Sets the gadget title.
    Parameters:
      String title - The preferred title

Back to top