More precision for EE data model

Owned by Mark Weitzel
Last updated: May 01, 2012 by Henry SaputraVersion comment

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.

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>

Target 

The preferredExpereince.target tells the container how the developer how they would like their information presented to the end user. 

Proposed possible type values:

  1. gadget : An OpenSocial application
  2. 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:

  1. view : OPTIONAL : An OpenSocial view defined in the gadget. If no view is specified, the default of "EMBEDDED" is used.
  2. 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. 

  1. viewTarget : A view target, as defined by OpenSocial, that is where the developer would prefer the application be rendered, e.g. MODALDIALOG.

Display

The preferredExperiences.display tells the container how the developer would like their embedded experience displayed to the user. 

Proposed display's type values:

  1. 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.
  2. image : The embedded experience should be displayed graphically to the user. 

DIsplay properties for link display type:

  1. 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>
  2. title : Text that can be used, e.g. in the case of a tool tip. 

Display properties for image display type:

  1. altText : Alternate text that can be used when displaying the image, typically used as a tool tip. 
  2. width : The preferred width of the image.
  3. 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.

Processing Rules

WIP. Graceful fail. What happens when no display. 

Associated Context

Format

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}
   }
  }
}
  1. id : The unique identifier of the object
  2. 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.
  3. 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. 

(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": {}
    }
}

Examples

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&region=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&region=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: