application/gadget URLs and the pain of requestNavigateTo

[Nat Brown (ilike.com)]

There are a lot of painful implications to how requestNavigateTo works
within OpenSocial that should be addressed asap. Failure to fix these
issues will hinder developers and business models on the platform.
Here is my suggestion.

Currently applications emit at the server or rewrite on the client
simple links into complicated javascript calls. For us in iLike,
instead of generating:

<a href="/ilike/artist/Led+Zeppelin">Led Zeppelin</a>

we find ourselves generating

<a href="/ilike/artist/Led+Zeppelin"
onClick="gadgets.views.requestNavigateTo(new
gadgets.views.View('canvas'), {path: 'artist/Led+Zeppelin'});return
false">Led Zeppelin</a>

Going through container javascript to navigate isn't the worst thing
in the world, but the fact that there is no real URL in the browser
has several perhaps non-obvious implications to the user experience,
business model, and technical layering which are worth thinking about
and fixing:

1) when links are real HREF's in the browser, users can see where
they are going when they hover over things, and they can copy/paste
links and send them to friends. They can DIGG them, they can post them
to facebook, they can copy them into google bookmarks. They can save
them in their browser favorites. They can open links in new tabs. They
can do none of these things in opensocial containers right now.

2) Links to canvas pages from activity stream items and any kind of
container notifications are also not going to work trivially -- gadget
javascript is not involved, we need to embed specific links into
activity streams, notifications, and messages. we can't do that right
now.

3) From a development perspective, the links are not only more
readable for us and lead us to the code backing them more quickly, but
we can also paste such links into our ticketing system and find and
resolve issues more quickly rather than needed to create tickets that
describe the steps to get to a sub-page. We can also concatenate
suffixes from production links onto our private workspace or staging
links to test out fixes. Partners can send us links that are broken or
that they have a question about. Customers can point us at particular
pages that have a problem, or our help buttons can automaticaly send
us the page the user was on. We can use simple site performance and
uptime monitoring tools to see how our opensocial application is
performing if we have URLs. When we don't have real URLs in some
fashion, all of this stops and our development process slows down and
our customers and partners do not bother taking the time to send us
feedback, or they are frustrated by the process, and we can't easily
monitor the uptime or performance of our application from an end-user
perspective. We get reports like "on the NNN artist page on Orkut
there is a link to a concert on July 3rd at the Gorge amphitheatre..."
we can ping our web cluster for basic uptime/performance, but we can't
ping specific user or canvas pages to see whether something is broken.
This makes developing for and supporting OpenSocial painful.

4) Also from a development perspective, when we use real URLs a whole
class of URL-signing and parameter-passing bugs that have plagued each
container and which continue plaguing us daily here would have been
eliminated or minimally easier to track down. Encoding & signing " "
and "+" was broken. UTF8 characters like Mötley Crüe weren't working.
All this because containers don't know exactly what to encode or how
and are doing it within JSON blobs. It's unclear why this wheel of URL-
encoding is being reinvented.

5) if there are javascript errors anywhere on the page and javascript
stops running, navigation simply breaks, which is a horrendous user
experience. They can refresh, but they can't go anywhere within our
content -- not good and makes our applications and opensocial feel
flaky. This happens regularly.

6) Finally from a business model perspective, real URLs give us the
ability to create ads and external references that refer to our canvas
pages. It allows us to cross-promote our applications and our canvas
pages between different opensocial containers and facebook and our own
sites. It allows applications to cross-link with one another within a
containers, for promotional or other reasons. It allows us to email
users and give them a link to visit Hi5, Orkut, or MySpace versions of
iLike and add our application, and it allows us to do conversion-
tracking for installs from ads or email pointers and to optimize our
conversion to installation. We have none of this without URLs. The
most trivial example of this kind of utility which opensocial recently
lost traffic from is that we launched a new REM album for free
streaming on 3/24 exclusively with iLike. We were able to point users,
the press, record labels, and bands (including the band itself, REM)
to http://apps.facebook.com/ilike/rem and to http://www.ilike.com/rem.
We have no URL to point press/analysts or the band to on Orkut, Hi5,
MySpace. On REM's "artist dashboard" on ilike we can point them to
their iLike-generated artist pages in non-OpenSocial containers so
they can preview how the songs and videos they are posting will appear
to their fans. We can't point them to their OpenSocial canvas pages.

You may think that this level of url cross-referencing is only useful
to complex/deep apps with many canvas pages like ours. This is not the
case -- even the smallest applications benefit from the business model
and development implications of URLs that can fall back on pure
navigation.

So, in a nutshell, here's the ideal API from my perspective: users can
copy-paste the URLs and we can construct urls offline or server-side
(given a known root, which ideally would be http://apps.<container>.com/ilike,
but fine with us if it's anything fixed like http://<container>/app_100)
and end up back in our application, but we actually use
requestNavigateTo under the covers which does all the good things
containers apparently need in all the different contexts and we can
support zany things like desktop/offline containers.

<a href="http://apps.<container>.com/ilike/artist/Led+Zeppelin?
a=1&b=1" onClick="gadgets.views.requestNavigateTo({view : 'canvas',
url : 'artist/Led+Zeppelin?a=1&b=1'}); return fa">Led Zeppelin</a>
OR
<a href="ilike/artist/Led+Zeppelin?a=1&b=1"
onClick="gadgets.views.requestNavigateTo({view : 'canvas', url :
'artist/Led+Zeppelin?a=1&b=1'}); return fa">Led Zeppelin</a>

