More learnings from using EE: Can we add more precision to the model?

[Mark W.]

OK... We've been getting our (collective) ands and feet dirty with Embedded Experiences. Most of the experience (pun intended) has been awesome. But we have run into a few challenges that I'd like to get on the table for us to discuss, and from these discussions, distill a proposal for an updated EE model. 

It turns out that EE is quite useful and can be applied in many different areas inside our platform, e.g. in an activity stream, search results, etc. One of the issues that we are running into is how the EE should be rendered. This was part of the motivations for my earlier posts seeing if we can add a label, get the entire embed context, etc. 

More than that though is the fact that we'd like the app to be more involved in how the embedded experience is rendered. Here's the example from the spec:

"embed" : {
    "url" : "http://www.example.com/embedded/123",
  "gadget" : "http://www.example.com/embedded/gadget.xml",
  "context" : {
    "title" : "Hello World",
    "id" : 123
  },
  "previewImage" : "http://www.example.com/embedded/123.png"
}
...

The question becomes... How does the know how to display this to the user? We could say... "It's up to the container", but this completely eliminates the app from the decision. Further, even IF it's up to the container, it's not clear what it should do. Is the preview image for the URL? Is it for the gadget? Both? Where can we put link text for the url? What about hover help/tool tip? 

What we did was step back and looked at how we were using each field. It turns out that we do two basic things with the fields; use them for display, or use them to tell the container what to open. What we've come up with to address these issues is to bring precision to the use of the fields in the data model by encapsulating them inside a tag that tells the container their intended purpose.

For example, if we want to display an image, that displays a nice tool tip and when clicked, would open a URL, we use the following model:

1. "embed" : { 
2.     display: {  
3.         type: "image",  
4.         previewImage: "http://myserver.com/images/preview-128x128.png",  
5.         label: "This is a tooltip."  
6.     }  
7. target: {  
8.     type: "url",  
9.     url: "http://www.jivesoftware.com"  
10.    }  
11. }

If I wanted the same experience, except instead of opening up a URL, we want the embedded experience rendered, then the model would look like this:

