The current OpenSocial Embedded Experience Data Model contains four fields:
url A URL to a web page that should be used as an embedded experience.
gadget A URL to a gadget definition that should be used as an embedded experience.
context Contextual data the gadget can use in order to know what content to embed. The format of this data is left up to the provider. This should only be included if a gadget is being used as the embedded experience.
previewImage (Optional) An image that can act as a preview for the content.
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:
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.)
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:
gadget : An OpenSocial application
url : A URL. A URL SHOULD resolve to an external HTML rendering of a resource, for example, a JIRA issue.
Each target type has an additional set of properties that are associated with the target type.
Target properties where type = gadget:
view : OPTIONAL : An OpenSocial view defined in the gadget. If no view is specified, the default of "EMBEDDED" is used.
viewTarget : OPTIONAL : A view target, as defined by OpenSocial, that is where the developer would prefer the application be rendered, e.g. MODALDIALOG.
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.
viewTarget : A view target, as defined by OpenSocial, that is where the developer would prefer the application be rendered, e.g. MODALDIALOG.
The preferredExperiences.display tells the container how the developer would like their embedded experience displayed to the user.
Proposed display's type values:
link : The embedded experience should be displayed as an HTML link to user. The container typically creates a well formed HTML anchor tag to represent this type of experience.
image : The embedded experience should be displayed graphically to the user.
DIsplay properties for link display type:
text : A section of text that should be displayed as the link. This is typically what is enclosed within the anchor tag, i.e. <a>This is the link text</a>
title : Text that can be used, e.g. in the case of a tool tip.
Display properties for image display type:
altText : Alternate text that can be used when displaying the image, typically used as a tool tip.
width : The preferred width of the image.
height : The preferred height of the image.
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:
type : The type of the object. This is not limited to just the OpenSocial types, e.g. org.opensocial.person, but can be either container specific, e.g. com.mycontainer.searchResult, or may be another industry specific type, e.g. from Schema.org or Facebook's open graph.
objectReference : Container MUST provide an id and type. objectReference is optional and is there as an optimization to avoid a remote call.
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.
Accessing the associated_context
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.
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".