opensocial-and-gadgets-spec@googlegroups.com

General OpenSocial social networking REST XML Extensible Markup Language JSON JavaScript Object Notation Atom

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

Gadgets are web-based software components based on HTML, CSS, and JavaScript. They allow developers to easily write useful web applications that work anywhere on the web without modification. They are defined using a declarative XML syntax that is processed by a gadget server into a format that allows them to be embedded into various contexts: standalone web pages, web applications, even other gadgets. A context into which a gadget is embedded is called a gadget container. The container is responsible for managing the gadgets' layout and controls, as well as for supporting various functionality on behalf of the gadget. A gadget may be a simple widget, a reusable component, or a full-blown application, possibly utilizing or communicating with other gadgets. This document describes the gadget XML syntax and how it is processed by a compliant gadget server. In addition, the document describes the core JavaScript APIs that must be made available to every gadget as it is rendered. In addition to the core JavaScript APIs, gadget servers SHOULD support the recommended features listed at the end of this document.

To be a compliant Core Gadget Container, a server MUST be able to satisfy the requests defined in this section.

Gadget Containers MUST be able to fetch remote files, such as gadget specs, message bundles, CSS files, or images. Files SHOULD be retrieved from the source URL that the Developer has provided to the Container. Containers MAY fetch equivalent documents from alternate sources (such as caches or rewriting services) as long as those services are responsible for retrieving the document themselves. Containers SHOULD cache the file after fetching it. If the Container caches a document, it MUST implement the caching policy as defined by RFC2616. Additionally, containers that cache documents SHOULD provide a mechanism to bypass the caching policy entirely to facilitate development, such as a "nocache" query string parameter passed to the page that the gadget is rendered on. Containers MAY use expired cache entries for files to ensure that temporary network problems do not affect end users.

XML documents MUST be well-formed, and Containers MUST display an error to Users if they are asked to process a malformed document. Containers SHOULD provide meaningful error messages to Developers when the specification is malformed. Containers MUST check for a @specificationVersion attribute in the root Module element of all XML documents they parse, and if the attribute is present in a document MUST parse and process the document in accordance with a version of this specification that matches the attribute's value, as described in Versioning. Containers SHOULD support as many historical specification versions as is practical, for backward compatibility with existing Gadgets. If a Container is unable to support a specification version that matches the value of a Gadget's @specificationVersion attribute, the Container MUST display an error message to Users, and SHOULD provide the specification versions that it does support to Developers. Gadget XML Schema and the Message Bundle Schema are provided as reference. These XSD schemas represent the standard elements and attributes defined in the specification body. Containers are allowed to support additional elements and attributes. Discussion Containers MAY support non-standard tags and attributes, but they MUST be enclosed in a separate XML namespace. This namespace SHOULD reflect the name of the organization responsible for the Container to avoid conflicts with other Containers. Containers are encouraged to try to find a way to work within the base schema whenever possible. Whenever an equivalent syntax is introduced into the standard, the Container MUST deprecate the proprietary extension and encourage their users to migrate to the standardized solution. Containers MUST ignore any attributes or tags that they can not interpret. This requirement is included to facilitate extensions to the schema for Container-specific uses. Containers MAY reject XML documents that do not provide all tags and attribute values required by the Container, but if they do so they MUST provide feedback to the Developer explaining the requirement. Containers MUST perform variable substitution according to the rules defined in Variable Substitution. Containers MUST interpret any relative URLs found in XML attributes or values as relative to the gadget spec's URL. Containers MAY refuse to use or display the content referenced by these URLs at their discretion.

A Gadget Container's main function is to translate a Gadget XML file into content to deliver to the end user. A Gadget Rendering Request uses the following inputs: Gadget XML, typically specified as a URL pointing to a file on the web. Any User Preferences stored for a User, used in Variable Substitution. The View to render, for identifying the correct <Content> element(s) to display. The Locale of the User, for Localization. The Module ID of the gadget instance, used in Variable Substitution (Optional). For type="url" gadgets, these inputs are used to generate a URL of content to display to the user as described in /Content/@type. For type="html" gadgets, these inputs are used to generate HTML, CSS, and JavaScript as follows: Fetch the gadget XML using a Retrieve Content Request. Parse the gadget XML using a Parse XML Request, following the behavior defined in Elements and Attributes. Output gadget content as HTML: Gadget MUST be rendered in HTML5 by default. See section on Gadget Doctype. Discussion Standard HTML header, opening <html> tag and <body> tag. <head> information is optional. Core gadgets JavaScript libraries and any additional libraries specified in the gadget. The server SHOULD consolidate all librariess into a single request to minimize the number of HTTP requests made by the client browser. This MAY be followed by JavaScripte required to initialize the included libraries. Results from parsing the Gadget XML file and processing the <Content> sections that match the specified View name. A single call to gadgets.util.runOnLoadHandlers(). Standard HTML closing tags. Containers must also be able to process Data Pipelining and Templating elements in the gadget XML spec.

For Gadgets using an OpenSocial specification version 2.0 or greater, Containers MUST render those Gadgets in HTML5 by default. If a Container supports rendering Gadgets with a specification version less than 2.0, those Gadgets SHOULD continue to be rendered in browser quirks mode. Refer to the Versioning rules for determining Gadget specification version. Containers MAY support ModulePrefs/@doctype as a method for allowing Gadgets to override the default behavior. Containers that implement this SHOULD override the default doctype when encountering ModulePrefs/@doctype. Developers should recognize it may not be possible to honor this attribute in all cases such as when multiple Gadgets are inlined on a single page. Discussion

In order for type="url" gadgets to access JavaScript libraries, the server MUST provide an HTTP service for retrieving core and feature-linked JavaScript. This HTTP service MUST handle requests to URLs provided in the 'libs' parameter described in /Content/@type. The response to these requests MUST contain JavaScript code corresponding to the API(s) required by the type URL gadget.

The following XML elements and attributes MUST be supported by the Container. Additional elements and attributes MAY be supported, but these elements are beyond the scope of this document. Discussion A Container MAY support a simplified XML schema. This format changes some core elements to optional and uses the canonical format for templates and data pipeline blocks. Discussion

The root node of a gadget XML specification is the Module element. The version of the OpenSocial specification that container MUST use to interpret the gadget, as described in Versioning. If absent, the default value is "1.0". This tag has child elements. Containers SHOULD NOT interpret child text nodes.

Serves as a container element for all Metadata, Features, and processing rules. For nested element descriptions, see their individual sections of this document. 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. Containers SHOULD use this value to provide a link target wherever @title is displayed. A verbose description of the gadget. Containers SHOULD use this value to provide a description of the gadget in any Directory. The name of the author of this gadget. Containers SHOULD display this value in any Directory. An email address to use as a point of contact for the author of the gadget. Containers MAY display this value on any Directory. 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. 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"elements. 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. The preferred default width of the gadget, in pixels. Containers SHOULD use this value to set an appropriate width for the gadget when it is first rendered. Optional. A string that identifies the preferred rendering method. When set to "quirksmode", the Gadget SHOULD be rendered in browser quirks mode. This attribute can later be extended to support other DOCTYPEs. Discussion This tag has child elements. Containers SHOULD NOT interpret child text nodes.

Declares Feature dependencies of the gadget. The name of the Feature. The version of the Feature to provide. Containers MUST interpret this value as described in Versioning. If absent, the default value is "1.0". A comma-separated list of Views to load this feature for. This parameter is optional. Containers SHOULD only load the feature when an appropriate view is being rendered. Discussion This tag has child elements. Containers SHOULD NOT interpret child text nodes. A Feature is a set of processing instructions and JavaScript libraries that provides some specific functionality for a Gadget. Containers MUST honor the feature-specific rules for any Feature that they claim to support. Any Feature not specified in this document SHOULD provide an external specification for processing so that implementations will be correct. Containers MUST provide an implementation of each Feature that matches the version specified by the Gadget in the /ModulePrefs/Required/@version or /ModulePrefs/Optional/@version attribute, applying the matching process described in Versioning. Containers MUST NOT substitute versions of Features that do not match the versions requested by the Gadget. Containers SHOULD support as many versions of each Feature as is practical, for backward compatibility with existing Gadgets. Containers MAY use the same implementation to satisfy several different versions of a Feature, if by doing so they fully comply with the Feature's specification. Containers MAY refuse to support Features or specific versions of Features that are known or assumed to be incompatible with the specification version required by the Gadget, or that are known to be incompatible with other Features or versions of Features required by the Gadget. For example, a Container MAY not support the combination of @specificationVersion="1.0" and <Require feature="opensocial" version="2.0">, or the combination of <Require feature="opensocial" version="1.0"> and <Require feature="opensocial-data" version="1.1">. In cases where such combinations are requested, the Features are said to be conflicting. Conflicting Features SHOULD be treated by Containers as if they were unsupported. Containers SHOULD provide an error message describing conflicts to Developers when a conflict is detected. If one or more of the conflicting Features is specified as Optional by a Gadget, and the set of Required features and specification version do not conflict, Containers SHOULD attempt to render the Gadget by removing the conflicting optional Features, returning false from gadgets.util.hasFeature for the features that have been removed. Containers SHOULD include the largest set of Optional Features that does not produce conflicts. It is possible for there to be Feature version conflicts when two valid Feature dependencies exist for the same Feature. This situation can occur when the same Feature is declared at a global scope (no @views specified) and at a view scope (@views specified) but with differing @version values. For example, if we are rendering a Gadget's "default" view and with <Require feature="myfeature" version="1"> and <Require feature="myfeature" version="2" views="default"> declared. In these cases, Containers SHOULD use the Feature version from the Feature declaration that explicitly matches the current View (See /ModulePrefs/Required/@views and /ModulePrefs/Optional/@views) over other Feature declarations. Developers can easily correct this conflict by always using the @views attribute for Features in Gadgets that use mixed Feature versions. Discussion Containers MUST display an error message for any feature that is requested by the Gadget as "required" but is not supported by the container. Containers MUST only return true for gadgets.util.hasFeature if they actually support the given feature name at the version specified in the Gadget XML. Containers MAY only return true for this function if the feature was also requested in the Gadget spec. In addition to explicitly requested features, there is one implicit feature (referred to as "core") that is always present in every Gadget. This "core" feature MUST make the following JavaScript libraries available to Gadgets at runtime without any additional requirements: gadgets.io gadgets.util gadgets.Prefs gadgets.json Gadgets may specify a particular version of the core Feature by including a /ModulePrefs/Require element with @feature="core" and the @version attribute specifying the required version. If an explicit version of the core Feature is not specified, Containers MUST provide a version matching the /@specificationVersion attribute of the Gadget, if present, or matching "1.0" if /@specificationVersion is absent. Containers claiming support for the following Features MUST provide the Gadget with the JavaScript library from the table below. See the JavaScript documentation for each feature for any additional requirements. Containers SHOULD support as many of these features as possible. Feature name Feature version JavaScript library rpc 1.0.0 gadgets.rpc flash 1.0.0 gadgets.flash skins 1.0.0 gadgets.skins dynamic-height 1.0.0 gadgets.window.adjustHeightand gadgets.window.getViewportDimensions settitle 1.0.0 gadgets.window.setTitle minimessage 1.0.0 gadgets.MiniMessage tabs 1.0.0 gadgets.Tab

Provides configuration parameters for a Feature. Containers MUST populate these values in gadgets.util.getFeatureParameters, with @name representing the key, and the child text node representing the value. Containers SHOULD select configuration parameters from the Feature that explicitly matches the current View (See /ModulePrefs/Required/@views and /ModulePrefs/Optional/@views) over other Feature declarations. Discussion The name of the parameter. Containers MUST use this as the key for inputs to gadgets.util.getFeatureParameters. The value for the parameter. Containers MUST use this as the value returned when a matching key is found in gadgets.util.getFeatureParameters.

An HTTP request to pre-fetch. Containers SHOULD pre-fetch all HTTP resources specified by /ModulePrefs/Preload elements. The URL of the request to prefetch. The authentication type to use for making this request. Valid values are the same as for gadgets.io.AuthorizationType, though the names are converted to lower case to appear more natural in XML. Indicates that the Owner should be passed to endpoints when using an authentication type that requires it. Containers MUST pass the owner id when this value is "true" (default). Indicates that the Viewer should be passed to endpoints when using an authentication type that requires it. Containers MUST pass the viewer id when this value is "true" (default). A comma-separated list of Views to pre-fetch this request for. This parameter is optional. Discussion Containers SHOULD only perform preloading when an appropriate view is being rendered. Not used at this time. When honoring the preloading mechanism, Containers MUST convert the results of the prefetching operation into a temporary object that is stored and accessed at runtime via gadgets.io.makeRequest. Containers MUST only consider a makeRequest call to map to a Preload when all of the following conditions are met: /ModulePrefs/Preload/@href matches the "url" parameter of gadgets.io.makeRequest. /ModulePrefs/Preload/@authz matches one of the valid parameters for gadgets.io.AuthorizationType, converted to lower case. /ModulePrefs/Preload/@sign_owner matches the value passed for gadgets.io.RequestParameters.SIGN_OWNER /ModulePrefs/Preload/@sign_viewer matches the value passed for gadgets.io.RequestParameters.SIGN_VIEWER /ModulePrefs/Preload/@views matches the current view (the views attribute is a comma-separated list of matching views).

A link or embedded image that serves as an icon for the gadget. The encoding used for the icon when embedding an image in the Icon element's child text node. Currently, only 'base64' is the only supported value. Containers SHOULD treat child text nodes as a base64 encoded image when this attribute is provided. Otherwise, child text nodes should be interpreted as an image URL. The MIME type of the embedded icon text. Containers SHOULD interpret the encoded child text node using this MIME type. Developers MUST provide a value for the child text node appropriate to the @mode value. If @mode is "base64", the child text node MUST be a base64-encoded image in the format specified by @type. If @mode is missing, the child text node MUST be a valid URL pointing to an image file.

Provides localization information. Containers MUST honor localization rules as specified in Localization. Each Locale tag represents localization information for a single locale. 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. 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. A URL pointing to an XML document that contains nested /ModulePrefs/Locale/msgelements. The XML document should follow the format shown in MessageBundles. Containers MUST honor Retrievaland Parsingrules 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 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. A comma-separated list of Views for this locale. This parameter is optional. Containers SHOULD only select this locale when an appropriate view is being rendered. Discussion This tag has child elements. Containers SHOULD NOT interpret child text nodes.

A single localized value, keyed by @name, with the value coming from text(). The name of the localized message. The Container MUST use this as the key for the JavaScript API method gadgets.Prefs.getMsgand for MSG substitutions (see Localization). The value of the message. Containers MUST substitute this value for @name according to Localizationrules, and provide this value for any key matching @name in gadgets.Prefs.getMsg.

Gadgets MAY specify any number of /ModulePrefs/Linkelements, 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". The relationship between this link and the document. Valid values are specified in Life Cycle Events, Icons, License, Terms of Service, Privacy Policy and Previews. Containers MAY support additional values, but they MUST be namespaced to avoid collisions. The URL of the link. Not used at this time.

OpenSocial defines three icon sizes. The reason for keeping them distinct is so that the container may choose to optimize downloading only one. For example a mobile device may only need "icon", where an application market listing may need all three. When the value for /ModulePrefs/Link/@rel is "icon", "mediumIcon", or "largeIcon", Containers SHOULD treat the link as a reference to an image that represents an application icon for the Gadget. This is preferred over using /ModulePrefs/Icon, which is deprecated.