1. "embed" : { 
2.     display: {  
3.         type: "image",  
4.         previewImage: "http://myserver.com/images/preview-128x128.png",  
5.         label: "This is a tooltip."  
6.     }  
7. target: {  
8.     type: "embedded",  
9.     view: "embedded.view_issue",  
10.     context: {  
11.         issueId: "1005"  
12.     }  
13. }  

In the model above, I get the same display rendering, e.g. a nice image & tooltip, but when it's clicked on, I get the embedded experience. We've found this model, in practice to be much more flexible than the existing EE model. It provides a cleaner conceptual model for both the developer and the container provider because it clarifies how the fields are used. Further this model will be easier to maintain for developers and container providers as we start to see more and more apps leverage EE. It also makes it easier for us to extend/expand the EE model again if we need to b/c we can simply add a new tag at the same level as target/display, e.g. "containerContext", or we can add new fields to either one without the risk of collision. 

What do you think??

-Mark W.

p.s. 

(Yes, Ryan, I'm choking back my vomit on the view there, but it turns out that b/c of the context, this is very helpful. I need more data points to understand if we can standardize them, e.g. embedded.search, but we are looking at it. And I'm still choking my vomit back.)

[Andy Smith]

Mark,

I like the addition of view to the model, which I think is needed.  This seems to be a logical approach.  Do you have use cases where you would need to manage multiple views or targets in the same model?   I could see the scenario where an EE needs to be rendered on a mobile vs desktop environment.  It would be reasonable for an app developer to define multiple view options in this case.

--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/FZSC2uzfrXkJ.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

--
Thank you,

Andy

[Ryan Baxter]

Mark, we need to finish our conversation from last time. I have been
swamped :( I would like to start a doc on ideas we have to enhance
embedded experiences. I would like to do enhancements in a way we
wont break providers supporting the existing embedded experiences
spec. Lets try and connect tomorrow.

> >    1. "embed" : {
> >    2.     display: {
> >    3.         type: "image",
> >    4.         previewImage: "
> >    http://myserver.com/images/preview-128x128.png",
> >    5.         label: "This is a tooltip."
> >    6.     }
> >    7. target: {
> >    8.     type: "url",
> >    9.     url: "http://www.jivesoftware.com"
> >    10.    }
> >    11. }

>
> > If I wanted the same experience, except instead of opening up a URL, we
> > want the embedded experience rendered, then the model would look like this:
>

> >    1. "embed" : {
> >    2.     display: {
> >    3.         type: "image",
> >    4.         previewImage: "
> >    http://myserver.com/images/preview-128x128.png",
> >    5.         label: "This is a tooltip."
> >    6.     }
> >    7. target: {
> >    8.     type: "embedded",
> >    9.     view: "embedded.view_issue",
> >    10.     context: {
> >    11.         issueId: "1005"
> >    12.     }
> >    13. }

>
> > In the model above, I get the same display rendering, e.g. a nice image &
> > tooltip, but when it's clicked on, I get the embedded experience. We've
> > found this model, in practice to be much more flexible than the existing EE
> > model. It provides a cleaner conceptual model for both the developer and
> > the container provider because it clarifies how the fields are used.
> > Further this model will be easier to maintain for developers and container
> > providers as we start to see more and more apps leverage EE. It also makes
> > it easier for us to extend/expand the EE model again if we need to b/c we
> > can simply add a new tag at the same level as target/display, e.g.
> > "containerContext", or we can add new fields to either one without the risk
> > of collision.
>
> > What do you think??
>
> > -Mark W.
>
> > p.s.
> > (Yes, Ryan, I'm choking back my vomit on the view there, but it turns out
> > that b/c of the context, this is very helpful. I need more data points to
> > understand if we can standardize them, e.g. embedded.search, but we are
> > looking at it. And I'm still choking my vomit back.)
>
> >  --
> > You received this message because you are subscribed to the Google Groups
> > "OpenSocial and Gadgets Specification Discussion" group.
> > To view this discussion on the web visit

> >https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/FZSC2uz...
> > .

[Mark W.]

Sounds great! One thing to keep in mind is that since we've got a new version of the spec (3.0), we have the ability to modify the API contracts. In terms of compatibility, the top level tags that we have are not currently used, so at least there would be no collisions. For example, in 2.0, if people are just getting the context passed in to their app, that's still possible to do. However, we need the entire embed structure, so we'll always be passing that in via the ee context. 

[Mark W.]

We are keeping it very simple. Adding multiple views or multiple targets adds back the convoluted container logic that has to be exposed to the developer. The approach we are taking is that if you need multiple presentations or multiple targets, you include a new embed tag. This is very clean for the developer and very clean for the container.

[James M Snell]

Just as an aside, With proper versioning in 3.0 updating the EE and continuing to support the existing stuff becomes pretty straightforward.

On Feb 10, 2012 6:38 AM, "Mark W." <weitze...@gmail.com> wrote:

Sounds great! One thing to keep in mind is that since we've got a new version of the spec (3.0), we have the ability to modify the API contracts. In terms of compatibility, the top level tags that we have are not currently used, so at least there would be no collisions. For example, in 2.0, if people are just getting the context passed in to their app, that's still possible to do. However, we need the entire embed structure, so we'll always be passing that in via the ee context. 

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/3doDDp91jeMJ.

[Mark W.]

@james +1

[Ryan Baxter]

Would I be allowed to leave the display property out of this revised
data model? Embedded experiences in emails would not really need this
information.

Can I include multiple targets? What if I wanted to provide both a
URL embedded experience and a gadget embedded experience? The current
data model allows for this and I would want to retain this
functionality.

Can we standardize that the view will either have to be the primary
view embedded or a sub view of this primary view?

I still have concerns about gadgets developed against 2.x being
backward compatible with 3.0. Gadget for 2.x would expect one data
model but in 3.0 they get something completely different. I suppose I
will have to look at how we handle versioning in 3.0. (both from a
gadget and container side of things)

On Feb 14, 3:30 pm, "Mark W." <weitzelm.w...@gmail.com> wrote:
> @james +1

[Mark W.]

Sure, we can make display optional. 

No. You cannot include multiple targets. The reason is that we want to keep it simple for the app developer and the container implementor. What you CAN do is have multiple embed tags. 

I think the view should default to embedded if not specified. I'm hesitant to force it to be embedded or a subview of embedded b/c we're still experimenting with mobile and not sure how that will work. 

Agree with the forward/backward compatibility. However, I think your other post on the spec timing is relavent here. We are just getting momentum on EE and making a change now is probably very containable. 

[Ryan Baxter]

Mark being able to specify multiple targets is key to not looking
functionality from the functionality in 2.0. As far as keeping it
simple, this new data model is already more complex than the original
one. I agree some of it may be necessary to support more than the
basic scenarios, but if we are talking about keeping things simple we
might want to see if we can refine things more. I am envision only
having 1 or 2 targets no more. In the majority of cases there will
just be one, but having 2 allows for the most flexibility to the
embedded experience provider. It wont get any more complex than this.

"embed" : {
display: {
type: "image",
previewImage: "http://myserver.com/images/preview-128x128.png",

label: "This is a tooltip."

},
targets: [
{

type: "embedded",
view: "embedded.view_issue",
context: {
issueId: "1005"

},
{

type: "url",
url: "http://www.jivesoftware.com"
}

]
}

For IBM we will likely have to end up supporting both because we will
have partners building against 2.0 for sure. This probably wont be
the end of the world since we can probably use a combination of the
data model and versioning to identify what the gadget expects.

[Mark W.]

I disagree that this new model is more complex than the original one. While there might be fewer fields, the commingling of the display/target concepts made it difficult to apply to new scenarios. For this reason, I'd say rather that the original model had some hidden complexity we didn't initially uncover until we tried to apply it in different ways. 

One of the main objectives with this proposal was to be able to disambiguate a) how to show to the user the EE and b) what to do when the user took action. The issues with the example above is that it makes the same assumption as the original model: that one display will work with multiple targets. That's not necessarily the case. 

For example, the label that you give a preview image may not be the same that you want displayed in the anchor tag of a URL. Consider gliffy. I might have a thumbnail where I want the label to read: "Click to edit in Glliffy", which is shown to the user when they hover over the image. However, when I have a link, I want it to read something like: "New process flow".

If the primary use case is that there will be only one embed, then why would we need to have a target array? That seems like extra overhead and it would be cleaner to simply allow for multiple embed tags. No conditional logic on the part of the implementing container. In the situation where we have multiple embed tags, then the container can choose the one they would like to display. For example, in iNotes, maybe only the URL type would be supported where Connections supports both. 

Overall, the simplifying assumption that we are putting forward is that the embed is an atomic unit--this display goes with this target. Having multiple targets reintroduces the confusion--for both developers and container providers--that we are looking to clarify in the first place. 

[Ryan Baxter]

I dont see why one display wont work with multiple targets. For me
the display and the type of EE are disjoint. In the above example the
service is saying use this display for this EE, whether it be a URL or
a gadget. I dont see why that wont work. If I don't have a preview
image then I can provide some link text. What I see being a bigger
problem is if the container only supports link displays and not
preview images, then what does the container show. Or, what does the
container show if it wants a display and the service doesn't provide
one in the data model?

The container may only display one embed, but me as a service
providing an EE I want to support all types of containers, whether
they support OpenSocial gadgets or not. Therefore my EE data model
should have both types of targets, so I can have my EE displayed in
the widest array of containers. Connections would choose to render
the taget with the type embedded while iNotes would choose to render
the EE with the type url, but me as the service provider did not need
to know that I can just provide the same data model.

[Ryan Baxter]

Just wanted to add something else...

The multiple targets also allows the container to "fallback" if it
can't render the gadget (ie it got a 404 trying to render the
gadget). If that happens then the container can choose to render the
URL EE if it is provided. Another use case could be if you wanted to
provide the "full" experience by going out the the actual application
via a URL.

Matt also came up with a good idea on how to deal with passing the
whole context in a reasonable way that won't break anything. If we
really need to pass the whole context than we could introduce a new
key for the data context which would pass the whole context object.
This would involve adding another API besides the one I suggested we
add here http://code.google.com/p/opensocial-resources/issues/detail?id=1249

[Henry Saputra]

I'd like to add support for different view in the Apache Shindig if
its ok. The code will simply check if view render params is passed and
respect that selection instead of embedded

- Henry

[Ryan Baxter]

It is certainly feasible, but the view to use would have to be
specified in the data mode, something similar to what Mark proposed.
We would probably need to specify what we fall back to if nothing is
in the data model. Maybe we always fall back to embedded.

On Feb 23, 2:00 pm, Henry Saputra <henry.sapu...@gmail.com> wrote:
> I'd like to add support for different view in the Apache Shindig if
> its ok. The code will simply check if view render params is passed and
> respect that selection instead of embedded
>
> - Henry
>
>
>
>
>
>
>
> On Thu, Feb 9, 2012 at 11:30 AM, Andy Smith <and...@gmail.com> wrote:
> > Mark,
>
> > I like the addition of view to the model, which I think is needed.  This
> > seems to be a logical approach.  Do you have use cases where you would need
> > to manage multiple views or targets in the same model?   I could see the
> > scenario where an EE needs to be rendered on a mobile vs desktop
> > environment.  It would be reasonable for an app developer to define multiple
> > view options in this case.
>

> >>https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/FZSC2uz....

[Henry Saputra]

You are right, I thought about getting it from the render params for
now as final resolution before getting back to embedded view.

Is the EE extension discussion on the schedule for the working session?

- Henry