OpenSocial Core Gadget Specification 2.5.1opensocial-and-gadgets-spec@googlegroups.com
General
OpenSocialsocial networkingRESTXMLExtensible Markup LanguageJSONJavaScript Object NotationAtomThe 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.
DiscussionContainers 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. DiscussionStandard 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. DiscussionIn 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. DiscussionA 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. DiscussionThe 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. DiscussionThis 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. DiscussionThis 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. DiscussionContainers 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.iogadgets.utilgadgets.Prefsgadgets.jsonGadgets 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 nameFeature versionJavaScript libraryrpc1.0.0gadgets.rpcflash1.0.0gadgets.flashskins1.0.0gadgets.skinsdynamic-height1.0.0
gadgets.window.adjustHeightand
gadgets.window.getViewportDimensionssettitle1.0.0gadgets.window.setTitleminimessage1.0.0gadgets.MiniMessagetabs1.0.0gadgets.TabProvides 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. DiscussionThe 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/LocaleSpecifies 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. DiscussionThis 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.DiscussionThere 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.
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.
EventDescriptionaddappEvent used to indicate the user has added the application. removeappEvent used to indicate the user has removed the application. appThis 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.
DiscussionWhen 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.
DiscussionWhen 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. DiscussionSupplies 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.DiscussionSupplies 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.
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:
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. DiscussionDiscussionCurrently, 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. DiscussionA 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. DiscussionThe 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.
DiscussionContains 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 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.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_CALLBACKoauth_request_token: gadgets.io.RequestParameters.OAUTH_REQUEST_TOKENoauth_request_token_secret: gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECREToauth_service_name: gadgets.io.RequestParameters.OAUTH_SERVICE_NAMEoauth2_scope: gadgets.io.RequestParameters.OAUTH2_SCOPE Discussionoauth_token_name: gadgets.io.RequestParameters.OAUTH_TOKEN_NAMEoauth_use_token: gadgets.io.RequestParameters.OAUTH_USE_TOKENrefresh_interval: gadgets.io.RequestParameters.REFRESH_INTERVALsign_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 preservedThe 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. DiscussionBoth 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. DiscussionVersions 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.
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 KeyDescriptionScopeMsgContains 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.
ViewParamsContains 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.PrefsContains 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.TopReserved variable used by
OpenSocial Templating to represent
the top level variables registered with the DataContextWithin content and templatesMyReserved variable used by
OpenSocial Templating to
hold local variables passed to the template instance.Within a template instanceCurReserved 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 loopContextVariable 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 loopViewerReserved for future use.N/AOwnerReserved for future use.N/AGadgetReserved for future use.N/AThe 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
LocalizationSee LocalizationCurrently, "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. DiscussionContainers 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.
DiscussionAs 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.
DiscussionOpenSocial'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:
NameTypeDescriptionmessageObjectThe message to log<static> gadgets.warn(message)Description: Log a warning message.Parameters:
NameTypeDescriptionmessageObjectThe message to log<static> gadgets.error(message)Description: Log an error message.Parameters:
NameTypeDescriptionmessageObjectThe message to log<static> gadgets.setLogLevel(logLevel)Description: Sets the log level threshold.Parameters:
NameTypeDescriptionlogLevelNumberNew 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:
NameTypeDescriptionfieldsObjectThe post fields you wish to encodeReturns:
TypeDescriptionStringThe 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:
NameTypeDescriptionurlStringThe URL to get the proxy URL foropt_paramsMap<String|String>Additional optional
parameters to
pass to the requestReturns:
TypeDescriptionStringThe 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.
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 ManagementIf 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.DiscussionReturns 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. DiscussionThe
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.NameTypeDescriptionurlStringThe URL where the content is locatedcallbackFunctionThe 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_paramsMap.<gadgets.io.RequestParameters|Object>Additional
request
parameters or
proxy request
parametersUsed 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:
NameTypeDescriptiontextStringThe string to transform into an object; usually the result of a
previous stringify callReturns:
TypeDescriptionObjectThe 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:
NameTypeDescriptionvObjectThe object to convertReturns:
TypeDescriptionStringThe JSON equivalentProvides 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:
gadgets.Prefs(opt_moduleId)Creates a new Prefs object.Parameters:
NameTypeDescriptionopt_moduleIdString | NumberAn optional parameter specifying the module ID to create prefs for; if
not provided, the default module ID is usedType: {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:
NameTypeDescriptionkeyStringThe preference to fetchReturns:
TypeDescriptionArray.<String>The preference; if not set, an empty arrayType: {Boolean} getBool(key)Description: Retrieves a preference as a boolean.Parameters:
NameTypeDescriptionkeyStringThe preference to fetchReturns:
TypeDescriptionBooleanThe preference; if not set, falseType: {String} getCountry()Description: Gets the current country, returned as ISO 3166-1 alpha-2
code.Returns:
TypeDescriptionStringThe country for this module instanceType: {Number} getFloat(key)Description: Retrieves a preference as a floating-point value.Parameters:
NameTypeDescriptionkeyStringThe preference to fetchReturns:
TypeDescriptionNumberThe preference; if not set, 0Type: {Number} getInt(key)Description: Retrieves a preference as an integer.Parameters:
NameTypeDescriptionkeyStringThe preference to fetchReturns:
TypeDescriptionNumberThe preference; if not set, 0Type: {String} getLang()Description: Gets the current language the gadget should use when
rendering, returned as a ISO 639-1 language code.Returns:
TypeDescriptionStringThe language for this module instanceType: {String | Number} getModuleId()Description: Gets the module ID for the current instance.Returns:
TypeDescriptionString | NumberThe module ID for this module instanceType: {String} getMsg(key)Description: Fetches an unformatted message.Parameters:
NameTypeDescriptionkeyStringThe message to fetchReturns:
TypeDescriptionStringThe messageType: {String} getString(key)Description: Retrieves a preference as a string.Parameters:
NameTypeDescriptionkeyStringThe preference to fetchReturns:
TypeDescriptionStringThe preference; if not set, an empty stringset(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:
NameTypeDescriptionkeyStringThe pref to storevalObjectThe values to storesetArray(key, val)Description: Stores an array preference. To use this call, the gadget
must require the feature setprefs.Parameters:
NameTypeDescriptionkeyStringThe pref to storevalArrayThe values to storeProvides 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:
NameTypeDescriptionstrStringThe string to escapeReturns:
TypeDescriptionStringThe 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:
NameTypeDescriptionfeatureStringThe feature to get parameters forReturns:
TypeDescriptionObjectThe parameters for the given feature, or null<static> Type: {Boolean} gadgets.util.hasFeature(feature)Description: Returns whether the specified feature is supported.Parameters:
NameTypeDescriptionfeatureStringThe feature to test forReturns:
TypeDescriptionBooleanTrue 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:
NameTypeDescriptioncallbackFunctionThe 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:
NameTypeDescriptiontextStringarbitrary text stringReturns:
TypeDescriptionStringa sanitized version that may include HTML tags, but will not execute
script.<static> Type: {String} gadgets.util.unescapeString(str)Description: Reverses escapeStringParameters:
NameTypeDescriptionstrStringThe string to unescape.Returns:
TypeDescriptionStringThe unescaped stringProvides 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:
NameTypeDescriptionurlTemplateA url template for a container viewenvironmentA set of named variables (for example, [OWNER | PATH | PARAMS |
NAME]) of type string.Returns:
TypeDescriptionStringA URL string<static> Type: {
gadgets.views.View }
gadgets.views.getCurrentView()Description: Returns the current view.Returns:
TypeDescriptiongadgets.views.ViewThe 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:
TypeDescriptionMap.<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:
TypeDescriptionMap<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. DiscussionParameters:
NameTypeDescriptionviewgadgets.views.ViewIf 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_paramsMap<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_ownerIdStringThe ID of the owner of the page to navigate to; defaults to the
current ownerDiscussion<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. DiscussionParameters:
NameTypeDescriptionresultCallbackfunctionCallback function to be called when the gadget closes.
The function will be called with the return value as a parameter.navigateCallbackfunctionCallback 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 ObjectThese are optional parameters which can be used to open gadgets.
The following parameters may be included in this object. opt_params:
NameTypeDescriptionview 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 ObjectView parameters for the view being rendered.coordinatesObject
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.
DiscussionParameters:
NameTypeDescriptionresultCallbackfunctionCallback function to be called when the gadget closes.
The function will be called with the return value as a parameter.navigateCallbackfunctionCallback 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).dataModelObjectThe 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 modelDiscussionopt_params ObjectThese are optional parameters which can be used to open gadgets.
The following parameters may be included in this object. opt_params:
NameTypeDescriptionviewTarget string The view that indicates where to open the gadget. For example,
tab, dialog or modaldialog.viewParams ObjectView parameters for the view being rendered.coordinatesObject
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. DiscussionParameters:
NameTypeDescriptionurlstringURL to a web page to open in a URL site in the container. (Note this should not be a URL to a gadget definition.)navigateCallbackfunctionCallback 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_coordinatesObject
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. DiscussionParameters:
NameTypeDescriptionopt_site_handlerObjectOptional 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. DiscussionParameters:
NameTypeDescriptionreturnValueObjectA 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:
NameTypeDescriptionenvironmentA set of named variables (for example, [OWNER | PATH | PARAMS |
NAME]) of type string.Returns:
TypeDescriptionStringA URL stringType: {
gadgets.views.ViewType |
String} getName()Description: Returns the name of this view.Returns:
TypeDescriptiongadgets.views.ViewType |
StringThe view name, usually specified as a gadgets.views.ViewTypeType: {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 applicationThe ID of the owner of the pageAn array of path steps`
Associative array or
array[param1,value1,param2,value2,...]Example
Here are some parameters:With those parameters, the two example URL template strings resolve to
the following URLs:See also:
bind()Returns:
TypeDescriptionStringA template that can be used to construct URLs that navigate to this
viewType: {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:
TypeDescriptionbooleanTrue if the gadget is the only visible gadget; otherwise, falseUsed 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'. DiscussionDiscussion
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.<static> DataContext opensocial.data.getContext()Gets the DataContext associated with the
gadget.None.TypeDescriptionDataContextThe 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.NameTypeDescriptionkeyStringThe key for the data object to be retrievedTypeDescriptionObjectThe 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..NameTypeDescriptionkeyStringThe key to use to refer to this datavalueString | ObjectThe 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.NameTypeDescriptiondataSetsObjectan object whose property names are data set keys, and whose
properties are actual data setsNone.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.NameTypeDescriptionkeysString | Array>String<>The key or list of keys to add the listener tocallbackFunctionA 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 outInput and output parameters match JSON-RPC calls 1:1 and share
documentationData 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 batchBatch 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 namespaceA 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.NameTypeDescriptioncallbackFunctionA 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. DiscussionNoneMultiple service requests can be combined into a single batch request using
the following methods:osapi.BatchRequest osapi.newBatch()Creates a new batch request.NoneTypeDescriptionosapi.BatchRequestA 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()).NameTypeDescriptionkeyStringA key to access the result of the given request from the parameter
sent to the callback function.requestosapi.RequestA request to add to the batch.TypeDescriptionosapi.BatchRequestA 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.NameTypeDescriptioncallbackFunctionA 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.NoneThe 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.
Application Error for Single Request
In this case, a top-level error object is set. Note, this is just
like the previous error case.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 usedas a key to batch.add()as a property of a JSON RPC batch response item.
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.NameTypeDescriptionparamsHTTP-Request-ParametersA JavaScript representation of HTTP-Request-Parameters.TypeDescriptionosapi.RequestA request to retrieve information from an arbitrary URL.<static> osapi.Request osapi.http.get(params)Creates a GET request to an arbitrary URL.NameTypeDescriptionparamsHTTP-Request-ParametersA JavaScript representation of HTTP-Request-Parameters.TypeDescriptionosapi.RequestA request to retrieve information from an arbitrary URL.<static> osapi.Request osapi.http.post(params)Creates a POST request to an arbitrary URL.NameTypeDescriptionparamsHTTP-Request-ParametersA 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.TypeDescriptionosapi.RequestA request to POST information to an arbitrary URL.<static> osapi.Request osapi.http.put(params)Creates a PUT request to an arbitrary URL.NameTypeDescriptionparamsHTTP-Request-ParametersA 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.TypeDescriptionosapi.RequestA request to PUT information to an arbitrary URL.<static> osapi.Request osapi.http.delete(params)Creates a DELETE request to an arbitrary URL.NameTypeDescriptionparamsHTTP-Request-ParametersA JavaScript representation of HTTP-Request-Parameters.TypeDescriptionosapi.RequestA request to delete information at an arbitrary URL.<static> osapi.Request osapi.http.patch(params)Creates a PATCH request to an arbitrary URL.NameTypeDescriptionparamsHTTP-Request-ParametersA JavaScript representation of HTTP-Request-Parameters.TypeDescriptionosapi.RequestA request to patch information at an arbitrary URL.DiscussionData 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.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:
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. DiscussionRequest 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.
NameTypeDescriptionkeyStringA key for accessing the response.methodStringThe name of the service and method to call.A JSON object representing the Return-Object specified by the service method.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:
NameTypeDescriptionkeyStringA key for accessing the response.methodStringHTTP 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.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.
Declare a literal value or result of an EL statement under a different key.The following attributes are supported.
NameTypeDescriptionkeyStringA key for accessing the value. REQUIREDvalueStringLiteral 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.
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 stringThe 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
The below places the result of the EL statement ${1+1} under the key "onePlusOne".
The below creates a JSON object and places it under the key "mockViewer"
Data pipelining tags can be top level elements in the <Content>
section of a gadget using Proxied 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.
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@paramsAn implementation MUST evaluate dynamic properties for these
attributes and MUST NOT evaluate dynamic properties for attributes not on
this list.
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".
DiscussionDiscussionDiscussionDiscussionDiscussionDiscussionThe 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 topGadget 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 toolbarAction 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:AttributeDescriptionRequired/OptionalidUnique identifierRequiredlabelText string to display for this actionRequiredpathThe container-defined location for this action, as described in Action Paths. Example: path=container/menus/EditOptional*dataTypeThe Open Social Data type, as described in Action Data Types, with which to associate this action. Example: opensocial.PersonOptional*tooltipTooltip to display on hovering over an iconOptionaliconPath to image icon. Absolute URL or URL relative to gadget URLOptionaliconSizeSee related issue on icon size for more information.OptionaliconOffsetx and y coordinates of icon if using image spritesOptionalviewThe view ID the gadget should navigate to when the action is invoked.OptionalviewTargetThe target area to render the view.OptionalurlSimple 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:
PathDescriptioncontainer/navigationLinksThe top level navigation links, providing links to related services.container/menusThe top level menu. For example to add a new action to File->New->Presentation path="container/menu/File/New." container/toolbarsTop level toolbars owned by the container. For example to add a new action to Toolbar in a docs editor.gadget/menuThe 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.Personopensocial.Messageopensocial.Activityopensocial.GroupBelow is an example of the declarative contribution in a gadget's metadata and the javascript code needed to bind action ID to callback function:<static> gadgets.actions.addAction(action)Description: Adds the specified action(s) to the container.Parameters:NameTypeDescriptionactionObjectThe action to be added to the containerExample 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:NameTypeDescriptionactionObjectThe action to be updated in the containerExample 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 containerParameters:NameTypeDescriptionidStringThe 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 functionParameters:NameTypeDescriptionpathStringThe String representation of the path to the actionscallbackFunctionA 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:NameTypeDescriptiondataTypeStringThe String representation of an OpenSocial data type.callbackFunctionA 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:NameTypeDescriptionactionIdStringThe id of the action to execute.opt_selectionObjectThe 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:NameTypeDescriptionshowActionsHandlerFunctionThe 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:NameTypeDescriptionactionObjsObject[]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:NameTypeDescriptionhideActionsHandlerFunctionThe 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:NameTypeDescriptionactionObjsObject[]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:
TypeDescriptionBooleanWhether 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:
NameTypeDescriptionswfUrlStringSWF URLswfContainerString | ObjectThe ID or object reference of an existing HTML container elementswfVersionNumberMinimum Flash Player version requiredopt_paramsObjectAn optional object that may contain any valid HTML parameter; all
attributes will be passed through to the Flash movie on creationReturns:
TypeDescriptionBooleanWhether the function call completes successfully<static> Type: {Number} gadgets.flash.getMajorVersion()Description: Detects Flash Player and its major version.Returns:
TypeDescriptionNumberThe major version of Flash Player or 0 if Flash is not supportedMiniMessage 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:
NameTypeDescriptionopt_moduleIdStringOptional module IDopt_containerHTMLElementOptional HTML container element where mini-messages will appearType: {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:
NameTypeDescriptionmessageString | ObjectThe message as an HTML string or DOM elementopt_callbackFunctionOptional 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:
TypeDescriptionHTMLElementHTML element of the created messageType: {HTMLElement} createStaticMessage(message)Description: Creates a static message that can only be dismissed
programmatically (by calling dismissMessage()).Parameters:
NameTypeDescriptionmessageString | ObjectThe message as an HTML string or DOM elementReturns:
TypeDescriptionHTMLElementHTML element of the created messageType: {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:
NameTypeDescriptionmessageString | ObjectThe message as an HTML string or DOM elementsecondsnumberNumber of seconds to wait before dismissing the messageopt_callbackFunctionOptional 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:
TypeDescriptionHTMLElementHTML element of the created messagedismissMessage(message)Description: Dismisses the specified message.Parameters:
NameTypeDescriptionmessageHTMLElementHTML element of the message to removeOAuth 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 linka "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:
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:
NameTypeDescriptiondestinationStringTarget URL for the popup window.windowOptionsStringOptions for window.open, used to specify look and feel of the
window.openCallbackFunctionFunction to call when the window is opened.closeCallbackFunctionFunction to call when the window is closed.Type: {Function} createOpenerOnClick()Returns:
TypeDescriptionFunctionan onclick handler for the "open the approval window" link.Type: {Function} createApprovedOnClick()Returns:
TypeDescriptionFunctionan 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:
NameTypeDescriptiontargetIdStringID of the RPC service provider; empty if calling the parent
containerserviceNameStringService name to callcallbackFunction|nullCallback 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:
NameTypeDescriptionparamsgadgets.rpc.ConfigParametersParameters 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:
NameTypeDescriptionreceiverIdStringID of the RPC service provider; empty if calling the parent
container
Returns:
TypeDescriptionString|nullIf 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:
NameTypeDescriptionserviceNameStringService name to registerhandlerFunctionService 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:
NameTypeDescriptionhandlerFunctionService handler<static> gadgets.rpc.unregister(serviceName)Description: Unregisters an RPC service.Parameters:
NameTypeDescriptionserviceNameStringService name to unregister<static> gadgets.rpc.unregisterDefault()Description: Unregisters the default service handler. Future unknown
remote procedure calls will fail silently.gadgets.rpc.ConfigParametersDescription: Object used to hold the parameters into the config method, supports the following properties: NameTypeDescriptionsecurityCallbackfunctionsecurityCallback: 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 timegadgets.rpc.FRAME_PHISH - receiver's iframe may have been maliciously redirected to a new locationgadgets.rpc.FORGED_MSG - RPC detected a possibly forged messageDiscussionThe 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 listselected activity in an activity streamselected item in a user's profileSelection 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:
NameTypeDescriptionselectionArrayObject[]Array of object(s) to be set as selected, with attributes defined in table below.Each selection object must have the following attributes:
NameTypeDescriptiontypeStringOpen Social data type, as specified in the Social Data SpecificationdataObjectObjectObject 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:
TypeDescriptionObject[]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. DiscussionNameTypeDescriptioncallbackFunctionThe callback function that is called for the specified selection event.<static> gadgets.selection.removeListener(callback)Description: Unregisters the callback function previously registered by addListener. DiscussionParameters:
NameTypeDescriptioncallbackFunctionThe 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:
NameTypeDescriptionpropertyKeyStringThe key to get data for; keys are defined in
gadgets.skins.PropertyReturns:
TypeDescriptionStringThe dataAll 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:
TabSetType: {Function} getCallback()Description: Returns the callback function that is executed when the
tab is selected.Returns:
TypeDescriptionFunctionThe callback function of the tabType: {HTMLElement} getContentContainer()Description: Returns the HTML element where the tab content is
rendered.Returns:
TypeDescriptionHTMLElementThe HTML element of the content containerType: {Number} getIndex()Description: Returns the tab's index.Returns:
TypeDescriptionNumberThe tab's indexType: {String} getName()Description: Returns the label of the tab as a string (may contain
HTML).Returns:
TypeDescriptionStringThe label of the tabType: {HTMLElement} getNameContainer()Description: Returns the HTML element that contains the tab's
label.Returns:
TypeDescriptionHTMLElementThe HTML element of the tab's labelA class gadgets can use to make tabs.gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)Creates a new TabSet objectParameters:
NameTypeDescriptionopt_moduleIdStringOptional suffix for the ID of tab containeropt_defaultTabStringOptional 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 defaultopt_containerHTMLElementThe HTML element to contain the tabs; if omitted, a new div element is
created and inserted at the very topType: {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:
NameTypeDescriptiontabNameStringLabel of the tab to createopt_paramsObjectOptional parameter objectReturns:
TypeDescriptionStringDOM id of the tab containeralignTabs(align, opt_offset)Description: Sets the alignment of tabs. Tabs are center-aligned by
default.Parameters:
NameTypeDescriptionalignString'left', 'center', or 'right'opt_offsetNumberOptional parameter to set the number of pixels to offset tabs from
the left or right edge; the default value is 3pxdisplayTabs(display)Description: Shows or hides tabs and all associated content.Parameters:
NameTypeDescriptiondisplayBooleanTrue to show tabs; false to hide tabsType: {HTMLElement} getHeaderContainer()Description: Returns the tab headers container element.Returns:
TypeDescriptionHTMLElementThe tab headers container elementType: {
gadgets.Tab } getSelectedTab()Description: Returns the currently selected tab object.Returns:
TypeDescriptiongadgets.TabThe currently selected tab objectType: {Array.<gadgets.Tab>} getTabs()Description: Returns an array of all existing tab objects.Returns:
TypeDescriptionArray.<gadgets.Tab>Array of all existing tab objectsremoveTab(tabIndex)Description: Removes a tab at tabIndex and all of its associated
content.Parameters:
NameTypeDescriptiontabIndexNumberIndex of the tab to removesetSelectedTab(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:
NameTypeDescriptiontabIndexNumberIndex of the tab to selectswapTabs(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:
NameTypeDescriptiontabIndex1NumberIndex of the first tab to swaptabIndex2NumberIndex of the secnod tab to swapProvides 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:
NameTypeDescriptionopt_heightNumberAn optional preferred height in pixels; If not specified, will
attempt to fit the gadget to its contentDiscussion<static> gadgets.window.adjustWidth(opt_width)Description: Adjusts the gadget width.Parameters:
NameTypeDescriptionopt_widthNumberAn optional preferred width in pixels; If not specified, will attempt to fit the gadget to its contentDiscussion<static> gadgets.window.adjustSize(opt_height, opt_width)Description: Adjusts the gadget size.Parameters:
NameTypeDescriptionopt_heightNumberAn optional preferred height in pixels; If not specified, will attempt to fit the gadget to its contentopt_widthNumberAn 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:
TypeDescriptionObjectAn 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. DiscussionParameter:
NameTypeDescriptionresultCallbackfunctionCallback function will be called with the return value as a parameter.<static> gadgets.window.setTitle(title)Description: Sets the gadget title.Parameters:
NameTypeDescriptiontitleStringThe preferred titleThe 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 valuesRegister an onLoad handlerThe 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:
NameTypeDescriptiontopicStringA 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:
NameTypeDescriptiontopicStringA 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.callbackStringA 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.scopeobject 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.onCompleteCallbackfunction 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:
TypeDescriptionStringAn opaque subscription identifier. This identifier is an arbitrary
ID string that is unique within this Hub instanceSee the OpenAjax Hub documentation for
more informationunsubscribe(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:
NameTypeDescriptionsubscriptionIdStringThe 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.AttributeTypeUsageDescriptionnameStringRequired
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 @nametypeStringOptionalType name for the event's payload data. When not specificed, any
type wil be allowed. See Event Data Types.titleStringOptionalTitle 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.publishbooleanOptionalIndicates if the gadget publishes events on this topic. The default value is "false".subscribebooleanOptionalIndicates if the gadget subscribes to events that are published on this topic. The default value is "false".descriptionStringOptional
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."aboutUrlStringOptional
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.
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 NameCommentsstringECMAScipt stringnumberECMAScipt number booleanECMAScipt boolean arrayECMAScipt 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 nulllength *Any CSS length value Howard 2009.11.10: CSS version?color *Any CSS color valueidID value - probably not useful for OpenSocial Gadgets, but might as well keep the two specs in syncclass *zero of more CSS class names, separated by spacesstyle *a string that could be used as value for a 'style' attributeurlA URL Howard 2009.11.09: Do we want "uri" also?htmlA 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].emailA string that represents an e-mail address.personA string that holds a person's name.postalcodeA string that represents a postal code.phoneA 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:
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.
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.
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.
To make this work, a string pattern needs to be passed in, like
what is done below:
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 yearW: Week of Month.D: Day of year.F: Day of Week in Month.g: Modified Julian dayMany 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.
SymbolLocationLocalized?Meaning0NumberYesDigit#NumberYesDigit, zero shows as absent..NumberYesDecimal separator or monetary decimal separator.-NumberYesMinus sign,NumberYesGrouping SeparatorENumberYesSeparates mantizza and exponent in scientific notation. Need not be
quoted in prefix or suffix.;Subpattern boundaryYesSeparates positive and negative subpatterns.%Prefix or suffixYesMultiply by 100 and show as percentage.\u2030Prefix or suffixYesMultiply by 1000 and show as per mile.¤ (\u00A4)Prefix or suffixNoCurrency 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 suffixNoUsed 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".
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.
Parameters:
NameTypeDescriptionpatternstring/numberString to specify patterns or Number used to reference predefined
pattern that a date should be formatted into.dateDateDate object being formatted.Returns:
TypeDescriptionstringstring 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.
Parameters:
NameTypeDescriptionpatternstring/numberString to specify patterns or Number used to reference predefined
pattern that a number should be formatted into.valuenumberThe number being formatted.opt_currencyCodestringoptional 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:
TypeDescriptionstringThe 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.
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.
Similar to the formatting functions, a predefined pattern could
also be passed in as the first parameter.
Parameters:
NameTypeDescriptionpatternstring/numberString to specify patterns or Number used to reference predefined
pattern that a date should be parsed from.textstringThe string that need to be parsed.startnumberThe character position in "text" where parse begins.dateDateThe date object that will hold parsed value.Returns:
TypeDescriptionnumberThe 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.
Parameters:
NameTypeDescriptionpatternstring/numberString to specify patterns or Number used to reference predefined
pattern that a number should be parsed from.textstringinput text being parsed.opt_posArrayoptional one element array that holds position information. It tells
from where parse should begin. Upon return, it holds parse stop
position.opt_currencyCodestringoptional 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:
TypeDescriptionnumberParsed 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 NameDescriptiondescription
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.
DiscussionEmbedded 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:PropertyDescriptioncontextIf 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".gadgetA URL to an OpenSocial Gadget definition document that defines the
gadget to be embedded.preferredExperienceAn optional collection of properties that describe the preferred
way the creator of the embedded experience would like containers to
render the content.previewImageAn 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.urlA 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.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.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.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.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.DiscussionWhile 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:PropertyDescriptionidThe 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.typeThe type of OpenSocial Data object containing the embedded
experience.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.PropertyDescriptionobjectReferenceThe JSON representation of the OpenSocial Data object
containing the embedded experience. This OpenSocial Data object
MUST contain the complete embedded experience data model.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.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.PropertyDescriptiondisplayDescribes 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.targetDescribes 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.When "type" equals "text", the additional properties on the
display object are:PropertyDescriptionlabelA required String that provides the text to display with the hyperlink.titleOptional 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. When "type" equals "image", the additional properties on the
display object are:PropertyDescriptionaltTextSpecifies optional, alternative text to display if the image cannot
be displayed. Equivalent to the HTML image tags alt attribute.heightSpecifies the preferred display height of the image in pixels.widthSpecifies 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.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:PropertyDescriptionviewThe preferred gadget view to render. If not specified, the value "embedded" is assumed.viewTargetSpecifies where the container SHOULD render the view. Possible
values are "TAB", "DIALOG", "MODALDIALOG", "FLOAT", and "SIDEBAR".When "type" equals "url", the additional properties on the
target object are:PropertyDescriptionviewTargetWhen 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.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 <static> gadgets.registerContextListener(listener)Description: Registers a function which will be called when the
embedded experience gadget recieves its context.Parameters:
NameTypeDescriptionlistenerFunctionA 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:DiscussionProposal for View Level Features in OS 2.0Propose fix for the 1.1 XSD schema in the core server specRemoving Quirks ModeSigning of URL Content requestsProposal for Simple Gadget format support in OS 2.0 specVariable substitution standardized on ELMessageBundle example missing from Core Gadget spec localization sectionAdd support for additional viewsView Enhancements To Support Opening Of Gadgets and URLsDeclarative Actions and Selection Proposal for OpenSearch Gadget ContributionsEmbedded Experiencesgadgets.window.adjustWidthLifecycle events section improperly removed in 1.xMove security policy to core gadgetsAdd 'alias' to HTTP RequestSpecification CleanupOAuth 2.0 SupportOAuth 2.0 service configuration in ModulePrefsCore Gadget Specification missing Content/@authz attribute in XSDEnhance open-views and CommonContainer apis to allow for opening gadgets/ees/views at specific locationsMissing ExternalServices tag in the gadget schemaAdd additional fields to the module section to support use in market placesNo explanation of callback function for osapi.http methodsgadgets.views.openEmbeddedExperience should take the data model as a String or an ObjectThe description of the opt_params parameter for requestNavigateTo appears to be wrongYou have to write a large amount of code to access the embedded experience contextCore Gadget Section 8 - Versioning Refers To The Wrong Version Of The SpecGadget XML Schema defines a scrolling attribute for content elementsError in selection specKey words for use in RFCs to Indicate Requirement LevelsHarvard UniversityReserved Top Level DNS NamesIBMHypertext Transfer Protocol -- HTTP/1.1UC IrvineCompaq/W3CCompaqW3C/MITXeroxMicrosoftW3C/MITCaja ProjectOpenSocial Templating SpecificationOpenSocial Templating SpecificationXML Schema Part 1: Structures Second EditionUniversity of EdinburghOracle CorporationCommerce OneLotus Development CorporationOAuth Core 1.0GoogleTwitterPownceFlickrma.gnoliaGoogleTwittersix apartYeddama.gnoliaJaikuOpenSocial Core API Server SpecificationOpenSocial Social API Server SpecificationJava Server Pages Expression LanguageOpenAjax Hub 2.0TBDThe OAuth 2.0 Authorization ProtocolYahoo !FacebookMicrosoft