Discussion There are multiple parties interested in gadget lifecycle events. Gadget lifecycle event notifications could be contained within the browser or transmitted over the web. The gadget specification provides a mechanism for generating web notifications about important lifecycle events. Such events include installs, uninstalls, rate limiting, directory listing changes, and blacklist/whitelist notifications. The Link element allows developers to specify URLs that the container will send data to when certain events are triggered. Whenever an "event" (such as installing or removing an application) occurs on a Container, and the Gadget has specified a value for a matching event name (either as the catch-all "events", or a specific event, named "event.eventtype", the Container MUST make an HTTP request to the specified URL. If the rel attribute matches "opensocialevent.TYPE", then events of TYPE are sent to that endpoint. An optional method attribute can be set to POST or GET to specify how the request should be sent. The default is GET.

Here are some examples: <Link rel="event" href="http://www.example.com/pingme" method="POST/> <Link rel="event.addapp" href="http://www.example.com/add" /> <Link rel="event.removeapp" href="http://www.example.com/remove" />

The request sent to the specified endpoint MUST be signed according to the rules in Signed Fetch. Additionally, one extra parameter named "eventtype" MUST be passed. This value MUST be the same as the event name part of the 'rel' attribute. The following event types are defined. Container custom events should be designated with a domainname prefix to avoid namespace collisions. Event Description addapp Event used to indicate the user has added the application. removeapp Event used to indicate the user has removed the application. app This event indicates that an action has been performed on the app. Note that this action may not have been caused by an action performed by the end user of an application. For example, it is permissible for an application directory or market place to send these events. In the case of an app event an action attribute MUST be included and valid values are "enabled", "disabled", "approved", "submitted", "rejected", "new" and "banned".

When the value for /ModulePrefs/Link/@rel is "license", Containers SHOULD treat the link as a reference to a document that represents the license for the service that is provided by the application. Discussion

When the value for /ModulePrefs/Link/@rel is "privacy-policy", Containers SHOULD treat the link as a reference to a document that represents the privacy policy for the service that is provided by the application. Discussion

When the value for /ModulePrefs/Link/@rel is "terms-of-service", Containers SHOULD treat the link as a reference to a document that represents is the terms of service for the service that is provided by the application. Discussion

It is RECOMMENDED that previews be available on a public Web site. However, considering OpenSocial's growing use behing firewalls it is not necessary for this to be publicly addressible. PNG is the preferred format, though GIF and JPG are also acceptable. Gadget previews SHOULD be 280 pixels wide. The height of the preview can vary so that a screenshot can be scaled appropriately. Containers SHOULD display this image on Directory pages to provide a preview of the gadget to Users. When the value for /ModulePrefs/Link/@rel is "preview", Containers SHOULD treat the link as a reference to an image that represents a screenshot for the Gadget. Additional values of "preview1", "preview2", "preview3","preview4", and "preview5" are also valid. Discussion

Supplies the Container with OAuth service configuration for the gadget. For details, see OAuth. This tag has no attributes and has child elements. Containers SHOULD NOT interpret child text nodes.

A single OAuth service configuration. The name of the service, used for referencing OAuth services at runtime. This parameter is optional, and if unspecified defaults to an empty string. Gadget developers specify which OAuth service they wish to use by passing the service name as a parameter to gadgets.io.makeRequest. Not used at this time.

Represents the OAuth request token URL. See OAuthfor details. The URL for the endpoint. The HTTP verb to use for making the request. Containers MUST use this HTTP method when sending the request to the service URL. This parameter is optional. If unspecified, it defaults to POST. One of 3 possible locations in the request to the service where the OAuth parameters may be passed. Developers MAY use this value to specify the location of OAuth-related parameters. The possible values are "uri-query", "auth-header", and "post-body", corresponding to the options described in Section 5.2 of the OAuth specification. The default value is "auth-header". Not used at this time.

Represents the OAuth access token URLs. See OAuthfor details. The URL for the endpoint. The HTTP verb to use for making the request. Containers MUST use this HTTP method when sending the request to the service URL. This parameter is OPTIONAL. If unspecified, it defaults to POST. One of 3 possible locations in the request to the service where the OAuth parameters may be passed. Developers MAY use this value to specify the location of OAuth-related parameters. The possible values are "uri-query", "auth-header", and "post-body", corresponding to the options described in Section 5.2 of the OAuth specification. The default value is "auth-header". Not used at this time.

The OAuth authorization URL. For details, see Section 6.2 of OAuth specification.

Discussion Supplies the Container with OAuth 2.0 service configuration for the gadget. For details, see OAuth. This tag has no attributes and has child elements. Containers SHOULD NOT interpret child text nodes.

A single OAuth 2.0 service configuration. The name of the service, used for referencing OAuth 2.0 services at runtime. This parameter is optional, and if unspecified defaults to an empty string. Gadget developers specify which OAuth 2.0 service they wish to use by passing the service name as a parameter to gadgets.io.makeRequest. The value of the OAuth 2.0 scope parameter to be used by default in requests. This value is superseded when gadgets.io.RequestParameters.OAUTH2_SCOPE is used. Access Token Scope is defined in Section 3.3 of the OAuth 2.0 specification. This parameter is OPTIONAL. Not used at this time.

Represents the OAuth 2.0 authorization endpoint. For details, see Section 3.1 of OAuth 2.0 specification. Containers MAY provide a default value if this element is not included. The URL for the endpoint. The HTTP verb to use for making the request. Containers MUST use this HTTP method when sending the request to the service URL. This parameter is OPTIONAL. If unspecified, it defaults to GET. Not used at this time.

Represents the OAuth 2.0 token endpoint. For details, see Section 3.2 of OAuth 2.0 specification. Containers MAY provide a default value if this element is not included. The URL for the endpoint. Not used at this time.

Discussion The Security Policy feature is used by an application to request permissions under which to run. Specific permissions are requested with <Param> elements. The Security Policy feature is specified with the feature name "security-policy". A container MAY support the Security Policy feature.

<ModulePrefs > <Optional feature="security-policy" > <Param name="el_escaping">html</Param> </Optional > </ModulePrefs >

Permissions are specified by using <Param> elements to identify the permission name and requested value for the permission. A container may override any application-requested permission with its own security policy. The "el_escaping" permission requests escaping behavior for Expression Language (EL) statements within templates. Valid values are: html - Automatically HTML encode all EL statements. A container MUST HTML escape all elements and attributes. A container SHOULD prevent any JavaScript code from executing in an EL statement. none - Disables automatic escaping. EL expression results will be emitted raw, any markup will be rendered. If an application requests a security policy that is not supported, the container MUST log an error to the gadgets.log. A container MAY render that gadget using a supported security policy, or display an appropriate error message. Escaping rules specified with the "el_escaping" parameter are applied to all views. An application may request a different escaping policy for a specific view by specifying the view name as a suffix with a preceeding colon to the el_escaping name. For example, to specify html escaping on the 'profile' view and no escaping for all other views, the following is used:

<ModulePrefs > <Optional feature="security-policy"> <Param name="el_escaping:profile" >html</Param> <Param name="el_escaping" >none</Param> </Optional > </ModulePrefs >

Containers SHOULD apply HTML escaping by default to all views that are not otherwise constrained or protected by a security mechanism (ex: jail domained IFrame, trusted partner, pre-filtered content). In addition to the above permission, a container may extend the Security Policy feature to add any container-specific security permission or experiment.

A User Preference specification. 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. This is also the key used when performing ${Prefs} variable substitutions (see Variable Substitution). The data type for this preference. Valid values are "string", "hidden", "bool", "list", and "number". The default value is "string". 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. Containers SHOULD use this value to render any editing interfaces for Users. A default value for this preference. Containers MUST provide this value for any calls to the getters in gadgets.Prefs whenever the key matches @name. 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. This tag has child elements. Containers SHOULD NOT interpret child text nodes. Containers MUST interpret /UserPref elements by making each preference available to the Gadget through the gadgets.Prefs library. Containers MUST treat /UserPref/@name as the keys for indexing into stored preference values when invoking the getters of gadgets.Prefs. Containers MUST perform Variable Substitution for user preferences by treating /UserPref/@name as the key in the token and the stored value for the preference as the replacement value. Containers MUST provide /UserPref/@default_value as the value for the preference when the User or Gadget has not set a value explicitly. Containers SHOULD support the following datatypes: A string accessed by gadgets.Prefs.getString. Default data type. Evaluates to true or false when accessed by gadgets.Prefs.getBool() a list of values specified by /UserPref/EnumValue elements. Current value is accessed by gadgets.Prefs.getString() a non-visible string that is not user editable but can be accessed by gadgets.Prefs.getString() a pipe-delimited (|) string of values, returned as a JavaScript array when accessed by gadgets.Prefs.getArray(). Containers SHOULD provide a user interface so that all visible User Preferences (any type other than "hidden") may be modified by the User of the Gadget.

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. The value for this enumeration element. 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. Not used at this time.

Contains data pipeline tags defined for the gadget. Data Pipeline results defined in this block are registered globally for all views by default. Individual Data pipeline tags may be scoped to a particular view(s) by adding the @view attribute to the tag. Adding the @view attribute to a data pipeline tag has the same effect as if the data pipeline tags were defined within a data script nested in a Content block. See Data Pipelining for more information on data pipeline tags. Discussion

Discussion Currently, when making a remote request, either through the OSAPI or makeRequest, the full URL of the remote service that is being invoked must be specified. However, often, there are multiple service endpoints that use the same API. Consider the following examples. A large enterprise may have a backend system, e.g. SharePoint, or a cloud system, e.g. Salesforce, whose information they would like to make available to application developers. These developers may be internal to the enterprise, or third party application providers. In addition, it's not uncommon to have multiple instances of the backend service that can be used, e.g. development, QA, Production. Internal developers should not have to change the gadget definition when moving between these environments. Further, third party vendors need a way to identify a particular service in the gadget XML and then allow for a "late binding" to the actual endpoint that realizes that service. The "Alias" request parameter may be used to satisfy these requirements. Configuring an "Alias" works in a manner similar to configuring an OAuth service. That is, in OAuth, there is configuration within the gadget XML to identify which request set of endpoints to use to get the access tokens etc, but the registration of the consumer secret is provided to the container outside of the gadget XML. In the case of "Alias", there is configuration within the gadget XML to name the service and specify which "service tag" the container should use. It is possible for the same service tag to be registered for multiple external service endpoints within the same container. For example, there could be multiple SharePoint instances even though the application has one alias. Determination of the proper external service endpoint is at the discretion of the container and various schemes may be used. For example, the container may prompt the user at the time of gadget installation to select which external service endpoint to use. One of the primary motivations for Alias is to make it easy for OpenSocial containers to expose legacy systems endpoints to application providers. Therefore, its expected that a common set of service tags will be defined and maintained publicly. One such example is maintained by the OpenSocial community and is available on the wiki at http://docs.opensocial.org/display/OSD/OpenSocial+External+Services+Tag+Registry.

The unique identifier of the API to the external service, e.g. opensocial:service://microsoft.com/sharepoint/api?version=1. The name to be used in the "alias" request parameters. The container will use the name to look up the proper service tag. The tag that identifies the API to the external service.

Contains the run time portion of the gadget. 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. When /Content/@type is "html", Containers MUST perform Variable Substitution on the final assembled content section. When /Content/@type is "url", Containers MUST display a direct view of the value for /Content/@href as specified in the Content Redirect section. Discussion A URL pointing to an external file containing the body of this element. If @type is "url", this value is REQUIRED. If @type is "url", this value represents an external document that SHOULD be presented directly to Users without filtering as specified in the Content Redirect section. If @type is "html", the Container MUST proxy the current content section. Discussion 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. If both the @height and @preferred_height are specified, the container SHOULD respect the value of @preferred_height. 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. If both the @width and @preferred_width are specified, the container SHOULD respect the value of @preferred_width. 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. To assemble a View, all Content sections where @view contains the required view name are concatenated. Concatenation does not happen when the @href is set on a <Content> block. In this case, the set of view names on <Content> blocks with @href set to a non-null, non-empty string MUST be unique within the Gadget XML. If this is not true, the markup is invalid. A container may process gadget markup ahead of acceptance into a container's application gallery, checking for the href conditions when importing gadget XML. This validity check need not be performed at render time. The request issued to the URL in /Content/@href MUST be signed according to the rules specified because of the current /Content/@type. Discussion 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.

Containers MAY support content rewriting. The feature supports rewriting the content of a generated gadget and allow developers to control how the behavior of the rewriter through an optional gadget feature named content-rewrite. The content-rewrite feature defines a set of rewriting operations that a container can perform on rendered and proxied content and defines rules to allow developers to control which content the rewriter can operate on.

The rewriter feature has the general form : <Optional feature="content-rewrite"> <Param name="expires">86400</Param> <Param name="include-url"></Param> <Param name="exclude-url">excluded</Param> <Param name="exclude-url">moreexcluded</Param> <Param name="minify-css">true</Param> <Param name="minify-js">true</Param> <Param name="minify-html">true</Param> </Optional>

The parameters are defined as follows: expires - The duration in seconds to force as minimum HTTP cache time for content fetched through the proxy via a rewritten URL. Default 86400. include-url - Any URL which contains this parameters value as a case-insensitive substring is considered rewriteable. The literal string "*" is a special case and implies all URLs. If not specified an entry with the value "*" is assumed. This parameter can be repeated. exclude-url - Any URL which contains this parameters value as a case-insensitive substring is excluded from rewriting. The literal string "*" implies all URLs and effectively disables all rewriting. This parameter can be repeated. minify-css - Controls whether the container will attempt to minify css in style tags and referenced css files. Valid values are "true"|"false". Default is "true". minify-js - Controls whether the container will attempt to minify JS in script tags and referenced JS files. Valid values are true|false. Valid values are "true"|"false". Default is "true". minify-html - Controls whether the container will attempt to minify HTML content. Valid values are true|false. Valid values are "true"|"false". Default is "true". Matches for "exclude-url" take precedence over matches for "include-url" Note that the special use of "*" to denote all URLs should not be interpreted as support for GLOB or RegEx matching on strings. Containers are free to perform additional optimizations when rewriting links including but not limited to: Extract @import directives from style tags and convert them into link tags in the head tag of the containing HTML content. Merge multiple CSS fetches from successive link tags into one link tag that causes the proxy to concatenate the content fetched from the individual URLs. Merge contiguous <script src=xxx> tags into one concatenating proxy fetch.

Rewrite only gif images <Optional feature="content-rewrite"> <Param name="include-url">.gif</Param> </Optional>

Rewrite only gif images that do not contain "animated" or "cdn" <Optional feature="content-rewrite"> <Param name="include-url">.gif</Param> <Param name="exclude-url">animated</Param> <Param name="exclude-url">cdn</Param> </Optional>

Disable all rewriting <Optional feature="content-rewrite"> <Param name="exclude-url">*</Param> </Optional>

When rendering an OpenSocial Gadget, the container MUST determine if the content for the active view is to be proxied. This is done by checking for the presence of a /Content/@href attribute. If the attribute is present, the container MUST issue an HTTP request to the URI specified by the href attribute following the rules defined in gadgets.io.makeRequest. Attributes on the Content element map to makeRequest as follows: authz: gadgets.io.AuthorizationType (values are canonicalized by converting to lower case. Default value is 'none') oauth_received_callback: gadgets.io.RequestParameters.OAUTH_RECEIVED_CALLBACK oauth_request_token: gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN oauth_request_token_secret: gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET oauth_service_name: gadgets.io.RequestParameters.OAUTH_SERVICE_NAME oauth2_scope: gadgets.io.RequestParameters.OAUTH2_SCOPE Discussion oauth_token_name: gadgets.io.RequestParameters.OAUTH_TOKEN_NAME oauth_use_token: gadgets.io.RequestParameters.OAUTH_USE_TOKEN refresh_interval: gadgets.io.RequestParameters.REFRESH_INTERVAL sign_owner: gadgets.io.RequestParameters.SIGN_OWNER (default 'true') sign_viewer: gadgets.io.RequestParameters.SIGN_VIEWER (default 'true') Note that these attributes also apply to Preload elements. The container MUST also add the following parameters to the URI query string: lang: The language of the user viewing the page as specified in Section 3 i under Process in this document. country: The country of the user viewing the page as specified in Section 3 i under Process in this document. opensocial_proxied_content: MUST be present and set to 1. Servers can use this to distinguish proxied content renders from gadgets.io.makeRequest() calls. Remote sites that expect proxied content requests SHOULD reject requests that do not have opensocial_proxied_content set to 1. If a remote site fails to implement this check, any content in the POST body may be spoofed by a malicious user or application. By default, the request is sent to the remote site MUST be sent to the remote site as an HTTP GET. When the Content section includes Data Pipelining elements, the container MUST send the data to the request URI using an HTTP POST. The structure of this data will match the JSON-RPC format. For more information on Data Pipelining and Proxied Content, see

If the response to the proxied request returns a successful HTTP status code, the container MUST interpret the resulting response body according to the rules for content declared inline. If the response to the proxied request returns an unsuccessful HTTP status code, the container SHOULD present a meaningful error message to the end user. Containers SHOULD obtain a suitable error message for display by displaying the content specified for a view named as view-name.error, where view-name matches the name of the view that the proxied request was being processed for. If an exact match can not be found, the special value default.error should be used. If default.error is not present, the container SHOULD display a generic message indicating that a problem occurred.

Containers SHOULD cache the results of the HTTP request following the recommendations of section 13 of RFC 2616. If a container does support caching of data, it MUST also support overriding HTTP caching by using the value specified for refresh_interval. Caches SHOULD be keyed using the following: The URI of the proxied request. The opensocial owner id, if sign_owner is set to true and requests are authenticated. The opensocial viewer id, if sign_viewer is set to true and requests are authenticated. The language and country passed in to the proxied URI. Containers MAY cache unsuccessful HTTP responses ("negative caching"), but SHOULD NOT cache unsuccessful responses for a period longer than 5 minutes.

The container MUST normalize content bodies in a way that preserves semantic meaning in the resulting HTML output. Specifically, containers MUST preserve the structure of the document for the context the gadget will be rendered in as follows: If the document is a complete HTML document, including opening and closing html tags, the container MUST retain the semantic meaning of document type definition declarations as well as the relative position of elements in the document. A container MAY choose to move elements from the head of a document and into the body (or vice versa), but the end result MUST behave the same as the original input . Containers MAY modify the document in other ways for optimization and security purposes as long as semantics are preserved

The container MUST resolve all URI attributes and values relative to the location of the gadget spec xml document. This DOES NOT include links inside of the body of the Content element at this point in time.

When /Content/@type is "url", Containers MUST display a direct view of the value for /Content/@href (for a web context, this SHOULD be an HTML iframe). The Container MUST append the following query string parameters to the URL: A query parameter for each User Preference as a name/value pair. The language of the User viewing the gadget (valid values are the same as for /ModulePrefs/Locale/@lang). The country of the User viewing the gadget. (valid values are the same as for /ModulePrefs/Locale/@country). A relative URL that points to any JavaScript files necessary to satisfy the features specified in /ModulePrefs/Require and /ModulePrefs/Optional elements in the Gadget. If the /Content/@authz attribute is present and it equals "signed", the container MUST vouch for the user's identity to the destination server. This follows the steps outlined in the Signed Fetch section of this specification. Discussion

Both the overall OpenSocial specification and individual Gadget Features are versioned. Gadgets SHOULD specify the version of the specification that Containers should use to interpret them by including the @specificationVersion attribute on the root Module element, and the versions of any Features they use by including the @version attribute on /ModulePrefs/Require and /ModulePrefs/Optional elements. The versions of standard Features defined by this specification are detailed in ModulePrefs. Extensions to the OpenSocial specification MUST define the version of any Features specified by the extension. Containers SHOULD document the version of any custom Features they provide. Discussion Versions are specified as a string of up to three non-negative integers, separated by the dot (.) character, for example "1.0.0", "1.2.1", or "1.3.12". The three components of a version each signify a guarantee about the compatibility of that version with other versions of the same specification or Feature. are represented by the first number in the sequence, for example "1" in "1.0.0", "1.0.2", "1.3.0", etc. Changes in the major version signify backward-incompatible changes from previous versions of the specification or Feature. For example, when Feature APIs or Gadget XML elements and attributes are removed or renamed, or significant changes to the Gadget rendering process are made that would result in malfunctions for existing Gadgets, the major version MUST be incremented. are represented by the second number in the sequence, for example "2" in "1.2.0", "1.2.1", "3.2.0", etc. Minor versions are interpreted relative to the preceding major version number. Changes in the minor version signify backward-compatible but forward-incompatible changes from previous versions of the specification or Feature. For example, when new Feature APIs or Gadget XML elements and attributes are added, the minor version MUST be incremented, but the major version SHOULD NOT change, because the new version is backward-compatible with Gadgets that were written to use previous minor versions of the same major version, but containers that do not implement the new minor version will not be forward-compatible with Gadgets written to use the new minor version. are represented by the third number in the sequence, for example "3" in "1.0.3", "1.1.3", "2.2.3", etc. Patch versions are interpreted relative to the preceding major and minor version numbers. Changes in the patch version signify changes that are both backward-compatible and forward-compatible with previous versions of the specification or Feature. For example, when making minor clarifications, fixing typos and bugs, or making other small changes that neither affect the functionality of existing Gadgets, nor introduce functionality that would be incompatible with containers that only implement older patch versions of the same minor version, the patch version MUST be incremented, but the minor and major versions SHOULD NOT change. The value of the /@specificationVersion, /ModulePrefs/Require/@version, and /ModulePrefs/Optional/@version attributes may fully specify all three of the major version, minor version, and patch version numbers. For example, "1.0.0" or "1.2.3". When all three version components are specified, containers MUST conform to the exact version of the specification or Feature that is requested. Alternately, these attributes may specify the major and minor versions only, without the patch version, or the major version only, without the minor and patch versions. For example, "1.0", "2.3", and "3" are all valid. When these attributes specify partial versions, the container MUST conform to a version of the specification or Feature that matches the version components specified, but MAY use any version of the unspecified components. For example, a Container that is processing a Gadget with /@specificationVersion="2.3" may process it according to specification version 2.3.0, 2.3.1, 2.3.22, etc., but not 2.2.0, 2.4.0, 2.30.0, 3.0.0, etc. A Container that is processing a Gadget with /ModulePrefs/Require/@version="3" MAY provide the specified Feature at version 3.0.0, 3.0.1, 3.1.0, 3.1.11, etc., but not 2.0.0, 4.0.0, 33.0.0, etc. It is RECOMMENDED that Gadget Developers specify the most general version that will satisfy the requirements of a Gadget. Usually, major and minor versions will suffice, and the patch version MAY be omitted from /@specificationVersion, /ModulePrefs/Require/@version, and /ModulePrefs/Optional/@version attributes. If the /@specificationVersion attribute or any /ModulePrefs/Require/@version or /ModulePrefs/Optional/@version attributes are absent, they are assumed to have the value "1.0". As described above, this value will match any version beginning with "1.0", including 1.0.0, 1.0.1, 1.0.22, etc., but not 1.1.0, 2.0.0, etc. This default value will not change in future versions of the specification, ensuring that Gadgets that omit these values will not have sudden, unexpected changes in behavior when containers adopt new versions of the OpenSocial specification or Features.

Variables may be substituted into a gadget by evaluating Expression Language (EL) statements. EL statements consist of a dollar sign and curly braces surrounding a statement.

Example: EL statement One plus one is equal to ${1+1}

EL statements may be used to access values stored in reserved variable keys, variables defined with data pipeline tags, or literal values. Containers MUST support resolving variables using this syntax.

The Expression Language (EL) is based on JSPEL. The EL version in OpenSocial supports all basic operations, such as string concatenation and match functions, but does not currently support defining custom functions. Discussion

All variables are stored in the DataContext.

There are a number of reserved variable keys. These are reserved for use by the container. If a gadget attempts to redefine any of these variables, the container MUST generate an error. Variable Key Description Scope Msg Contains all message bundle variables for the current locale. Available anywhere within gadget, including ModulePrefs and root Module element. Message bundle values may reference other message bundle variables by making use of the ${Msg.NAME} syntax within the value. ViewParams Contains all values passed as viewParams with a call to gadgets.views.requestNavigateTo. EL statements against this key will resolve to the same values as calls against the result of gadgets.views.getParams in the Javascript API. Available within Content blocks, Data Pipeline tags, and OpenSocial Markup Language (OSML) tags. Prefs Contains all named values defined in the UserPref section of the gadget and module dimensions and messages. EL statements against this key will resolve to the same values as calls against the result of gadgets.Prefs in the Javascript API. Values are exposed as fields to the EL. Ex: Current language is accessed as ${Prefs.Lang}. Available anywhere within gadget. Top Reserved variable used by OpenSocial Templating to represent the top level variables registered with the DataContext Within content and templates My Reserved variable used by OpenSocial Templating to hold local variables passed to the template instance. Within a template instance Cur Reserved variable used by OSML repeaters as defined in the OpenSocial Templating specification. Represents the current value or object as a for-each loop would. Within a repeater loop Context Variable used by OSML and templates to hold additional variables generated while processing templates and loops as defined in the OpenSocial Templating specification. Additional variables are unique ID, current index in repeat, and count of repeat. Within a template or repeater loop Viewer Reserved for future use. N/A Owner Reserved for future use. N/A Gadget Reserved for future use. N/A

The older variable tokens format has been deprecated in favor of the EL syntax. The legacy variables take the form __<TYPE>_<key>__. For all substitutions, the full token is to be replaced by a value for the following values of <TYPE>: See Localization See Localization Currently, "ID" is the only <key> value supported. Containers SHOULD provide a unique value for ID for each instance of a gadget displayed simultaneously. See User Preferences. 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, 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 of a gadget is achieved primarily through Variable Substitution, using the ${Msg} variable and message bundles. To determine appropriate keys and values for substitution, Containers MUST select an appropriate /ModulePrefs/Locale based on the following rules: An exact match for the language and country of the User viewing the gadget. An exact match for language, country = "all". Language = "all", country = "all'. Containers SHOULD select a Locale that supports the current view over any other Locale. The Views supported by a Locale are specified at /ModulePrefs/Locale/@views. Discussion 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"

Discussion The gadgets i18n strategy centers around message bundles. Message bundles are XML files that contain the translated strings for a given locale. Each string is identified by a unique name that is the same across bundles. Message bundles can be hosted at any URL, and can be shared between applications. Message bundles contain only one locale. Message bundles have the following format: <messagebundle> <msg name="hello_world"> Hello World. </msg> <msg name="color">Color</msg> <msg name="red">Red</msg> <msg name="green">Green</msg> <msg name="blue">Blue</msg> <msg name="gray">Gray</msg> <msg name="purple">Purple</msg> <msg name="black">Black</msg> </messagebundle> By convention, external message bundles are named as <language>_<country>.xml Where there is no language- or country-specific value, the convention is to use “ALL.” For example, the file de_ALL.xml applies to all German speakers, regardless of their country. The message bundle ALL_ALL.xml is the file that is used by default. Message bundles may be specified inline or as externally referenced XML files in the /ModulePrefs/Locale section.

Containers MUST support signing of HTTP requests for gadgets.io.makeRequest, Proxied Content, Content Redirect, Life Cycle Events, and Preloading (Discussion). The container does this by doing the following: Removing any request parameters with names that begin with oauth, xoauth, or opensocial (case insensitive). Adding the following parameters to the request query string: Optional. The ID of the current viewer, which matches the getId() value on the viewer person object. Required. The ID of the current owner, which matches the getId() value on the owner person object. 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. 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. 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. 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. Signing the resulting request according to section 9 of the OAuth specification.

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.

Note that the OAuth 2.0 specification is not currently approved by the IETF and references to OAuth 2 capabilities are based on version 22 of the OAuth 2.0 specification. Discussion As mentioned previously in this specification and other OpenSocial 2.0 specifications, OpenSocial containers MUST be able to proxy OAuth requests for gadgets. The main mechanism used to accomplish proxy requests is the gadgets.io.makeRequest method. This method MUST be implemented to handle gadget OAuth proxy requests. When proxying a gadget's request, Core Gadget Servers SHOULD use an OAuth token specific to the gadget making the request, and specific to either the Viewer or the Owner of the container page. This implies that OAuth information, such as access tokens are stored so they may be retrieved by service name, gadget id and user id, although this is implementation specific. When proxying a gadget's request, OpenSocial containers MAY use an OAuth client key and secret specific to the gadget making the request (xoauth_requestor_id request context parameter), or MAY use the container's OAuth client key and secret. For more details, see the OAuth 1.0A specification or the OAuth 2.0 specification.

OAuth client keys and secrets are typically obtained by registering a gadget, application or server with a service provider at a web page provided by the service provider. Once the keys/secrets are obtained, they are typically placed in a key store on the Core Gadget Server. However, the exact method of accomplishing registration is implementation specific. If a Core Gadget Server uses its own client key and secret when making OAuth requests, it must be registered with each service provider it will communicate with. In this case, the Core Gadget Server will use the same client key and client secret for every OAuth request to a particular service provider.

When proxying a gadgets.io.makeRequestof gadgets.io.AuthorizationType 'OAUTH' for OAuth 1.0A, the container SHOULD do the following: If the Core Gadget Server finds an appropriate OAuth access token and secret for the request, the Container signs the outgoing request according to the OAuth specification. If the container finds no appropriate OAuth access token, but an appropriate OAuth request token for the request, the container accesses the access token endpoint of the target service provider, and attempts to exchange the request token for an access token. If successful, the container then immediately uses the access token to sign the request made by the gadget. If the container finds neither an appropriate OAuth access token or request token, it accesses the request token endpoint of the target service provider to obtain a request token. It then returns an error message to the Gadget that contains, among other things, the user authorization URL at the target service provider. The Gadget is expected to redirect the User Agent to that authorization URL and re-attempt the gadgets.io.makeRequestonce the user has approved the OAuth access. Proxying a request for an OAuth 2 service provider is different based on the grant type being used. This description is for an authorization grant. gadgets.io.makeRequestof gadgets.io.AuthorizationType 'OAUTH2' for OAuth 2.0, the container SHOULD do the following: It is assumed the Core Gadget Server can find a client key and secret for the service provider to be contacted. If these cannot be found, a "permanent" failure is returned to the gadget. If the Core Gadget Server finds an appropriate OAuth access token it contacts the service provider resource endpoint using OAuth 2.0 client code that is compatible with the specific OAuth 2.0 implementation of the service provider, passes the token (among other data), and requests the data. If the Core Gadget Server finds no appropriate OAuth access token, it returns an error to the gadget along with a redirection URL based on the gadget XMLs /ModulePrefs/OAuth/Service/Authorization setting. The gadget is expected to redirect the User Agent (browser) to the authorization URL for the service provider. Once the user authenticates and authorizes the gadget, the gadget will receive a redirection URL from the serivce provider that includes an authorization code. The gadget redirects the User Agent (browser) back to the Core Gadget Server, which receives the authorization code from the service provider. The Core Gadget Server contacts the token endpoint of the service provider, passing the client key/secrets along with the authorization code to obtain an access token. The Core Gadget Server returns an error to the gadget to indicate a need to retry the makeRequest. The gadget retries the makeRequest. Discussion

OpenSocial's JavaScript API uses the following patterns: JavaScript is not strongly typed, but in order to make the developer experience consistent, the APIs are defined as if JavaScript supported strongly typed data. Cases where a parameter or return value are defined as a certain type in the documentation indicate that this is the only type that can be provided or accepted for OpenSocial compatibility. Any exceptions to this rule will be directly documented in the reference. As an example, the getErrorCode method is defined in the JavaScript API reference as returning a value of the type opensocial.ResponseItem.Error, although in practice this value will be a normal JavaScript string. However, developers can be assured that in a compliant container, the string returned is one of the opensocial.ResponseItem.Error fields. Enumerations figure heavily into the OpenSocial API. Developers are permitted to reference an enum or use the enum's value directly. To avoid collisions related to extensibility, containers must ensure that the names and values for an enum match the ones defined in the spec and that custom values are namespaced appropriately. For example, an Orkut custom field named MY_PERSON_FIELD could have a name of Orkut.PersonField.MY_PERSON_FIELD and a value of "Orkut.myPersonField". Many of the OpenSocial methods have a large number of optional parameters. JavaScript's lack of strong typing makes overloading difficult at best, and having functions with a large amount of parameters can be difficult to manage (especially for developers not using a nice IDE). OpenSocial uses the "object bag" approach to optional parameters: many methods take an additional opt_params parameter that takes the form of a map of parameter names to their corresponding values. For each method which uses an opt_params map the spec defines all of the valid fields that will be read out of the map by the container. These fields have defined types as discussed in the Virtual typing section. If a developer adds an invalid value for a field in the map the container SHOULD return the BAD_REQUEST error code.

Namespace for top-level gadget functions.

<static> gadgets.log(message) Description: Log an informational message. Parameters: Name Type Description message Object The message to log

<static> gadgets.warn(message) Description: Log a warning message. Parameters: Name Type Description message Object The message to log

<static> gadgets.error(message) Description: Log an error message. Parameters: Name Type Description message Object The message to log

<static> gadgets.setLogLevel(logLevel) Description: Sets the log level threshold. Parameters: Name Type Description logLevel Number New log level threshold.

Used by gadgets.setLogLevel. Log level for informational logging. Log level for warning logging. Log level for error logging. Log level for no logging.

Provides remote content retrieval functions.

<static> Type: {String} gadgets.io.encodeValues(fields) Description: Converts an input object into a URL-encoded data string. (key=value&...) Parameters: Name Type Description fields Object The post fields you wish to encode Returns: Type Description String The processed post data; this includes a trailing ampersand (&)

<static> Type: {String} gadgets.io.getProxyUrl(url, opt_params) Description: Gets the proxy version of the passed-in URL. Parameters: Name Type Description url String The URL to get the proxy URL for opt_params Map<String|String> Additional optional parameters to pass to the request Returns: Type Description String The proxied version of the URL

<static> gadgets.io.makeRequest(url, callback, opt_params) Description: 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);

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. This follows the steps outlined in the Signed Fetch section of this specification.

