Convenience APIs For Embedded Experiences

Today gadget developers need to write the same few lines of javascript to access the embedded experiences context.

gadgets.util.registerOnLoadHandler(function() {
  opensocial.data.getDataContext().registerListener('org.opensocial.ee.context', function(key) {
    var context = opensocial.data.getDataContext().getDataSet(key);
    //finally do something with the context
  });
});

This code is the same for ALL embedded experience gadgets who want to access their context, no matter what. It can be simplified and made easier for the gadget developer by wrapping all of this code in a simple API...

<static> gadgets.ee.registerContextListener(listener)

Description: Registers a listener for when the embedded experience context object is passed to the gadget. The listener will be called whenever the context object is updated for this gadget.

Parameters:

Name	Type	Description
listener	Function	A function that will be called whenever the embedded experience context is set for this gadget. The function should take one parameter which is a JSON object representing the embedded experience context from the gadget. See the embedded experiences data model description for more information on the context object.

Example:

gadgets.ee.registerContextListener(function(context) {
  //Do something with the context
});

Additional Considerations:

We also need to support the ability for a gadget to get the parent object containing the embedded experience. There should be a similar API to accomplish that as well, but those discussions are on going at the moment. See this wiki page.

<static> gadgets.ee.registerRootContextListener(listener)

Description: Registers a listener for when the root object containing this embedded experience is passed to the object. The embedded experience data model is contained within the root object being passed.

Parameters:

Name	Type	Description
listener	Function	A function that will be called when the root object containing this embedded experience is passed to the gadget. The function should take one parameter which is a JSON object representing a root context object.

Example:

gadgets.ee.registerRootContextListener(function(rootContext) {
  var eeDataModel;
  if(rootContext.type === opensocial.type.ActivityEntry) {
    eeDataModel = rootContext.root.openSocial.embed;
  } else if(rootContext.type === opensocial.type.Message) {  
    //At the time this proposal was written EE was not integrated into the OpenSocial Message object
    eeDataModel = rootContext.root.embed;
  } else if(rootContext.type === opensocial.type.SearchResult) {  
    //At the time this proposal was written there is no SearchResult object in the OpenSocial spec
    eeDataModel = rootContext.root.embed;
  } else {
    gadgets.error('Unknown type');
  }
});

<static> gadgets.ee.getEmbeddedExperiencesDataModel(rootContext)

Description: Given an embedded experiences root context object it will return the embedded experiences data model.

Returns: An embedded experiences data model.

Parameters:

Name	Type	Description
rootContext	opensocial.ee.RootContext	The embedded experiences root context object, ie an activity entry, message, etc, to get the embedded experiences data model from.

Example:

gadgets.ee.getEmbeddedExperiencesDataModel(function(rootContext) {
  var eeDataModel = getEmbeddedExperiencesDataModel(rootContext);
  if(!eeDataModel) {
    gadgets.error('No data model');
    return;
  }
  //Do something with the data model
});

Embedded Experiences Root Context Object

The embedded experience root context object is an object that represents the type of OpenSocial data object containing the embedded experience. The possible data types include

An Activity Stream activity.
A Message - We need to define this.
A Search Object - We need to define this.

The embedded experiences root context object has two fields.

Name	Type	Description
type	opensocial.type	Indicates the type of OpenSocial object containing the embedded experience.
root	Object	A JSON object containing the embedded experience.

opensocial.type

This is basically a set of constants defining the different OpenSocial data types.

<static> opensocial.type.ActivityEntry

Description: A constant for an activity entry in an activity stream.

<static> opensocial.type.Message

Description: A constant for the OpenSocial Message type.

Note: Proposal to introduce embedded experiences in the OpenSocial Message object is here.

<static> opensocial.type.SearchResult

Description: A constant for a search result.

Note: We need to define Search and Search results in the OpenSocial spec.