opensocial-and-gadgets-spec@googlegroups.com

General OpenSocial Core Container

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

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.

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 allows 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.

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.

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.

When a gadget renders in a container it goes through several stages from the time it is added to the time it is eventually removed from the container. Some or all of these stages may occur for each gadget in the container. We refer to the different stages a gadget goes through as it is rendered in the container lifecycle events.

Name Type Description osapi.container.CallbackType.ON_BEFORE_PRELOAD String The container MUST call this lifecycle listener before a gadget is preload. If multiple gadgets are preloaded at the same time the container should call this listener once for the set of gadgets that are being preloaded. The listener function will be passed an array of gadget URLs. osapi.container.CallbackType.ON_PRELOADED String The container MUST call this lifecycle listener after a gadget is preload. If multiple gadgets are preloaded at the same time the container should call this listener once for the set of gadgets that were preloaded. The listener function will be passed a preload response object. osapi.container.CallbackType.ON_BEFORE_NAVIGATE String The container MUST call this lifecycle listener before a gadget is navigated to in the container. The listener function will be passed the URL of the gadget being navigated. osapi.container.CallbackType.ON_NAVIGATED String The container MUST call this lifecycle listener after a gadget is navigated to in the container. This listener may be called before the gadget has finished rendering in the container. See osapi.container.CallbackType.ON_RENDER. The listener function will be passed the gadget site. osapi.container.CallbackType.ON_BEFORE_CLOSE String The container MUST call this lifecycle listener before a gadget is closed in the container. The listener function will be passed the gadget site. osapi.container.CallbackType.ON_CLOSED String The container MUST call this lifecycle listener after a gadget is closed in the container. The listener function will be passed the gadget site. osapi.container.CallbackType.ON_BEFORE_UNLOAD String The container MUST call this lifecycle listener before a gadget is unloaded from the container. If multiple gadgets are unloaded at the same time this listener will be called one time for each gadget that is unloaded. The listener function will be passed the gadget URL of the gadget being unloaded. osapi.container.CallbackType.ON_UNLOADED String The container MUST call this lifecycle listener after a gadget is unloaded from the container. If multiple gadgets are unloaded at the same time this listener will be called one time for each gadget that is unloaded. The listener function will be passed the gadget URL of the gadget being unloaded. osapi.container.CallbackType.ON_BEFORE_RENDER String The container MUST call this lifecycle listener before a gadget has rendered. This would typically occur during gadget navigation. The listener function will be passed the gadget URL of the gadget being renderd. osapi.container.CallbackType.ON_RENDER String The container MUST call this lifecycle listener after a gadget has rendered. The listener function will be passed the gadget URL of the gadget being renderd. This does not necessarily mean that all the UI of the gadget has finished rendering but that the gadget has finished loading everthing it needs render. This listener may or may not be called after osapi.container.CallbackType.ON_NAVIGATED.

This is an example of how to listen for lifecycle events.

...... var listeners = {}; listeners[osapi.container.CallbackType.ON_BEFORE_PRELOAD] = function(gadgetUrls) { gadgets.log('osapi.container.CallbackType.ON_BEFORE_PRELOAD called'); }; listeners[osapi.container.CallbackType.ON_PRELOADED] = function(response) { gadgets.log('osapi.container.CallbackType.ON_PRELOADED called'); gadgets.log(gadgets.json.stringify(response)); }; listeners[osapi.container.CallbackType.ON_BEFORE_NAVIGATE] = function(gadgetUrl) { gadgets.log('osapi.container.CallbackType.ON_BEFORE_NAVIGATE called'); gadgets.log('About to navigate to ' + gadgetUrl); }; listeners[osapi.container.CallbackType.ON_NAVIGATED] = function(site) { gadgets.log('osapi.container.CallbackType.ON_NAVIGATED called'); }; listeners[osapi.container.CallbackType.ON_BEFORE_CLOSE] = function(site) { gadgets.log('osapi.container.CallbackType.ON_BEFORE_CLOSE called'); }; listeners[osapi.container.CallbackType.ON_CLOSED] = function(site) { gadgets.log('osapi.container.CallbackType.ON_CLOSED called'); }; listeners[osapi.container.CallbackType.ON_BEFORE_RENDER] = function(gadgetUrl) { gadgets.log('osapi.container.CallbackType.ON_BEFORE_RENDER called'); gadgets.log('About to render ' + gadgetUrl); }; listeners[osapi.container.CallbackType.ON_RENDER] = function(gadgetUrl) { gadgets.log('osapi.container.CallbackType.ON_RENDER called'); gadgets.log('The gadget at the URL ' + gadgetUrl + ' has rendered'); }; listeners[osapi.container.CallbackType.ON_BEFORE_UNLOAD] = function(gadgetUri) { gadgets.log('osapi.container.CallbackType.ON_BEFORE_UNLOAD called'); gadgets.log('About to unload ' + gadgetUri); }; listeners[osapi.container.CallbackType.ON_UNLOADED] = function(gadgetUri) { gadgets.log('osapi.container.CallbackType.ON_UNLOADED called'); gadgets.log(gadgetUri + 'has been unloaded'); }; CommonContainer.addGadgetLifecycleCallback('com.example.commoncontainer', lifecycle); .....

