OpenSocial 1.0‎ > ‎

Core Gadget Spec

OpenSocial Pages supports the following OpenSocial Core Gadget Specification 1.0.

Elements and Attributes

/Module

The root node of a gadget XML specification is the Module element.

@specificationVersion The version of the OpenSocial specification that container MUST use to interpret the gadget, as described in Versioning (Section 7). If absent, the default value is "1.0".
text()
This tag has child elements. Containers SHOULD NOT interpret child text nodes.

/ModulePrefs

Serves as a container element for all Metadata, Features, and processing rules. For nested element descriptions, see their individual sections of this document.

@title The gadget's title. Containers SHOULD use this value in any situation where a title bar or other identifying name for the gadget is required.
@title_url
Containers SHOULD use this value to provide a link target wherever @title is displayed.
@description A verbose description of the gadget. Containers SHOULD use this value to provide a description of the gadget in any Directory.
@author The name of the author of this gadget. Containers SHOULD display this value in any Directory.
@author_email An email address to use as a point of contact for the author of the gadget. Containers MAY display this value on any Directory.
@screenshot Optional. A 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. Containers SHOULD display this image on Directory pages to provide a preview of the gadget to Users.
@thumbnail Optional. A 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. This SHOULD be smaller than @screenshot and larger than any /ModulePrefs/Link/@rel="icon" (Section 4.1.1.5.1)elements.
@height
The preferred default height of the gadget, in pixels. Containers SHOULD use this value to set an appropriate height for the gadget when it is first rendered.
@width
The preferred default width of he gadget, in pixels. Containers SHOULD use this value to set an appropriate width for the gadget when it is first rendered.
text() This tag has child elements. Containers SHOULD NOT interpret child text nodes.

/ModulePrefs/Require and /ModulePrefs/Optional

Declares Feature dependencies of the gadget.

@feature The name of the Feature.
@version The version of the Feature to provide. Containers MUST interpret this value as described in Versioning (Section 7). If absent, the default value is "1.0".
text() This tag has child elements. Containers SHOULD NOT interpret child text nodes.

Core Features

  • gadgets.io
  • gadgets.util
  • gadgets.Prefs
  • gadgets.json

Optional Features

  • setprefs
  • osapi

/ModulePrefs/Require/Param and /ModulePrefs/Optional/Param

/ModulePrefs/Preload

/ModulePrefs/Icon

Deprecated. Use /ModulePrefs/Link/@rel="icon" (Section 4.1.1.5.1)instead.

/ModulePrefs/Locale

Provides localization information. Containers MUST honor localization rules as specified in Localization (Section 9). Each Locale tag represents localization information for a single locale.

@lang The language for this locale. Containers MUST interpret this as an ISO-639-1 language code, or the special (default) value "all", which Containers MUST interpret as applying to all languages, unless a more specific match is found.
@country The language for this locale. Containers MUST interpret this as an ISO-3166-1 country code, or the special (default) value "all", which Containers MUST interpret as applying to all countries unless a more specific match is found.
@messages A URL pointing to an XML document that contains nested /ModulePrefs/Locale/msg (Section 4.1.1.4.1)elements. Containers MUST honor Retrieval (Section 3.1)and Parsing (Section 3.2)rules for these files. Containers MUST treat all child elements of the root XML element in the document as though they are child nodes of /ModulePrefs/Locale
@language_direction Specifies the direction to render the gadget in. Valid values are "rtl" (right to left) and "ltr" (left to right). Containers SHOULD use this value for determining the appropriate rendering direction for gadget content in this locale. This value controls language direction variables in Localization (Section 9).
text() This tag has child elements. Containers SHOULD NOT interpret child text nodes.

/ModulePrefs/Locale/msg

A single localized value, keyed by @name, with the value coming from text().

@name The name of the localized message. The Container MUST use this as the key for the JavaScript API method gadgets.Prefs.getMsg (Section 12.9.2.8)and for MSG substitutions (see Localization (Section 9)).
text() The value of the message. Containers MUST substitute this value for @name according to Localization (Section 9)rules, and provide this value for any key matching @name in gadgets.Prefs.getMsg (Section 12.9.2.8).

/ModulePrefs/Link

Gadgets MAY specify any number of /ModulePrefs/Link (Section 4.1.1.5)elements, which the Container SHOULD process according to rules specific to the value of /ModulePrefs/Link/@rel. Containers MAY support additional links, but they should pick an appropriate namespace for the rel attribute so as to not conflict with the standard. Containers MUST NOT support non-standard rel attributes with any of the following prefixes: "opensocial", "gadgets", or "events".

@rel The relationship between this link and the document. Valid values are specified in Life Cycle Events (Section 4.1.1.5.2) and Icons (Section 4.1.1.5.1). Containers MAY support additional values, but they MUST be namespaced to avoid collisions.
@href The URL of the link.
text() Not used at this time.

/ModulePrefs/OAuth

/UserPref

A User Preference specification.