Note: This text was moved to section OAuth Key Management

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.

The following additional parameters may be specified in opt_params: Specifies the 'Alias' request parameter as defined by Core-Data Request Parameters. Discussion Returns the full headers from the response. The URL to return after authorization. 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. The secret corresponding to a preapproved request token. This parameter is optional. The nickname the gadget uses to refer to the OAuth <Service> element from its XML spec. If unspecified, defaults to "". The value of the OAuth 2.0 scope parameter to be used with this request. Access Token Scope is defined in Section 3.3 of the OAuth 2.0 specification. Discussion 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. This parameter can be either "never", "if_available", or "always". Some service provider APIs to do not require an OAuth access token. Such APIs authenticate the calling application via the OAuth consumer key, and then allow the request to proceed. You can set OAUTH_USE_TOKEN to "never" to avoid unnecessarily requesting the user's approval to access such an API. Some OAuth APIs provide limited data if a user has not granted approval, but can offer additional functionality if a user has granted the calling application an access token. If you are using an API that can accept an OAuth access token, but does not require the token, you can set OAUTH_USE_TOKEN to "if_available". If the user has already approved access, the access token will be sent. If the user has not approved access, the request will proceed without an access token. Many OAuth APIs only function if an access token is sent. You must ask for the user's approval before using such an API. Set OAUTH_USE_TOKEN to "always" to require that an access token be available. If no access token is available, the approval URL will be returned to your gadget. If you set AUTHORIZATION to SIGNED, the default value for OAUTH_USE_TOKEN is "never". If you set AUTHORIZATION to OAUTH, the default value for OAUTH_USE_TOKEN is "always". 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 opensocial_app_url that identifies the gadget making the request.

When using Signed Fetch, the param used to indicate the URL of the application making the request is "opensocial_app_url". This has the same semantic as " xoauth_app_url". In order to be consistent, the same identifier will be used for OAuth. Containers SHOULD use "opensocial_app_url" and treat "xoauth_app_url" as deprecated. However, for backward compatibility, and to avoid breaking a container on a point release, MUST support either parameter.

The function specified as the callback parameter is passed a JavaScript object with the following fields: Parsed data of the response, if applicable. This will contain a different type of data depending on the type of request that was made. See the ContentType parameters for information about what to expect in this field. The raw response text is returned if the response could not be parsed. This will contain an array of any errors that occurred when making this request. For example, if a 500 error occurred in the request: [ "500 error" ] An object containing the response headers. Header names are used as the keys for this object. This is a numeric value representing the HTTP status code of the response. This will return the unparsed text of the response. 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. 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. 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.

Name Type Description url String The URL where the content is located callback Function The function to call with the data from the URL once it is fetched. The callback function will not be called until after the existing callstack has completed execution. opt_params Map.<gadgets.io.RequestParameters|Object> Additional request parameters or proxy request parameters

Used by RequestParameters. No authorization. This field may be used interchangeably with the string 'NONE'. The container will use OAuth 1.0A for authentication. This field may be used interchangeably with the string 'OAUTH'. The container will use OAuth 2.0 for authentication. This field may be used interchangeably with the string 'OAUTH2'. Discussion The request will be signed by the container. This field may be used interchangeably with the string 'SIGNED'.

Used by RequestParameters. Returns a DOM object; used for fetching XML. This field may be used interchangeably with the string 'DOM'. Returns a JSON representation of an RSS or Atom feed. This field may be used interchangeably with the string 'FEED'. Returns a JSON object. This field may be used interchangeably with the string 'JSON'. Returns text; used for fetching HTML. This field may be used interchangeably with the string 'TEXT'.

Defines values for RequestParameters.METHOD. Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'DELETE'. The default type. This field may be used interchangeably with the string 'GET'. Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'HEAD'. Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'POST'. Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'PATCH'. Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'PUT'.

Used by gadgets.io.getProxyUrl() method. Explicitly sets the lifespan of cached content. The Refresh Interval is the number of seconds the container should cache the given response. By default, the HTTP caching headers will be respected for fetched content. If the refresh interval is set, this value will take precedence over any HTTP cache headers. If this value is not set and there are no HTTP caching headers specified, this value will default to 3600 (one hour). Note that Signed requests and objects with POST_DATA present will generally not be cached. This field may be used interchangeably with the string 'REFRESH_INTERVAL'.

Used by the gadgets.io.makeRequest() method. The type of authentication to use when fetching the content; defaults to AuthorizationType.NONE. Specified as an AuthorizationType. This field may be used interchangeably with the string 'AUTHORIZATION'. The type of content that lives at the URL; defaults to ContentType.TEXT. Specified as a ContentType. This field may be used interchangeably with the string 'CONTENT_TYPE'. If the content is a feed, whether to fetch summaries for that feed; defaults to false. Specified as a Boolean. This field may be used interchangeably with the string 'GET_SUMMARIES'. The HTTP headers to send to the URL; defaults to null. Specified as a Map.<String,String>. This field may be used interchangeably with the string 'HEADERS'. The method to use when fetching content from the URL; defaults to MethodType.GET. Valid values are specified by MethodType. This field may be used interchangeably with the string 'METHOD'. If the content is a feed, the number of entries to fetch; defaults to 3. Specified as a Number. This field may be used interchangeably with the string 'NUM_ENTRIES'. The data to send to the URL using the POST method; defaults to null. Specified as a String. This field may be used interchangeably with the string 'POST_DATA'. Explicitly sets the lifespan of cached content. The Refresh Interval is the number of seconds the container should cache the given response. By default, the HTTP caching headers will be respected for fetched content. If the refresh interval is set, this value will take precedence over any HTTP cache headers. If this value is not set and there are no HTTP caching headers specified, this value will default to 3600 (one hour). Note that Signed requests and objects with POST_DATA present will generally not be cached. This field may be used interchangeably with the string 'REFRESH_INTERVAL'. Indicates that the container should include the owner ID when signing the request. Specified as a Boolean. This field may be used interchangeably with the string 'SIGN_OWNER'. Indicates that the container should include the viewer ID when signing the request. Specified as a Boolean. This field may be used interchangeably with the string 'SIGN_VIEWER'.

Provides operations for translating objects to and from JSON.

<static> Type: {Object} gadgets.json.parse(text) Description: Parses a JSON string, producing a JavaScript value. Parameters: Name Type Description text String The string to transform into an object; usually the result of a previous stringify call Returns: Type Description Object The object parsed from the passed in text; false if an error occurred

<static> Type: {String} gadgets.json.stringify(v) Description: Converts a JavaScript value to a JSON string. Parameters: Name Type Description v Object The object to convert Returns: Type Description String The JSON equivalent

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();

gadgets.Prefs(opt_moduleId) Creates a new Prefs object. Parameters: Name Type Description opt_moduleId String | Number An optional parameter specifying the module ID to create prefs for; if not provided, the default module ID is used

Type: {Array.<String>} getArray(key) Description: Retrieves a preference as an array. UserPref values that were not declared as lists are treated as one-element arrays. Parameters: Name Type Description key String The preference to fetch Returns: Type Description Array.<String> The preference; if not set, an empty array

Type: {Boolean} getBool(key) Description: Retrieves a preference as a boolean. Parameters: Name Type Description key String The preference to fetch Returns: Type Description Boolean The preference; if not set, false

Type: {String} getCountry() Description: Gets the current country, returned as ISO 3166-1 alpha-2 code. Returns: Type Description String The country for this module instance

Type: {Number} getFloat(key) Description: Retrieves a preference as a floating-point value. Parameters: Name Type Description key String The preference to fetch Returns: Type Description Number The preference; if not set, 0

Type: {Number} getInt(key) Description: Retrieves a preference as an integer. Parameters: Name Type Description key String The preference to fetch Returns: Type Description Number The preference; if not set, 0

Type: {String} getLang() Description: Gets the current language the gadget should use when rendering, returned as a ISO 639-1 language code. Returns: Type Description String The language for this module instance

Type: {String | Number} getModuleId() Description: Gets the module ID for the current instance. Returns: Type Description String | Number The module ID for this module instance

Type: {String} getMsg(key) Description: Fetches an unformatted message. Parameters: Name Type Description key String The message to fetch Returns: Type Description String The message

Type: {String} getString(key) Description: Retrieves a preference as a string. Parameters: Name Type Description key String The preference to fetch Returns: Type Description String The preference; if not set, an empty string

set(key, val) Description: 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: Name Type Description key String The pref to store val Object The values to store

setArray(key, val) Description: Stores an array preference. To use this call, the gadget must require the feature setprefs. Parameters: Name Type Description key String The pref to store val Array The values to store

Provides general-purpose utility functions.

<static> Type: {String} gadgets.util.escapeString(str) Description: 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: Name Type Description str String The string to escape Returns: Type Description String The escaped string

<static> Type: {Object} gadgets.util.getFeatureParameters(feature) Description: Returns the value of parameters for this feature. A gadget specifies parameters using the <Param> subelement of the <Requires> or <Optional> element. Parameters: Name Type Description feature String The feature to get parameters for Returns: Type Description Object The parameters for the given feature, or null

<static> Type: {Boolean} gadgets.util.hasFeature(feature) Description: Returns whether the specified feature is supported. Parameters: Name Type Description feature String The feature to test for Returns: Type Description Boolean True if the feature is supported

