Core Container Specification 2.0.1 INCUBATINGopensocial-and-gadgets-spec@googlegroups.com
General
OpenSocialCore ContainerAll content in this specification of OpenSocial is considered to be incubating. It is provided as a
guide to the developers wishing to implement this specification. The API defined in this specification
is provisional, and while the community will work to keep the API stable, it may change based on
implementation experience, additional requirements, or other factors.
A web-based software component based on HTML, CSS and JavaScript. It allows
developers to write modularized, reusable web applications that work
anywhere on the web without modification.
A context into which a gadget is embedded into. This is typically an HTML
page, served by an arbitrary web-service, viewable by a browser.
A security mechanism to allow gadgets to make secure connections to server
end points for data that may be valid only for the current user's context.
This commonly appears as a query/fragment param st= in the iframe URL.
Common container is a lightweight gadget-and-container framework, based on
JavaScript and server-driven end-point. Its mission is to simplify container
and gadget integration model. It allow container developers to easily
transform their page into a gadget-compliant container that can properly
embed gadgets rendered by a gadget service. It does not address
container-specific business-logic and layout.
To be a gadget-compliant container, a container MUST be able to satisfy
requirements defined in this section.
The framework is installed in a container page by a script tag, with its
source pointing to the common container JS. This also provides a near-zero
barrier to entry for new container clients.
The framework lives in the container page to provide API to container
developers to navigate/open and close gadgets on the page, in a way that
ensures opened gadgets continue to work, until they are closed.
Sets up container for gadget-to-container, container-to-gadget and
gadget-to-gadget communication via gadgets.rpc. This involves setting up
relay files and registering callbacks/hooks, to ensure the wiring is
all setup to receive all gadgets.rpc mediated commands. Increasing height
of gadget is a common example.
The framework allows container developers to track the latency times
required to do a gadget navigation. This involves starting a timer when a
gadget navigation is requested and stopping the timer when a gadget is
fully rendered. Latency times can be broadcasted to the container for
container-specific consumption.
Its lifespan starts from time when it is instantiated to time when the
page is navigated away. AJAX-y pages will tend to have longer lifespan.
To avoid expired security tokens, the framework will fetch for new tokens
at a regular interval and have the new token pushed to the gadget that
requires tokens to be updated.
Changes in a gadget render may require simultaneous change on the container
implementation. This framework will allow new container changes to be
picked up at the same time when a gadget render service is updated,
avoiding version-skew. Additionally, it will also promote all common-
container-enabled pages to become updated at the same time.
Namespace for top level container functions.
This represents the container. This provides top-most-level set of APIs for
container developers, to accomplish functionalities defined in
GadgetNavigation and more.
Internally, this manages work required to ensure that navigated gadgets
continue to work. There MUST be not more than one instance of this in a
page, due to usage of global resources and possible race conditions.
container.Container(opt_config)Constructs the container object.Parameters:
NameTypeDescriptionopt_configObject
A bag-style JSON object with configuration parameters. See
container.Container.preloadGadget(gadgetUrl, opt_callback)Description: Pre-load one gadget metadata information.
See also:
preloadGadgetsParameters:
NameTypeDescriptiongadgetUrlStringA URL to the gadget definition.opt_callbackfunction
A callback function to be called when the gadget metdata is returned.
The callback function should have one parameter called response.
container.Container.preloadGadgets(gadgetUrls, opt_callback)
Pre-load gadgets metadata information.
This will not render the gadget.
Parameters:
NameTypeDescriptiongadgetUrlsArrayGadget URLs to preload.opt_callbackfunction
A callback function to be called when the gadget metdata is returned.
The callback function should have one parameter called response.
container.Container.unloadGadget(gadgetUrl)
Unloads a single gadget.
Parameters:
NameTypeDescriptiongadgetUrlStringGadget URL to unload.container.Container.unloadGadgets(gadgetUrls)
Unload preloaded gadgets.
Parameters:
NameTypeDescriptiongadgetUrlsArrayGadget URLs to unload.container.Container.navigateGadget(site, gadgetUrl, viewParams,
renderParams, opt_callback)
Renders (navigates) to the specified gadget.
Parameters:
NameTypeDescriptionsitecontainer.GadgetSiteThe gadget site to use to render the gadgetgadgetUrlstringThe gadget URL to render (navigate) to.viewParamsObject
View parameters to pass to the view being specified in the
renderParams.
renderParamsObject
Contains parameters on how the container wants to render this
gadget see .
opt_callbackfunctionCallback function called after the gadget has been rendered.container.Container.closeGadget(site)
Closes the gadget in the site.
Parameters:
NameTypeDescriptionsitecontainer.GadgetSiteThe site containing the gadget to close.container.Container.getGadgetMetadatat(gadgetUrl, callback)
Gets the metadata for a gadget.
Parameters:
NameTypeDescriptiongadgetUrlcontainer.GadgetSite
The URL pointing to the gadget definition to get the metadta
for.
callbackfunction
Function called when the metadata has been retrieved.
The callback function should have a single response parameter.
container.Container.rpcRegister(service, callback)
Registers a function to call for a specified RPC service.
Parameters:
NameTypeDescriptionserviceStringThe name of the RPC service.callbackfunctionThe function to call when the service is envoked.Discussioncontainer.Container.addGadgetLifecycleCallback(lifeCycleCallback)
Add a callback object to be called when a gadget is added, navigated to or closed.
Parameters:
NameTypeDescriptionlifeCycleCallbackfunction
The callback function to call when the gadget lifecycle changes. Needs to have preloaded(metadataResponse),
navigated(gadgetSite), closed(gadgetSite) and unloaded(gadgetURL) methods to react to lifecycle events
These are invoked(respectively) by the preloadGadgets,
navigateGadget, and
closeGadget and
unloadGadgets container methods. Containers may also
choose to call some of the
gadget lifecycle events
in the core gadget spec in order to inform the gadget host
that the gadget has been added/removed from the container.
container.Container.removeGadgetLifecycleCallback(lifeCycleCallback)
Remove a lifecycle callback object from the container's registry.
Parameters:
NameTypeDescriptionlifeCycleCallbackfunction
remove a lifecycle callback previously registered with the container
This represent the gadget context. Container developers refer a gadget as
a GadgetSite.
container.GadgetSite.setHeight(height)
Sets the height of the gadget site.
Parameters:
NameTypeDescriptionheightNumber
Value to set the gadget site height to.
container.GadgetSite.setWidth(width)
Sets the width of the gadget site.
Parameters:
NameTypeDescriptionwidthNumber
Value to set the gadget site width to.
container.GadgetSite.rpcCall(serviceName, callback, var_args)
Sends the RPC call to the current/visible gadget.
Parameters:
NameTypeDescriptionserviceNameString
The name of the service to call.
callbackfunction
Function to call upon RPC completion.
var_args{....number}
Arguments to pass to the recipient.
Configuring common container is done at instantiation, by passing a
bag-style JSON, with keys defined under container.ContainerConfig.
All of these are optional.
These affect all gadgets renders, unless overridden by
GadgetRenderConfiguration.
Allow gadgets to render in unspecified view. Default is true.
Whether cajole mode is turned on. Default is true.
Whether debug mode is turned on. Default is false.
Whether test mode is turned on. Default is false.
These are not gadget render related.
The debug param name to look for in container URL for per-request debugging.
Security token refresh interval (in ms) for debugging. Default is 30 * 60 * 1000.
Globally-defined callback function upon gadget navigation. Useful to
broadcast timing and stat information back to container.
Provide server reference time for preloaded data. This time is used
instead of each response time in order to support server caching of results.
Contains preloaded hash of gadgets metadata.
Contains preloaded hash of gadgets tokens.
A callback function that will return the correct language locale part to use when
asking the server to render a gadget or when asking the server for 1 or more
gadget's metadata.
A callback function that will return the correct country locale part to use when
asking the server to render a gadget or when asking the server for 1 or more
gadget's metadata.
A callback function that will return the preferences to use when asking the server
to render a gadget or when asking the server for gadget metadata. The format
returned here should be the same as is required for USER_PREFS
. It will be
passed the following parameters:
NameTypeDescriptionsiteIdstringGadget Site IDgadgetUrlstringGadget Url
A callback function that will persist the preferences. It will be passed the
following parameters:
NameTypeDescriptionsiteIdstringGadget Site IDgadgetUrlstringGadget UrlpreferencesobjectPreferences to persist. The format supplied here will be the same as is
required for USER_PREFS .
Requesting for a gadget render with specifics (like view, visual appearance
and debug mode) can be made by passing a bag-style JSON, with keys defined
under container.RenderParam into
container.Container.prototype.navigateGadget().
All of these are optional.
Allow gadgets to render in unspecified view
Whether to enable cajole mode.
Style class to associate to iframe.
Whether to turn on debugging mode. Default is false.
The starting gadget iframe height (in pixels). Default is 200.
Whether to disable cache.
Whether to enable test mode. Default is false.
The gadget user prefs to render with. If undefined, and GET_PREFERENCES
has been provided when configuring
the container, the container should use GET_PREFERENCES to obtain preferences.
The view of gadget to render.
The starting gadget iframe width (in pixels). Default is 320.
Discussioncontainer.Container.ee.navigate(element, dataModel, renderParams)
Renders an embedded experience from the given embedded experience
data model.
Parameters:
NameTypeDescriptionelementHTMLElementThe HTML DOM element in which to render the embedded experience.dataModelObjectThe embedded experience data model.renderParamsObjectThe render params to use when rendering this embedded experience.opt_callbackfunctionCalled when the embedded experience has been rendered. The
function takes in two parameters, the site and the metadata.container.Container.ee.close(site)
Closes a site containing an embedded experience. This can close
a gadget site or a
URL site.
Parameters:
NameTypeDescriptionsitecontainer.GadgetSite | container.UrlSiteThe site to close.
Render params can be passed to the navigate function
() to configure how
the embedded experience should render.
All of these are optional.
A bag of JSON style parameters from
A bag of JSON style parameters which can specify height and width
for a URL embedded experience.
A bag of JSON style parameters which will be passed to the
embedded experience view if the embedded experience is a gadget.
Discussion
The container APIs for OpenSearch allow containers to access
OpenSearch description information contained within the
gadgets which it has loaded or is currently showing on the
page. Containers can use this information in order to allow
users of the container to search accross multiple gadgets
at the same time.
Type: {Array} container.Container.opensearch.getOpenSearchURLs(mimeType)
Description: Retrieves all gadget search URLs based on the
data type parameter. Containers may support zero or more of
the data types.
Parameters:
NameTypeDescriptionmimeTypeString
The type of OpenSearch URLs you want to be returned.
This should be a valid MIME type.
Returns:
TypeDescriptionArray
An array of name and URL pairs, where name
is the display name, and URL is the OpenSearch template
URL.
Type: {Array} container.Container.opensearch.getOpenSearchDescriptions(mimeType)
Description: Retrieves all OpenSearch descriptions from gadgets
which have OpenSearch feature in their gadget definition.
Parameters:
NameTypeDescriptionmimeTypeString
The MIME for the OpenSearch template URL within the
OpenSearch description.
Returns:
TypeDescriptionArray
An array of OpenSearch definitions. The
definitions should be the JSON representation of the
OpenSearch definition represented in XML.
Example Array Returned By container.opensearch.getOpenSearchDesription
container.Container.opensearch.addOpenSearchCallback(callback)
Description: Registers a callback function to be called when a new gadget
containing an opensearch feature is preloaded by the container, or when an existing gadget with an opensearch feature is closed.
Parameters:
NameTypeDescriptioncallbackfunction(Map descriptions, boolean added)
A callback function to be called when a new gadget
containing a valid opensearch feature is preloaded
by the container, or a gadget containing a valid opensearch feature is closed.
descriptions: gadget url as a key, open search description as value.
added: true if gadget is added, false if gadget is removed.
container.Container.opensearch.removeOpenSearchCallback(callback)
Description: Un-registers a callback function registered via
addOpenSearchCallBack()
Parameters:
NameTypeDescriptioncallbackfunction
The callback function to be unregistered
DiscussionThe actions feature, as described in the gadgets.actions overview,
allows gadgets to contribute actions to various parts of a container's user interface. The container can then render the actions consistently
in context menus or action areas associated with particular data types, in global contribution areas (ie. navigation links at the top),
or as part of the action areas of each gadget's chrome (ie. gadget's dropdown menu). The container can access actions either by retrieving an action from the registry based on a specified identifier, or retrieving all actions
by data type or path specification, via the four getter functions below:
getAction(),
getAllAction(),
getActionsByType(), and
getActionsByPath(). In addition, the container must
register a show actions function in order
to render the actions in its UI, as well as a hide actions function
to remove the actions from its UI when a contributing gadget has been unloaded.
The container must register a navigate gadget handler
to render and navigate to the gadget upon action execution if the gadget has not yet been rendered.
container.Container.actions.getAction(actionId)Description: Returns the action object (as described in the
gadgets specification)
associated with the specified id.Returns:TypeDescriptionObjectAn action object currently in the registry with the specified ID.container.Container.actions.getAllActions()Description: Returns an array of action objects (as described in the
gadgets specification)
currently in the registry.Returns:TypeDescriptionObject[]An array of action objects currently in the registry.container.Container.actions.getActionsByPath(path)Description: Returns an array of action objects bound to a specific path. For gadget-specific contributions
(ie. actions that are to be added to a gadget's chrome), this API returns actions with a global identifier for the path.
For example, if a gadget contributes an action to the path "gadget/menu/myaction1", this function would return
an action with path "<gadgetID>/gadget/menu/myaction1" where <gadgetID> represents the specific gadget site in the container's UI.Parameters:NameTypeDescriptionpathStringText representation of a path to an action.Returns:TypeDescriptionObject[]Array of action objects associated with the given path.container.Container.actions.getActionsByObject(dataType)Description: Returns an array of action objects bound to a specific data type.Parameters:NameTypeDescriptiondataTypeStringOpen Social data type.Returns:TypeDescriptionObject[]Array of action objects associated with the given data type.container.Container.actions.runAction(actionId, opt_selection)Description: Renders the gadget if it has not yet been rendered, and
executes the action callback associated with the specified actionId in
the context of the gadget. The container should call this function
whenever an action is triggered by the user.Parameters:NameTypeDescriptionactionIdStringIdentifier for the action to be executed.opt_selectionObjectThe current selection. This is an optional parameter.container.Container.actions.registerShowActionsHanlder(showActionsHandler)Description: Registers a function to render actions in the container.
The function will be called when the container preloads a gadget(s) containing action contributions,
as well as when a gadget programmatically adds an action via the gadgets API. At this time, the container may
contribute the action to its UI.Parameters:NameTypeDescriptionshowActionHandlerFunctionThe container'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 using your containers JS library
// to do the invocation of the action, call the following API:
// container.Container.actions.runAction(actionObject[0].id);
}
container.Container.actions.registerShowActionsHandler(myShowActionsHandler);
container.Container.actions.registerHideActionsHanlder(hideActionsHandler)Description: Registers a function to remove actions from the container.
The function will be called when the container unloads a gadget containing action contributions.Parameters:NameTypeDescriptionhideActionHandlerFunctionThe container's function to remove actions from its UI. The
function takes in one parameter which is an array of action objects to remove.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
}
container.Container.actions.registerHideActionsHandler(myHideActionsHandler);
container.Container.actions.registerNavigateGadgetHandler(navigateHandler)Description: Allows the container to implement its specific UI to show a requested gadget as requested
by a declarative action. The container registers the handler, and the actions feature calls the handler
upon execution of an action, if the gadget is not yet rendered. The container may re-use the gadget site if it
is already visible on the page, or may choose to render it in a new or existing gadget view site.Parameters:NameTypeDescriptionnavigateHandlerFunctionThe container's function to render and navigate to gadgets in its UI.
Parameters for navigateHandler function:NameTypeDescriptiongadgetUrlStringGadget Spec URLopt_paramsObjectA bag-style JSON object that contains parameters to indicate
how the container should render the specified gadget.Example:
var myNavigateToHandler = function(gadgetUrl, opt_params){
// invoke common container APIs to show the appropriate gadg et, this could be viewed as a
// wrapper call to CommonContainer.navigateGadget(site, gadgetUrl, viewParams, renderParams, opt_callback);
// or return the gadgetID of an existing visble gadget navigatingTo the optional viewId.
return gadgetId;
}
container.Container.actions.registerNavigateGadgetHandler( myNavigateToHandler );
Actions may specify the view to render or the target location in the container UI to render the gadget.
This information is passed to the navigateHandler in the form of a bag-style JSON object with keys
defined in actions.OptParam. All of these are optional.
The view of gadget to render.
The target area of the container to render the view.
DiscussionThe selection feature allows the container to support a singleton selected object, or array of objects,
that can be set by the gadget or the container itself. For more information, please see the
gadgets.selection specification.The below methods allow the container itself to interact with the selected object(s).container.Container.selection.setSelection(selectionArray)Description: Sets the selection in 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.container.Container.selection.getSelection()Description: Gets the current selection in the container.Returns:TypeDescriptionObject[]The array of currently selected objects, each with type and dataObject properties, as described
in the gadgets.selection specificationDiscussion
The purpose of these APIs is to add the ability for the gadget to open
and/or close gadget and URL sites within the container which it is rendered.
Containers should override the following methods to define the behavior
for opening gadget and URL sites. The container may choose not to
override these methods, in which case if a gadget calls them the
container won't do anything.
Type: {Object} container.views.createElementForGadget(metadata, opt_view, opt_viewTarget)
Description: Method called when a gadget wants to open a view of
itself in a new gadget site.
Parameters:
NameTypeDescriptionmetadataObject
Gadget metadata for the gadget being opened.
opt_view string
Optional parameter, the surface view that indicates the type of gadget site.
opt_viewTarget string
Optional parameter, the view that indicates where to open the gadget. For example, tab, dialog or modaldialog.
Returns:
TypeDescriptionHTMLElement
The DOM element to place the gadget site in.
Type: {Object} container.views.createElementForEmbeddedExperience(opt_viewTarget)
Description: Method called when a gadget wants to open an embedded experience.
Parameters:
NameTypeDescriptionopt_viewTarget string
Optional parameter, the view that indicates where to open the gadget. For example, tab, dialog or modaldialog.
Returns:
TypeDescriptionHTMLElement
The DOM element to place the gadget site in.
Type: {Object} container.views.createElementForUrl(opt_viewTarget)
Description: Method called when a gadget wants to open a URL in a new URL site.
Parameters:
NameTypeDescriptionopt_viewTargetstring
Optional parameter, the view target to open. If the view target is not included
it is up to the container to choose how to open this URL.
Returns:
TypeDescriptionHTMLElement
The DOM element to place the URL site object in.
container.views.destroyElement(site)
Description: Method called when a gadget wants to close itself or the
parent gadget wants to close a gadget or URL site it has opened.
Parameters:
NameTypeDescriptionsiteObject
The the gadget or url site to close.
The framework is developed with extensibility in mind.
This is done by namespace assignment and augmenting custom methods.
// ensure container is defined here.
foo.container = container;
foo.container.prototype.newMethod = function() { ... }
This is done by re-defining overridable methods.
foo.container.Container.prototype.onConstructed = function(opt_config) { ... }
foo.container.GadgetSite.prototype.onConstructed = function() { ... }
foo.container.GadgetSite.prototype.onNavigateTo = function(data) { ... }
foo.container.GadgetHolder.prototype.onConstructed = function() { ... }
foo.container.Service.prototype.onConstructed = function(opt_config) { ... }
This is done by calling static function addMixin.
container.Container.addMixin('foo', function() { ... });
Gadget Lifecycle registryEmbedded ExperiencesOpenSearch Gadget ContributionsDeclarative Actions & SelectionView Enhancements To Support Opening Of Gadgets and URLs by the Container