(the latter if the iframe host puts our docroot into place as they
host our manifest, or we could do that ourselves given a fixed base
URL)

Note that I would prefer this was shortened to take an URL instead of
making us do all the path, options crud to indicate a GET -- this is
just code that each application duplicates over and over again and we
should optimize the most common case. If you couldn't do that we could
stick with the longer convoluted arguments -- I don't really mind,
though I think it creates an irritating barrier to entry for
programmers to figure out for this API -- we would probably be
rewriting this content on the client by looking for rel="nofollow" or
some such on <a tags, like:

<a rel="nofollow" href="ilike/artist/Led+Zeppelin?a=1&b=1">Led
Zeppelin</a>

Which we would convert/rewrite at the client to have the onClick=
within them.

Thx, n@

[Kevin Brown]

I think that, fundamentally, Nat is right. Links should be links. They've served the web quite well for decades. I'm personally quite annoyed with the way navigation works (or doesn't) in most widgets on the web, whether we're talking about opensocial gadgets or not. A lot of this is just tied to differences between normal web navigation and the javascript-heavy approaches being favored lately, and the architecture of opensocial is such that it strongly favors a javascript-heavy approach, to a certain extent at the expense of simpler applications that are more like traditional web pages.

This means that if I'm developing a widget that is more "application"-like, such as an email or IM client, the opensocial model works quite well, but if I'm developing something more "web page" like, such as a directory of artists, a simpler html-based approach is really more ideal.

Some other problems:

1. Not all containers have the same format. For a fixed container, it's trivial to dictate url format, because you only have to worry about one container and their url structure is all that matters. This works fine if you're only targeting just facebook or just myspce, but it stops working when you have to deal with 10 different containers, each with their own format.

We could mandate that all containers have some fixed url format, but I have a feeling that getting containers to agree on the format would be difficult at best. Rewriting is a pretty good idea, but it falls down when you have dynamically generated content, so we'd still have to come up with a function to generate dynamic links as well.

2. Gadgets are in iframes

This is probably a more fundamental issue. Navigation when you're in an iframe is difficult, because you've got two types of navigation: changing the parent page, and changing some iframe parameters. The former problem can mostly be solved by opening the link in a new tab. This doesn't quite cover situations such as linking to a different gadget or a different viewer, but it covers a lot of other situations. The latter problem is more complex.

3. Some containers don't want to allow navigation at all, or at least not in certain contexts.

--
~Kevin

[John Panzer]

+1 - blogspot, for example, really really wants real linkable urls
wherever possible.

-John

On Mar 27, 2008, at 11:49 PM, "Nat Brown (ilike.com)"

[Evan Gilbert]

Nat - all really good points.

I think it will be difficult to standardize URLs across containers, even given a common server base. One particular problem will be with more AJAX-y applications - even if we all agree, some will want to navigate to http://container.com/#ilike?params and some to /ilike?params (the # allows you to fake navigation without an actual browser navigation request). It's worth starting the discussion to see if we could all agree on a convention, but I'm not sure we'll converge.

Would it work if we had an API for getting a URL for a given container, i.e.: opensocial.getUrlFor(app, path, params). This would allow containers to have their own URL schemes but also support getting a URL you could actually put into links. It's a bit less convenient, as you wouldn't be able to easily generate per-container URLs from your own servers, but it avoids trying to get consensus on URL structures which seems a little daunting.

Evan

[John Panzer]

-John

On Mar 28, 2008, at 8:14 AM, Evan Gilbert <uid...@google.com> wrote:

Nat - all really good points.

I think it will be difficult to standardize URLs across containers, even given a common server base. One particular problem will be with more AJAX-y applications - even if we all agree, some will want to navigate to http://container.com/#ilike?params and some to /ilike?params (the # allows you to fake navigation without an actual browser navigation request). It's worth starting the discussion to see if we could all agree on a convention, but I'm not sure we'll converge.

Would it work if we had an API for getting a URL for a given container, i.e.: opensocial.getUrlFor(app, path, params). This would allow containers to have their own URL schemes but also support getting a URL you could actually put into links. It's a bit less convenient, as you wouldn't be able to easily generate per-container URLs from your own servers,

Add to the RESTful APIs?

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com
To unsubscribe from this group, send

[Graham Spencer]

Would it be sufficient for a container to specify a URL template, e.g.

http://container.com/apps/${appName}/${appPath}?${appParams}
http://apps.container.com/${appName}#${appPath}?${appParams}
http://container.com/?app=${appName}&path=${appPath}&${appParams}

We could have a JS method and/or a RESTful method for returning the template, but the template would be assumed to be effectively permanent so apps wouldn't actually have to query it at runtime. That way they could build URLs on the server side.

--g

[Kevin Brown]

On Fri, Mar 28, 2008 at 2:25 PM, Graham Spencer <g...@google.com> wrote:

Would it be sufficient for a container to specify a URL template, e.g.

http://container.com/apps/${appName}/${appPath}?${appParams}
http://apps.container.com/${appName}#${appPath}?${appParams}
http://container.com/?app=${appName}&path=${appPath}&${appParams}

We could have a JS method and/or a RESTful method for returning the template, but the template would be assumed to be effectively permanent so apps wouldn't actually have to query it at runtime. That way they could build URLs on the server side.

You can't really make it permanent, because that would prevent the container from ever changing their url structure, which may become necessary for other reasons (such as domain name changes). It's also quite possible that you'd have something like locale information in the url, e.g.:

apps.container.com/...
apps.container.cn/...
apps.container.co.uk/...

I don't think just adding the container domain to the template resolves this, because then you'd just need another API for getting the container domain.

There's also an issue with parameter naming. If the site has some parameters passed in the query string, and other parameters are passed to the gadget, you've got a conflict. Sites that have taken care to construct urls to get around this wouldn't be affected, but otherwise a parameter naming scheme would be necessary, or a function (REST / js) would be necessary to produce the final url.
 

--
~Kevin

[Graham Spencer]

On Fri, Mar 28, 2008 at 2:38 PM, Kevin Brown <et...@google.com> wrote:

On Fri, Mar 28, 2008 at 2:25 PM, Graham Spencer <g...@google.com> wrote:

Would it be sufficient for a container to specify a URL template, e.g.

http://container.com/apps/${appName}/${appPath}?${appParams}
http://apps.container.com/${appName}#${appPath}?${appParams}
http://container.com/?app=${appName}&path=${appPath}&${appParams}

We could have a JS method and/or a RESTful method for returning the template, but the template would be assumed to be effectively permanent so apps wouldn't actually have to query it at runtime. That way they could build URLs on the server side.

You can't really make it permanent, because that would prevent the container from ever changing their url structure, which may become necessary for other reasons (such as domain name changes).

Although I agree in principle, I think in practice most sites try pretty hard to preserve their old URLs.

At worst, the method could return a TTL indicating how long an app can rely on the template.
 

It's also quite possible that you'd have something like locale information in the url, e.g.:

apps.container.com/...
apps.container.cn/...
apps.container.co.uk/...

I don't think just adding the container domain to the template resolves this, because then you'd just need another API for getting the container domain.

I'd be in favor of leaving this out of the spec until a container actually requests it.
 

There's also an issue with parameter naming. If the site has some parameters passed in the query string, and other parameters are passed to the gadget, you've got a conflict. Sites that have taken care to construct urls to get around this wouldn't be affected, but otherwise a parameter naming scheme would be necessary, or a function (REST / js) would be necessary to produce the final url.

Parameter naming could probably be expressed through some simple pattern rules, right?

I agree that we lose some theoretical generality by trying to create a static policy instead of requiring all URLs to be calculated at runtime, all the time. However, there are huge developer benefits to being able to create URLs on the server without pinging an OpenSocial API; I think in practice most containers will want relatively long-lived URLs; and I think most naming rules will be easily expressible. So I recommend that we design this for reasonable extensibility but we don't let somewhat speculative cases prevent us from enabling easy URL rules that will work on all current containers.

--g

[fer...@gmail.com]

So did this thread just die?
Does anybody care about generating clean urls in a standard cross-
container manner?

> tohttp://apps.facebook.com/ilike/remand tohttp://www.ilike.com/rem.

> We have no URL to point press/analysts or the band to on Orkut, Hi5,
> MySpace. On REM's "artist dashboard" on ilike we can point them to
> their iLike-generated artist pages in non-OpenSocial containers so
> they can preview how the songs and videos they are posting will appear
> to their fans. We can't point them to their OpenSocial canvas pages.
>
> You may think that this level of url cross-referencing is only useful
> to complex/deep apps with many canvas pages like ours. This is not the
> case -- even the smallest applications benefit from the business model
> and development implications of URLs that can fall back on pure
> navigation.
>
> So, in a nutshell, here's the ideal API from my perspective: users can
> copy-paste the URLs and we can construct urls offline or server-side

> (given a known root, which ideally would behttp://apps.<container>.com/ilike,

> but fine with us if it's anything fixed like http://<container>/app_100)

> and end up back in our application, but we actually userequestNavigateTounder the covers which does all the good things

[Graham Spencer]

In keeping with the proposal for spec changes that Cassie just announced (+1 on that BTW), let's make an official call for spec change on this topic.

I'll officially propose what I informally proposed above: we should add JS and RESTful API methods that allow apps to fetch a (long-lived) URL template.

opensocial.containerUrlTemplate = function() { ... }

This returns a string containing "${}" variables. The three supported variables are:
- name: the name or id of the application
- path: an application-defined path string
- params: application-defined parameters, query-encoded.

Examples of URL template strings:
http://container.com/apps/${name}/${path}?${params}
http://apps.container.com/${name}#${path}?${params}
http://container.com/?app=${name}&path=${path}&${params}

For discussion:
- Should we add other parameters, e.g. locale?
- Should we add configuration for parameter prefixing as proposed by Kevin? (In that case containerUrlTemplate might return an object instead of just a string, and the object would have a second template for parameter names, e.g. "up_${paramName}".)
- Do we standardize on application id? This is a tricky issue -- I'm inclined to say that an app name is the same as a domain name, but that might be beyond the scope of 0.8 changes.
- Should we use "{}" instead of "${}"? The latter is consistent with the current proposal for OpenSocial templates, but the former is consistent with a separate proposal for URI templates: <http://bitworking.org/news/URI_Templates>.
- How long should the template live? Is it permanent, or can the container specify an expiration (again by returning an object)?

Or we can do something else entirely, but if people have strong objections, let's get another proposal on the table before the 18th.

--g

[David Primmer]

I don't know why OpenSocial chose ${} but I don't see a reason for a
divergence from Joe's draft spec
http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt

I also want to add that in addition, the API server will provide a
service document to allow clients to discover the various endpoints
available. http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.html#appdocs
Right now I'm assuming the three workspaces: people, activities and
app data, but if the app data store is not the right place to store
this info, maybe we could add another workspace with app urls.
Navigating these docs can be a little heavy weight so maybe we could
expose the methods we use to generate it for quicker json-rpc-like
access.

davep

[Vasudeva Nori]

It is really not possible to statically enumerate the collections on, for example Person or Activity because many of the collections are defined based on the data available.
For example, friends of FOO collection is defined when FOO is a valid Person. If the person doesn't exist, then a service document cannot include this collection - but it doesn't mean the collection won't exist in the future.
Worse yet, the above collection may exist at the time of service document retrieval but may not exist after sometime, if FOO is no longer valid.

so, implementing service document retrieval is not really that useful.
and it is not part of the proposal by John Panzer originally..
 

[David Primmer]

On Thu, Apr 10, 2008 at 12:01 PM, Vasudeva Nori <vasu...@gmail.com> wrote:
> On Thu, Apr 10, 2008 at 11:25 AM, David Primmer <david....@gmail.com>
> wrote:
> > I don't know why OpenSocial chose ${} but I don't see a reason for a
> > divergence from Joe's draft spec
> > http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt
> >
> > I also want to add that in addition, the API server will provide a
> > service document to allow clients to discover the various endpoints
> > available.
> http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.html#appdocs
>
> It is really not possible to statically enumerate the collections on, for
> example Person or Activity because many of the collections are defined based
> on the data available.
> For example, friends of FOO collection is defined when FOO is a valid
> Person. If the person doesn't exist, then a service document cannot include
> this collection - but it doesn't mean the collection won't exist in the
> future.
> Worse yet, the above collection may exist at the time of service document
> retrieval but may not exist after sometime, if FOO is no longer valid.
>
> so, implementing service document retrieval is not really that useful.
> and it is not part of the proposal by John Panzer originally..

Ok, so you're saying service docs don't work for dynamic web services,
only simple static publishing? I think they're specified rather
loosely and I haven't seen many non-trivial examples that would prove
what you're saying. In the absence of a specific description format
like OpenSearch, what about a WADL file?

Sorry this is getting a little off topic from the proposed URI template RPC.

davep

[Vasudeva Nori]

we need dynamic discovery of resources (workspaces, collections), in the absence of a "reliable" service document.
By that I mean, a mechanism to discover the URLs for resources - not templates, but complete and accurate URLs.
Don't know of any such mechanism available right now. No agreement on WADL in the community yet. 

[Cassie]

Okay - going back to the js apis for a moment. Graham suggested a
container url template approach. I would like to propose an additional
solution:

/**
* Returns a url for navigating to the current app on the given
surface. Will include the path and parameters in the url. Similar to
requestNavigateTo.
*
* @param {gadgets.views.View} view The view to navigate to
* @param {String} path The path to navigate to
* @param {Map.&lt;String, String&gt;} opt_params Parameters to pass to the
* gadget after it has been navigated to on the surface
*
* @return {String} a url that can be used by the gadget
* @member opensocial
*/
gadgets.views.getUrlFor = function(surface, path, opt_params) {};

So, for 0.8 would we rather:

1. Add a method to fetch a url template from the container. This would
be what Graham proposed (except it might fit better on the
gadgets.views object instead of opensocial) or
2. Add a method to get a url for a given surface, path and set of
params. (The method right above)

Please vote or suggest other proposals.

Thanks!

- Cassie

[fer...@gmail.com]

Good start, I would ask to add ownerId to any of these proposals.

> - CassieOn Thu, Apr 10, 2008 at 9:36 PM, Vasudeva Nori <vasun...@gmail.com> wrote:
>
> > On Thu, Apr 10, 2008 at 12:24 PM, David Primmer <david.prim...@gmail.com>
> > wrote:
>
> >> On Thu, Apr 10, 2008 at 12:01 PM, Vasudeva Nori <vasun...@gmail.com>

> >> wrote:
> >> > On Thu, Apr 10, 2008 at 11:25 AM, David Primmer

> >> > <david.prim...@gmail.com>

> >> > wrote:
> >> > > I don't know why OpenSocial chose ${} but I don't see a reason for a
> >> > > divergence from Joe's draft spec
> >> > >http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt
>
> >> > > I also want to add that in addition, the API server will provide a
> >> > > service document to allow clients to discover the various endpoints
> >> > > available.
>

> >> >http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.ht...

[Graham Spencer]

The main reason I had proposed the container URL template approach was so that developers could quickly and easily generate URLs on their own servers without having to make either JS or RESTful API calls (except maybe once the first time).

So I like the idea of having a JS function that actually generates the URL, but I don't think it's sufficient if we want server-side URLs to be easy to create. Cassie -- do you have thoughts or suggestions about the server-side URL issue?

--g

[Kevin Brown]

I agree with Graham -- being able to pre-generate urls is very important, especially when the data is ultimately fetched over HTTP and can't take advantage of templating mechanisms and the like. My chief concern is ensuring that the url generation scheme is sound.

--
~Kevin

[Brandon Duncan]

+1 from LinkedIn. Especially when it comes to embedded links to canvas
pages in activity feeds. We had discussed making our own ${canvas_url}
token and do replacement on our servers, but we know developers are
going to want to generate these URLs on their own servers. Basically
points 2 & 6 that Nat made in the original post.

-Brandon

On Apr 14, 12:16 pm, "Kevin Brown" <e...@google.com> wrote:
> I agree with Graham -- being able to pre-generate urls is very important,
> especially when the data is ultimately fetched over HTTP and can't take
> advantage of templating mechanisms and the like. My chief concern is
> ensuring that the url generation scheme is sound.
>
>
>
> On Mon, Apr 14, 2008 at 11:50 AM, Graham Spencer <g...@google.com> wrote:
> > The main reason I had proposed the container URL template approach was so
> > that developers could quickly and easily generate URLs on their own servers
> > without having to make either JS or RESTful API calls (except maybe once the
> > first time).
>
> > So I like the idea of having a JS function that actually generates the
> > URL, but I don't think it's sufficient if we want server-side URLs to be
> > easy to create. Cassie -- do you have thoughts or suggestions about the
> > server-side URL issue?
>
> > --g
>

> > > On Thu, Apr 10, 2008 at 9:36 PM, Vasudeva Nori <vasun...@gmail.com>

> > > wrote:
>
> > > > On Thu, Apr 10, 2008 at 12:24 PM, David Primmer <

> > > david.prim...@gmail.com>
> > > > wrote:
>
> > > >> On Thu, Apr 10, 2008 at 12:01 PM, Vasudeva Nori <vasun...@gmail.com>

> > > >> wrote:
> > > >> > On Thu, Apr 10, 2008 at 11:25 AM, David Primmer

> > > >> > <david.prim...@gmail.com>

> > > >> > wrote:
> > > >> > > I don't know why OpenSocial chose ${} but I don't see a reason
> > > for a
> > > >> > > divergence from Joe's draft spec
>
> > >http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt
>
> > > >> > > I also want to add that in addition, the API server will provide
> > > a
> > > >> > > service document to allow clients to discover the various
> > > endpoints
> > > >> > > available.
>

> > >http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.ht...

[Cassie]

Okay, container templates it is. So, for a proposal like this:
(I included an owner param)

opensocial.getContainerUrlTemplate = function() { ... }

This returns a string containing "${}" variables. The four supported variables are:

- name: the name or id of the application

- owner: the id of the owner of the page

- path: an application-defined path string
- params: application-defined parameters, query-encoded.

Examples of URL template strings:

http://container.com/apps/${name}/${owner}/${path}?${params}

http://apps.container.com/${name}#${path}?${params}

http://container.com/?app=${name}&owner=${owner}&path=${path}&${params}


I -think- we have +1s from kevin, graham, brandon, and fernman.
If this is right and we get one more person to +1 then it is good to go.

- Cassie

[Arne Roomann-Kurrik (Google)]

I'm tentatively +1 on this, but wanted to clarify a couple questions:

How explicit can the spec be about defining what should be pointed to
by such URLs? We can't specify a view name like "canvas", but can the
wording be something like "should navigate to a view where the
application corresponding to ${name} is featured prominently on the
page?"

It appears that some parameters are optional... for example, "http://
apps.container.com/${name}#${path}?${params} " doesn't include $
{owner}. Which parameters are optional? What happens if a container
returns something like "http://apps.container.com/person/${owner}"??

~Arne

[Louis Ryan]

Im also a tentative +1 here but I think some details need to be worked out before committing

Is the existing mechanism of extracting parentURL from the URL params using the gadgets.util fine for app developers to access the 'path' variable information?

Which id's are we talking about here. This may be a problem unique to Orkut but we have used a different id space for opensocial than the one we use for our URLs, open social owner id != page owner id. I'm loath to propose modifying the spec to include a NAVIGATION_ID to resolve this issue but...

'params' are currently exposed as JSON objects in gadgets js, are we proposing changing this to query encoded and have apps accommodate the associated change in structure this implies?

What rules do we expect containers to enforce about the naming conventions of params. Most containers are likely to have a diverse though small set of always reserved params. Does the spec need to say something about this?

[Kevin Brown]

On Fri, Apr 25, 2008 at 9:54 AM, Louis Ryan <lr...@google.com> wrote:

Im also a tentative +1 here but I think some details need to be worked out before committing

Is the existing mechanism of extracting parentURL from the URL params using the gadgets.util fine for app developers to access the 'path' variable information?

That's an implementation specific detail, so by definition it can't be "fine" unless we standardize it (and that's just a different class of badness :)).

Which id's are we talking about here. This may be a problem unique to Orkut but we have used a different id space for opensocial than the one we use for our URLs, open social owner id != page owner id. I'm loath to propose modifying the spec to include a NAVIGATION_ID to resolve this issue but...

'params' are currently exposed as JSON objects in gadgets js, are we proposing changing this to query encoded and have apps accommodate the associated change in structure this implies?

What rules do we expect containers to enforce about the naming conventions of params. Most containers are likely to have a diverse though small set of always reserved params. Does the spec need to say something about this?

This seems like asking for trouble. There should be standard ways to get access to params (such as we see with view parameters), but standardizing how they are passed will make things very difficult for containers, especially those based on limited application frameworks that refuse to accept doing things any way other than the one that they like.
 

[Louis Ryan]

On Fri, Apr 25, 2008 at 10:04 AM, Kevin Brown <et...@google.com> wrote:

On Fri, Apr 25, 2008 at 9:54 AM, Louis Ryan <lr...@google.com> wrote:

Im also a tentative +1 here but I think some details need to be worked out before committing

Is the existing mechanism of extracting parentURL from the URL params using the gadgets.util fine for app developers to access the 'path' variable information?

That's an implementation specific detail, so by definition it can't be "fine" unless we standardize it (and that's just a different class of badness :)).

So do we want to standardize on parentURL as the mechanism and require the gadget to figure out what to do container by container? This isnt particularly friendly but is that status quo. Another alternative is to use syndicator/container rules to expose patterns for parentURLs in the JS and provide gadgets JS utilities to extract their components
 

Which id's are we talking about here. This may be a problem unique to Orkut but we have used a different id space for opensocial than the one we use for our URLs, open social owner id != page owner id. I'm loath to propose modifying the spec to include a NAVIGATION_ID to resolve this issue but...

'params' are currently exposed as JSON objects in gadgets js, are we proposing changing this to query encoded and have apps accommodate the associated change in structure this implies?

What rules do we expect containers to enforce about the naming conventions of params. Most containers are likely to have a diverse though small set of always reserved params. Does the spec need to say something about this?

This seems like asking for trouble. There should be standard ways to get access to params (such as we see with view parameters), but standardizing how they are passed will make things very difficult for containers, especially those based on limited application frameworks that refuse to accept doing things any way other than the one that they like.

Im actually proposing giving containers more control not less. ${params} doesnt provide enough information to gadget developers about what to generate

[Marco Ensing]

-1,

Great ideas, but this is crossing the path with the templating spec. I
would suggest to get these use cases addressed in the template
specification. (that exceeds just acitivity templates)

On Apr 25, 12:22 pm, "Louis Ryan" <lr...@google.com> wrote:

> >>>http://container.com/apps/${name}/${owner}/${path}?${params}<http://container.com/apps/$%7Bname%7D/$%7Bowner%7D/$%7Bpath%7D?$%7Bpa...>
> >>>http://apps.container.com/${name}#${path}?${params}<http://apps.container.com/$%7Bname%7D#$%7Bpath%7D?$%7Bparams%7D>
> >>>http://container.com/?app=${name}&owner=${owner}&path=${path}&${params}<http://container.com/?app=$%7Bname%7D&owner=$%7Bowner%7D&path=$%7Bpat...>

> ...
>
> read more »- Hide quoted text -
>
> - Show quoted text -- Hide quoted text -
>
> - Show quoted text -

[Arne Roomann-Kurrik]

The templating specification isn't up for inclusion in 0.8, and this is very important functionality that I'd like to see in for 0.8.  In my opinion, it's better to get this in now and get it more in line with templating when that arrives (in 0.9?).

~Arne

--
OpenSocial IRC - irc://irc.freenode.net/opensocial

[Cassie]

Marco - I actually don't think this issue will be addressed by opensocial templates.

- not all apps will use opensocial templates
- opensocial templates will be a feature built on top of opensocial. they shouldn't really have access to any data that the js apis themselves don't provide. in other words, once translated they should look like a opensocial gadget that did not use templates. they sorta just make lives simpler and easier for developers with optional server side processing. it would be bad for non-ui functionality to hide within the templates themselves.

Given those two issues and Arne's point I agree that this shouldn't wait until templates are done.
What do you think?

Thanks.
- Cassie

[Graham Spencer]

I agree with Arne and Cassie that we should get this into 0.8, not wait on templates.

Louis -- I think the general question is how the gadget should extract parameters from the URL. It should be possible to write some general utility code that compares a real URL to the URL template and extracts the data, right?

Kevin -- I agree that dealing with query arguments is hard, but I think we should do the best we can and not try to accommodate every possible broken framework. Would it be sufficient to specify a pattern for arguments as well, e.g. "up_${name}"?

--g

[John Panzer]

I'd like to back up and +1 David's proposal to adopt the syntax from http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt.  The RESTful API has some of the same needs, but it also needs to (for example) specify that one can concatenate several values together with , to form a composite value.  URI Templates address things like this cleanly and are I think no harder to parse than any other format.

[John Panzer]

Aside:  If there is a need for general URI template discovery, I'd like to propose adopting XRDS-Simple (http://xrds-simple.net/core/1.0/), which is the format used by OpenID discovery and is also the proposed discovery syntax for OAuth.

It would need one extension to allow for URI template in addition to concrete URIs; the format would look like this:

      <XRDS xmlns="xri://$xrds">
          <XRD xmlns:simple="http://xrds-simple.net/core/1.0" xmlns="xri://$XRD*($v*2.0)" version="2.0">

              <Type>xri://$xrds*simple</Type>
              <Service>
                <Type>http://opensocial.org/discovery/people</Type>

                <URI-Template>http://my-sn-apis.com/resource/people/{ownerid}/{groupid}/{personid}</URI>
              </Service>

          </XRD>
      </XRDS>

This would not be for 0.8 obviously :).  But it would be good not to have multiple ways to discover things; since we already support OAuth we're likely to need to support this format as well at some point anyway.

[Louis Ryan]

It may not be general but rather container specific, either way the net effect should be the same so yes we should be able to extract.  We need to document where this information is accessible to the gadget. It seems the options are

1. Layered into viewParams

2. Added as some additional object on currentView

3. Left for gadget developers to parse how they see fit using some provided utilities

1&2 Seem like the only viable options.

Im 

+1 on the ietf template proposal

+1 on dropping support for JSON encoded params in favor of query params (Gadgets can always do it themselves)

+1 on punting on reserved param names if necessary to get this approved

+1 on including the information from a back-parsed URI template in view params

[Graham Spencer]

I would be happy with all of Louis's +1s.

We've gotten strenuous feedback from developers that they really need this, so I'm eager to get it into 0.8 -- if people agree, can we get more +1s? Thanks!

--g

[Lou Moore]

+1 on all of those, we’d like to see this in 0.8 too

> >>>http://container.com/apps/${name}/${owner}/${path}?${params} <http://container.com/apps/$%7Bname%7D/$%7Bowner%7D/$%7Bpath%7D?$%7Bparams%7D> <http://container.com/apps/$%7Bname%7D/$%7Bowner%7D/$%7Bpath%7D?$%7Bpa...>
> >>>http://apps.container.com/${name}#${path}?${params} <http://apps.container.com/$%7Bname%7D#$%7Bpath%7D?$%7Bparams%7D> <http://apps.container.com/$%7Bname%7D#$%7Bpath%7D?$%7Bparams%7D>
> >>>http://container.com/?app=${name}&owner=${owner}&path=${path}&${params} <http://container.com/?app=$%7Bname%7D&amp;owner=$%7Bowner%7D&amp;path=$%7Bpath%7D&amp;$%7Bparams%7D> <http://container.com/?app=$%7Bname%7D&owner=$%7Bowner%7D&path=$%7Bpat...>

[Paul Lindner]

Indeed +1

On Wed, Apr 30, 2008 at 05:52:06PM -0700, Lou Moore wrote:
> +1 on all of those, we¹d like to see this in 0.8 too
>
>
> On 4/30/08 5:22 PM, "Graham Spencer" <g...@google.com> wrote:
>
> > I would be happy with all of Louis's +1s.
> >
> > We've gotten strenuous feedback from developers that they really need this, so
> > I'm eager to get it into 0.8 -- if people agree, can we get more +1s? Thanks!
> >
> >

> >>>>>>>>>> <http://container.com/?app=$%7Bname%7D&amp;amp;owner=$%7Bowner%7D&amp
> >>>>>>>>>> ;amp;path=$%7Bpath%7D&amp;amp;$%7Bparams%7D>
> >>>>>>>>>> <http://container.com/?app=$%7Bname%7D&owner=$%7Bowner%7D&path=$%7Bpa
> >>>>>>>>>> t...>
> >>>>>>>>>> <http://container.com/?app=$%7Bname%7D&amp;owner=$%7Bowner%7D&amp;pat

> You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
> 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
> -~----------~----~----~----~------~----~------~--~---
>

--
Paul Lindner ||||| | | | | | | | | |
lin...@inuus.com

[Dan Peterson]

I also li ke the approach of making this type of navigation no longer require lots of requests to build the URL.

+1 for getting this into 0.8

-Dan

[Cassie]

Okay, so we are approved here.. but I really have no idea what this spec change actually is :)
So far we have the getTemplateUrl function - but Louis, do your comments require another code change?

Let's just make sure we all review the release notes/js diffs I will send out soon so that we get this right.
Thanks.

- Cassie

[Louis Ryan]

No code changes but definitely some doc clarifications.

[Bob]

It seems like the client side evaluation that actually binds the
template and the variables needs to be specified.

How about something like this:

/**
* Binds a container template with an environment of variables to
produce an URL string.
*
* - template: A container-generated template for an URL.
* - environment: A set of named variables,
* e.g. [OWNER | PATH | PARAMS | NAME], of type string.
*
* See also, <a href="opensocial.util.html#containerUrlTemplate">
* containerUrlTemplate</a>.
* @return {String} An URL String
* @member opensocial.util
*/
opensocial.util.bind(template, environment)


Bob

On Apr 21, 4:13 am, Cassie <d...@google.com> wrote:

> > > ~Kevin *

[Louis Ryan]

We definitely need this. Some notes

opensocial.util.html.bindUrlTemplate as method name and scope instead of opensocial.util.bind which seems a bit too generic?

Also I think the param definition needs to be synced up with the IETF standard

[Robert Evans]

bindUrlTemplate is much better. How about the following.

Bob

/**
 * Binds a container URI template with an environment of variables to
 * produce an URL string.
 *
 * The URI template conforms to the
 * <a href="http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.html">
 * W3C spec draft</a> with variables for substitution.

 * 
 * - template: A container-generated template for an URL.

 * - environment: A set of named variables.
 *

 *   The four supported variables in the environment are:
 *    - name: the name or id of the application
 *    - owner: the id of the owner of the page
 *    - path: an array of path steps
 *    - params: associative array or array [param1,value1,param2,value2,...]
 *

 *
 * See, <a href="opensocial.util.html#containerUrlTemplate">

 *              containerUrlTemplate</a> for detailed discussion.

 * @return {String} An URL String
 *

 * @member opensocial.util.html
 */
opensocial.util.html.bindUrlTemplate(template, environment)

[Louis Ryan]

Works for me.

[Robert Evans]

So, I went to update the 0.8 spec with the newly agreed-upon bind method. I have two questions.

Right now, the getContainerUrlTemplate is in opensocial.js, as opensocial.getContainerUrlTemplate.

1) Seems like the two should match, but I like Louis' suggestion to put it in the opensocial.util namespace. Should we create a new spec js file, <root>/opensocial/util.js with just the bindUrlTempalte and getContainerUrlTemplate methods? Or should I throw it in the opensocial.js file with getContainerUrlTemplate?

2) Also, since these two methods are really here to facilitate gadgets.views.requestNavigateTo, should they be in the gadgets.util namespace instead?

