THIS IS A VERY EARLY DRAFT AND INCORPORATES INCOMPLETE AND CURRENTLY UNACCEPTED/UNAPPROVED TECHNICAL CHANGES BASED ON THE CURRENT Enhanced EE Proposal.... It is posted here as a convenience for REVIEW.
<section title="Embedded Experiences" anchor="Embedded-Experiences">
<xref target="Issue-1144">Discussion</xref>
<t>Embedded experiences provide a mechanism for embedding OpenSocial
gadgets and other web-accessible content sources directly into a
variety of contexts such as Activity Streams, email messages and Atom feeds.
The mechanism works by inserting a small structure of data that includes
a reference to the embedded content along with contextual data an OpenSocial
container would need to render the content appropriately.</t>
<t>This data structure can be serialized as either a JSON object or XML and
includes the following properties:</t>
<texttable>
<ttcol align="left" width="15%">Property</ttcol>
<ttcol align="left">Description</ttcol>
<c><spanx style="verb">context</spanx></c>
<c>If the Embedded Experience is used to embed an OpenSocial gadget,
the "context" field is used to pass data to the gadget so that it
knows exactly which content to render. For instance, a gadget that
displays a person's profile information will need to know which
profile to display; a gadget that displays an album of recent photos
will need to know the identity of the album to display. The content
of the "context" field is undefined and specific to each individual
gadget definition.</c>
<c><spanx style="verb">gadget</spanx></c>
<c>A URL to an OpenSocial Gadget definition document that defines the
gadget to be embedded.</c>
<c><spanx style="verb">preferredExperience</spanx></c>
<c>An optional collection of properties that describe the preferred
way the creator of the embedded experience would like containers to
render the content.</c>
<c><spanx style="verb">previewImage</spanx></c>
<c>An optional URI to an image that can be used as a preview for the
embedded content.</c>
<c><spanx style="verb">root_context</spanx></c>
<c>An optional reference to the object with which the embedded
experience is associated. For instance, if the embedded experience is
included within an Activity, the root_context would refer to that
Activity. If contained within an email, however, the root_context would
refer to the email.</c>
<c><spanx style="verb">url</spanx></c>
<c>A URL to a web page that allows virtually any web-accessible
resource to be used as an Embedded Experience.</c>
</texttable>
<t>The "url" and "gadget" properties each reference content that is to
be embedded. Typically, an Embedded Experience will provide one or the
other. However, both properties MAY be specified. When both properties
are specified within the Embedded Experience, the decision about which
to render is left to the container.</t>
<t>When serialized as JSON, the embedded experience take the form of a
single JSON Object with four distinct properties: "context", "gadget",
"previewImage" and "url". Additional extension properties MAY be included
in the JSON object.</t>
<figure><preamble>For instance, a simple JSON Embedded Experience
that references an OpenSocial gadget:</preamble>
<artwork>
{
"gadget" : "http://www.example.com/embedded/gadget.xml",
"context" : {
"title" : "Hello World",
"id" : 123
},
"previewImage" : "http://www.example.com/embedded/123.png"
}
</artwork></figure>
<t>When serialized as XML, it is expressed in the form of a root element
<embed> containing four child elements: <context>,
<gadget>, <previewImage>, and <url>. Additional extension
elements and attributes MAY be included in the JSON object.</t>
<figure><preamble>For example,</preamble>
<artwork><![CDATA[
<embed>
<gadget>http://www.example.com/embedded/gadget.xml</gadget>
<context>
<title>Hello World</title>
<id>123</id>
</context>
<previewImage>http://www.example.com/embedded/123.png</previewImage>
</embed>
]]></artwork></figure>
<section title="Additional Examples">
<figure><preamble>A simple URL embedded experience using the JSON
serialization:</preamble><artwork>
{
"url" : "http://www.example.org/embed/123.html"
}
</artwork></figure>
<figure><preamble>The same URL embedded experience using the XML
serialization:</preamble><artwork><![CDATA[
<embed>
<url>http://www.example.org/embed/123.html</url>
</embed>
]]></artwork></figure>
<figure><preamble>An embedded experience that specifies both a gadget
and URL serialized as JSON:</preamble><artwork>
{
"gadget" : "http://www.example.com/embedded/gadget.xml",
"url" : "http://www.example.org/embed/123.html",
"context" : {
"title" : "Hello World",
"id" : 123
},
"previewImage" : "http://www.example.com/embedded/123.png"
}
</artwork></figure>
<figure><preamble>The same embedded experience serialized as XML:</preamble>
<artwork><![CDATA[
<embed>
<gadget>http://www.example.com/embedded/gadget.xml</gadget>
<url>http://www.example.org/embed/123.html</url>
<context>
<title>Hello World</title>
<id>123</id>
</context>
<previewImage>http://www.example.com/embedded/123.png</previewImage>
</embed>
]]></artwork></figure>
</section>
<section title="Considerations for Embedded Gadgets">
<section title="The "embedded" View">
<t>When rendering a gadget as an embedded experience, the container
will look within the gadget definition for a view named "embedded".
Gadget developers can used the "embedded" view to specify a customized
view of the gadget that is specific to the embedded experience. If
an "embedded" view is not found within the gadget definition, the
contain SHOULD render the gadget's default view.</t>
</section>
<section title="Accessing The Context">
<t>An embedded experience gadget has the option of requiring some
contextual information in order to render itself. By abstracting the
data from the gadget itself, gadget developers can develop
generalized gadgets that can be used for all embedded expereinces of a
specific type. For example, a gadget developed to display videos can
be built so that the id of the video is contained and extracted from
the embedded experience's "context" property.</t>
<figure><artwork>
{
"gadget" : "http://example.org/embedded/video.xml",
"context" : {
"video-id" : "abc123"
}
}
</artwork></figure>
<t>Gadgets that are written to support embedded experiences MUST require
the "embedded-experiences" feature within their gadget definition in
order to access the context. The contextual data is stored within the
<xref target="DataContext">data context</xref> object for the gadget.
The key, "org.opensocial.ee.context", is used to access the context.
Gadgets can add a listener on the data context object for this key, or
it may retreive the key's value by using the data context APIs.</t>
<figure><preamble>For instance, the Gadget below registers a listener
with the data context to retrieve any context data included with the
embedded experience:</preamble>
<artwork xml:space="preserve">
<Module>
<ModulePrefs title="Embedded Experiences Test" description="Tests the embedded experiences APIs.">
<Require feature="embedded-experiences"></Require>
</ModulePrefs>
<Content type="html" view="embedded">
<![CDATA[
<script type="text/javascript">
function myCallback(key){
var value = opensocial.data.getDataContext().getDataSet(key);
document.getElementById("contextData").innerHTML = "Context Information For This Gadget: " + value;
}
function initData() {
opensocial.data.getDataContext().registerListener('org.opensocial.ee.context', myCallback);
}
gadgets.util.registerOnLoadHandler(initData);
</script>
<div id="contextData"></div>
]]>
</Content>
</Module></artwork>
</figure>
</section>
<section title="Accessing the Root Context" anchor="rootContext">
<t>Every embedded experience is associated with a source object
known as it's "root context". For instance, for an embedded
experience contained within an Activity in a JSON Activity Stream,
the root context is often the containing activity. When rendered,
a gadget often needs to access information from the root context.</t>
<t>The value of the "root_context" property within the "embed" is
an object with two properties:</t>
<texttable>
<ttcol align="left" width="15%">Property</ttcol>
<ttcol align="left">Description</ttcol>
<c><spanx style="verb">id</spanx></c>
<c>Specifies the unique identifier of the root context object.
The specific format of the identifier is dependent on the type
of the root context.</c>
<c><spanx style="verb">type</spanx></c>
<c>Specifies the root context's object type as defined by the
Core Data specification [TODO: New Core Data Spec Ref].</c>
</texttable>
<figure><preamble>The following example shows an embedded experience
that references it's root context activity:</preamble>
<artwork>
{
"id" : "http://example.org/activities/1",
"verb" : "post",
"actor" : ...,
"object" : ...,
"openSocial" : {
"embed" : {
"gadget" : "http://example.com/embedded/foo.xml",
"root_context" : {
"id" : "http://example.org/activities/1",
"type" : "opensocial.Activity"
}
}
}
}
</artwork></figure>
<t>TODO: Complete this... Lots of questions need answering: see
http://docs.opensocial.org/display/OSD/More+precision+for+EE+data+model?focusedCommentId=6684693&#comment-6684693</t>
</section>
</section>
<section title="Preferred Experiences" anchor="preferredExperience">
<t>While the container retains control over deciding exactly how an
embedded experience is processed and rendered, there are situations
where the creator of the embedded experience might wish to provide
clues to the container as to how it would prefer the content to be
displayed. These clues are included within the Embedded Experience
using the "preferredExperience" property.</t>
<figure><preamble>The following illustrates a basic example:</preamble>
<artwork>
{
"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",
"preferredExperience" : {
"target" : {
"type" : "gadget",
"view" : "my-ee-view"
},
"display" : {
"type" : "link"
}
}
</artwork></figure>
<t>In this example, we have an embedded experience serialized as JSON.
The structure defines both a "url" and a "gadget" property, both of w
which can be used by the container to display embedded content. Typically,
the decision of which to display when the embedded experience is rendered
is up to the container. The "preferredExperience.target" property allows the
creator of the embedded experience to indicate that it would prefer the
container to use the "gadget" property for rendering, and specifically that
the "my-ee-view" view within that gadget be used. The "preferredExperience.display"
property indicates that rather than simply displaying the gadget automatically,
the embedded experience's creator would rather the container initially display a
hyperlink that, when clicked, causes the gadget to be displayed.</t>
<texttable>
<ttcol align="left" width="15%">Property</ttcol>
<ttcol align="left">Description</ttcol>
<c><spanx style="verb">display</spanx></c>
<c>Describes preferences for how the embedded experience should
initially be displayed by the container. The value of the
"display" property is an object that contains a
required "type" property, the value of which determines
what other properties might appear within the object.</c>
<c><spanx style="verb">target</spanx></c>
<c>Describes preferences for which type of embedded experience
the container should render. For instance, if the embed includes
both a "url" and "gadget" property, the "target" is used to specify
which is preferred. The value of the "target" property is an
object that contains a required "type" property, the value of which
determines what other properties might appear within the object.</c>
</texttable>
<section title="Display Types">
<t>This specification currently defines three possible values for the
type property on the display object: "link", "image", and "text".
Each of which are illustrated below.</t>
<figure><preamble>Display using a hyperlink:</preamble><artwork>
{
"gadget" : "...",
...,
"preferredExperience" : {
"target": {...},
"display": {
"type" : "link",
"text" : "Click on me!",
"title" : "Click on this link!"
}
}
}
</artwork></figure>
<t>When "type" equals "link", the additional properties on the
display object are:</t>
<texttable>
<ttcol align="left" width="15%">Property</ttcol>
<ttcol align="left">Description</ttcol>
<c><spanx style="verb">text</spanx></c>
<c>The text of the hyperlink.</c>
<c><spanx style="verb">title</spanx></c>
<c>The text to display as the "popup help" or "tooltip" of
the hyperlink.</c>
</texttable>
<figure><preamble>Display using the previewImage:</preamble><artwork>
{
"gadget" : "...",
...,
"previewImage" : "http://example.org/preview.png",
"preferredExperience" : {
"target": {...},
"display": {
"type" : "image",
"altText" : "The alt text",
"width" : 100,
"height" : 100
}
}
}
</artwork></figure>
<t>When "type" equals "image", the additional properties on the
display object are:</t>
<texttable>
<ttcol align="left" width="15%">Property</ttcol>
<ttcol align="left">Description</ttcol>
<c><spanx style="verb">altText</spanx></c>
<c>Specifies alternative text to display if the image cannot
be displayed. Equivalent to the HTML image tags alt attribute.</c>
<c><spanx style="verb">data</spanx></c>
<c></c>
<c><spanx style="verb">height</spanx></c>
<c>Specifies the display height of the image.</c>
<c><spanx style="verb">width</spanx></c>
<c>Specifies the display width of the image.</c>
</texttable>
<figure><preamble>Display using text:</preamble><artwork>
{
"gadget" : "...",
...,
"previewImage" : "http://example.org/preview.png",
"preferredExperience" : {
"target": {...},
"display": {
"type" : "text",
"content" : "This is some text"
}
}
}
</artwork></figure>
<t>When "type" equals "text", the additional properties on the
display object are:</t>
<texttable>
<ttcol align="left" width="15%">Property</ttcol>
<ttcol align="left">Description</ttcol>
<c><spanx style="verb">content</spanx></c>
<c></c>
</texttable>
<t>Implementations are free to define additional display types,
each with their own properties. If a container encounters an
embedded experience that uses an unknown or unsupported display
type, the container MUST ignore the display preferences.</t>
</section>
<section title="Target Types">
<t>This specification currently defines three possible values for the
type property on the target object: "gadget" and "url". Each of which
are illustrated below.</t>
<figure><preamble>Preferring the gadget target:</preamble><artwork>
{
"gadget" : "...",
"url" : "...",
...,
"preferredExperience" : {
"target": {
"type" : "gadget",
"view" : "my-ee-view"
},
"display": {
...
}
}
}
</artwork></figure>
<t>When "type" equals "gadget", the additional properties on the
target object are:</t>
<texttable>
<ttcol align="left" width="15%">Property</ttcol>
<ttcol align="left">Description</ttcol>
<c><spanx style="verb">view</spanx></c>
<c>The preferred gadget view to render.</c>
<c><spanx style="verb">viewTarget</spanx></c>
<c></c>
</texttable>
<figure><preamble>Preferring the url target:</preamble><artwork>
{
"gadget" : "...",
"url" : "...",
...,
"preferredExperience" : {
"target": {
"type" : "url",
"windowTarget" : "_new"
},
"display": {
...
}
}
}
</artwork></figure>
<t>When "type" equals "url", the additional properties on the
target object are:</t>
<texttable>
<ttcol align="left" width="15%">Property</ttcol>
<ttcol align="left">Description</ttcol>
<c><spanx style="verb">windowTarget</spanx></c>
<c></c>
</texttable>
<t>Implementations are free to define additional target types,
each with their own properties. If a container encounters an
embedded experience that uses an unknown or unsupported target
type, the container MUST ignore the target preferences.</t>
</section>
</section>
<section title="Security">
<t>Embedded experiences allow content to be rendered on the page that
user has not necessarily requested, therefore it needs to be secured.
The container SHOULD only ever render content that the user has
previously approved. This specification does not dictate how
secure rendering of embedded experiences is to be performed.</t>
</section>
<section title="Embedded Experiences within Activity Streams">
<t>Embedded experiences can be used within an Activity Streams
document in order to provide a more interactive experience. Whereas
the core properties of the Activity provide a textual description of
the event, an included embedded experience can provide a direct representation
of the object involved.</t>
<figure><preamble>For instance, if a user uploads a collection of photos
and creates a new photo album, an embedded experience can be used within
the activity to provide a representation of the album itself:</preamble>
<artwork xml:space="preserve">
{
"postedTime": "2011-02-10T15:04:55Z",
"actor": {
"objectType" : "person",
"id": "tag:example.org,2011:martin",
"displayName": "Martin Smith"
}
"verb": "post",
"object" : {
"objectType":"collection",
"objectTypes":["image"]
"id": "http://example.org/albums/germany-2009",
"url": "http://example.org/albums/germany-2009",
},
"openSocial" : {
"embed" : {
"gadget" : "http://example.org/AlbumViewer.xml",
"context" : {
"albumName": "Germany 2009",
"photoUrls": [
"http://examplephotos.com/3495/3925132517_5959dac775_t.jpg",
"http://examplephotos.com/3629/3394799776_47676abb46_t.jpg",
"http://examplephotos.com/4009/4413640211_715d924d9b_t.jpg",
"http://examplephotos.com/2340/3528537244_d2fb037aba_t.jpg",
"http://examplephotos.com/36/98407782_9c4c5866d1_t.jpg",
"http://examplephotos.com/48/180544479_bb0d0f6559_t.jpg",
"http://examplephotos.com/2668/3858018351_1e7b73c0b7_t.jpg"
]
}
}
}
}</artwork></figure>
<t>As illustrated in the example, when included within an activity,
the embedded experience MUST appear as the value of the "embed" property
as a child of the "openSocial" property.</t>
</section>
<section title="Embedded Experiences within Email">
<t>Numerous services send email notifications to your inbox in
order to let you know something took place that you may be
interested in. Most of the time however these notifications do not
provide much useful information beyond a link back to the service's
website. By leveraging embedded experiences, services can send an
embedded representation of the object the notification is about, and
allow the user to take action on the notification directly from within
an embedded experiences enabled email client.</t>
<t>Embedded experiences serialized as either JSON or XML can be embedded
Multipart MIME encoded email messages. Such email messages MUST utilize
the "multipart/alternative" MIME variant and MUST contain at least two
MIME parts -- one containing regular content of the email message as would
be typically sent to an email client (typically text/plain or text/html),
and another containing the embedded experience content using either the
"application/embed+json" or "application/embed+xml" MIME media type,
respectively representing the JSON and XML serializations. Additional
MIME parts MAY be included </t>
<figure>
<preamble>For instance,</preamble>
<artwork xml:space="preserve">
From: notifications@socialnetwork.com
To: johndoe@example.com
Subject: Social Network: Mary Has Commented On Your Status
MIME-Version: 1.0
Content-Type: multipart/alternative;
boundary="XXXXboundary text"
Mary has commented on your status.
--XXXXboundary text
Content-Type: text/plain
Mary has commeneted on your status.
--XXXXboundary text
Content-Type: text/html
<html>
<!-- HTML representation here -->
</html>
--XXXXboundary text
Content-Type: application/embed+json
{
"gadget" : "http://www.socialnetwork.com/embedded/commentgadget.xml",
"context" : 123
}</artwork>
</figure>
</section>
</section>