Containers often need information about the gadget they are going to render, either before or after the rendering occurs. In the terms of the container this infomation is typically referred to as the gadget's metadata and MAY contain information such as the gadget's title, the features the gadget uses, and the views a gadget has. The container can use information such as the gadget title in the chrome around the gadget when it renders.

Obtaining gadget metadata can be done before or after a gadget has rendered. To obtain a single gadget's metadata before a gadget is rendered a container can call osapi.container.Container.preloadGadget. To obtain metadata for multiple gadgets at the same time before any of them are rendered a container can all osapi.container.Container.preloadGadget. A container can also recieve a gadget's metadata after rendering a gadget. The callback passed to navigateGadget takes one parameter which is the gadget metadata for the gadget that was renderd. Since a gadget's metadata is unlikely to change very often containers SHOULD cache a gadget's metadata in order to avoid making the same request each time the gadget is rendered. Containers SHOULD purge a gadget's metadata when osapi.container.Container.unloadGadget or osapi.container.Container.unloadGadgets is called.

Namespace for top level container functions.

This represents the container. This provides a top-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 not be more than one instance of this in a page, due to usage of global resources and possible race conditions.

osapi.container.Container(opt_config) Constructs the container object. Parameters: Name Type Description opt_config Object A bag-style JSON object with configuration parameters. See

osapi.container.Container.preloadGadget(gadgetUrl, opt_callback) Description: Pre-loads a single gadget in the container. See also: preloadGadgets Parameters: Name Type Description gadgetUrl String A URL to the gadget definition. opt_callback function A callback function to be called when the gadget metdata is returned. The callback function should have one parameter which is the response from preloading the gadget. Example:

