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.
| Code Block |
|---|
<!-- ///////////// --> <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> with one exception: the special property name <c>A"opensocial" URLis toreserved anfor OpenSocialuse Gadgetby definitionthe documentcontainer thatimplementation. defines the gadget to be embedded.</c> The "context" properties JSON object value or XML element structure <c><spanx style="verb">preferredExperience</spanx></c> MUST NOT contain a property named "opensocial".</c> <c>An optional collection of properties that describe the preferred <c><spanx style="verb">gadget</spanx></c> way<c>A theURL creatorto ofan theOpenSocial embeddedGadget experiencedefinition woulddocument likethat containersdefines tothe rendergadget to thebe contentembedded.</c> <c><spanx style="verb">previewImage<>imageData</spanx></c> <c>An optional URIstring tovalue an image that cancontaining beBase64-encoded usedbinary asdata afor previewan for the image resource that represents the embedded content.</c> This can be <c><spanx style="verb">root_context</spanx></c> <c>An optional reference to the object with which the embedded the same image resource linked to by the previewImage property or experiencea isseparate associatedimage. ForAn instance,embedded ifexperience theSHOULD embeddedNOT experiencecontain isboth includedthe withinimageData anand Activity, the root_context would refer to thatpreviewImage properties.</c> <c><spanx style="verb">preferredExperience</spanx></c> Activity. If contained within an email, however, the root_context would <c>An optional collection of properties that describe the preferred way the creator of the embedded experience would like containers to referrender to the emailcontent.</c> <c><spanx style="verb">url<>previewImage</spanx></c> <c>A<c>An optional URLURI to aan web pageimage that allowscan virtuallybe anyused web-accessible as a preview for the embedded content.</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,At anleast Embeddedone Experienceof willthese provideproperties oneMUST orbe the specified. other.When However, both properties MAY be specified. When both properties are specifiedused 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, the order of which is considered insignificant: <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"> <t>Note that no XML namespace is currently declared for the XML serialization. <figure><preamble>AThis simplemeans URLthat embeddedspecial experiencecare usingmust thebe JSON taken when serialization:</preamble><artwork> { "url" : "http://www.example.org/embed/123.html" } </artwork></figure> including an XML embedded experience into another type of XML document. For example, the following shows an XML embedded experience within <figure><preamble>Thea samepartial URLAtom embeddedEntry experienceDocument. usingNote the XMLaddition of serialization:</preamble><artwork><![CDATA[ <embed><spanx style="verb">xmlns=""</spanx> on the embed element in order <url>http://www.example.org/embed/123.html</url> </embed> ]]></artwork></figure>to "undeclare" the in-scope default XML namespace.</t> <figure><artwork><![CDATA[ <figure><preamble>An embedded experience that specifies both a gadget <entry xmlns="http://www.w3.org/2005/Atom"> <id>http://example.org/entries/1</id> ... and URL serialized as JSON:</preamble><artwork> {<embed xmlns=""> "gadget" : "http<gadget>http://www.example.com/embedded/gadget.xml",xml</gadget> "url" : "http://www.example.org/embed/123.html",<context> "context" :<title>Hello {World</title> "title" : "Hello World", <id>123</id> "id" : 123 </context> }, "previewImage" : "http://<previewImage>http://www.example.com/embedded/123.png"png</previewImage> }</embed> </entry> <]]></artwork></figure> <section title="Additional Examples"> <figure><preamble>A <figure><preamble>Thesimple sameURL embedded experience serializedusing the as XML:</preamble>JSON <artwork><![CDATA[serialization:</preamble><artwork> <embed>{ <gadget>http://www.example.com/embedded/gadget.xml</gadget> <url>http"url" : "http://www.example.org/embed/123.html</url>html" } <context> </artwork></figure> <title>Hello World</title> <figure><preamble>The same URL embedded experience using the XML <id>123</id> serialization:</context>preamble><artwork><![CDATA[ <embed> <previewImage>http<url>http://www.example.comorg/embeddedembed/123.png<html</previewImage>url> </embed> ]]></artwork></figure> </section> <figure><preamble>An embedded experience that specifies both a gadget <section title="Considerations for Embedded Gadgets"> and URL serialized as JSON:</preamble><artwork> { <section title="The "embedded" View">"gadget" : "http://www.example.com/embedded/gadget.xml", "url" : "http://www.example.org/embed/123.html", <t>When"context" rendering: a{ gadget as an embedded experience, the container"title" : "Hello World", "id" will: look123 within the gadget}, definition for a"previewImage" view: named "embedded"."http://www.example.com/embedded/123.png" } </artwork></figure> Gadget developers can used<figure><preamble>The thesame "embedded" viewexperience toserialized specify a customized as XML:</preamble> <artwork><![CDATA[ view<embed> of the gadget that is specific to the embedded experience. If <gadget>http://www.example.com/embedded/gadget.xml</gadget> <url>http://www.example.org/embed/123.html</url> an<context> "embedded" view is not<title>Hello foundWorld</title> within the gadget definition, the <id>123</id> </context> contain SHOULD render the gadget's default view.</t> <previewImage>http://www.example.com/embedded/123.png</previewImage> </embed> ]]></artwork></figure> </section> <section title="AccessingConsiderations Thefor ContextEmbedded Gadgets"> <t>An embedded experience gadget has the option of requiring some <section title="The "embedded" View"> contextual<t>When informationrendering ina ordergadget toas renderan itself.embedded Byexperience, abstractingthe thecontainer datawill look fromwithin the gadget itself,definition gadgetfor developersa canview developnamed "embedded". generalized gadgetsGadget thatdevelopers can beuse usedthis forview allto embeddedspecify expereincesa of acustomized specificview type.of Forthe example,gadget athat gadgetis developedspecific to the displayembedded videosexperience. can If bean built"embedded" soview thatis thenot idfound ofwithin the videogadget isdefinition, containedthe and extracted from contain SHOULD render the embedded experiencegadget's "context"default propertyview.</t> </section> <figure><artwork><section title="Accessing The Context"> { "gadget" : "http://example.org/embedded/video.xml", <t>An embedded experience gadget has the option of requiring some contextual "context"information :in {order to render "video-id" : "abc123"itself. By abstracting the } data }from the gadget itself, gadget </artwork></figure> developers can develop generalized <t>Gadgetsgadgets that can arebe writtenused tofor supportall embedded experiencesexpereinces MUSTof require a specific the "embedded-experiences" feature within their gadget definition in type. For example, a gadget developed to display videos can orderbe built toso accessthat the context.id Theof contextualthe datavideo is contained storedand withinextracted the from <xref target="DataContext">data context</xref> object for the gadget.the embedded experience's "context" property.</t> <figure><artwork> { The key, "org.opensocial.ee.context", is used to access the context. gadget" : "http://example.org/embedded/video.xml", "context" : { Gadgets can add a listener on the data context object for this key, or"video-id" : "abc123" } } </artwork></figure> it<t>Gadgets maythat retreiveare thewritten key'sto valuesupport byembedded usingexperiences theMUST data context APIs.</t> require <figure><preamble>For instance, the Gadget below registers a listenerthe "embedded-experiences" feature within their gadget definition in order to withaccess the data context. to The retrievecontextual anydata contextis datastored included withwithin the embedded experience:</preamble> <xref target="DataContext">data context</xref> object for the gadget. The <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">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 context = opensocial.data.getDataContext().getDataSet(key); var video_id = context["video-id"]; } 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 title="Additional Container Specific Context" anchor="rootContext"> <t>While the contextual data associated with the "org.opensocial.ee.context" key will generally originate from the information provided by the "context" property within the Embedded Experience document, containers are free to insert additional, container specific contexual data into the object. For example, a container might wish to communicate information about the type of parent object within which the Embedded Experience information was received.</t> <t>If such additional information is provided, the object associated with the "org.opensocial.ee.context" key will have an <![CDATA[ additional "opensocial" property, whose value is itself a <script type="text/javascript"> object with at least one property named "associatedContext" whose function myCallback(key){ value is an object whose properties are entirely defined by the varspecific valuecontainer = opensocial.data.getDataContext().getDataSet(key);implementation.</t> document.getElementById("contextData").innerHTML = "Context Information For This Gadget: " + value; <figure><preamble>The following example illustrates how this additional }context information is accessed:</preamble><artwork> function initDatamyCallback(key) { var context = opensocial.data.getDataContext().registerListener('org.opensocial.ee.context', myCallback)getDataSet(key); var video_id = context["video-id"]; var associatedContext = context.opensocial.associatedContext; // the properties are }container specific var ac_id = gadgets.util.registerOnLoadHandler(initData)associatedContext.id; var ac_type = associatedContext.type; </script>// ... } function initData() { <div id="contextData"></div> opensocial.data.getDataContext().registerListener( ]]>"org.opensocial.ee.context", myCallback); } </Content> </Module></artwork> gadgets.util.registerOnLoadHandler(initData); </artwork></figure> </section> <t>Specific container implementations are <section title="Accessing the Root Context" anchor="rootContext"> free to insert any additional information they <t>Everywish embeddedinto experienceboth isthe associated"associatedContext" withand a"opensocial" source object object knownvalues. asThe it's "root context". For instance, for an embedded interpretation and use of any such information is experience contained withinconsidered anout Activityof inthe ascope JSONof Activity Stream,this specification.</t> the root</section> context is often the</section> containing activity. When rendered, </section> a gadget often needs to access information from the root context.</t> <section title="Preferred Experiences" anchor="preferredExperience"> <t>While the container retains control over deciding exactly how an <t>Theembedded valueexperience ofis the "root_context" property within the "embed" is an object with two properties:</t> processed and rendered, there are situations where the creator of the embedded experience might wish to provide <texttable> clues to the container <ttcol align="left" width="15%">Property</ttcol> <ttcol align="left">Description</ttcol> as to how it would prefer the content to be displayed. <c><spanx style="verb">id</spanx></c> <c>Specifies the unique identifier of the root context object. These clues are included within the Embedded Experience using the "preferredExperience" property.</t> The<figure><preamble>The specificfollowing formatillustrates ofa thebasic identifierexample is dependent onserialized the typeas JSON:</preamble> <artwork> { of the"gadget" root context.</c>: "http://www.example.com/embedded/gadget.xml", "url" : "http://www.example.com/foo/bar.html", <c><spanx style="verb">type</spanx></c> context" : { <c>Specifies"title" the: root context's object type as defined by the"Hello World", "id" : 123 }, Core"previewImage" Data specification [TODO: New Core Data Spec Ref].</c>: "http://www.example.com/embedded/123.png", "preferredExperience" : { </texttable> "target" : { <figure><preamble>The"type" following example shows an embedded experience : "gadget", that references it's root context activity:</preamble>"view" : "my-ee-view" <artwork>}, { "iddisplay" : "http://example.org/activities/1",{ "verbtype" : "postlink", "actor"} : ..., } "object" : ...,</artwork></figure> "openSocial" : {<figure><preamble>And the same example using the alternative XML serialization:</preamble> "embed" : { <artwork><![CDATA[ <embed> "gadget" : "http<gadget>http://www.example.com/embedded/gadget.xml</gadget> <url>http://www.example.com/embeddedfoo/foo.xml",bar.html</url> <context> "root_context" : { <title>Hello World</title> <id>123</id> "id" : "http </context> <previewImage>http://www.example.org/activities/1", "type" : "opensocial.Activity" com/embedded/123.png</previewImage> <preferredExperience> <target> } }<type>gadget</type> } }<view>my-ee-view</view> </artwork></figure>target> <display> <t>TODO: Complete this... Lots of questions need answering: see <type>link</type> </display> </preferredExperience> </embed> http://docs.opensocial.org/display/OSD/More+precision+for+EE+data+model?focusedCommentId=6684693&#comment-6684693</t> ]]></artwork></figure> </section> </section> <section title="Preferred Experiences" anchor="preferredExperience"> <t>While the container retains control over deciding exactly how an <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 processed and rendered, there are situations whereis theup creator ofto the embeddedcontainer. experience might wish to provide The "preferredExperience.target" property allows the cluescreator toof the containerembedded asexperience to indicate howthat it would prefer the content to becontainer to use displayed. These clues are included within the Embedded Experience the "gadget" property for rendering, and specifically that using the "preferredExperience" property.</t> <figure><preamble>The following illustrates a basic example:</preamble>my-ee-view" view within that gadget be used. The "preferredExperience.display" property <artwork>indicates that {rather than simply "gadget"displaying : "http://www.example.com/embedded/gadget.xml"the gadget automatically, "url" : "http://www.example.com/foo/bar.html", "context" : { the embedded experience's creator would rather the container initially display a "title" : "Hello World", "id" : 123hyperlink that, when clicked, causes the gadget to be displayed.</t> <texttable> }, <ttcol align="previewImageleft" : "http://www.example.com/embedded/123.png",width="15%">Property</ttcol> <ttcol align="preferredExperienceleft" : {>Description</ttcol> <c><spanx style="target" : {verb">display</spanx></c> "type" : "gadget", <c>Describes preferences for how the embedded experience should initially be displayed "view"by : "my-ee-view" },the container. The value of the "display" : { property is an object that contains a required "type" : "link" }property, the value of which determines } </artwork></figure> <t>In this example, we have an embedded experience serialized as JSON. what other properties might appear within the object.</c> The structure defines both a "url" and a "gadget" property, both of w<c><spanx style="verb">target</spanx></c> <c>Describes preferences for which type of embedded experience which canthe becontainer usedshould byrender. theFor containerinstance, toif displaythe embeddedembed content.includes Typically, both thea decision"url" ofand which to display when the embedded experience is rendered"gadget" property, the "target" is used to specify which is uppreferred. toThe thevalue container.of Thethe "preferredExperience.target" property allowsis the an creator ofobject thethat embeddedcontains experiencea torequired indicate that it would prefer the"type" property, the value of which container todetermines usewhat theother "gadget"properties propertymight forappear rendering, and specifically that the "my-ee-view" view within that gadget be used. The "preferredExperience.display"within the object.</c> </texttable> <section title="Display Types"> property indicates<t>This thatspecification rathercurrently thandefines simplytwo displayingpossible thevalues gadgetfor automatically,the the embedded experience's creator would ratherrequired "type" property on the containerdisplay initially display a object: "link", "image". hyperlink that,Each whenof clicked,which causesare the gadget to be displayedillustrated below.</t> <texttable> <figure><preamble>Display using <ttcol align="left" width="15%">Property</ttcol> a hyperlink:</preamble><artwork> { <ttcol align="leftgadget">Description</ttcol> <c><spanx style="verb">display</spanx></c> : "...", ..., <c>Describes preferences"preferredExperience" for how the embedded experience should : { initially be displayed by the container. The value of the "target": {...}, "display": { property is an object that"type" contains a : "link", required "typetext" property,: the"Click value of which determines on me!", what"title" other: properties"Click mighton appear within the object.</c> this link!" <c><spanx style="verb">target</spanx></c>} } <c>Describes} preferences for which type of embedded experience </artwork></figure> the<t>When container"type" should render. For instance, if the embed includes equals "link", the additional properties on the bothdisplay a "url" and "gadget" property, the "target" is used to specifyobject are:</t> <texttable> which is preferred. The value of the "target" property is an <ttcol align="left" width="15%">Property</ttcol> <ttcol align="left">Description</ttcol> object that contains a required "type" property, the value of which determines what other properties might appear within the object<c><spanx style="verb">text</spanx></c> <c>A required String that provides the text to display with the hyperlink.</c> </texttable> <section<c><spanx titlestyle="Display Types"> verb">title</spanx></c> <t>This specification currently defines three possible values for the type property<c>Optional ontext theto display object:as the "link",popup help" or "imagetooltip", and "text".of Each of which are illustrated below.</t>the hyperlink.</c> </texttable> <figure><preamble>Display using athe hyperlinkpreviewImage:</preamble><artwork> { "gadget" : "...", ..., "previewImage" : "http://example.org/preview.png", "preferredExperience" : { "target": {...}, "display": { "type" : "linkimage", "altText" : "The alt text" : "Click on me!", "width" : 100, "titleheight" : "Click on this link!"100 } } } </artwork></figure> <t>When<figure><preamble>Display "type"using equals "link", the additional properties on the contained Base64-encoded binary data:</preamble><artwork> { "gadget" display object are:</t> : "...", ..., "imageData" <texttable> : "{Base64-encoded Image}", <ttcol align="leftpreferredExperience" width="15%">Property</ttcol> : { <ttcol align="lefttarget">Description</ttcol> : {...}, <c><spanx style="verb">text</spanx></c>display": { <c>The"type" text of the hyperlink.</c> : "image", "altText" <c><spanx: style="verb">title</spanx></c>"The alt text", <c>The text to display as the "popup help"width" or "tooltip" of : 100, the hyperlink.</c>"height" : 100 </texttable>} } } <figure><preamble>Display using the previewImage:</preamble><artwork>artwork></figure> { <t>When "gadgettype" :equals "...image", the additional properties on the ..., "previewImage"display :object "httpare://example.org/preview.png",</t> "preferredExperience" :<texttable> { "target": {...},<ttcol align="left" width="15%">Property</ttcol> <ttcol align="displayleft":>Description</ttcol> { "type" : "image",<c><spanx style="verb">altText</spanx></c> "altText" : "The alt text", "width" : 100,<c>Specifies optional, alternative text to display if the image cannot "height" : 100 } } }be displayed. Equivalent to the HTML image tags alt attribute.</c> </artwork></figure> <c><spanx style="verb">height</spanx></c> <c>Specifies the <t>Whenpreferred "type"display equals "image",height of the additionalimage properties on the in pixels.</c> display object are:</t><c><spanx style="verb">width</spanx></c> <c>Specifies the <texttable>preferred display width of the <ttcol align="left" width="15%">Property</ttcol>image in pixels.</c> </texttable> <ttcol align="left">Description</ttcol> <c><spanx style="verb">altText</spanx></c> <t>Implementations are free to define additional display types, <c>Specifieseach alternativewith texttheir toown displayproperties. ifIf thea imagecontainer cannot encounters an beembedded displayed.experience Equivalentthat touses thean HTMLunknown imageor tagsunsupported alt attribute.</c>display <c><spanx style="verb">data</spanx></c> type, the container MUST ignore the display preferences.</t> <c><</c>section> <c><spanx<section styletitle="verb">height</spanx></c>Target Types"> <t>This <c>Specifiesspecification thecurrently displaydefines heighttwo ofpossible the image.</c> values for the <c><spanx style="verb">width</spanx></c> <c>Specifies the display width of the image.</c>type property on the target object: "gadget" and "url". Each of which are illustrated below.</texttable> t> <figure><preamble>Preferring <figure><preamble>Displaythe usinggadget texttarget:</preamble><artwork> { "gadget" : "...", "url" : "...", "previewImage" : "http://example.org/preview.png"..., "preferredExperience" : { "target": {...}, "displaytype" : {"gadget", "typeview" : "text", my-ee-view" }, "contentdisplay": { : "This is some text" ... } } } </artwork></figure> <t>When "type" equals "text", the additional properties on the <t>Note that the preferred experience target's "type" property is only required displayif object are:</t> <texttable>the preferred target is not obvious within the embedded experience. <ttcol align="left" width="15%">Property</ttcol> <ttcol align="left">Description</ttcol>For instance, if the embedded experience only defines an <c><spanx style="verb">content</spanx></c> <c></c>IRI value for the "gadget" property, then the preferred target type </texttable> <t>Implementations are free to define additional display types,is "gadget". However, if both the "url" and "gadget" properties are specified, as eachin withthe theirexample ownabove, properties.the Iftarget atype containerin encountersthe an preferred embeddedexperience experienceMUST thatbe usesspecified. anContainers unknownMUST orignore unsupportedthe display preferred experience if the target type, thevalue containerdoes MUSTnot ignorematch the display preferences.</t> options specified </section>within the Embedded <section title="Target Types"> Experience (e.g. target type specifies "url" but only <t>Thisa specification"gadget" currentlyIRI definesis three possible values for the provided, etc).</t> <t>When "type" property on the target object: equals "gadget", and "url". Each of which the additional properties on the aretarget illustratedobject below.are:</t> <figure><preamble>Preferring<texttable> the gadget target:</preamble><artwork> { <ttcol align="gadgetleft" : "...",width="15%">Property</ttcol> "url" :<ttcol align="...",left">Description</ttcol> ..., <c><spanx style="preferredExperienceverb">view</spanx></c> : { "target": { "type" : "gadget",<c>The preferred gadget view to render. If not specified, the value "embedded" is assumed.</c> <c><spanx style="viewverb">viewTarget</spanx></c> : "my-ee-view" <c>Specifies where },the container SHOULD "display": { render the view. Possible ... values } } }are "TAB", "DIALOG", "MODALDIALOG", "FLOAT", and "SIDEBAR".</c> </artwork></figure>texttable> <t>When "type" equals "gadget",<figure><preamble>Preferring the additional properties on the url target:</preamble><artwork> { "gadget" target object are:</t> : "...", "url" : "...", <texttable> ..., <ttcol align="leftpreferredExperience" width="15%">Property</ttcol> : { <ttcol align="left">Description</ttcol>target": { "type" <c><spanx: style="verb">view</spanx></c>url", <c>The"viewTarget" preferred gadget view to render.</c> : "_new" }, <c><spanx style="verb">viewTarget</spanx></c>display": { <c></c>... </texttable>} } } <figure><preamble>Preferring the url target:</preamble><artwork> { </artwork></figure> <t>When "gadgettype" :equals "...url", the "url" : "...",additional properties on the ..., target "preferredExperience"object are:</t> { "target": { <texttable> <ttcol align="typeleft" : width="url15%",>Property</ttcol> "windowTarget" : "_new"<ttcol align="left">Description</ttcol> }, <c><spanx style="display": { verb">viewTarget</spanx></c> ...<c>When specifying a URL, }rather } } </artwork></figure> than being forced to render in an <t>When "type" equals "url"embedded view, the additionaldeveloper propertiesmay onwish the to indicate to the target object are:</t> container that <texttable>the page be opened in <ttcol align="left" width="15%">Property</ttcol> <ttcol align="left">Description</ttcol>a new browser window. In this case, the <c><spanx style="verb">windowTarget</spanx></c> target properties for a URL match those that are defined by the <c>< HTML spec, e.g. "_blank".</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 asencoded would be typically sent to an email client (typically as text/plain or text/html), html content, and another containing the embedded experience contentcontent using either the 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> |