@name The name of the preference. Containers MUST provide the current value of the preference when this key is passed to the getters found in gadgets.Prefs (Section 12.9). This is also the key used when performing UP substitutions (see Localization (Section 9)).
@datatype The data type for this preference. Valid values are "string", "hidden", "bool", "list", and "number". The default value is "string".
@display_name The name of the preference for use when rendering an editing interface for prefs. Developers SHOULD use this value to provide a localized name for the preference as described in Localization (Section 9). Containers SHOULD use this value to render any editing interfaces for Users.
@default_value A default value for this preference. Containers MUST provide this value for any calls to the getters in gadgets.Prefs (Section 12.9) whenever the key matches @name.
@required Whether or not a valid value needs to be set for this preference in order for the gadget to function correctly. Valid values are "true" and "false" (default). If the value is "true", Containers SHOULD display an error message or a prompt if there is no valid value stored.
text()
This tag has child elements. Containers SHOULD NOT interpret child text nodes.

/UserPref/EnumValue

A single value that serves as a constraint on User Preferences when /UserPref/@datatype is "enum". Containers SHOULD use EnumValue elements to present Users with a menu when rendering a preferences interface. For details on handling enum preferences, see User Preferences (Section 4.1.2).

@value The value for this enumeration element.
@display_value A textual representation of @value. Defaults to the value of @value. Containers SHOULD display this value in place of @value when rendering a user interface for editing preferences.
text()
Not used at this time.

/Content

Contains the run time portion of the gadget.

@type
REQUIRED. The type of content included in the body of this element. Valid values are "html" and "url". Containers MUST interpret the body of this element according to the specific processing rules for each type.
@href A URL pointing to an external file containing the body of this element.
@preferred_height The suggested default height, in pixels, to use when rendering this gadget. Containers SHOULD use this value as the default height for a gadget in any environment that allows gadgets to have variable heights.
@preferred_width The suggested default width, in pixels, to use when rendering this gadget. Containers SHOULD use this value as the default width for a gadget in any environment that allows gadgets to have variable widths.
@view A comma delimited list of Views in which to include the content in this section. Example: <Content view="Profile, Home, Home.About"/> contains Content for three named views: Profile, Home, and Home.About.
text()
Contains data in an appropriate format to satisfy the requirements for @type. When @type is "html", if no @href is specified, this value MUST be a block of html. The text within this element SHOULD be wrapped in CDATA to avoid having to escape HTML tags and to prevent them from being interpreted by the XML parser.

Variable Substitution

Variables may be substituted into a gadget by replacing special variable tokens with an appropriate value defined elsewhere in the spec. Tokens take the form __<TYPE>_<key>__. For all substitutions, the full token is to be replaced by a value for the following values of <TYPE>:

MSG See Localization (Section 9)
BIDI See Localization (Section 9)
MODULE Currently, "ID" is the only <key> value supported. Containers SHOULD provide a unique value for ID for each instance of a gadget displayed simultaneously.
UP See User Preferences (Section 4.1.2). Whenever there is no value for a token declared in the gadget, Containers SHOULD still replace the token with an empty string. Containers MUST NOT replace tokens with an unknown TYPE with an empty string. Instead, the token should be left in the gadget in it's original form.

Containers MUST perform substitution on all elements and attributes defined in Elements and Attributes (Section 4), with the exceptions of /ModulePrefs/Locale (and children), or any element with an explicit enumeration. Containers SHOULD perform substitution on any custom elements or fields that they support.

Containers MUST perform MSG substitutions in the order listed above. Containers MUST substitute BIDI, MODULE, and UP tokens after substituting MSG values, but they MUST NOT recursively substitute any other tokens.

Localization

Localization of a gadget is achieved primarily through Variable Substitution (Section 8), using the MSG token.

To determine appropriate keys and values for substitution, Containers MUST select an appropriate /ModulePrefs/Locale based on the following rules:

  1. An exact match for the language and country of the User viewing the gadget.
  2. An exact match for language, country = "all".
  3. Language = "all", country = "all'.

Containers MAY provide their own translations or use a third-party translation service if there is no appropriate Locale defined in the gadget.

After selecting a Locale, Containers MUST replace all MSG tokens by using /ModulePrefs/Locale/msg/@name for keys and /ModulePrefs/Locale/msg/text() for values.

Containers MUST perform BIDI token substitution with the following values if /ModulePrefs/Locale/@language_direction is "rtl":

START_EDGE: "right"
END_EDGE: "left"
DIR: "rtl"
REVERSE_DIR: "ltr"

Otherwise:

START_EDGE: "left"
END_EDGE: "right"
DIR: "ltr"
REVERSE_DIR: "rtl"

osapi