... CommonContainer.preloadGadget('http://example.com/gadget.xml', function(result) { for (var gadgetURL in result) { if(!result[gadgetURL].error) { var metadata = result[gadgetURL]; //do something with the metadata } else { gadgets.error('Error preloading gadget ' + gadgetURL); } } }); ...

osapi.container.Container.preloadGadgets(gadgetUrls, opt_callback) Pre-load gadgets metadata information. Parameters: Name Type Description gadgetUrls Array Gadget URLs to preload. opt_callback function A callback function to be called when the gadget metdata is returned. The callback function should have one parameter which is the response from preloading the gadget. Example:

... CommonContainer.preloadGadgets(['http://example.com/gadget1.xml', 'http://example.com/gadget2.xml'], function(result) { for (var gadgetURL in result) { if(!result[gadgetURL].error) { var metadata = result[gadgetURL]; //do something with the metadata } else { gadgets.error('Error preloading gadget ' + gadgetURL); } } }); ...

osapi.container.Container.unloadGadget(gadgetUrl) Unloads a single gadget. Parameters: Name Type Description gadgetUrl String Gadget URL to unload.

osapi.container.Container.unloadGadgets(gadgetUrls) Unload preloaded gadgets. Parameters: Name Type Description gadgetUrls Array Gadget URLs to unload.

osapi.container.Container.navigateGadget(site, gadgetUrl, viewParams, renderParams, opt_callback) Renders (navigates) to the specified gadget. Parameters: Name Type Description site osapi.container.GadgetSite The gadget site to use to render the gadget gadgetUrl string The gadget URL to render (navigate) to. viewParams Object View parameters to pass to the view being specified in the renderParams. renderParams Object Contains parameters on how the container wants to render this gadget see . opt_callback function Optional callback function called after the gadget has been rendered. The callback will be called with one parameter containing the metadata for the gadget that was rendered. Example:

... var el = document.getElementById('gadget-site'); var gadgetSite = CommonContainer.newGadgetSite(el); var params = {}; params[osapi.container.RenderParam.WIDTH] = '100%'; params[osapi.container.RenderParam.VIEW] = 'home'; CommonContainer.navigateGadget(gadgetSite, 'http://example.com/gadget.xml', {}, params, function(metadata){ if(metadata.error) { gadgets.error('There was an error rendering http://example.com/gadget.xml'); } else { //do something with the gadgets metadata } }); ...

osapi.container.Container.navigateUrl(site, url, renderParams) Navigates to an arbitrary URL in the container. Parameters: Name Type Description site osapi.container.UrlSite The URL site to navigate to the URL within. url String The URL to navigate to. renderParams Object Contains parameters for how the container wants to render this URL. See . This function only accepts osapi.container.RenderParam.HEIGHT and osapi.container.RenderParam.WIDTH as valid render params. Example:

... var el = document.getElementById('url-site'); var urlSite = CommonContainer.newUrlSite(el); var params = {}; params[osapi.container.RenderParam.WIDTH] = '100%'; CommonContainer.navigateUrl(gadgetSite, 'http://example.com', {}, params); ...

osapi.container.Container.closeGadget(site) Closes the gadget in the site. Parameters: Name Type Description site osapi.container.GadgetSite The site containing the gadget to close.

Discussion osapi.container.Container.addGadgetLifecycleCallback(name, lifeCycleCallback) Add a callback object to be called when a gadget is added, navigated to or closed. Parameters: Name Type Description name String The name of the callback function. Used to uniquely identify this callback function. lifeCycleCallback function 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: Name Type Description lifeCycleCallback function remove a lifecycle callback previously registered with the container

osapi.container.Container.newGadgetSite(element, opt_bufferElement) Creates a new GadgetSite and registers it with the container. The ID attribute of element will be used as the siteId. If no ID has been assigned to element you pass in, a unique id will be assigned to the site by the container. Parameters: Name Type Description element Element The element to create a gadget site from. opt_bufferElement Element The element to use as a buffer when rendering the gadget site. Returns: Type Description osapi.container.GadgetSite A gadget site to render a gadget in.

osapi.container.Container.newUrlSite(element) Creates a new UrlSite and registers it with the container. The ID attribute of element will be used as the siteId. If no ID has been assigned to element you pass in, a unique id will be assigned to the site by the container. Parameters: Name Type Description element Element The element to create a url site from. Returns: Type Description osapi.container.UrlSite A URL site to render a URL in. Discussion

This represents a spot in the container where either a gadget or a URL can be rendered. This is a super class for URL sites and gadget sites.

osapi.container.Site.setHeight(height) Sets the height of the site. Parameters: Name Type Description height Number Value to set the site height to.

osapi.container.Site.setWidth(width) Sets the width of the site. Parameters: Name Type Description width Number Value to set the site width to.

osapi.container.Site.close() Closes the site in the container.

Represents a spot in the container where a gadget can render. This is a subclass of osapi.container.Site.

osapi.container.GadgetSite.setHeight(height) Sets the height of the gadget site. Parameters: Name Type Description height Number Value to set the gadget site height to.

osapi.container.GadgetSite.setWidth(width) Sets the width of the gadget site. Parameters: Name Type Description width Number Value to set the gadget site width to.

osapi.container.GadgetSite.close() Closes the site in the container.

Represents a spot in the container where a URL can render. This is a subclass of osapi.container.Site.

osapi.container.UrlSite.setHeight(height) Sets the height of the URL site. Parameters: Name Type Description height Number Value to set the Url site height to.

osapi.container.UrlSite.setWidth(width) Sets the width of the URL site. Parameters: Name Type Description width Number Value to set the URL site width to.

osapi.container.UrlSite.close() Closes the site in the container.

Configuring common container is done at instantiation, by passing a bag-style JSON, with keys defined under osapi.container.ContainerConfig. All of these are optional. These affect all rendering, unless overridden by Render Configuration. Name Type Description osapi.container.ContainerConfig.ALLOW_DEFAULT_VIEW String Equivalent to the String allowDefaultView. Allow gadgets to render in an unspecified view. Default is true. osapi.container.ContainerConfig.RENDER_DEBUG String Equivalent to the String renderDebug. Indicates whether debug mode is turned on. Default is false. osapi.container.ContainerConfig.RENDER_DEBUG_PARAM String Equivalent to the String renderDebugParam. The name of the query parameter to look for in the container's URL that indicates whether to put the container in debug mode. If this config parameter is passed and the query parameter is present in the container URL the container MUST honor its value over the osapi.container.ContainerConfig.RENDER_DEBUG config parameter. osapi.container.ContainerConfig.RENDER_TEST String Equivalent to the String renderTest. Indicates whether test mode is turned on. Default is false. The following parameters do not effect rendering in the container. Name Type Description osapi.container.ContainerConfig.GET_LANGUAGE String Equivalent to the String GET_LANGUAGE. 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. The callback function should return a string equal to the language locale part. osapi.container.ContainerConfig.GET_COUNTRY String Equivalent to the String GET_COUNTRY. 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. The callback function should return a String equal to the country locale part. osapi.container.ContainerConfig.GET_PREFERENCES String Equivalent to the String GET_PREFERENCES. A function that will asynchronously fetch the preferences to use when asking the server to render a gadget or when asking the server for gadget metadata. Discussion It will be passed the following parameters: Name Type Description siteId string Gadget Site ID gadgetUrl string Gadget Url callback function(Map<String, Object> preferences) An asynchronous callback that will receive the value of the fetched preferences, if any. The GET_PREFERENCES function passed in the config should call this callback function with a Map that is constructed just like the Map for USER_PREFS Discussion osapi.container.ContainerConfig.SET_PREFERENCES String Equivalent to the String SET_PREFERENCES. A callback function that will persist the preferences. It will be passed the following parameters: Name Type Description siteId string Gadget Site ID gadgetUrl string Gadget Url preferences object Preferences to persist. The format supplied here will be the same as is required for USER_PREFS.

The following constants my be passed in a bag-style JSON object to functions in the container which render gadgets and URLs. Name Type Description osapi.container.RenderParam.ALLOW_DEFAULT_VIEW String Equivalent to the String allowDefaultView. Allow gadgets to render an unspecified view. The default is true. osapi.container.RenderParam.DEBUG String Equivalent to the String debug. Indicates whether to turn on debugging mode. The default is false. osapi.container.RenderParam.HEIGHT String Equivalent to the String height. The starting site height (in pixels). The default is 200. osapi.container.RenderParam.NO_CACHE String Equivalent to the String nocache. Indicates whether to disable cache. The default is false. osapi.container.RenderParam.TEST_MODE String Equivalent to the String testmode. Indicates whether to enable test mode. The default is false. osapi.container.RenderParam.USER_PREFS String Equivalent to the String userPrefs. 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 value of USER_PREFS should be a Map of preferences keys (Strings) to preference values (String or Array). osapi.container.RenderParam.VIEW String Equivalent to the String view. The view of the gadget to render. osapi.container.RenderParam.WIDTH String Equivalent to the String width. The starting site width (in pixels). The default is 320.

Here is an example of how you would render a gadget in a container implementing the common container specification.

//The gadget we are going to navigate to. var gadgetUrl = 'http://example.com/gadget.xml'; //The URL we are going to navigate to. var url = 'http://opensocial.org'; //Configuration for our container. var config = {}; config[osapi.container.ContainerConfig.RENDER_DEBUG] = true; config[osapi.container.ContainerConfig.GET_COUNTRY] = function() { return 'ALL'; }; config[osapi.container.ContainerConfig.GET_LANGUAGE] = function() { return 'ALL'; }; //Construct the container object var container = new osapi.container.Container(config); //We want to log how long it is taking to preload gadgets so add the necessary preload lifecycle listeners var preloadStartTime = 0; listeners[osapi.container.CallbackType.ON_BEFORE_PRELOAD] = function(gadgetUrls) { preloadStartTime = new Date().getTime(); }; listeners[osapi.container.CallbackType.ON_PRELOADED] = function(response) { var time = new Date().getTime() - preloadStartTime; var urls = []; for(url in response) { urls[urls.length] = url; } gadgets.log('It took ' + time + ' ms to preload the URL(s) ' + urls); }; //Create the gadget site that the gadget will render in. var gadgetSiteElement = document.getElementById('my_gadget_site'); var gadgetSite = container.newGadgetSite(gadgetSiteElement); var renderParams = {}; renderParams[osapi.container.RenderParam.VIEW] = gadgets.views.ViewType.HOME; //Render the gadget! container.navigateGadget(gadgetSite, gadgetUrl, {}, renderParams, function(gadgetMetadata){ if(gadgetMetadata.error) { gadgets.error('There was an error rendering the gadget at ' + gadgetUrl); } }); //Create the URL site the URL will render in. var urlSiteElement = document.getElementById('my_url_site'); var urlSite = container.newUrlSite(urlSiteElement); //Render the URL! container.navigateUrl(urlSite, url, {});

Discussion

osapi.container.Container.ee.navigate(element, dataModel, renderParams, opt_callback, opt_containerContext) Renders an embedded experience from the given embedded experience data model. Parameters: Name Type Description element HTMLElement The HTML DOM element in which to render the embedded experience. dataModel Object The embedded experience data model. renderParams Object The render params to use when rendering this embedded experience. opt_callback function Called when the embedded experience has been rendered. The function takes in two parameters, the site and the metadata. opt_containerContext Object This object will be added to the context property of the data model parameter under the 'openSocial' namespace. This object can be used to pass the associatedContext to the embedded experience gadget.

osapi.container.Container.ee.close(site) Closes a site containing an embedded experience. This can close a gadget site or a URL site. Parameters: Name Type Description site osapi.container.Site The 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. Name Type Description osapi.container.ee.RenderParam.GADGET_RENDER_PARAMS String Equivalent to the String gadgetRenderParams. The value of this parameter should be an object that is made up of parameters from the section on render configuration. osapi.container.ee.RenderParam.URL_RENDER_PARAMS String Equivalent to the String urlRenderParams. The value of this parameter should be an object that MUST only be made up of osapi.container.RenderParam.WIDTH and osapi.container.RenderParam.HEIGHT parameters from the section on render configuration. osapi.container.ee.RenderParam.GADGET_VIEW_PARAMS String Equivalent to the String gadgetViewParams. The value of this parameter should be an object that are view params passed to the embedded experience 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} osapi.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: Name Type Description mimeType String The type of OpenSearch URLs you want to be returned. This should be a valid MIME type. Returns: Type Description Array An array of name and URL pairs, where name is the display name, and URL is the OpenSearch template URL.

Type: {Array} osapi.container.Container.opensearch.getOpenSearchDescriptions(mimeType) Description: Retrieves all OpenSearch descriptions from gadgets which have OpenSearch feature in their gadget definition. Parameters: Name Type Description mimeType String The MIME type for the OpenSearch template URL within the OpenSearch description. If null all OpenSearch descriptions will be returned. Returns: Type Description Array An array of OpenSearch definitions. The definitions should be the JSON representation of the OpenSearch definition represented in XML. Example Array Returned By osapi.container.opensearch.getOpenSearchDesription

[ { "mimeType" : "application/atom+xml", "OpenSearchDescription : { "ShortName" : "Example Search", "Description" : "Realtime Example Search", "Url" : { "@type" : "application/atom+xml", "@method" : "get", "@template" : "http://search.example.com/search.atom?q={searchTerms}" }, "Image" : { "@width" : "16", "@height" : "16", "#text" : "http://search.example.com/favicon.png" }, "InputEncoding" : "UTF-8", "SearchForm" : "http://example.search.com/" } } ]

osapi.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: Name Type Description callback function(Map<String, Object> 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.

osapi.container.Container.opensearch.removeOpenSearchCallback(callback) Description: Un-registers a callback function registered via addOpenSearchCallBack() Parameters: Name Type Description callback function The callback function to be unregistered

Discussion The 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.

{Array} osapi.container.Container.actions.getAction(actionId) Description: Returns the action object (as described in the gadgets specification) associated with the specified id. Returns: Type Description Object An action object currently in the registry with the specified ID.

{Array} osapi.container.Container.actions.getAllActions() Description: Returns an array of action objects (as described in the gadgets specification) currently in the registry. Returns: Type Description Object[] An array of action objects currently in the registry.

{Array} osapi.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: Name Type Description path String Text representation of a path to an action. Returns: Type Description Object[] Array of action objects associated with the given path.

{Array} osapi.container.Container.actions.getActionsByObject(dataType) Description: Returns an array of action objects bound to a specific data type. Parameters: Name Type Description dataType String OpenSocial data type. Returns: Type Description Object[] Array of action objects associated with the given data type.

osapi.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: Name Type Description actionId String Identifier for the action to be executed. opt_selection Object The current selection. This is an optional parameter.

osapi.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: Name Type Description showActionHandler Function The 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: Name Type Description actionObjs Object[] 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: // osapi.container.Container.actions.runAction(actionObject[0].id); } osapi.container.Container.actions.registerShowActionsHandler(myShowActionsHandler);

osapi.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: Name Type Description hideActionHandler Function The 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: Name Type Description actionObjs Object[] An array of action objects. Example: var myHideActionsHandler = function(actionObjs){ // remove any UI elements that were created to represent the action } osapi.container.Container.actions.registerHideActionsHandler(myHideActionsHandler);

osapi.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: Name Type Description navigateHandler Function The container's function to render and navigate to gadgets in its UI. Parameters for navigateHandler function: Name Type Description gadgetUrl String Gadget Spec URL opt_params Object A 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 gadget, this could be viewed as a // wrapper call to osapi.container.Container.navigateGadget(site, gadgetUrl, viewParams, renderParams, opt_callback); // or return the site ID of an existing visble gadget. return gadgetId; } osapi.container.Container.actions.registerNavigateGadgetHandler( myNavigateToHandler );

osapi.container.Container.actions.addListener(listener, opt_actionId) Description: Allows the container to listen for actions firing. The actions feature calls the listener upon execution of an action, with the same arguments as the gadgets.actions.runAction(actionId, opt_selection). Parameters: Name Type Description listener Function The listener opt_actionId String An optional action id. If not provided, listener will be notified for all action ids. Example: osapi.container.Container.actions.addListener(function(actionId, opt_selection) { // Possibly handle some ui positioning or other ui related operation when this interesting action is run. }, "some.interesting.gadget.action"); Discussion

osapi.container.Container.actions.removeListener(listener) Description: Remove the listener from the collection of listeners. The listener will no longer be called by the actions feature. Parameters: Name Type Description listener Function The listener to remove Example: var listener = function() { // Possibly handle some ui positioning or other ui related operation when this interesting action is run. }; osapi.container.Container.actions.addListener(listener, "some.interesting.gadget.action"); osapi.container.Container.actions.removeListener(listener); Discussion

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 registered with osapi.container.Container.actions.registerNavigateGadgetHandler in the form of a bag-style JSON object with keys defined in actions.OptParam. All of these are optional. Name Type Description osapi.container.actions.OptParam.VIEW String Equivalent to the String view. You can use this String to get the value from the opt_params parameter passed the navigation handler. If there is a value for this property in the opt_params parameter the navigation handler MUST navigate to this view when rendering the gadget. osapi.container.actions.OptParam.VIEW_TARGET String Equivalent to the String viewTarget. You can use this String to get the value from the opt_params parameter passed the navigation handler. If there is a value for this property in the opt_params parameter the navigation handler MUST render the gadget in the view target specificed.

Discussion The 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).

osapi.container.Container.selection.setSelection(selectionArray) Description: Sets the selection in the container. The selection may be an array of multiple objects. Parameters: Name Type Description selectionArray Object[] Array of object(s) to be set as selected, with attributes defined in table below. Each selection object must have the following attributes: Name Type Description type String Open Social data type, as specified in the Social Data Specification dataObject Object Object representing the selection.

{Array} osapi.container.Container.selection.getSelection() Description: Gets the current selection in the container. Returns: Type Description Object[] The array of currently selected objects, each with type and dataObject properties, as described in the gadgets.selection specification

Discussion 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.

Type: {Element} osapi.container.Container.views.createElementForGadget(metadata, rel, opt_view, opt_viewTarget, opt_coordinates, parentSite, opt_callback) Description: Method called when a gadget wants to open a view of itself in a new gadget site. Parameters: Name Type Description metadata Object Gadget metadata for the gadget being opened. rel Element The element which the opt_coordinates are relative to. opt_view string Optional parameter, the surface view that indicates the type of gadget site. opt_viewTarget string Optional parameter, the view target that indicates where to open the gadget. For example, tab, dialog or modaldialog. opt_coordinates Object Object containing the desired absolute positioning css parameters (top|bottom|left|right) with appropriate values. Container implementations SHOULD honor optionally specified coordinates for the FLOAT viewTarget. Containers MAY honor coordinates for any other target they choose. parentSite osapi.container.GadgetSite The site opening the gadget. opt_callback Function If the container needs to asynchronously create the element for the gadget to render in this function MUST call the callback parameter with the element and return undefined. If the element can be created synchronously than the container MUST just return that element as the return value from this function. Discussion Returns: Type Description Element The DOM element to place the gadget site in.

Type: {Element} osapi.container.Container.views.createElementForEmbeddedExperience(rel, opt_gadgetInfo, opt_viewTarget, opt_coordinates, parentSite, opt_callback) Description: Method called when a gadget wants to open an embedded experience. Parameters: Name Type Description rel Element The element which the opt_coordinates are relative too. opt_gadgetInfo Object If the embedded experience is a gadget the metadata for that gadget will be passed in this parameter. opt_viewTarget string Optional parameter, the view target that indicates where to open the embedded experience. For example, tab, dialog or modaldialog. opt_coordinates Object Object containing the desired absolute positioning css parameters (top|bottom|left|right) with appropriate values. Container implementations SHOULD honor optionally specified coordinates for the FLOAT viewTarget. Containers MAY honor coordinates for any other target they choose. parentSite osapi.container.GadgetSite The site of the gadget opening the embedded experience opt_callback Function If the container needs to asynchronously create the element for the embedded experience to render in this function MUST call the callback parameter with the element and return undefined. If the element can be created synchronously than the container MUST just return that element as the return value from this function. Discussion Returns: Type Description Element The DOM element to place the site in.

Type: {Element} osapi.container.Container.views.createElementForUrl(rel, opt_viewTarget, opt_coordinates, parentSite, opt_callback) Description: Method called when a gadget wants to open a URL in a new URL site. Parameters: Name Type Description rel Element The element to which opt_coordinates values are relative. opt_viewTarget string 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. opt_coordinates Object Object containing the desired absolute positioning css parameters (top|bottom|left|right) with appropriate values. Container implementations SHOULD honor optionally specified coordinates for the FLOAT viewTarget. Containers MAY honor coordinates for any other target they choose. parentSite osapi.container.GadgetSite The site of the gadget that is opening the URL. opt_callback Function If the container needs to asynchronously create the element for the gadget to render in this function MUST call the callback parameter with the element and return undefined. If the element can be created synchronously than the container MUST just return that element as the return value from this function. Discussion Returns: Type Description Element The DOM element to place the URL site object in.

osapi.container.Container.views.destroyElement(site) Description: Method called when a gadget wants to close, or a gadget that used the open-views feature to open a gadget view wants to close that gadget view. This method MUST ultimately call osapi.container.Container.closeGadget(site) so that the gadget's lifecycle events are completed in addition to any DOM cleanup the container implementation may wish to do. Discussion Parameters: Name Type Description site osapi.container.Site 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.osapi.container.Container.prototype.navigateGadget = function(....) { ... } foo.osapi.container.Container.prototype.newGadgetSite = function(....) { ... } foo.osapi.container.Container.prototype.closeGadget = function(....) { ... }

This is done by calling static function addMixin. osapi.container.Container.addMixin('foo', function() { ... });

Harvard University IBM