Thanks,
Bob

[Louis Ryan]

It definitely seems like this is a kink that should be resolved in 0.9 along with a potential unification of template processing and the NavigationParams and ViewParams.

In the interim it may be best to add the bind function to gadgets.util and keep getContainerUrlTemplate where it is. Having getContainerUrlTemplate in opensocial is not that much of a stretch.

The real question is whether there is 1-1 correspondance between gadgets.views.getSupportedViews() and the set of supported URL templates. If so we should remove getContainerUrlTemplate and just add the URL template to the gadgets view object. In Orkut I dont see there being any difference so I have no objection to doing this.

[Louis Ryan]

Ok, how about something like this. I believe this resolves our issue

1. Remove getContainerUrlTemplates from opensocial

2. Add the gadgets.views.VIew.getUrlTemplate

/**
 * Returns a string URI template conforming to the

 * <a href=http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.html">

 * W3C spec draft</a> with variables for substitution.
 *  

 * The four supported variables are:

 * - name: the name or id of the application
 * - owner: the id of the owner of the page
 * - path: an array of path steps
 * - params: associative array or array [param1,value1,param2,value2,...]
 *

 * Simple examples of URL template strings:
 * http://container.com/{-list|/|name,owner,path}?{-join|&|params}
 * http://container.com/apps/{name}/{owner}{-prefix|/|path}{-opt|?os_|params}{-join|&os_|params} 
 *
 * Given the params
 * {
 *  name : 'Wilma',
 *  owner : 'Betty',
 *  path : ['dino','car'], 
 *  params = { a : 'Barney', b : 'Fred'}
 * } 
 *
 * The above two examples yield
 * http://container.com/Wilma/Betty/dino/car?a=Barney&b=Fred
 * http://container.com/apps/Wilma/Betty/dino/car?os_a=Barney&os_b=Fred
 *
 * @return {String} A template which can be used to construct urls for
 *     that navigate to this vuew
 * @member gadgets.views.View
 */