<static> gadgets.util.registerOnLoadHandler(callback) Description: Registers an onload handler; a function that's executed when the gadget loads. Multiple handlers can be registered, and all will be invoked in the same order that they were registered. Parameters: Name Type Description callback Function The handler to run. The callback function will not be called until after the existing callstack has completed execution.

<static> Type: {String} gadgets.util.sanitizeHtml(text) Description: Sanitizes a text string. The returned value is safe to assign to innerHTML. The returned value may include HTML tags. If plain text is desired, use gadgets.util.escapeString instead. Parameters: Name Type Description text String arbitrary text string Returns: Type Description String a sanitized version that may include HTML tags, but will not execute script.

<static> Type: {String} gadgets.util.unescapeString(str) Description: Reverses escapeString Parameters: Name Type Description str String The string to unescape. Returns: Type Description String The unescaped string

Provides operations for dealing with views. See also: gadgets.views.View

<static> Type: {String} gadgets.views.bind(urlTemplate, environment) Description: Binds a URL template with variables in the passed environment to produce a URL string. See also: View.getUrlTemplate() Parameters: Name Type Description urlTemplate A url template for a container view environment A set of named variables (for example, [OWNER | PATH | PARAMS | NAME]) of type string. Returns: Type Description String A URL string

<static> Type: { gadgets.views.View } gadgets.views.getCurrentView() Description: Returns the current view. Returns: Type Description gadgets.views.View The current view

<static> Type: {Map.<String|String>} gadgets.views.getParams() Description: 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: Type Description Map.<String|String> The parameter map

<static> Type: {Map<gadgets.views.ViewType | String|gadgets.views.View>} gadgets.views.getSupportedViews() Description: Returns a map of all the supported views. Keys each gadgets.view.View by its name. This function only returns the primary views and does not return any secondary views. Example: if the markup indicates a set of views named Canvas.About, Profile.About, Home.About, Canvas.Help the returned views will only be Canvas, Profile, Home. Returns: Type Description Map<gadgets.views.ViewType | String|gadgets.views.View> All supported views, keyed by their name attribute.

<static> gadgets.views.requestNavigateTo(view, opt_params, opt_ownerId) Description: Attempts to navigate to this gadget in a different view. If the container supports parameter passing it will pass the optional parameters along to the gadget in the new view. This also allows for navigation to named views on the current surface. Views are composed of names that are [Surface](.[Secondary])?. The canonical Surface names are defined by the View Type. The Secondary names are user defined. When navigating from [Surface].valueX to [Surface].valueY, the container can stay on the same Surface but will show the appropriate <Content> sections whose View is [Surface].valueY. When navigating from SurfaceA.[Secondary] to SurfaceB.[Secondary], the container will switch to the SurfaceB surface and show the appropriate <Content> sections whose View is SurfaceB.[Secondary]. In no case must the .[Secondary] item be declared. Discussion Parameters: Name Type Description view gadgets.views.View If set to a string, the name of the view to navigate to. If set to a View, the View object to navigate to. Passing a View has been deprecated. opt_params Map<String|String> If the value is an object, it represents parameters to pass to the gadget after it has been navigated to on the surface. If the view navigated to contains an href and opt_params is a string, the value in opt_params is treated as a relative path that must be resolved relative to the href of the referenced view according to RFC 3986. If opt_params is a string all query parameters including query parameters encoded in a fragment are available in the receiving view using gadgets.views.getParams() opt_ownerId String The ID of the owner of the page to navigate to; defaults to the current owner Discussion

<static> gadgets.views.openGadget(resultCallback, navigateCallback, opt_params) Description: Opens a gadget in the container UI. The location of the gadget site in the container will be determined by the view target passed in. The container would open the view in a dialog, if view target is dialog or the gadgets view in a tab for view target is tab. Discussion Parameters: Name Type Description resultCallback function Callback function to be called when the gadget closes. The function will be called with the return value as a parameter. navigateCallback function Callback function to be called with the site handler and metadata as parameters. The site handler can only be used as parameter in gadgets.views.close(opt_site_handler). opt_params Object These are optional parameters which can be used to open gadgets. The following parameters may be included in this object. opt_params: Name Type Description view string The surface view that indicates the type of gadget site. viewTarget string The view that indicates where to open the gadget. For example, tab, dialog or modaldialog. viewParams Object View parameters for the view being rendered. coordinates Object Object containing the desired absolute positioning css parameters (top|bottom|left|right) with appropriate values. All values are relative to the calling gadget. Do not specify top AND bottom or left AND right parameters to indirectly define height and width. Use viewParams for that. The result of doing so here is undefined. Container implementations SHOULD honor optionally specified coordinates for the FLOAT viewTarget. Containers MAY honor coordinates for any other target they choose. Discussion

<static> gadgets.views.openEmbeddedExperience(resultCallback, navigateCallback, dataModel, opt_params) Description: Opens an embedded experience in the container UI. The location of the gadget or URL site in the container will be determined by the view target passed in. The container would open the embedded experience in a dialog, if view target is dialog or the embedded exerience view in a tab for view target is tab. Discussion Parameters: Name Type Description resultCallback function Callback function to be called when the gadget closes. The function will be called with the return value as a parameter. navigateCallback function Callback function to be called with the site handler and metadata as parameters. The site handler can only be used as parameter in gadgets.views.close(opt_site_handler). dataModel Object The embedded experiences data model. If a String is passed, it is assumed to be a parsable XML representation of the embedded experiences data model. See appendix on the embedded experiences data model Discussion opt_params Object These are optional parameters which can be used to open gadgets. The following parameters may be included in this object. opt_params: Name Type Description viewTarget string The view that indicates where to open the gadget. For example, tab, dialog or modaldialog. viewParams Object View parameters for the view being rendered. coordinates Object Object containing the desired absolute positioning css parameters (top|bottom|left|right) with appropriate values. All values are relative to the calling gadget. Do not specify top AND bottom or left AND right parameters to indirectly define height and width. Use viewParams for that. The result of doing so here is undefined. Container implementations SHOULD honor optionally specified coordinates for the FLOAT viewTarget. Containers MAY honor coordinates for any other target they choose. Discussion

<static> gadgets.views.openUrl(url, navigateCallback, opt_viewTarget) Description: Opens a URL in the container UI. The location of the URL site will be determined by the container based on the target view. The container would open the view in a dialog, if opt_viewTarget=dialog or the gadgets view in a tab for opt_viewTarget=tab. Discussion Parameters: Name Type Description url string URL to a web page to open in a URL site in the container. (Note this should not be a URL to a gadget definition.) navigateCallback function Callback function to be called with the handler of the site which has been opened. The site handler can only be used as paramater in gadgets.views.close(opt_site_handler). opt_viewTarget string Optional parameter,the view that indicates where to open the URL. opt_coordinates Object Optional parameter, Object containing the desired absolute positioning css parameters (top|bottom|left|right) with appropriate values. All values are relative to the calling gadget. You may specify top AND bottom or left AND right parameters to indirectly define height and width. Container implementations SHOULD honor optionally specified coordinates for the FLOAT viewTarget. Containers MAY honor coordinates for any other target they choose. Discussion

<static> gadgets.views.close(opt_site_handler) Description: Closes an opened site. If the opt_site_handler parameter is null the container will close the calling site. Discussion Parameters: Name Type Description opt_site_handler Object Optional parameter which specifies handler to what site to close. If null it will close the current gadget site.

<static> gadgets.views.setReturnValue(returnValue) Description: Sets the return value for the current window. This method should only be called inside those secondary view types defined in gadgets.views.ViewType. For example, DIALOG or MODALDIALOG. Discussion Parameters: Name Type Description returnValue Object A serializable JSON object which specifies return value.

Base interface for all view objects.

Type: {String} bind(environment) Description: Binds the view's URL template with variables in the passed environment to produce a URL string. See also: getUrlTemplate() Parameters: Name Type Description environment A set of named variables (for example, [OWNER | PATH | PARAMS | NAME]) of type string. Returns: Type Description String A URL string

Type: { gadgets.views.ViewType | String} getName() Description: Returns the name of this view. Returns: Type Description gadgets.views.ViewType | String The view name, usually specified as a gadgets.views.ViewType

