General improvements to Core-Gadget

These are proposals...

Thumbnail and Screenshot Links

We already dumped the Icon element in favor of Link/@rel="icon" ... we should do the same for @screenshot and @thumbnail links...

e.g. <Link rel="screenshot" href="..." /> and <Link rel="thumbnail" href="..." />

http://code.google.com/p/opensocial-resources/issues/detail?id=1288

Privacy Policy, License, and Terms-of-Use License Links

We should use Link relations for the privacy policy, license and terms-of-use stuff...

See: http://tools.ietf.org/html/draft-snell-additional-link-relations-01.html for "privacy-policy" and "terms-of-service"

See: http://tools.ietf.org/html/rfc4946 for "license"

e.g. <Link rel="license" href="..." /> and <Link rel="privacy-policy" href="..." /> and <Link rel="terms-of-service" href="..." /> ... etc

http://code.google.com/p/opensocial-resources/issues/detail?id=1289

Use Lang Ranges on Locale elements instead of separate country and language attributes

RFC 4647 defines a standard format for language tags and ranges for matching. These are pretty straightforward to use. We should be using those instead of separate language and country codes...

e.g. instead of <Locale language="en" country="US" /> it would be something like <Locale for="en-US-*" /> ... much more concise... 

Likewise, when using proxied content, the spec currently says that the container can put country and lang attributes as querystrings in the request... why? Why not use Accept-Language instead?

e.g. instead of sending http://example.org/foo?lang=en&country=US ... why not send

  GET /foo HTTP/1.1
  Accept-Language: en-US

That way we don't have to muck around with the querystring for these items.

http://code.google.com/p/opensocial-resources/issues/detail?id=1290

Expand use of URL Templates

Right now we have things like <Content type="url" href="http://example.org?foo" /> and we require that the container munge around with the provided URI to provide additional querystring parameters, e.g. for OAuth, Signed Fetch, and Country/Language... a bit more flexible approach would be to use URL Templates... e.g. 

<Content type="url" tref="http://example.org{/country}{/lang}/page{?signedfetch*,sign_owner,sign_viewer}" />

The variables used in the tref (template ref) attribute would be defined by the OpenSocial spec.. the appropriate values would be inserted where appropriate by evaluating and expanding the template. Such templates can be used in Content, Link, Preload, etc... and could be used within makeRequest and osapi.http requests also.

API to access <Link> Elements

I note that there is currently no API to access the collection of Link elements defined for a gadget spec. This seems like an important limitation. 

As a Gadget developer, it would be handy to be able to define links such that I can reference them easily within code and have the container proxy the requests for me.. e.g. if I have...

<Module>
  <ModulePrefs>
    <Link rel="foo" href="http://example.org" authz="signed" />
    <Link rel="foo" href="http://example.net" authz="oauth2" />
    <Link rel="bar" href="http://example.com" authz="none" />
  </ModulePrefs>
  ...
</Module>

Then within my Javascript code, I should be able to do something along the lines of...

 osapi.links["foo"][0].get().execute(function(result) {...});
 osapi.links["foo"][1].get().execute(function(result) {...});
 osapi.links["bar"].get().execute(function(result) {...});

And have the container fetch the linked resource for me with proper authentication handled.

Alternatively, we can add a label to Link's to differentiate between multiple instances of a single rel...

<Module>
  <ModulePrefs>
    <Link rel="foo" label="one" href="http://example.org" authz="signed" />
    <Link rel="foo" label="two" href="http://example.net" authz="oauth2" />
    <Link rel="bar" href="http://example.com" authz="none" />
  </ModulePrefs>
  ...
</Module>

Such that...

osapi.links["one"].get().execute(function(result) {...});
osapi.links["two"].get().execute(function(result){...});
osapi.links["bar"].get().execute(function(result){...});

should also be able to reference the links using variable substitution... e.g.

 <img src="${Links.foo.1}" />
 <img src="${Links.foo.2}" />
 <script src="${Links.bar}" />
 <iframe src="${Links.one}" />

And again, have the container proxy those links for me with appropriate authentication in place.

http://code.google.com/p/opensocial-resources/issues/detail?id=1291

Calling osapi.links[?] would return a Link Service object... when the Link points to an HTTP resource, the Link Service object is essentially an osapi.http Service object that supports the various get, post, put, etc methods prepopulated with the parameters from the Link element. An additional proxy() method would be included to return a proxy service object for the Link as a shortcut to using gadgets.io.getProxyUrl() ... e.g.

 osapi.links["one"].proxy().get().execute(function(result) {...});

Which could also be used in variable substitution...

 <img src="${Links.one.proxy}" />

Preload Elements can be replaced by Link/@rel="prefetch"

The "prefetch" link relation is already defined and registered within the IANA registry of Link relations. We can eliminate the existing Preload element in favor of prefetch links. To be a complete replacement, we can add a view attribute to the Link element.

e.g. instead of...

 <Module>
   <ModulePrefs>
     <Preload href="http://example.org/foo" authz="signed" views="home,foo" />
     <Link rel="icon" href="..." />
   </ModulePrefs>
 </Module>

it would be..

 <Module>
   <ModulePrefs>
     <Link rel="prefetch" href="http://example.org/foo" authz="signed" views="home,foo" />
     <Link rel="icon" href="..." />
   </ModulePrefs>
 </Module>

http://code.google.com/p/opensocial-resources/issues/detail?id=1292

ExternalService Elements can be replaced by Link/@rel="external-service"

A new "external-service" rel value can be defined to replace the existing ExternalService mechanism, eliminate extraneous elements from the gadget spec vocabulary and simplify the overall format.. for instance..

instead of...

 <Module>
   ...
   <ExternalServices>
     <ServiceTag alias="opensocial:my.external.service">foo</ServiceTag>
   </ExternalServices>
   <Content type="html">
     <script>
       gadgets.io.makeRequest("",function(res){...},{"alias":"foo"};
     </script>
   </Content>
 </Module>

it would be..

 <Module>
   <ModulePrefs>
     ...
     <Link rel="external-service" label="foo" href="opensocial:my.external.service" />
     ...
   </ModulePrefs>
   <Content type="html">
     <script>
       osapi.links["foo"].get().execute(function(res) {...});
     </script>
   </Content>
 </Module>

By combining this change with the Links API change above, we can completely streamline how external linked resources are accessed and make it absolutely seamless and consistent across the board.

http://code.google.com/p/opensocial-resources/issues/detail?id=1295

New os:Link Data Pipeline element

Introduce a new os:Link element as a possible replacement for os:HttpRequest ... and tie it to the Link element... for instance:

<Module>
  <ModulePrefs>
    <Link rel="prefetch" label="foo" href="http://example.org" />
  </ModulePrefs>
  <Data>
    <os:Link label="foo" />
  </Data>
</Module>

When the container renders the gadget, it will first process all prefetch links, precaching the result... then when the data pipeline elements are processed, it would see the os:Link and use the referenced Link element to pump the resulting data into the DataContext for the view.

Using this approach, combined with some of the other suggestions listed above, we can achieve some rather interesting use cases... for instance, pipelining data from an external service into the datacontext declaratively..

<Module>
  <ModulePrefs>
    <Link rel="external-service" label="foo" href="opensocial:my.external.service" />
  </ModulePrefs>
  <Data>
    <os:Link label="foo" />
  </Data>
</Module>

This currently is not possible given the current gadget spec design unless the external service is accessed in code and the data is pumped into the datacontext programmatically.

http://code.google.com/p/opensocial-resources/issues/detail?id=1296