The osapi API is more natural to JavaScript developers and more succinct for creating OpenSocial gadgets than the existing JS APIs. It relies on the existing JSON-RPC protocol handlers, and is marked by the use of simple JSON objects as input and output. Note: this specification follows the JSON-RPC spec 1:1, but could also be implemented over REST.

  • Introduces standard method signature for data requests - JSON in, JSON out
  • Input and output parameters match JSON-RPC calls 1:1 and share documentation
  • Data requests look like functions on "service" objects, e.g., osapi.people.get(), instead of opensocial.DataRequest.newXXXRequest()
  • Data requests can be called individually or as part of a batch
  • Batch calls are designed for call chaining. The newBatch() call returns the batch, as does add, so that you can succinctly add more requests to the batch and execute it.
  • Located in the osapi namespace

A container MUST emit the osapi JavaScript libraries and data files required by the libraries if an application includes <Require feature="osapi"/> in the ModulePrefs section of the gadget XML file. The container SHOULD emit the osapi JavaScript libraries and data files required by the libraries if an application optionally requests the feature by including <Optional feature="osapi"/> in the ModulePrefs of the gadget XML file.

Services objects available are dependent upon the container. The server SHOULD generate service objects for all available services. For example, Social API Servers supporting services such as People, and Activities would create JavaScript objects for osapi.people and osapi.activites.

Each service object SHOULD make JavaScript functions available for all methods that the service supports. These functions SHOULD take a single parameter which is a JavaScript representation of the service method's parameters. These functions MUST return a osapi.Request object that may be sent immediately by the osapi.Request.execute, or may be added to a osapi.BatchRequest.

osapi.Request

All methods of osapi service objects (e.g. osapi.people.get()) return a JavaScript object representing the request. These objects MUST support the following method(s):

execute

Signature
osapi.Request.execute(callback)
Description
Sends a request to execute a request to a service method. Generally invoked as <service-name>.<method-name>(params).execute(callback) to send a request to the given method (<method-name>) on the specified service (<service-name>). Takes a callback for response processing.
Parameters
callback Function A callback function to handle the response. The callback function will be invoked with a parameter which contains the response payload specified by the service method that is invoked.
Returns
None

osapi.BatchRequest

Multiple service requests can be combined into a single batch request using the following methods:

newBatch

Signature
osapi.BatchRequest osapi.newBatch()
Description
Creates a new batch request.
Parameters
None
Returns
osapi.BatchRequest A new batch request.

add

Signature
osapi.BatchRequest osapi.add(key, request)
Description
Adds a service request to the batch associated with the specified key. A single batch request can contain both JSON-RPC calls (e.g. osapi.people.get()) and HTTP calls to third parties (e.g. osapi.http.get()).
Parameters
key String A key to access the result of the given request from the parameter sent to the callback function.
requestosapi.RequestA request to add to the batch.
Returns
osapi.BatchRequest A batch request containing the given request (and any previously added requests).

execute

Signature
void osapi.BatchRequest.execute(callback)
Description
Executes all of the requests in the batch. Takes a callback for response processing, which is passed a JSON object mapping each request key to a JSON response object.
Parameters
callback Function A callback function to handle the response. The callback function will be invoked with a parameter which contains a map. The key is the "key" specified in the osapi.BatchRequest.add method. The value is the response payload for the service method that is invoked.
Returns
None

osapi.http

Service object for making HTTP requests to third party servers. This is not a JSON-RPC endpoint, but a third party web service. The object created by methods (e.g. get(), post()) is an osapi.Request object, suitable for immediate execution with osapi.Request.execute or batch operations with osapi.BatchRequest.

head

Signature
<static> osapi.Request osapi.http.head(params)
Description
Creates a HEAD request to an arbitrary URL.
Parameters
params HTTP-Request-Parameters  A JavaScript representation of HTTP-Request-Parameters.
Returns
osapi.Request A request to retrieve information from an arbitrary URL.

get

Signature
<static> osapi.Request osapi.http.get(params)
Description
Creates a GET request to an arbitrary URL.
Parameters
params HTTP-Request-Parameters  A JavaScript representation of HTTP-Request-Parameters.
Returns
osapi.Request A request to retrieve information from an arbitrary URL.

post

Signature
<static> osapi.Request osapi.http.post(params)
Description
Creates a POST request to an arbitrary URL.
Parameters
params HTTP-Request-Parameters A JavaScript representation of HTTP-Request-Parameters. osapi.http.post supports an additional property, 'body', whose value is used as the post body of the HTTP request.
Returns
osapi.Request A request to POST information to an arbitrary URL.

put

Signature
<static> osapi.Request osapi.http.put(params)
Description
Creates a PUT request to an arbitrary URL.
Parameters
params HTTP-Request-Parameters A JavaScript representation of HTTP-Request-Parameters. osapi.http.put supports an additional property, 'body', whose value is used as the post body of the HTTP request.
Returns
osapi.Request A request to PUT information to an arbitrary URL.

delete

Signature
<static> osapi.Request osapi.http.delete(params)
Description
Creates a DELETE request to an arbitrary URL.
Parameters
params HTTP-Request-Parameters A JavaScript representation of HTTP-Request-Parameters.
Returns
osapi.Request A request to delete information at an arbitrary URL.

Comments