gadgets.views.View.getUrlTemplate = function() {};

3. Add gadgets.views.bindTemplate(urlTemplate, templateParams) and a wrapper on gadgets.views.View.bindTemplate(templateParams)

/**
 *  Binds a URL template with an environment of variables to produce an URL string.
 *
 * - urlTemplate: A url template for a container view

 * - environment: A set of named variables,
 *       e.g. [OWNER | PATH | PARAMS | NAME], of type string.
 *

 * See also, <a href="gadgets.views.View#getUrlTemplate">
 *              getUrlTemplate</a>.

 * @return {String} An URL String

 * @member gadgets.views
 */
gadgets.views.bind(urlTemplate, environment)

/**
 *  Binds a URL template with an environment of variables to produce an URL string.

 *

 * - environment: A set of named variables,
 *       e.g. [OWNER | PATH | PARAMS | NAME], of type string.
 *

 * See also, <a href="gadgets.views#bind">
 *              bind</a>.

 * @return {String} An URL String

 * @member gadgets.views.View
 */
gadgets.views.bind(environment)

I think this fits the bill. It also points to a path for merging NavigationParams and bind-environments in 0.9 quite nicely.

[Robert Evans]

Looks good to me.

Bob

[Dan Peterson]

This seems like a good cleanup (+1)

-Dan

[Graham Spencer]

I agree, +1. Thanks Louis.

--g

[Cassie]

+1

[Evan Gilbert]

+1, makes a lot of sense

[Kevin Brown]

+1

[Zhen Wang]

+1

On Wed, May 21, 2008 at 11:40 AM, Louis Ryan <lr...@google.com> wrote:

[Robert Evans]

So, does a View have an implicit template?

On Wed, May 21, 2008 at 11:40 AM, Louis Ryan <lr...@google.com> wrote:

[Louis Ryan]

No, just its explicit one. If a view can be navigated to via requestNavigateTo it will almost always have a template.