Type: {String} getUrlTemplate() Description: Returns a string URI template conforming to the IETF spec draft with variables for substitution. Four variables are supported: The name or ID of the application The ID of the owner of the page An array of path steps` 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: Type Description String A template that can be used to construct URLs that navigate to this view

Type: {boolean} isOnlyVisibleGadget() Description: 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: Type Description boolean True if the gadget is the only visible gadget; otherwise, false

Used by View objects. A view used to provide descriptive information regarding the gadget. This view is typically rendered in a smaller area. The viewer is not always the same as the owner. This field may be used interchangeably with the string 'ABOUT'. Discussion 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. This field may be used interchangeably with the string 'CANVAS'. A view used when an gadget is to be rendered in the context of some other content. For example, an activity stream entry may include a diagram. Rather than requiring the user to navigate to a dashboard, the container may render the gadget "embedded" in the stream. The developer should anticipate that there may be limited chrome surrounding the gadget. The viewer is not always the same as the owner. This field may be used interchangeably with the string 'EMBEDDED'. Discussion 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. This field may be used interchangeably with the string 'HOME'. A view used to allow the user to display and set the user preferences defined by the gadget. For example, it is common for gadgets to present a form for visible user prefs. Because the user preferences are specific to a user, owner and viewer MUST be the same in this view. This field may be used interchangeably with the string 'PREFERENCES'. Discussion A demo view of the gadget. In this view the owner and viewer are not known. This field may be used interchangeably with the string 'PREVIEW'. A view where the gadget is displayed in a small area usually on a page with other gadgets. A typical use case for this view is for the gadget to be placed on the profile page of a user, for example, a gadget that allows you to schedule a meeting with the person. The viewer is not always the same as the owner. This field may be used interchangeably with the string 'PROFILE'. A view used to communicate to the user where to get support information for the gadget. Typically, the gadget is displayed in a small area. The viewer MUST always the same as the owner. This field may be used interchangeably with the string 'SUPPORT'. Discussion

Discussion A view where the gadget is displayed inside a container tab. This field may be used interchangeably with the string 'TAB'. A view where the gadget is displayed in a pop up box. This field may be used interchangeably with the string 'DIALOG'. A view where the gadget is displayed in a modal pop up box. This field may be used interchangeably with the string 'MODALDIALOG'. A view where the gadget is displayed in a floating box. It is similar to the 'DIALOG' view type, but without chrome around it. This field may be used interchangeably with the string 'FLOAT'. A view where the gadget is displayed in a sidebar area. This field may be used interchangeably with the string 'SIDEBAR'.

The opensocial.data namespace provides an API to access the pipelined data on the client. There are methods to get the data returned from the data pipeline, set additional data, and listen to changes in data of a given key. Pipelined data is only available to the client when embedded in @type="html" content or content returned by a proxied content request. Data posted as part of a pipelined data request MUST not be available on the client.

Examples var viewer = opensocial.data.getContext().getDataSet('Viewer'); alert('Hello ' + viewer.name); os.data.getDataContext().putDataSet('Params', {"Page": 2, "PageSize": 10}); opensocial.data.getDataContext().registerListener('Friends', function(key) { var el = document.getElementById('friend-details'); el.style.display = 'show'; });

<static> DataContext opensocial.data.getContext() Gets the DataContext associated with the gadget. None. Type Description DataContext The data associated with Data Pipelining requests.

The DataContect object maintains all the data associated with the current gadget's data pipelining requests.

Object getDataSet(String key) Retrieves the object data that is currently mapped to the specified key. Name Type Description key String The key for the data object to be retrieved Type Description Object The object stored with the given key.

void putDataSet(String key, String|Object value) Puts additional data into the data context. This data can later be accessed using the key provided.. Name Type Description key String The key to use to refer to this data value String | Object The data to store. If the value is a JSON string, it will be parsed and stored as a JavaScript object. None.

void putDataSets(Object dataSets) Puts many data sets into the data context at once, with appropriate listeners firing after all the updates are done. Name Type Description dataSets Object an object whose property names are data set keys, and whose properties are actual data sets None.

void registerListener(String | Array>String<> keys, Function callback) Listens for any updates to data keyed by one of "keys". The wildcard key, "*", may be used to listen to all keys. Name Type Description keys String | Array>String<> The key or list of keys to add the listener to callback Function A function to invoke when the data at the given keys changes. When the function is invoked, it MUST receive a single parameter, which is a list of the keys that have newly-updated values. None.

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. Developers wanting to write gadgets safely can test for the existence of a service and method as follows: if (osapi.people && osapi.people.getViewer) { osapi.people.getViewer().execute(function(result) { if (!result.error) { alert('Your name is ' + result.displayName + '!'); } }); }

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

osapi.Response.execute(callback) 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. Name Type Description callback Function A callback function to handle the response. The callback function will be invoked with a parameter which contains the response payload (Core HTTP-Response-Payload) specified by the service method that is invoked. Discussion None

A simple example to request the owner's friends and display the total number of friends. Note that the 'totalResults' property contains the total number of friends, even only a portion of the collection is actually returned (e.g. for paging purposes): var params = {"userId": "@owner", "groupId": "@friends"}; osapi.people.get(params).execute(callback); function callback(ownerFriends) { if (!ownerFriends.error) { alert('You have ' + ownerFriends.totalResults + ' friends'); } });

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

osapi.BatchRequest osapi.newBatch() Creates a new batch request. None Type Description osapi.BatchRequest A new batch request.

osapi.BatchRequest osapi.add(key, request) 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()). Name Type Description key String A key to access the result of the given request from the parameter sent to the callback function. request osapi.Request A request to add to the batch. Type Description osapi.BatchRequest A batch request containing the given request (and any previously added requests).

void osapi.BatchRequest.execute(callback) 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. Name Type Description 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. None

An example illustrating two requests batched together: var batch = osapi.newBatch(). add("viewer", osapi.people.getViewer()). add('activities', osapi.activities.get({ userId : '@viewer', groupId : '@self'})). batch.execute(function(result) { if (!result.error) { alert('Hi, ' + result.viewer.displayName + '!'); alert('You have ' + result.activities.totalResults + ' activities.'); } });

The error handling works exactly as it does for the JSON-RPC interface, since this api is based on that protocol. The JSON object returned reflects any errors that occurred in the request. This breaks down into 3 types of errors: Network error, these return a top level error. For example, in the callback, the object passed will have an error object.

Example: osapi.people.get({userId: '@owner', groupId: '@friends'}).execute(function(ownerFriends) { if (ownerFriends.error) { alert('Error occurred: ' + error.message); } else { alert('You have ' + ownerFriends.totalResults + ' friends'); } });

Application Error for Single Request In this case, a top-level error object is set. Note, this is just like the previous error case.

Example: osapi.people.get({userId: '@owner', groupId: '@friends'}).execute(function(ownerFriends) { if (ownerFriends.error) { alert('Error occurred: ' + error.message); } else { alert('You have ' + ownerFriends.totalResults + ' friends'); } });

Application Error for a Batched Request. In this case, a top-level error is set, but results are still returned for all individual requests that succeeded, if any. The individual request that failed has an error set. Note that 'error' is reserved and may not be used as a key to batch.add() as a property of a JSON RPC batch response item.

Example: Bailing out if there is any error in the batch: var batch = osapi.newBatch(). add("viewer", osapi.people.getViewer()). add('activities', osapi.activities.get({ userId : '@viewer', groupId : '@self'})). batch.execute(function(result) { if (result.error) { alert("This batch had an error: " + error.message); } else {alert('Hi, ' + result.viewer.displayName + '!'); alert('You have ' + result.activities.totalResults + ' activities.'); } });

Example: Processing any sub requests in the batch that succeeded: var batch = osapi.newBatch(). add('v', osapi.people.getViewer()). add('vf', osapi.people.getViewerFriends()); batch.execute(function(result) { for (var name in result) { if (result.hasOwnProperty(name)) { if (result[name].error) { gadgets.log("Found an error: ", result[name].error.message); } else { gadgets.log("Got some data: ", result[name]); } } } });

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.

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

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

<static> osapi.Request osapi.http.post(params) Creates a POST request to an arbitrary URL. Name Type Description 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. Type Description osapi.Request A request to POST information to an arbitrary URL.

<static> osapi.Request osapi.http.put(params) Creates a PUT request to an arbitrary URL. Name Type Description 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. Type Description osapi.Request A request to PUT information to an arbitrary URL.

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

<static> osapi.Request osapi.http.patch(params) Creates a PATCH request to an arbitrary URL. Name Type Description params HTTP-Request-Parameters A JavaScript representation of HTTP-Request-Parameters. Type Description osapi.Request A request to patch information at an arbitrary URL.

Suppose a request to http://www.somephotosite.com/latest returns the following JSON: { photos : [ "http://www.somephotosite.com/photos/1.jpg", "http://www.somephotosite.com/photos/2.jpg", "http://www.somephotosite.com/photos/3.jpg", ], lastUpdate : "Mon, 13 Apr 2009 23:17:04 GMT" }

The data can be retrieved and accessed as follows: osapi.http.get({href:'http://www.somephotosite.com/latest'}).execute(function(result) { if (!result.error) { alert('There are ' + result.content.photos.length + ' new photos'); } });

An example illustrating some available request parameters: var params = { 'href': 'http://www.somephotosite.com/prefs?uid=1234', 'format': 'json', 'headers': {'Content-Type': ['application/json;charset=utf-8'], "Accept-Language": ["en-us"]}, 'body': {'numResults': 100, theme: 'beach'}, 'authz': 'SIGNED', }; osapi.http.post(params).execute(function(result) { if (!result.error) { alert('Request to update user preferences was successful'); } });

This example demonstrates the use of 'alias' var params = { 'alias': 'sharepoint', 'href': '/departmentList', 'format': 'json', 'headers': {'Content-Type': ['application/json;charset=utf-8'], "Accept-Language": ["en-us"]} }; osapi.http.get(params).execute(function(result) { if (!result.error) {...} });

Discussion

Data Pipelining is a declarative syntax for defining the data a gadget requires from the container. The <os:DataRequest> element provides access to OpenSocial data, and the <os:HttpRequest> element provides access to content from any HTTP endpoint. All Data Pipelining tags MUST have a 'key' attribute which contains a string that is used to identify the data in the response. Values of the key attribute are case-sensitive when referenced through the data context object or the Expression Language. Tags that invoke API Server methods support a 1:1 mapping between the XML attributes and the service method parameters. See and for information on the parameters available for each service method. Note that Data Pipelining MUST only be used for API Server calls that get data. Service methods that update data MUST NOT be implemented as Data Pipelining tags. Here's an example of Data Pipelining tags in a gadget XML file.

<Content type="html"><![CDATA[ <script xmlns:os="http://ns.opensocial.org/2008/markup" type="text/os-data"> <os:DataRequest key="vwr" method="people.get" userId="@viewer" fields="name,birthday"/> <os:HttpRequest key="mydata" href="http://example.com/api"/> </script> ... HTML content here ... ]]></Content>

Data Pipelining creates a new feature name for use in the Gadget Specification: opensocial-data. When data pipelining elements are embedded in type=@html, the Module must contain this XML:

<ModulePrefs> <Require feature="opensocial-data"/> </ModulePrefs>

The DataContect object maintains all the data associated with the current gadget's data pipelining requests. Items in the data context may be access through EL statements or on the client with the opensocial.data APIs. Data may be placed into the data context with any data pipeline tags, such as <os:Var>, or through the opensocial.data APIs. Data in the Data Context is available in three contexts: Proxied content requests. This data will be POSTed to the developer party server with requests for proxied content. OpenSocial Templates. The data will be available as named variables in OpenSocial templates. JavaScript. This data will be available in the JavaScript API.

A data block may be defined to hold a number of data pipeline tags. See the Data Element section for more information on this element. Discussion

<Module> <Data> <os:DataRequest key="PagedFriends" method="people.get" userId="@owner" groupId="@friends" startIndex="40" count="20"/> </Data> <Content> ... </Content> </Module>

Request to get OpenSocial data, including person data, activity data, and any container-specific endpoints. The following attributes are REQUIRED. Any additional attributes will be passed as parameters to the service method. Name Type Description key String A key for accessing the response. method String The name of the service and method to call. A JSON object representing the Return-Object specified by the service method.

Example of tag syntax: <os:DataRequest key="PagedFriends" method="people.get" userId="@owner" groupId="@friends" startIndex="40" count="20"/>

Request for arbitrary URL data, equivalent to osapi.http. Containers SHOULD cache the results of these requests. MUST support all of the fields in HTTP-Request-Params as attributes. In addition, following fields are REQUIRED: Name Type Description key String A key for accessing the response. method String HTTP method to use, one of "get" or "post". Defaults to "get". If method is "post", then <os:HttpRequest> supports an addition parameter, "body" which contains key/value pairs to send as POST content with a content type of "application/x-www-form-urlencoded". A RPC-Response-Payload object with "id", "error", and "result" properties. The "result" object is not available for 4xx or 5xx responses. When available, the "result" object in turn contains a HTTP-Response-Payload.

Example of tag syntax: <os:HttpRequest key="Pets" href="http://example.com/api" authz="signed"/>

For errors, the "message" property MUST NOT contain the response body, but SHOULD contain a descriptive message describing the HTTP error. The error MAY contain a data block providing the content and headers.

Example responses: // @format='text' example {result: { content: 'Hi there!', status: 200, headers: {'Content-Type': ['text/plain;charset=utf-8']} }} // @format='json' example {result: { content: {'hi': 'there!'}, status: 200, headers: {'Content-Type': ['application/json;charset=utf-8']} }} // 404 error {error: { code: 404, message: 'Resource not found', // Optional data block data: { content : {'<html><body>File not found... '}, headers: {'Content-Type': ['text/html; charset=iso-8859-1']} } }} // Unparseable JSON {error: { message: "JSON could not be parsed", code: 406, data: { content: {'This isn't JSON'} } }}

Declare a literal value or result of an EL statement under a different key. The following attributes are supported. Name Type Description key String A key for accessing the value. REQUIRED value String Literal string, EL statement, or JSON object. OPTIONAL. If not specified the contents of the tag are used for value. Value as resolve by below processing rules.

Example of tag syntax: <os:Var key="myNumber" value="1"/>

When processing values, the processor attempts to resolve the value of the os:Var tag in the following manner: Process to replace EL statements (${} markup) Attempt to parse it as a JSON value and return the resulting object if successful. If all other processing does not resolve the value, return as a string The value created with os:Var may contain literals, JSON data, or EL statements. An array may be declared using JSON or JavaScript array syntax. The below example creates a one-dimensional array with values [1,2,3,5,7] and assigns it to the key "primes" in the data context

Example: simple array <os:Var key="primes" value="[1,2,3,5,7]" />

The below places the result of the EL statement ${1+1} under the key "onePlusOne".

Example: EL statement <os:Var key="onePlusOne" value="${1+1}" />

The below creates a JSON object and places it under the key "mockViewer"

Example: JSON object <os:Var key="mockViewer" > {"displayName": "John Doe", "thumbnailUrl": "http://example.org/person.png" } </os:Var>

Data pipelining tags can be top level elements in the <Content> section of a gadget using Proxied Content.

Example <Content href="http://example.com/canvas" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PeopleRequest key="vf" userId="@viewer" groupId="@friends"/> </Content>

When preparing a request for proxied content, a container MUST process data pipelining elements that are direct children of the proxied content's <Content> element. Data pipelining elements are ALWAYS valid when preparing a request for proxied content, even if the opensocial-data feature is not present. The results of the data pipelining requests will be sent to the href of the <Content> section as POSTed JSON data. The structure will be in JSON-RPC format. Elements in a data pipeline with @userId referencing the viewer (via @viewer, @me) will return a 403 (Forbidden) error response if the container is unable to also send the opensocial_viewer URL parameter to the 3rd party server. The same holds true for @owner and opensocial_owner URL parameter.

With pipelined data prepared for proxied content, errors are simply delivered to the href of the <Content> element as POSTed JSON data with the JSON-RPC error format unmodified. With pipelined data prepared for the Javascript API, or otherwise embedded in @type="html" content, per-item errors are not modified, but errors that fail the entire request are modified by cloning the error into each item.

Example <script xmlns:os="http://ns.opensocial.org/2008/markup" type="text/os-data"> <os:ViewerRequest key="vwr"/> <os:PeopleRequest key="vf" userId="@viewer" groupId="@friends"/> </script> If the above request failed with a server error, the resulting dataset would contain content resembling: {vwr: {error: {message: 'Server error', code: 500}}, vf: {error: {message: 'Server error', code: 500}}}

Containers should ignore unrecognized tags or return error code 404 (Not Found). If a tag is ignored, the JSON structure can either include a null value for the request key or just not include the request key.

The XML namespace for all of the Data Pipelining tags is http://ns.opensocial.org/2008/markup. (Note that namespace declarations on <Content> and <Module> elements do not apply to content inside of CDATA sections, so namespaces must be declared within CDATA.)

Data and HTTP requests often need to change based on input parameters. Two key use cases: Passing gadgets view parameters to a request, for example the current page in a paginated list. Passing OpenSocial data to a following <os:HttpRequest>, specifically IDs of (viewer, owner, viewer friends, owner friends). Data pipelining will support a limited subset of the expression language used in OpenSocial templates (based on JSP EL): Expressions of format ${A(.B)*} will be supported, where "A" is the key and "B" is any number of properties. Examples: ${UserPrefs.size}, ${ViewParams.nav.first}. Multiple expressions may appear within a single attribute, and mixed with non-expression text. The result of all non-expression text and expression evaluations will be concatenated. The key "ViewParams" is reserved and refers to the parameters passed into the gadget rendering, equivalent to gadgets.views.getParams(). The key "UserPrefs" is reserved and refers to gadget user preferences - ${UserPrefs.PREF} will return the value of gadgets.Prefs.getString('PREF') - see [API]. The results of expression evaluation are treated as if the results were inserted as the literal string value of the XML attribute. JSON arrays within ViewParams are output as "a,b", not "[a,b]". The results of expression evaluation for URL-typed attributes - specifically, @href and @param on <os:HttpRequest> - MUST be RFC 1738, Section 2.2 encoded (URL encoded) before being inserted into a final string. The following attributes support expressions: Any attribute on os:DataRequest other than @key and @method @userId @groupId @fields @startIndex @count @sortBy @sortOrder @filterBy @filterOp @filterValue @activityIds @href @params An implementation MUST evaluate dynamic properties for these attributes and MUST NOT evaluate dynamic properties for attributes not on this list.

Example <os:PeopleRequest key="PagedFriends" userId="@owner" groupId="@friends" startIndex="${ViewParams.first}" count="20"/> <os:HttpRequest href="http://example.com/api?ids=${PagedFriends.ids}"/>

Dynamic parameters may access request attributes of other data tags through the special "Request" key and response meta information of other data requests through the reserved keys "totalResults", "startIndex", and "count".

Example <os:PeopleRequest key="Page1" userId="@owner" groupId="@friends" startIndex="${ViewParams.first}" count="20"/> <os:PeopleRequest key="Page2" userId="${Page1.Request.userId}" groupId="@friends" startIndex="${Page1.Request.startIndex + Page1.Request.count}" count="${Page1.Request.count}"/>

<?xml version="1.0"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="Module"> <xs:complexType> <xs:sequence> <xs:element name="ModulePrefs" minOccurs="0"> <xs:complexType> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="Require" type="GadgetFeatureType"/> <xs:element name="Optional" type="GadgetFeatureType"/> <xs:element name="Preload"> <xs:complexType> <xs:attribute name="href" type="xs:string" use="required"/> <xs:attribute name="authz" default="none"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="none"/> <xs:enumeration value="signed"/> <xs:enumeration value="oauth"/> <xs:enumeration value="oauth2"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="sign_owner" type="xs:boolean" default="true"/> <xs:attribute name="sign_viewer" type="xs:boolean" default="true"/> <xs:attribute name="views" type="xs:string" use="optional"/> </xs:complexType> </xs:element> <xs:element name="icon"> <xs:complexType> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="mode"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="base64"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="type" type="xs:string"/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:element> <xs:element name="mediumIcon"> <xs:complexType> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="mode"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="base64"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="type" type="xs:string"/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:element> <xs:element name="largeIcon"> <xs:complexType> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="mode"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="base64"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="type" type="xs:string"/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:element> <xs:element name="Locale"> <xs:complexType> <xs:sequence> <xs:element name="msg" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="desc" type="xs:string" use="optional"/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="lang" type="xs:string" use="optional"/> <xs:attribute name="country" type="xs:string" use="optional"/> <xs:attribute name="messages" type="xs:string" use="optional"/> <xs:attribute name="language_direction"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="ltr"/> <xs:enumeration value="rtl"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="views" type="xs:string" use="optional"/> </xs:complexType> </xs:element> <xs:element name="Link"> <xs:complexType> <xs:attribute name="href" type="xs:string" use="required"/> <xs:attribute name="rel" use="required"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="gadgets.help"/> <xs:enumeration value="gadgets.support"/> <xs:enumeration value="icon"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> <xs:element name="OAuth" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:sequence> <xs:element name="Service" maxOccurs="unbounded"> <xs:complexType> <xs:all> <xs:element name="Request" type="OAuthResourceType" minOccurs="0"/> <xs:element name="Access" type="OAuthResourceType" minOccurs="0"/> <xs:element name="Authorization" minOccurs="0"> <xs:complexType> <xs:attribute name="url" type="xs:string" use="required"/> </xs:complexType> </xs:element> </xs:all> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="name" type="xs:string" use="optional"/> </xs:complexType> </xs:element> <xs:element name="OAuth2" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:sequence> <xs:element name="Service" maxOccurs="unbounded"> <xs:complexType> <xs:all> <xs:element name="Authorization" type="OAuthResourceType" minOccurs="0"/> <xs:element name="Token" type="OAuthResourceType" minOccurs="0"/> </xs:all> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="name" type="xs:string" use="optional"/> <xs:attribute name="scope" type="xs:string" use="optional"/> </xs:complexType> </xs:element> </xs:choice> <xs:attribute name="title" type="xs:string" use="optional"/> <xs:attribute name="title_url" type="xs:string" use="optional"/> <xs:attribute name="description" type="xs:string" use="optional"/> <xs:attribute name="author" type="xs:string" use="optional"/> <xs:attribute name="author_email" type="xs:string" use="optional"/> <xs:attribute name="screenshot" type="xs:string" use="optional"/> <xs:attribute name="thumbnail" type="xs:string" use="optional"/> </xs:complexType> </xs:element> <xs:element name="UserPref" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="EnumValue" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:attribute name="value" type="xs:string" use="required"/> <xs:attribute name="display_value" type="xs:string" use="optional"/> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="display_name" type="xs:string" use="optional"/> <xs:attribute name="default_value" type="xs:string" use="optional"/> <xs:attribute name="required" type="xs:string" use="optional"/> <xs:attribute name="datatype" default="string"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="string"/> <xs:enumeration value="hidden"/> <xs:enumeration value="bool"/> <xs:enumeration value="enum"/> <xs:enumeration value="number"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> <xs:element name="Content" minOccurs="1" maxOccurs="unbounded"> <xs:complexType> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="type" use="optional" default="html"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="html"/> <xs:enumeration value="url"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="authz" use="optional" default="none"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="none"/> <xs:enumeration value="signed"/> <xs:enumeration value="oauth"/> <xs:enumeration value="oauth2"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="href" type="xs:string" use="optional"/> <xs:attribute name="view" type="xs:string" use="optional"/> <xs:attribute name="preferred_height" type="xs:integer" use="optional"/> <xs:attribute name="preferred_width" type="xs:integer" use="optional"/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:element> <xs:element name="ExternalServices" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:sequence> <xs:element name="ServiceTag" maxOccurs="unbounded"> <xs:complexType> <xs:attribute name="alias" type="xs:string" use="required"/> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="specificationVersion" type="xs:string" use="optional" default="1.0.0"/> </xs:complexType> </xs:element> <xs:complexType name="GadgetFeatureType"> <xs:sequence> <xs:element name="Param" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="name" type="xs:string" use="required"/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="feature" type="xs:string" use="required"/> <xs:attribute name="version" type="xs:string" use="optional"/> <xs:attribute name="views" type="xs:string" use="optional"/> </xs:complexType> <xs:complexType name="OAuthResourceType"> <xs:attribute name="url" type="xs:string" use="required"/> <xs:attribute name="method" use="optional" default="GET"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="GET"/> <xs:enumeration value="POST"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="param_location" use="optional" default="auth-header"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="auth-header"/> <xs:enumeration value="uri-query"/> <xs:enumeration value="post-body"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:schema>

Discussion Discussion Discussion Discussion Discussion

<?xml version="1.0"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="messagebundle"> <xs:complexType> <xs:sequence> <xs:element name="msg" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="desc" type="xs:string" use="optional"/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>

Discussion

The actions feature allows gadgets to contribute actions to the container's UI. Some containers have global action contribution areas such as the header and footers of the container, which may include links, buttons, or menus. Additionally, a gadget may need to contribute actions to specific Open Social Data Objects. In traditional desktop applications, these actions are often rendered as menu items on context menus when you click on a person or file. For example, when a user right-clicks on a Person object to bring up the context menu, they may see actions specific to Person objects, including "Start a Chat" or "View Contact Information." Some use cases are as follows: Action contribution by path Gadget contributes a top level action to the container, aka such as a link at the top Gadget contributes a action to the Gadget's drop down menu(drawn by the container) Gadget contributes an action to a container specific defined path location, such as a container's toolbar Action contribution to an Open Social Data type Gadget contributes an action to container's Person object. Example, a gadget providing SMS capability can bind to a container's list of active contacts/buddy list. Gadget contributes an action to a container's Message. Example, a new button or action is added to the forward, reply, delete list when displaying a message. Same holds true for all Open Social defined data types Group, Activity, etc. Gadgets may bind to any container specific types that are defined. Containers shall make all efforts to use types in shared namespace and to contribute back new types to the spec to maintain cross-container abilities of gadgets. The container controls how to render the items such that all actions can be rendered consistently throughout the container, regardless of which gadget contributes the action. Gadgets register actions by specifying a label, icon and a callback function. Gadget developers do not need to worry about other UI details. A gadget may programmatically contribute actions at any time by calling addAction(actionObject). In addition, a gadget may declaratively contribute an action to the container in the gadget definition. This allows actions to be added to the container before the gadget has been fully rendered.

An action object is a JSON representation of an action, and may contain the following attributes: Attribute Description Required/Optional id Unique identifier Required label Text string to display for this action Required path The container-defined location for this action, as described in Action Paths. Example: path=container/menus/Edit Optional* dataType The Open Social Data type, as described in Action Data Types, with which to associate this action. Example: opensocial.Person Optional* tooltip Tooltip to display on hovering over an icon Optional icon Path to image icon. Absolute URL or URL relative to gadget URL Optional iconSize See related issue on icon size for more information. Optional iconOffset x and y coordinates of icon if using image sprites Optional view The view ID the gadget should navigate to when the action is invoked. Optional viewTarget The target area to render the view. Optional url Simple actions that are just links can specify a url instead of a callback function. Optional * Either path or dataType MUST be specified.

Gadgets may contribute actions to container-defined common action locations. These may include the following suggested standardized paths, but the container may also choose to support additional paths to which gadgets can contribute: Path Description container/navigationLinks The top level navigation links, providing links to related services. container/menus The top level menu. For example to add a new action to File->New->Presentation path="container/menu/File/New." container/toolbars Top level toolbars owned by the container. For example to add a new action to Toolbar in a docs editor. gadget/menu The optional menu drawn by the container, around each gadget.

Gadgets may use any of the data types defined in Social-Data.xml when binding actions to OpenSocial Data types. These include, but are not limited to, the following: opensocial.Person opensocial.Message opensocial.Activity opensocial.Group

Below is an example of the declarative contribution in a gadget's metadata and the javascript code needed to bind action ID to callback function:

<Module> <ModulePrefs title="Sample VOIP"> <Optional feature="actions"> <Param name="action-contributions"> <![CDATA[ <action id="org.samplevoip.callbyperson" dataObject="opensocial.Person" label="Call using VOIP Phone" view="DialByPerson" icon="http://ww.samplervoip.org/phone.gif" /> <action id="org.samplervoip.navLink" path="container/navigationLinks" label="Phone" /> ]]> </Param> </Optional> </ModulePrefs> <Content type="html"> <![CDATA[ <script> // Bind javascript function to action ID var mycallback = function(){ ... }; var myaction = { id: "org.samplevoip.callbyperson", callback: mycallback } gadgets.actions.updateAction(myaction); </script> ]]> </Content> </Module>

<static> gadgets.actions.addAction(action) Description: Adds the specified action(s) to the container. Parameters: Name Type Description action Object The action to be added to the container Example contributing an action to a container's Person object: var mycallback = function(){ ... }; var myaction = { id: "com.acme.mycallaction", tooltip: "My Action Tooltip", label: "Call Person", icon: "images/myicon.png", callback: mycallback, dataType: "opensocial.Person" } gadgets.actions.addAction(myaction);

<static> gadgets.actions.updateAction(action) Description: Updates the specified action(s) in the container. Parameters: Name Type Description action Object The action to be updated in the container Example updating a declarative action to bind a callback function: var mycallback = function(){ ... }; var myaction = { id: "com.acme.mycallaction", callback: mycallback } gadgets.actions.updateAction(myaction);

<static> gadgets.actions.removeAction (actionId) Description: Removes the specified action from the container Parameters: Name Type Description id String The ID referencing the action to be removed from the container

<static> gadgets.actions.getActionsByPath (path, callback) Description: Gets array of actions from the container at the specified path and passes the result to the callback function Parameters: Name Type Description path String The String representation of the path to the actions callback Function A callback function to handle the returned actions array

<static> gadgets.actions.getActionsByDataType (dataType, callback) Description: Gets array of actions from the container for the specified data type and passes the result to the callback function. Parameters: Name Type Description dataType String The String representation of an OpenSocial data type. callback Function A callback function to handle the returned actions array

<static> gadgets.actions.runAction (actionId, opt_selection) Description: Executes the action callback associated with the specified actionId in the context of the gadget which contributed that action. The gadget should call this method whenever an action is triggered by the user. Parameters: Name Type Description actionId String The id of the action to execute. opt_selection Object The current selection. This is an optional parameter.

<static> gadgets.actions.registerShowActionsListener (showActionsHandler) Description: Registers a function to render actions in the gadget. The function will be called whenever new actions are added to the container. The gadget can use this listener to add the new actions to its UI. Parameters: Name Type Description showActionsHandler Function The gadgets's function to render actions in its UI. The function takes in one parameter which is an array of action objects to render. Parameters for show actions handler function: Name Type Description actionObjs Object[] An array of action objects. Example: var myShowActionsHandler = function(actionObjs){ // draw the UI, toolbars menus, etc // to do the invocation of the action, call the following API: // gadgets.actions.runAction(actionObjs[0].id); } gadgets.actions.registerShowActionsHandler(myShowActionHandler);

<static> gadgets.actions.registerHideActionsListener (hideActionsHandler) Description: Registers a function to remove actions from the gadget. The function will be called whenever the container unloads a gadget which contributes actions. Parameters: Name Type Description hideActionsHandler Function The gadgets's function to hide actions in its UI. The function takes in one parameter which is an array of action objects to hide. Parameters for hide actions handler function: Name Type Description actionObjs Object[] An array of action objects. Example: var myhideActionsHandler = function(actionObjs){ // remove any UI elements that were created to represent the action } gadgets.actions.registerHideActionsHandler(myHideActionHandler);

Embeds Flash content in gadgets.

<static> Type: {Boolean} gadgets.flash.embedCachedFlash() Description: Injects a cached Flash file into the DOM tree. Accepts the same parameters as gadgets.flash.embedFlash does. Returns: Type Description Boolean Whether the function call completes successfully

<static> Type: {Boolean} gadgets.flash.embedFlash(swfUrl, swfContainer, swfVersion, opt_params) Description: Injects a Flash file into the DOM tree. Parameters: Name Type Description swfUrl String SWF URL swfContainer String | Object The ID or object reference of an existing HTML container element swfVersion Number Minimum Flash Player version required opt_params Object An optional object that may contain any valid HTML parameter; all attributes will be passed through to the Flash movie on creation Returns: Type Description Boolean Whether the function call completes successfully

<static> Type: {Number} gadgets.flash.getMajorVersion() Description: Detects Flash Player and its major version. Returns: Type Description Number The major version of Flash Player or 0 if Flash is not supported

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.

gadgets.MiniMessage(opt_moduleId, opt_container) Creates a MiniMessage. Parameters: Name Type Description opt_moduleId String Optional module ID opt_container HTMLElement Optional HTML container element where mini-messages will appear

Type: {HTMLElement} createDismissibleMessage(message, opt_callback) Description: 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: Name Type Description message String | Object The message as an HTML string or DOM element opt_callback Function Optional callback function to be called when the message is dismissed. The callback function will not be called until after the existing callstack has completed execution. Returns: Type Description HTMLElement HTML element of the created message

Type: {HTMLElement} createStaticMessage(message) Description: Creates a static message that can only be dismissed programmatically (by calling dismissMessage()). Parameters: Name Type Description message String | Object The message as an HTML string or DOM element Returns: Type Description HTMLElement HTML element of the created message

Type: {HTMLElement} createTimerMessage(message, seconds, opt_callback) Description: 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: Name Type Description message String | Object The message as an HTML string or DOM element seconds number Number of seconds to wait before dismissing the message opt_callback Function Optional callback function to be called when the message is dismissed. The callback function will not be called until after the existing callstack has completed execution. Returns: Type Description HTMLElement HTML element of the created message

dismissMessage(message) Description: Dismisses the specified message. Parameters: Name Type Description message HTMLElement HTML element of the message to remove

OAuth popup window manager. Expected usage: Gadget attempts to fetch OAuth data for the user and discovers that approval is needed. The gadget creates two new UI elements: a "personalize this gadget" button or link a "personalization done" button or link, which is initially hidden. The "personalization done" button may be unnecessary. The popup window manager will attempt to detect when the window closes. However, the "personalization done" button should still be displayed to handle cases where the popup manager is unable to detect that a window has closed. This allows the user to signal approval manually. Gadget creates a popup object and associates event handlers with the UI elements:

// Called when the user opens the popup window. var onOpen = function() { $("personalizeDone").style.display = "block" } // Called when the user closes the popup window. var onClose = function() { $("personalizeDone").style.display = "none" fetchData(); } var popup = new gadgets.oauth.Popup( response.oauthApprovalUrl, "height=300,width=200", onOpen, onClose ); personalizeButton.onclick = popup.createOpenerOnClick(); personalizeDoneButton.onclick = popup.createApprovedOnClick();

When the user clicks the personalization button/link, a window is opened to the approval URL. The onOpen function is called to notify the gadget that the window was opened. When the window is closed, the popup manager calls the onClose function and the gadget attempts to fetch the user's data.

gadgets.oauth.Popup(destination, windowOptions, openCallback, closeCallback) Description: used to create a new OAuth popup window manager. Parameters: Name Type Description destination String Target URL for the popup window. windowOptions String Options for window.open, used to specify look and feel of the window. openCallback Function Function to call when the window is opened. closeCallback Function Function to call when the window is closed.

Type: {Function} createOpenerOnClick() Returns: Type Description Function an onclick handler for the "open the approval window" link.

Type: {Function} createApprovedOnClick() Returns: Type Description Function an onclick handler for the "I've approved" link. This may not ever be called. If we successfully detect that the window was closed, this link is unnecessary.

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

<static> gadgets.rpc.call(targetId, serviceName, callback, var_args) Description: Calls an RPC service. Parameters: Name Type Description targetId String ID of the RPC service provider; empty if calling the parent container serviceName String Service name to call callback Function|null Callback function (if any) to process the return value of the RPC request. The callback function will not be called until after the existing callstack has completed execution. var_args * Parameters for the RPC request

<static> gadgets.rpc.config(params) Description: Configures the existing RPC instance with the given parameters. Paramaters is a gadgets.rpc.ConfigParameters Parameters: Name Type Description params gadgets.rpc.ConfigParameters Parameters object passed into the config method.

<static> gadgets.rpc.getReceiverOrigin(receiverId) Description: Returns the origin for the given RPC service provider. If the origin cannot be verified, returns null. Parameters: Name Type Description receiverId String ID of the RPC service provider; empty if calling the parent container Returns: Type Description String|null If the underlying transport is parent-verifiable, then returns the origin for the given receiverId, otherwise, returns null.

<static> gadgets.rpc.register(serviceName, handler) Description: Registers an RPC service. Parameters: Name Type Description serviceName String Service name to register handler Function Service handler

<static> gadgets.rpc.registerDefault(handler) Description: Registers a default service handler to process all unknown remote procedure calls, which fail silently by default. Parameters: Name Type Description handler Function Service handler

<static> gadgets.rpc.unregister(serviceName) Description: Unregisters an RPC service. Parameters: Name Type Description serviceName String Service name to unregister

<static> gadgets.rpc.unregisterDefault() Description: Unregisters the default service handler. Future unknown remote procedure calls will fail silently.

gadgets.rpc.ConfigParameters Description: Object used to hold the parameters into the config method, supports the following properties: Name Type Description securityCallback function securityCallback: Callback function which is invoked when RPC connection encounters a security issue. Function syntax is securityCallback( receiverId, error ). The following are the defined security errors: gadgets.rpc.LOAD_TIMEOUT - receiver failed to connect in time gadgets.rpc.FRAME_PHISH - receiver's iframe may have been maliciously redirected to a new location gadgets.rpc.FORGED_MSG - RPC detected a possibly forged message

Discussion

The selection feature gives gadgets the ability to participate in the container's selection eventing. The concept of selection is common among many containers. Examples include: selected person in a buddy or contacts list selected activity in an activity stream selected item in a user's profile Selection is a user-driven singleton belonging to the container. For example, when a user selects a Person in their contact list before sending that Person a message, that Person becomes the selected object. Typically, a user gesture triggers a gadget to post selection to the container's selection service. Each time something is posted to the selection service, gadgets that are registered to listen for selection events are notified. The current selection for the container represents what was posted last and can be queried at any time. The selected object can represent a single object or a collection of objects. Note: gadgets must opt in to publish data via selection and should be aware it is a broadcast event.

<static> gadgets.selection.setSelection (selectionArray) Description: Sets the selection for the container. The selection may be an array of multiple objects. Parameters: Name Type Description selectionArray Object[] Array of object(s) to be set as selected, with attributes defined in table below. Each selection object must have the following attributes: Name Type Description type String Open Social data type, as specified in the Social Data Specification dataObject Object Object representing the selection. Example: //an array of 2 people who are currently selected var selection = [ {type: "opensocial.Person", dataObject: bob}, {type: "opensocial.Person", dataObject: joe} ]; gadgets.selection.setSelection(selection);

<static> Type: Object[] gadgets.selection.getSelection() Description: Gets the current selection for the container. Returns: Type Description Object[] The array of currently selected objects, each with type and dataObject properties

<static> gadgets.selection.addListener(callback) Description: Registers the callback function to be called for selection events. Discussion Name Type Description callback Function The callback function that is called for the specified selection event.

<static> gadgets.selection.removeListener(callback) Description: Unregisters the callback function previously registered by addListener. Discussion Parameters: Name Type Description callback Function The callback function to be unregistered.

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

<static> Type: {String} gadgets.skins.getProperty(propertyKey) Description: Fetches the display property mapped to the given key. Parameters: Name Type Description propertyKey String The key to get data for; keys are defined in gadgets.skins.Property Returns: Type Description String The data

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. The color that anchor tags should use. This field may be used interchangeably with the string 'ANCHOR_COLOR'. The color of the background of the gadget. This field may be used interchangeably with the string 'BG_COLOR'. An image to use in the background of the gadget. This field may be used interchangeably with the string 'BG_IMAGE'. The color in which the main font should be rendered. This field may be used interchangeably with the string 'FONT_COLOR'.

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

Type: {Function} getCallback() Description: Returns the callback function that is executed when the tab is selected. Returns: Type Description Function The callback function of the tab

Type: {HTMLElement} getContentContainer() Description: Returns the HTML element where the tab content is rendered. Returns: Type Description HTMLElement The HTML element of the content container

Type: {Number} getIndex() Description: Returns the tab's index. Returns: Type Description Number The tab's index

Type: {String} getName() Description: Returns the label of the tab as a string (may contain HTML). Returns: Type Description String The label of the tab

Type: {HTMLElement} getNameContainer() Description: Returns the HTML element that contains the tab's label. Returns: Type Description HTMLElement The HTML element of the tab's label

A class gadgets can use to make tabs.

gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container) Creates a new TabSet object Parameters: Name Type Description opt_moduleId String Optional suffix for the ID of tab container opt_defaultTab String 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 opt_container HTMLElement The HTML element to contain the tabs; if omitted, a new div element is created and inserted at the very top

Type: {String} addTab(tabName, opt_params) Description: Adds a new tab based on the name-value pairs specified in opt_params. The following properties are supported in opt_params: An existing HTML element to be used as the tab content container. If omitted, the tabs library creates one. A callback function to be executed when the tab is selected. The callback function will not be called until after the existing callstack has completed execution. A tooltip description that pops up when user moves the mouse cursor over the tab. The index at which to insert the tab. If omitted, the new tab is appended to the end. Parameters: Name Type Description tabName String Label of the tab to create opt_params Object Optional parameter object Returns: Type Description String DOM id of the tab container

alignTabs(align, opt_offset) Description: Sets the alignment of tabs. Tabs are center-aligned by default. Parameters: Name Type Description align String 'left', 'center', or 'right' opt_offset Number Optional parameter to set the number of pixels to offset tabs from the left or right edge; the default value is 3px

displayTabs(display) Description: Shows or hides tabs and all associated content. Parameters: Name Type Description display Boolean True to show tabs; false to hide tabs

Type: {HTMLElement} getHeaderContainer() Description: Returns the tab headers container element. Returns: Type Description HTMLElement The tab headers container element

Type: { gadgets.Tab } getSelectedTab() Description: Returns the currently selected tab object. Returns: Type Description gadgets.Tab The currently selected tab object

Type: {Array.<gadgets.Tab>} getTabs() Description: Returns an array of all existing tab objects. Returns: Type Description Array.<gadgets.Tab> Array of all existing tab objects

removeTab(tabIndex) Description: Removes a tab at tabIndex and all of its associated content. Parameters: Name Type Description tabIndex Number Index of the tab to remove

setSelectedTab(tabIndex) Description: 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: Name Type Description tabIndex Number Index of the tab to select

swapTabs(tabIndex1, tabIndex2) Description: Swaps the positions of tabs at tabIndex1 and tabIndex2. The selected tab does not change, and no callback functions are called. Parameters: Name Type Description tabIndex1 Number Index of the first tab to swap tabIndex2 Number Index of the secnod tab to swap

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

<static> gadgets.window.adjustHeight(opt_height) Description: Adjusts the gadget height. Parameters: Name Type Description opt_height Number An optional preferred height in pixels; If not specified, will attempt to fit the gadget to its content

Discussion <static> gadgets.window.adjustWidth(opt_width) Description: Adjusts the gadget width. Parameters: Name Type Description opt_width Number An optional preferred width in pixels; If not specified, will attempt to fit the gadget to its content

Discussion <static> gadgets.window.adjustSize(opt_height, opt_width) Description: Adjusts the gadget size. Parameters: Name Type Description opt_height Number An optional preferred height in pixels; If not specified, will attempt to fit the gadget to its content opt_width Number An optional preferred width in pixels; If not specified, will attempt to fit the gadget to its content

<static> Type: {Object} gadgets.window.getViewportDimensions() Description: Detects the inner dimensions of a frame. See http://www.quirksmode.org/dom/w3c_cssom for more information. Returns: Type Description Object An object with width and height properties

<static> gadgets.window.getContainerDimensions(resultCallback) Description: Gets the dimensions of the container displaying this gadget through callback function which will be called with the return value as a parameter. Discussion Parameter: Name Type Description resultCallback function Callback function will be called with the return value as a parameter.

<static> gadgets.window.setTitle(title) Description: Sets the gadget title. Parameters: Name Type Description title String The preferred title

The inter-gadget eventing mechanism in OpenSocial, commonly known as pub/sub, provides the ability for loosely coupled inter-gadget communication via the delivery of messages on topics. The definition of the OpenSocial API is based on the OpenAjax Hub 2.0 (OA Hub) specification defined by the OpenAjax Alliance. The addition of this capability adds API in three areas, an event hub to manage the subscription and publication of events on the client, the publish and subscribe methods for the gadgets, and wiring meta-data that can be used by advanced containers and tooling. The semantics of the API offered in OpenSocial will match that of the OA Hub. Process: Pub/sub is handled through messages between a client and the hub, which are defined in the OpenAjax specification. There is one hub client per gadget instance. When the gadget is loaded, the client is "connected" to the hub. The general pattern for using pub/sub in a gadget is as follows: (Optional) Override the default settings used to configure the gadget's hub client instance. Call publish or subscribe methods. The full capability of the OpenAjax Hub is available for use within OpenSocial. To understand the complete set of capability provided by the hub, please refer to OpenAjax Web site for the complete documentation and specification. In order to take advantage of intergadget communication, each instance of a gadget needs a client that that is connected to the hub. The full specification for the client is available on the OpenAjax Alliance documentation Web site. Please refer to OpenAjax Hub Client section for more information. Following the general pattern of pub/sub based systems, a gadget will publish a message on a topic. Other gadgets (or even the publishing gadget) may subscribe to the topic to receive the information that has been published. In addition, the OpenAjax Alliance has defined a collection of best practices that should be used as guidelines when developing gadgets that leverage pub/sub. Please see OpenAjax Hub 2.0 Specification Best Practices for more information.

In order to ensure that the OpenAjax Hub client is properly configured, when the PubSub feature is added, the container MUST provide the following initialization steps for the gadget when this feature is added. The behavior described in this section ensures that simple gadgets do not need to do anything at all to set up their HubClient instances; but it allows gadgets with special needs to override the default parameters and behavior as required. Set default values Register an onLoad handler The onLoad handler constructs the HubClient and calls HubClient.connect.

The publish and subscribe methods, as well as the wiring metadata make use of a "topic". A "topic" MUST be a String and MUST conform to the Topic Name Rules defined by the OpenAjax Hub. The following list summarizes the content that is described by the OA Hub speicificaiton. Wildcards usage on topic subscription: Valid wild cards are "*" for single token and "**" for multiple token. Considerations on unicode and special characters: Developers SHOULD NOT not use control, whitespace, quote, or punctuation characters in topic names. Reverse DNS topic names: To avoid potential topic name conflicts with other components, it is RECOMMENDED that all topic names begin with a registered internet domain expressed in reverse order, such as org.openajax.registerLibrary. Further, there SHOULD be a logical correlation between the reverse DNS namespace of the topic name and the prefix pattern used when defining an extension to the OpenSocial data model. See OpenSocial Specification for more details on the extension model. See OpenAjax Hub 2.0 Specification Topic Names for more information.

OpenSocial reserves the reverse DNS namespace org.opensocial, and all derivities, for use within the OpenSocial specification. Developers MUST NOT use org.opensocial or any derivitive namespace when defining their own topics.

publish(topic, payload) Description: The publish method conforms to the semantics of the OA Hub. The OAHub embraces the notion that pubsub is anonymous and does not automatically include any information about the identification of the publishing gadget with the message. The following is an excerpt from their documentation. Parameters: Name Type Description topic String A string that conforms to the rules defined above and by the OA Hub to name the channel that the payload will be deliverd on. Wildcards are NOT permitted. payload * It is permissible to publish any object. The payload MUST be serializable to JSON. See the OpenAjax Hub 2.0 documentation for more information.

subscribe(topic, callback [,scope [,onCompleteCallback [,subscriberData]]]) Description: The subscribe method is used to indicate to the hub the topic from which the gadget is interested in receiving information. When information is published on the topic, the hub will invoke the callback method on the gadget. Since a gadget may have multiple subscriptions on the same topic, the subscribe method returns an opaque identifier that is used to uniquely identify the subscription. This identifier is used to unsubscribe to the topic. It is gadget developer's responsibility to manage this identifier. Parameters: Name Type Description topic String A string that conforms to the rules defined above and by the OA Hub to name the channel that the payload will be deliverd on. Wildcards MAY be used. callback String A callback function to be executed when the tab is selected. The callback function will not be called until after the existing callstack has completed execution. scope object When onData callback or onComplete callback is invoked, the JavaScript "this" keyword refers to this scope object. If no scope is provided, default is window. onCompleteCallback function Function invoked to tell the client application whether the subscribe operation succeeded or failed. subscriberData * Client application provides this data, which is handed back to the client application in the subscriberData parameter of the onData callback function. Returns: Type Description String An opaque subscription identifier. This identifier is an arbitrary ID string that is unique within this Hub instance See the OpenAjax Hub documentation for more information

unsubscribe(subscriptionId) Description: This method is used to remove a subuscription for a gadget from the hub. The unsubscribe function immediately throws an exception if there is no subscription with the specified subscription ID. Otherwise, unsubscribe immediately deactivates the subscription. Parameters: Name Type Description subscriptionId String The subscriptionId is the opaque string that is returned from the subscribe(...) method. See the OpenAjax Hub documentation for more information.

The 'gadgets.Hub' object is an instance of IframeHubClient and supports some additional methods. Please see the OpenAjax Hub documentation for more information.

The following example illustrates how a container could provide support for this feature. Set default values. // Create a pubsub settings object gadgets.HubSettings = {}; // Set default HubClient constructor params object gadgets.HubSettings.params = { HubClient: { onSecurityAlert: function( alertSource, alertType ) { alert( "Gadget stopped attempted security breach: " + alertType ); window.location.href = "about:blank"; // Forces container to see Frame Phish alert and probably close this gadget }, scope: gadgetInstance } }; // Set default onComplete function for HubClient.connect gadgets.HubSettings.onConnected = function( hub, suc, err ) { }; Register an onLoad handler An onLoad handler to actually create the HubClient and connect it to the ManagedHub. Delaying the HubClient creation and connection allows the gadget to override default values stored in gadgets.HubSettings. For example, IframeHubClient supports params properties such as seed, tokenLength and log, which are not set by default; and a gadget might need to override onSecurityAlert and/or scope, for which default values are provided. More importantly, the onComplete function for HubClient.connect usually sets up the gadget's subscriptions by calling gadgets.Hub.subscribe, or if the connection fails asynchronously, the onComplete function handles the error. // Register an onLoad handler gadgets.util.registerOnLoadHandler( function() { try { // Create the HubClient. gadgets.Hub = new OpenAjax.hub.IframeHubClient( gadgets.HubSettings.params ); // Connect to the ManagedHub gadgets.Hub.connect( gadgets.HubSettings.onConnect ); } catch(e) { // TODO: error handling should be consistent with other OS gadget initialization error handling } } );

By default, a HubClient is instantiated automatically by the pubsub-2 code, on gadget load. If the gadget wants to override the default parameters to the HubClient constructor, it can do so by setting values on gadgets.HubSettings. For example: gadgets.HubSettings.params.HubClient.onSecurityAlert = function(alertSource, alertType) { // handle security alert here }; gadgets.HubSettings.params.HubClient.log = function(msg) { // custom logging code here, for recording logging msgs from HubClient }; gadgets.util.registerOnLoadHandler(function() { gadgets.Hub.subscribe("org.foo.bar.topic", callback); gadgets.Hub.publish("org.foo.bar.topic2", data); }); See OpenAjax Hub 2.0 Specification document for more information.

The OpenSocial specification defines additional metadata that can be used to describe the events that a gadget publishes or to which it is able to subscribe. This allows the container to automatically "wire" gadgets together, and/or provide a UI that allows the user to wire publisher gadgets to subscriber gadgets. For example, manual wiring is often necessary because there sometimes are multiple widgets publishing to or subscribing to the same topic, such as "date", where one widget might provide a start date and the other widget an end date, and also because sometimes topic names and/or payload types are too generic for automatic mapping.

Attribute Type Usage Description name String Required The dot-delimited topic name, e.g. "org.example.randomNumber". This name follows the rules defined in the OpenAjax Widget Metadata specification. Developers of gadgets MAY allow the @name attribute to be ovveridden using user preference variables. See Using Varuables for @name type String Optional Type name for the event's payload data. When not specificed, any type wil be allowed. See Event Data Types. title String Optional Title for this type of event that is appropriate for a non-technical reader. When not specified, the value of the "name" attribute will be used. publish boolean Optional Indicates if the gadget publishes events on this topic. The default value is "false". subscribe boolean Optional Indicates if the gadget subscribes to events that are published on this topic. The default value is "false". description String Optional The textual description of the gadget's publish or subscribe endpoint. This can be used as an indication of the gadget's behavior. Consider a gadget that subscribes to a topic "com.example.address". The description migh read, "When this gadget receives an event on the com.example.address topic, it displays mass transit options within 10km of the address received as the event payload." aboutUrl String Optional A URL pointing to a resource that provides more extensive descriptive information than can be provided in the description attribute.

In the absence of a specific standard for events within a given domain, it is inevitable that different groups of developers, working in different niches on similar problems, will use different topic naming schemes for what is essentially the same event. While some developers in a domain may eventually consolidate around a standard set of topic names, it's also inevitable that installed bases, legacy implementations, politics, requirement to integrate with third party gadgets from other domains, schedule constraints and other factors will ensure that once a topic space becomes balkanized, it will remain that way for a long time. It is important that the specification offer a mechanism that allows developers to bridge simple mismatches between gadgets. It is important that gadget developers use this mechanism where possible. This will maximize the reusability of gadgets -- a major goal.

The following is an example of how to use variable substituion in the definition of the @name attribute.

<Require feature="pubsub-2"> <Param name="topics"><![CDATA[ <Topic title="Selected Location" name="__UP_location__" description="The currently selected location" type="http://nsgs.gov/geo#Place" publish="false" subscribe="true" aboutUrl="http://nsgs.gov"> </Topic> <!-- etc. for other topics --> ]]></Param> </Require>

The OpenAjax Hub has a predefined set of identifiers that are used to indicate the data type. Tooling and runtime container code can use this to infer information about the messages being published as well as the parameters a gadget expects to receive when it subscribes to a topic. The data types provided by the OpenAjax Hub are "built in". These are referred to as the OpenAjax common types, and they require no namespace qualifier. When a type other than an OpenAjax common type is used, it MUST contain a namesake qualifier. The namespace should conform to reverse DNS rules. The namespace org.opensocial.* MUST NOT be used and is reserved for types defined in the specification, e.g. social data types. Type Name Comments string ECMAScipt string number ECMAScipt number boolean ECMAScipt boolean array ECMAScipt array, e.g. [ 1, 1, 2, 3, 5, 8 ]. The element type/s are not specified when the generic "array" type is used. object * ECMAScipt object, e.g. { foo: "bar", baz: "boo" }. The specifics of the object are not specified when the generic "object" type is used. null * ECMAScipt null length * Any CSS length value Howard 2009.11.10: CSS version? color * Any CSS color value id ID value - probably not useful for OpenSocial Gadgets, but might as well keep the two specs in sync class * zero of more CSS class names, separated by spaces style * a string that could be used as value for a 'style' attribute url A URL Howard 2009.11.09: Do we want "uri" also? html A fragment of HTML markup. countrycode * A string that represents an [http://www.iso.org/iso/country_codes/iso_3166_code_lists.htm A3 ISO 3166 country code]. languagecode * A string that represents an [http://www.loc.gov/standards/iso639-2/php/code_list.php ISO 639-2 language code]. email A string that represents an e-mail address. person A string that holds a person's name. postalcode A string that represents a postal code. phone A string that represents a phone number. date * A string that represents a date. MUST be expressed using the "Date Time String Format" defined in the [http://www.ecmascript.org/docs/tc39-2009-043.pdf ECMAScript5 specification] using one of the date-only forms. For example: "2009-12-15" time * A string that represents a time of day. MUST be expressed using the "Date Time String Format" defined in the [http://www.ecmascript.org/docs/tc39-2009-043.pdf ECMAScript5 specification] using one of the time-only forms. For example: "18:45:00Z" or "10:26:24-05:00" timestamp * A string that represents a date and time of day. MUST be expressed using the "Date Time String Format" defined in the [http://www.ecmascript.org/docs/tc39-2009-043.pdf ECMAScript5 specification]. For example: "2009-12-15:18:45.000Z" duration * A string that represents a duration. MUST have format "PYYYY-DDDThh:mm:ss.fff". For example, "P0400-152T20:45:33.123" means "400 years, 152 days, 20 hours, 45 minutes, 33.123 seconds, while "P0003-000T01:56:22.000" means "3 years, 1 hour, 56 minutes and 22.000 seconds." (Must use this one variant defined in the ISO 8601 standard). * Asterisk, or missing type attribute, means "any datatype"

The Pub/Sub feature supports format for metadata that uses a string to represent the topic information. The format of this string is as follows:

<Require feature="pubsub-2"> <Param name="topics"><![CDATA[ <Topic title="string" name="string" description="string" type="string" publish="boolean" subscribe="boolean" aboutUrl="string"> </Topic> <!-- etc. for other topics --> ]]</Param> </Require>

A container MUST emit the OpenSocial JavaScript internationalization libraries and data files required by the libraries if an application requires the feature <Require feature="opensocial-i18n"/>. The container SHOULD emit the OpenSocial JavaScript internationalization libraries and data files required by the libraries if an application optionallly requests the feature <Optional feature="opensocial-i18n"/>.

Class for internationalization features.

Gadgets locale is set at render time. The i18n package above will use getCountry and getLanguage to load the corresponding formatter/parser for that locale if any of the functions in the package are invoked. For example, let's say gadgets has lanuguage as french and country as france, the i18n package will use formatter/parser following french conventions by default. That means gadget developers could format/parse French date/time/number/currency using the predefined CURRENCY_PATTERN.

Example gadgets.i18n.parseNumber(gadgets.i18n.CURRENCY_PATTERN, "20 000 \u20AC"); // will return 20000

They could also parse foreign currency by passing in a opt_currencyCode. Note when French writes an amount of foreign currency, they will still use the French way of writing numbers the positioning currency code - just the currency code is different.

Example gadgets.i18n.parseNumber(gadgets.i18n.CURRENCY_PATTERN, "20 000 $", 0, "USD"); // will return 20000

It gets a little bit complicated if a foreign currency written in the foreign way is to be parsed. In that case, predefined patterns won't work, and string patterns need to be used. The example below returns 0 (indicating error in parsing), as the number presented is not in French format.

Example gadgets.i18n.parseNumber(gadgets.i18n.CURRENCY_PATTERN, "$20,000"); // will return 0, indicating error

To make this work, a string pattern needs to be passed in, like what is done below:

Example gadgets.i18n.parseNumber("#,###", "$20,000", 0, "USD"); // will return 20000

Both Formatting and Parsing following the same pattern specification. The date/time pattern specifications are found in Unicode Locale Data Markup Language, Date Format Patterns The following specifiers are not required in this release: w: Week of year W: Week of Month. D: Day of year. F: Day of Week in Month. g: Modified Julian day

Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. For example, the '#' character is replaced by a localized digit. Often the replacement character is the same as the pattern character; in the U.S. locale, the ',' grouping character is replaced by ','. However, the replacement is still happening, and if the symbols are modified, the grouping character changes. Some special characters affect the behavior of the formatter by their presence; for example, if the percent character is seen, then the value is multiplied by 100 before being displayed. To insert a special character in a pattern as a literal, that is, without any special meaning, the character must be quoted. There are some exceptions to this which are noted below. The characters listed here are used in non-localized patterns. Localized patterns use the corresponding characters taken from corresponding locale symbol collection. Two exceptions are the currency sign and quote, which are not localized. Symbol Location Localized? Meaning 0 Number Yes Digit # Number Yes Digit, zero shows as absent. . Number Yes Decimal separator or monetary decimal separator. - Number Yes Minus sign , Number Yes Grouping Separator E Number Yes Separates mantizza and exponent in scientific notation. Need not be quoted in prefix or suffix. ; Subpattern boundary Yes Separates positive and negative subpatterns. % Prefix or suffix Yes Multiply by 100 and show as percentage. \u2030 Prefix or suffix Yes Multiply by 1000 and show as per mile. ¤ (\u00A4) Prefix or suffix No Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If present in a pattern, the monetary decimal separator is used instead of the decimal separator. ' Prefix or suffix No Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock". A NumberFormat pattern contains a postive and negative subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric part, and a suffix. If there is no explicit negative subpattern, the negative subpattern is the localized minus sign prefixed to the positive subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit negative subpattern, it serves only to specify the negative prefix and suffix; the number of digits, minimal digits, and other characteristics are ignored in the negative subpattern. That means that "#,##0.0#;(#)" has precisely the same result as "#,##0.0#;(#,##0.0#)". The prefixes, suffixes, and various symbols used for infinity, digits, thousands separators, decimal separators, etc. may be set to arbitrary values, and they will appear properly during formatting. However, care must be taken that the symbols and strings do not conflict, or parsing will be unreliable. For example, the decimal separator and thousands separator should be distinct characters, or parsing will be impossible. The grouping separator is a character that separates clusters of integer digits to make large numbers more legible. It commonly used for thousands, but in some locales it separates ten-thousands. The grouping size is the number of digits between the grouping separators, such as 3 for "100,000,000" or 4 for "1 0000 0000".

pattern := subpattern (';' subpattern)? subpattern := prefix? number exponent? suffix? number := (integer ('.' fraction)?) | sigDigits prefix := '\u0000'..'\uFFFD' - specialCharacters suffix := '\u0000'..'\uFFFD' - specialCharacters integer := '#'* '0'* '0' fraction := '0'* '#'* sigDigits := '#'* '@' '@'* '#'* exponent := 'E' '+'? '0'* '0' padSpec := '*' padChar padChar := '\u0000'..'\uFFFD' - quote Notation: X* 0 or more instances of X X? 0 or 1 instances of X X|Y either X or Y C..D any character from C up to D, inclusive S-T characters in S, except those in T

The first subpattern is for positive numbers. The second (optional) subpattern is for negative numbers.

Pattern for currency. Pattern for decimal numbers. Format for full representations of dates. Format for short representations of datetimes. Format for full representations of times. Format for long representations of dates. Format for short representations of datetimes. Format for long representations of times. Format for medium representations of dates. Format for medium representations of datetimes. Format for medium representations of times. Pattern for percentages. Pattern for scientific numbers. Format for short representations of dates. Format for short representations of datetimes. Format for short representations of times.

<static> Type: {string} gadgets.i18n.formatDateTime(pattern, date) Description: This method formats a "Date" object with provided pattern specification. The pattern could be a string using ICU notation or a predefined pattern. A string using ICU notation offers the most flexibility. Each field as specified in the pattern has locale specific behavior. The pattern string is allowed to contain string literals, and one type of pattern might not work for all locales. In those case, the pattern itself could also be locale specific, thus not good for sharing among locales.

Example date = new Date(2006, 6, 27, 13, 10, 10, 250); assertEquals("13:10:10", gadgets.i18n.formatDateTime("HH:mm:ss", date));

Parameters: Name Type Description pattern string/number String to specify patterns or Number used to reference predefined pattern that a date should be formatted into. date Date Date object being formatted. Returns: Type Description string string representation of date/time.

<static> Type: {string} gadgets.i18n.formatNumber(pattern, value, opt_currencyCode) Description: Format number using the pattern specified. The pattern could be a string pattern or one of the predefined patterns. The formatted string is returned. If an error is encountered, zero will be returned.

Example var str = gadgets.i18n.formatNumber("#,###", 1234567890); assertEquals("1,234,567,890", str); var str = gadgets.i18n.formatNumber(gadgets.i18n.CURRRENCY_PATTERN, 1234.569); assertEquals("$1,234.58", str);

Parameters: Name Type Description pattern string/number String to specify patterns or Number used to reference predefined pattern that a number should be formatted into. value number The number being formatted. opt_currencyCode string optional international currency code, it determines the currency code/symbol should be used in format/parse. If not given, the currency code for current locale will be used. Returns: Type Description string The formatted string.

<static> Type: {number} gadgets.i18n.parseDateTime(pattern, text, start, date) Description: This method will parse the input string ("text"), interpretting it as specified by pattern. The parsed result will be saved into a Date object ("date"). "start" indicates from where in the string the parse should start. This method returns the number of characters consumed.

Example assertTrue(gadgets.i18n.parseDateTime("yyMMdd", "991202", 0, date) > 0); assertEquals(1999, date.getFullYear()); assertTrue(date.getMonth() == 12 - 1); assertTrue(date.getDate() == 02); assertTrue(gadgets.i18n.parseDateTime("yyyyMMdd", "20051202", 0, date) > 0); assertEquals(2005, date.getFullYear()); assertTrue(date.getMonth() == 12 - 1); assertTrue(date.getDate() == 02);

A whole piece of string is usually the target for parsing. But in some cases, you might just want to parse part of the string, "start" parameter and return value also make it very convenient. For example, suppose you want to parse a string like "88/01, 99/03, 98/05, 97/02", the following code will do the job.

Example var date_array = []; var pos = 0; var text = "88/01, 99/03, 98/05, 97/02"; while(1) { var date = new Date; var consumed = gadgets.i18n.parseDateTime("yy/MM", text, pos, date); if (consumed <= 0) break; date_array.push(date); pos += consumed; if (pos < text.length && text[pos] == ',') ++pos; if (pos < text.length && text[pos] == ' ') ++pos; }

Similar to the formatting functions, a predefined pattern could also be passed in as the first parameter.

Example //assume locale has already been set to zh_CN var date = new Date(); gadgets.i18n.parseDateTime(gadgets.i18n.LONG_DATE_FORMAT, "2006年7月24日", 0, date); assertEquals(date.getFullYear(), 2006); assertEquals(date.getMonth(), 7 - 1); assertEquals(date.getDate(), 24);

Parameters: Name Type Description pattern string/number String to specify patterns or Number used to reference predefined pattern that a date should be parsed from. text string The string that need to be parsed. start number The character position in "text" where parse begins. date Date The date object that will hold parsed value. Returns: Type Description number The number of characters advanced or 0 if failed.

<static> Type: {number} gadgets.i18n.parseNumber(pattern, text, opt_pos, opt_currencyCode) Description: Parse string to get a number the pattern specified. The pattern could be a string pattern or one of the predefined patterns.

Example var value = gadgets.i18n.parseNumber("0E0", "1.2345E+4"); assertEquals(12345.0, value); //assume locale has already been set to fr var value = gadgets.i18n.parseNumber(gadgets.i18n.CURRENCY_PATTERN, "0,30 €"); assertEquals(0.30, value);

Parameters: Name Type Description pattern string/number String to specify patterns or Number used to reference predefined pattern that a number should be parsed from. text string input text being parsed. opt_pos Array optional one element array that holds position information. It tells from where parse should begin. Upon return, it holds parse stop position. opt_currencyCode string optional international currency code, it determines the currency code/symbol should be used in format/parse. If not given, the currency code for current locale will be used. Returns: Type Description number Parsed number, 0 if in error.

Discussion The OpenSearch feature in OpenSocial allows gadgets to declare that they have searchable material by providing an OpenSearch 1.1 description in their gadget definition. The OpenSeach description is passed as a parameter to the OpenSearch feature. Gadget developers may choose to embed the OpenSearch descriptior right in the gadget definition itself, or they may reference an OpenSearch description hosted on a server by using it's URL. Gadget developers SHOULD make the OpenSearch feature optional in thier gadget defintions to allow for ineroperability in all containers.

The OpenSearch description can be declared in two ways, first by embedding it in the gadget definition itself, or secondly by providing a URL to the description document. To do this gadget developers should provide a feature parameter to the OpenSearch feature. The parameter names can be one of the following. Parameter Name Description description XML for the full OpenSearch 1.1 description as described on the OpenSearch site. url A URL to the OpenSearch 1.1 description document.

The description parameter contains the full XML of the OpenSearch 1.1 description, as described in the OpenSearch Specification. The description contains the template url for fetching results, the type of results returned, the title of the search contribution, and other information. Please see the link above for more details.

The url parameter points to an XML document that contains the full OpenSearch 1.1 description.

<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="OpenSearch Example"> <Optional feature="opensearch"> <Param name="description"> <![CDATA[ <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"> <ShortName>Example Search</ShortName> <Description>Realtime Example Search</Description> <Url type="application/atom+xml" method="get" template="http://search.example.com/search.atom?q={searchTerms}"/> <Image width="16" height="16">http://search.example.com/favicon.png</Image> <InputEncoding>UTF-8</InputEncoding> <SearchForm>http://search.example.com/</SearchForm> </OpenSearchDescription> ]]> </Param> </Optional> </ModulePrefs> <Content type="url" href="http://example.com/searchGadget.xml" /> </Module>

<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="OpenSearch Example"> <Optional feature="opensearch"> <Param name="url">http://search.example.com/openSearchDescription.xml</Param> </Optional> </ModulePrefs> <Content type="url" href="http://example.com/searchGadget.xml" /> </Module>

Discussion Embedded experiences provide a mechanism for embedding OpenSocial gadgets and other web-accessible content sources directly into a variety of contexts such as Activity Streams, email messages and Atom feeds. The mechanism works by inserting a small structure of data that includes a reference to the embedded content along with contextual data an OpenSocial container would need to render the content appropriately. This data structure can be serialized as either a JSON object or XML and includes the following properties: Property Description context If the Embedded Experience is used to embed an OpenSocial gadget, the "context" field is used to pass data to the gadget so that it knows exactly which content to render. For instance, a gadget that displays a person's profile information will need to know which profile to display; a gadget that displays an album of recent photos will need to know the identity of the album to display. The content of the "context" field is undefined and specific to each individual gadget definition with one exception: the special property name "opensocial" is reserved for use by the container implementation. The "context" properties JSON object value or XML element structure MUST NOT contain a property named "opensocial". gadget A URL to an OpenSocial Gadget definition document that defines the gadget to be embedded. preferredExperience An optional collection of properties that describe the preferred way the creator of the embedded experience would like containers to render the content. previewImage An optional URI to an image that can be used as a preview for the embedded content. This property accepts URL data scheme (http://tools.ietf.org/html/rfc2397) to specify the image as Base64-encoded embedded data. url A URL to a web page that allows virtually any web-accessible resource to be used as an Embedded Experience. The "url" and "gadget" properties each reference content that is to be embedded. At least one of these properties MUST be specified. When both properties are used within the Embedded Experience, the decision about which to render is left to the container. When serialized as JSON, the embedded experience take the form of a single JSON Object with four distinct properties: "context", "gadget", "previewImage" and "url". Additional extension properties MAY be included in the JSON object.

For instance, a simple JSON Embedded Experience that references an OpenSocial gadget: { "gadget" : "http://www.example.com/embedded/gadget.xml", "context" : { "title" : "Hello World", "id" : 123 }, "previewImage" : "http://www.example.com/embedded/123.png" }

When serialized as XML, it is expressed in the form of a root element <embed> containing four child elements, the order of which is considered insignificant: <context>, <gadget>, <previewImage>, and <url>. Additional extension elements and attributes MAY be included in the XML object.

For example, http://www.example.com/embedded/gadget.xml 123 http://www.example.com/embedded/123.png ]]>

Note that no XML namespace is currently declared for the XML serialization. This means that special care must be taken when including an XML embedded experience into another type of XML document. For example, the following shows an XML embedded experience within a partial Atom Entry Document. Note the addition of xmlns="" on the embed element in order to "undeclare" the in-scope default XML namespace.

http://example.org/entries/1 ... http://www.example.com/embedded/gadget.xml 123 http://www.example.com/embedded/123.png ]]>

A simple URL embedded experience using the JSON serialization: { "url" : "http://www.example.org/embed/123.html" }

The same URL embedded experience using the XML serialization: http://www.example.org/embed/123.html ]]>

An embedded experience that specifies both a gadget and URL serialized as JSON: { "gadget" : "http://www.example.com/embedded/gadget.xml", "url" : "http://www.example.org/embed/123.html", "context" : { "title" : "Hello World", "id" : 123 }, "previewImage" : "http://www.example.com/embedded/123.png" }

The same embedded experience serialized as XML: http://www.example.com/embedded/gadget.xml http://www.example.org/embed/123.html 123 http://www.example.com/embedded/123.png ]]>

When rendering a gadget as an embedded experience, the container will look within the embedded experience data model and see if there is a "preferred experience" object containing a "target" property. If the target object type is equal to "gadget" and there is a view property specified, the container will try and render the value of the "view" property. If there is no "view" property in the target object or there is no target object, or if there is no preferred experience in the data model, the container will render a view called "embedded". If an "embedded" view or the view specified within the target object of the embedded experience data model is not found within the gadget definition, the container SHOULD render the gadget's default view.

An embedded experience gadget has the option of requiring some contextual information in order to render itself. By abstracting the data from the gadget itself, gadget developers can develop generalized gadgets that can be used for all embedded expereinces of a specific type. For example, a gadget developed to display videos can be built so that the id of the video is contained and extracted from the embedded experience's "context" property.

{ "gadget" : "http://example.org/embedded/video.xml", "context" : { "video-id" : "abc123" } }

Gadgets that are written to support embedded experiences MUST require the "embedded-experiences" feature within their gadget definition in order to access the context. The contextual data is stored within the data context object for the gadget. The key, "org.opensocial.ee.context", is used to access the context. Gadgets can add a listener on the data context object for this key, or it may retreive the key's value by using the data context APIs.

For instance, the Gadget below registers a listener with the data context to retrieve any context data included with the embedded experience: <Module> <ModulePrefs title="Embedded Experiences Test" description="Tests the embedded experiences APIs."> <Require feature="embedded-experiences"></Require> </ModulePrefs> <Content type="html" view="embedded"> <![CDATA[ <script type="text/javascript"> function myCallback(key) { var context = opensocial.data.getDataContext().getDataSet(key); document.getElementById('contextData').innerHTML = gadgets.json.stringify(context); } function initData() { opensocial.data.getDataContext().registerListener( 'org.opensocial.ee.context', myCallback); } gadgets.util.registerOnLoadHandler(initData); </script> <div id="contextData"></div> ]]> </Content> </Module>

Instead of using the data context APIs to get the embedded experiences context you may choose to use the gadgets.ee.registerContextListener API in order to lessen the amount of code you need to write. The above gadget example can be rewriten to use the registerContextListener API: <Module> <ModulePrefs title="Embedded Experiences Test" description="Tests the embedded experiences APIs."> <Require feature="embedded-experiences"></Require> </ModulePrefs> <Content type="html" view="embedded"> <![CDATA[ <script type="text/javascript"> gadgets.util.registerOnLoadHandler(function() { gadgets.ee.registerContextListener(function(context) { document.getElementById('contextData').innerHTML = gadgets.json.stringify(context); }); }); </script> <div id="contextData"></div> ]]> </Content> </Module>

Discussion

While the contextual data associated with the "org.opensocial.ee.context" key will generally originate from the information provided by the "context" property within the Embedded Experience document, containers are free to insert additional, container specific contexual data into the object. For example, a container might wish to communicate information about the type of parent object within which the Embedded Experience information was received. If the "context" property of the embedded experience document is not an object than containers SHOULD NOT add any additional information to the "context" property. If such additional information is provided, the object associated with the "org.opensocial.ee.context" key MUST have an additional "openSocial" property. Containers MAY use the "openSocial" property to communicate additional information about the object containing the embedded experience being rendered. This information should be added to the "associatedContext" property and MUST contain the following properties: Property Description id The id of the OpenSocial Data object containing the embedded experience. The type of id will depend on the type of OpenSocial Data object containing the embedded experience. type The type of OpenSocial Data object containing the embedded experience.

The following is an example of what the embedded experience data model looks like if the container adds the required fields of the "associatedContext" object. { "gadget" : "http://example.org/AlbumViewer.xml", "context" : { "albumName": "Germany 2009", "photoUrls": [ "http://examplephotos.com/3495/3925132517_5959dac775_t.jpg", "http://examplephotos.com/3629/3394799776_47676abb46_t.jpg", "http://examplephotos.com/4009/4413640211_715d924d9b_t.jpg", "http://examplephotos.com/2340/3528537244_d2fb037aba_t.jpg", "http://examplephotos.com/36/98407782_9c4c5866d1_t.jpg", "http://examplephotos.com/48/180544479_bb0d0f6559_t.jpg", "http://examplephotos.com/2668/3858018351_1e7b73c0b7_t.jpg" ], "openSocial" : { "associatedContext" : { "id" : "container.com:123abc", "type" : "opensocial.ActivityEntry" } } } }

Note: As stated above, everything inside the "openSocial" property of the above example was added by the container. In addition to the "id" and the "type" properties, containers MAY add an additional property to the associated context called "objectReference". If present, the "objectReference" property will contain the JSON representation of the OpenSocial Data object containing the embedded experience. Property Description objectReference The JSON representation of the OpenSocial Data object containing the embedded experience. This OpenSocial Data object MUST contain the complete embedded experience data model.

The following is an example of what the embedded experience data model would look like if the container added the required and optional fields of the "associatedContext" object. { "gadget" : "http://example.org/AlbumViewer.xml", "context" : { "albumName": "Germany 2009", "photoUrls": [ "http://examplephotos.com/3495/3925132517_5959dac775_t.jpg", "http://examplephotos.com/3629/3394799776_47676abb46_t.jpg", "http://examplephotos.com/4009/4413640211_715d924d9b_t.jpg", "http://examplephotos.com/2340/3528537244_d2fb037aba_t.jpg", "http://examplephotos.com/36/98407782_9c4c5866d1_t.jpg", "http://examplephotos.com/48/180544479_bb0d0f6559_t.jpg", "http://examplephotos.com/2668/3858018351_1e7b73c0b7_t.jpg" ], "openSocial" : { "associatedContext" : { "id" : "container.com:123abc", "type" : "opensocial.ActivityEntry", "objectReference" : { "postedTime": "2011-02-10T15:04:55Z", "actor": { "objectType" : "person", "id": "tag:example.org,2011:martin", "displayName": "Martin Smith" }, "verb": "post", "object" : { "objectType":"collection", "objectTypes":["image"] "id": "http://example.org/albums/germany-2009", "url": "http://example.org/albums/germany-2009", }, "openSocial" : { "embed" : { "gadget" : "http://example.org/AlbumViewer.xml", "context" : { "albumName": "Germany 2009", "photoUrls": [ "http://examplephotos.com/3495/3925132517_5959dac775_t.jpg", "http://examplephotos.com/3629/3394799776_47676abb46_t.jpg", "http://examplephotos.com/4009/4413640211_715d924d9b_t.jpg", "http://examplephotos.com/2340/3528537244_d2fb037aba_t.jpg", "http://examplephotos.com/36/98407782_9c4c5866d1_t.jpg", "http://examplephotos.com/48/180544479_bb0d0f6559_t.jpg", "http://examplephotos.com/2668/3858018351_1e7b73c0b7_t.jpg" ] } } } } } } } }

The following example illustrates how this additional context information is accessed: function myCallback(key) { var context = opensocial.data.getDataContext().getDataSet(key); var video_id = context['albumName']; var associatedContext = context.openSocial.associatedContext; var ac_id = associatedContext.id; var ac_type = associatedContext.type; //The container MAY also add an object reference var obj_ref = associatedContext.objectReference if(typeof obj_ref !== 'undefined') { //Do something with the object reference } // ... } function initData() { opensocial.data.getDataContext().registerListener( 'org.opensocial.ee.context', myCallback); } gadgets.util.registerOnLoadHandler(initData);

Specific container implementations are free to insert any additional information they wish into the and "openSocial" object values. The interpretation and use of any such information is considered out of the scope of this specification.

While the container retains control over deciding exactly how an embedded experience is processed and rendered, there are situations where the creator of the embedded experience might wish to provide clues to the container as to how it would prefer the content to be displayed. These clues are included within the Embedded Experience using the "preferredExperience" property.

The following illustrates a basic example serialized as JSON: { "gadget" : "http://www.example.com/embedded/gadget.xml", "url" : "http://www.example.com/foo/bar.html", "context" : { "title" : "Hello World", "id" : 123 }, "previewImage" : "http://www.example.com/embedded/123.png", "preferredExperience" : { "target" : { "type" : "gadget", "view" : "my-ee-view" }, "display" : { "type" : "text" } }

And the same example using the alternative XML serialization: http://www.example.com/embedded/gadget.xml http://www.example.com/foo/bar.html 123 http://www.example.com/embedded/123.png gadget my-ee-view text ]]>

In this example, we have an embedded experience serialized as JSON. The structure defines both a "url" and a "gadget" property, both of which can be used by the container to display embedded content. Typically, the decision of which to display when the embedded experience is rendered is up to the container. The "preferredExperience.target" property allows the creator of the embedded experience to indicate that it would prefer the container to use the "gadget" property for rendering, and specifically that the "my-ee-view" view within that gadget be used. The "preferredExperience.display" property indicates that rather than simply displaying the gadget automatically, the embedded experience's creator would rather the container initially display a hyperlink that, when clicked, causes the gadget to be displayed. Property Description display Describes preferences for how the embedded experience should initially be displayed by the container. The "display" property provides the preferred style to container on how it should render the hyperlink to open the embedded experience. The value of the "display" property is an object that contains a required "type" property, the value of which determines what other properties might appear within the object. target Describes preferences for which type of embedded experience the container should render. For instance, if the embed includes both a "url" and "gadget" property, the "target" is used to specify which is preferred. The value of the "target" property is an object that contains a required "type" property, the value of which determines what other properties might appear within the object.

This specification currently defines two possible values for the required "type" property on the display object: "text", "image". Each of which are illustrated below.

Display using a hyperlink: { "gadget" : "...", ..., "preferredExperience" : { "target": {...}, "display": { "type" : "text", "label" : "Click on me!", "title" : "Click on this link!" "icon" : "http://mycontainer.com/app/openissue.jpg" } } }

When "type" equals "text", the additional properties on the display object are: Property Description label A required String that provides the text to display with the hyperlink. title Optional text to display as the "popup help" or "tooltip" of the hyperlink. icon The developer MAY provide a URL to an icon that can be used to decorate the text. For example, an issue management application may provide different icons for open issues than for those that are closed. Because it is expected that embedded experiences flow between containers, the URL MUST be absolute. Developers providing embedded experiences SHOULD ensure that the URL is able to be resolved by any container that will encounter the embedded experience. The container makes no assumptions about the size of the icon and MAY resize it to a size appropriate for the display needs. Use of the icon is optional. Depending on how the text is displayed, the container is not required to display the icon. The container MAY choose to display the icon in a manner appropriate to the current rendering of the object that contains the embedded experience. For example, it would be acceptable for the container to display the link in front of the text, or as a tool tip.

Display using the previewImage: { "gadget" : "...", ..., "previewImage" : "http://example.org/preview.png", "preferredExperience" : { "target": {...}, "display": { "type" : "image", "altText" : "The alt text", "width" : 100, "height" : 100 } } }

Display using Base64-encoded binary data in the URL data scheme: { "gadget" : "...", ..., "previewImage" : "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA...", "preferredExperience" : { "target": {...}, "display": { "type" : "image", "altText" : "The alt text", "width" : 100, "height" : 100 } } }

When "type" equals "image", the additional properties on the display object are: Property Description altText Specifies optional, alternative text to display if the image cannot be displayed. Equivalent to the HTML image tags alt attribute. height Specifies the preferred display height of the image in pixels. width Specifies the preferred display width of the image in pixels. Implementations are free to define additional display types, each with their own properties. If a container encounters an embedded experience that uses an unknown or unsupported display type, the container MUST ignore the display preferences.

This specification currently defines two possible values for the type property on the target object: "gadget" and "url". Each of which are illustrated below.

Preferring the gadget target: { "gadget" : "...", "url" : "...", ..., "preferredExperience" : { "target": { "type" : "gadget", "view" : "my-ee-view" }, "display": { ... } } }

Note that the preferred experience target's "type" property is only required if the preferred target is not obvious within the embedded experience. For instance, if the embedded experience only defines an IRI value for the "gadget" property, then the preferred target type is "gadget". However, if both the "url" and "gadget" properties are specified, as in the example above, the target type in the preferred experience MUST be specified. Containers MUST ignore the preferred experience if the target type value does not match the options specified within the Embedded Experience (e.g. target type specifies "url" but only a "gadget" IRI is provided, etc). When "type" equals "gadget", the additional properties on the target object are: Property Description view The preferred gadget view to render. If not specified, the value "embedded" is assumed. viewTarget Specifies where the container SHOULD render the view. Possible values are "TAB", "DIALOG", "MODALDIALOG", "FLOAT", and "SIDEBAR".

Preferring the url target: { "gadget" : "...", "url" : "...", ..., "preferredExperience" : { "target": { "type" : "url", "viewTarget" : "_new" }, "display": { ... } } }

When "type" equals "url", the additional properties on the target object are: Property Description viewTarget When specifying a URL, rather than being forced to render in an embedded view, the developer may wish to indicate to the container that the page be opened in a new browser window. In this case, the target properties for a URL match those that are defined by the HTML spec, e.g. "_blank". Implementations are free to define additional target types, each with their own properties. If a container encounters an embedded experience that uses an unknown or unsupported target type, the container MUST ignore the target preferences.

Embedded experiences allow content to be rendered on the page that user has not necessarily requested, therefore it needs to be secured. The container SHOULD only ever render content that the user has previously approved. This specification does not dictate how secure rendering of embedded experiences is to be performed.

Embedded experiences can be used within an Activity Streams document in order to provide a more interactive experience. Whereas the core properties of the Activity provide a textual description of the event, an included embedded experience can provide a direct representation of the object involved.

For instance, if a user uploads a collection of photos and creates a new photo album, an embedded experience can be used within the activity to provide a representation of the album itself: { "postedTime": "2011-02-10T15:04:55Z", "actor": { "objectType" : "person", "id": "tag:example.org,2011:martin", "displayName": "Martin Smith" }, "verb": "post", "object" : { "objectType":"collection", "objectTypes":["image"] "id": "http://example.org/albums/germany-2009", "url": "http://example.org/albums/germany-2009", }, "openSocial" : { "embed" : { "gadget" : "http://example.org/AlbumViewer.xml", "context" : { "albumName": "Germany 2009", "photoUrls": [ "http://examplephotos.com/3495/3925132517_5959dac775_t.jpg", "http://examplephotos.com/3629/3394799776_47676abb46_t.jpg", "http://examplephotos.com/4009/4413640211_715d924d9b_t.jpg", "http://examplephotos.com/2340/3528537244_d2fb037aba_t.jpg", "http://examplephotos.com/36/98407782_9c4c5866d1_t.jpg", "http://examplephotos.com/48/180544479_bb0d0f6559_t.jpg", "http://examplephotos.com/2668/3858018351_1e7b73c0b7_t.jpg" ] } } } }

As illustrated in the example, when included within an activity, the embedded experience MUST appear as the value of the "embed" property as a child of the "openSocial" property.

Numerous services send email notifications to your inbox in order to let you know something took place that you may be interested in. Most of the time however these notifications do not provide much useful information beyond a link back to the service's website. By leveraging embedded experiences, services can send an embedded representation of the object the notification is about, and allow the user to take action on the notification directly from within an embedded experiences enabled email client. Embedded experiences serialized as either JSON or XML can be embedded Multipart MIME encoded email messages. Such email messages MUST utilize the "multipart/alternative" MIME variant and MUST contain at least two MIME parts -- one containing regular content of the email message encoded as text/html content, and another containing the embedded experience content using either the "application/embed+json" or "application/embed+xml" MIME media type, respectively representing the JSON and XML serializations. Additional MIME parts MAY be included

For instance, From: notifications@socialnetwork.com To: johndoe@example.com Subject: Social Network: Mary Has Commented On Your Status MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="XXXXboundary text" Mary has commented on your status. --XXXXboundary text Content-Type: text/plain Mary has commeneted on your status. --XXXXboundary text Content-Type: text/html <html> <!-- HTML representation here --> </html> --XXXXboundary text Content-Type: application/embed+json { "gadget" : "http://www.socialnetwork.com/embedded/commentgadget.xml", "context" : 123 }

<static> gadgets.registerContextListener(listener) Description: Registers a function which will be called when the embedded experience gadget recieves its context. Parameters: Name Type Description listener Function A function that will be called whenever the embedded experience context is set for this gadget. The function should take one parameter which is a JSON object representing the embedded experience context from the gadget. See the embedded experiences data model description for more information on the context object. Example:

<script type="text/javascript"> gadgets.util.registerOnLoadHandler(function() { gadgets.ee.registerContextListener(function(context) { document.getElementById('contextData').innerHTML = gadgets.json.stringify(context); }); }); </script>

Discussion

Harvard University IBM UC Irvine Compaq/W3C Compaq W3C/MIT Xerox Microsoft W3C/MIT University of Edinburgh Oracle Corporation Commerce One Lotus Development Corporation Google Twitter Pownce Flickr ma.gnolia Google Twitter six apart Yedda ma.gnolia Jaiku TBD Yahoo ! Facebook Microsoft