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
});
The suggested model for the root context is potentially a major interop problem. Per Henry's follow up to my questions on the updated EE model, the container is free to determine what exactly the "root context" for a given EE is, which means that it's possible that different containers will give a single gadget different root context objects depending on how they are implemented. The example code you provide above already shows fairly ugly logic for determining what kind of object has been passed in.
Rather than this...
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'); } });Perhaps it could be based on an abstraction such as...
gadgets.ee.registerRootContextListener(function(rootContext) { var eeDataModel = rootContext.getString("org.opensocial.embed"); // returns the embedded experience model... if (rootContext.has("other")) var other_property = rootContext.getString("other"); // returns the "other" property.... var vnd_property = rootContext.getString("org.example.property"); var raw_parent = rootContext.getString("org.opensocial.container"); // returns the raw container object... });Following this model, the type of root context object is largely irrelevant. A number of common properties for the root object can be defined and the container can fill in the rest. This gives the container complete freedom of how to map the containing root object to the rootContext object and keeps us from having to define Yet Another Type for every possible type of container. This design would be significantly more interoperable and allows gadgets and embedded experiences to be far more portable.
The methods on the rootContext object would be:
function has(prop) => returns true if the root context contains the named property
function getString(prop) => returns the value of the property as a string
function getNumber(prop) => returns the value of the property as a number
function getBool(prop) => returns the value of the property as a boolean
function getArray(prop) => returns the value of the property as an Array
function get...(prop) => (any other specific data type variations necessary)
The two default properties support for all rootContext objects would be:
org.opensocial.embed => identifies the embedded experience data structure
org.opensocial.container => identifies the raw object that contains the embedded experience, just in case an application does need specific access to it. This would potentially be container specific