The current OpenSocial Embedded Experience Data Model contains four fields:
Proposal
However, our use cases require additional information. This new proposal introduces allows the developer to indicate a preferred rendering of the embedded experience through a new structure, called preferredExperience, that contains a display element, and a target element. Each embed tag MUST contain only one preferredExperience.
For compatibility reasons, we maintain the existing structure:
"embed" : { "gadget" : "http://www.example.com/embedded/gadget.xml", "context" : { "title" : "Hello World", "id" : 123 }, "previewImage" : "http://www.example.com/embedded/123.png" } |
There is an additional field on the embedded experience model that indicates the preferred way the application developer would like their embedded experience rendered, preferredExperience. (This follows the same model as preferredHeight, preferredWidth that's in the app definition today.)
"embed" : { "gadget" : "http://www.example.com/embedded/gadget.xml", "url" : "http://www.example.com/foo/bar.html", "context" : { "title" : "Hello World", "id" : 123 }, "previewImage" : "http://www.example.com/embedded/123.png", "imageData" : "<base64 encoded image>", "preferredExperience" : { "target" : { "type" : "gadget", "view" : "my-ee-view" }, "display" : { "type" : "link", "text" : "Click me to say Hello World" } } } |
In addition, we introduced the notion of "type" on the target to tell the container the preferred rendering of the embedded experience. The container SHOULD respect as much as possible of the preferredExperience. There are situations, however, where support for specific capabilities is not present in a container. For example, the developer may include both a view and viewTarget in the preferredExperience. However, a container, e.g. a mobil device, may not support a viewTarget of TAB. In this scenario, the container SHOULD still respect the declaration of the preferred view.
imageData is the data field is used because it may not be possible to resolve the image and the "data" (the encoded image) must flow with the activity stream. If the display type is image, the developer MUST either a preivewImage or imageData, but should not provide both.
<Add the rules of if target type = x then i must have y>
The preferredExpereince.target tells the container how the developer how they would like their information presented to the end user.
Proposed possible type values:
Each target type has an additional set of properties that are associated with the target type.
Target properties where type = gadget:
Target properties for type = url:
When 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.
The preferredExperiences.display tells the container how the developer would like their embedded experience displayed to the user.
Proposed display's type values:
DIsplay properties for link display type:
Display properties for image display type:
Note: In the case of width & height, these are preferred. The container MAY scale this to more suitable dimensions. However, when scaling the image, the container SHOULD make every attempt to preserve the image ratio.
WIP. Graceful fail. What happens when no display.
It is often necessary for the application whose embedded experience is being rendered to have additional contextual information provided by the container. For example, in the case of a search result, the application may not know the the ID and type of the containing object when it provides the embedded experience. That is, the container may provide that information after the result is returned. The format for the associated context is as follows:
associated_context Format
{ "associated_context" : { "id" : "123abc", "type" : "opensocial.ActivityEntry", "objectReference" : {json object that matches the id} } } } |
Note: The container is free to extend the associated context with additional, container specific information. This MUST follow the extension rules defined in the specification, i.e. each extension contains a container prefix to "namespace" it's contents.
The associated_context is appended to the existing embedded experience context and is therefore accessed via the same key (org.opensocial.ee.context). ith the embedded experience is made available via a key in the gadget data context to store the containing context: org.opensocial.ee.associated_context. This maintains the 2.0 programming model of allowing the developer to listen to only a single key in the data context.
(Discussion Notes: We discussed the practicalities of having two data context keys. So, the developer would register on the 2.5 key, and then, immediately ask the data context for the 2.0 key. However, because of the asynchronous nature of JavaScript and the app loading, we could not guarantee that the data context would have the 2.0 key when it was asked for it. (We could force the container to adhere to strict data context loading rules, but this feels bad.)
Here's what a context object would look like if it contained the additional associated_context information. Note that the "associated_context" information is in the reserved "opensocial" namespace, i.e. "opensocial_associated_context".
context : { "title": "HelloWorld", "appProvidedId": "xyz135218", "opensocial": { "associatedContext": { "id": "123abc", "type": "opensocial.ActivityEntry", "objectReference": {} }, "jive": {} } } |
Embedded experience rendered as a link:
The embed tag contains:
{ "gadget": "http://www.example.com/embedded/gadget.xml", "context": { "title": "Hello World", "id": 123 }, "previewImage": "http://chart.finance.yahoo.com/t?s=JIVE&lang=en-US®ion=US", "preferredExperience": { "target": { "type": "gadget", "view": "my-ee-view" }, "display": { "type": "link", "text" : "Click me to say Hello World"} } } |
The display is:
Click me to say Hello World
When the user selects "clicks" on the hyperlink, the application's 'my-ee-view' will render.
Embedded experience rendered as an image:
{ "gadget": "http://www.example.com/embedded/gadget.xml", "context": { "title": "Hello World", "id": 123 }, "previewImage": "http://chart.finance.yahoo.com/t?s=JIVE&lang=en-US®ion=US", "preferredExperience": { "target": { "type": "gadget", "view": "my-ee-view" }, "display": { "type": "image", "altText" : "Open the Stock Quote App", "width" : 300, " height" : 180 } } } |
The display is: