Kudos to Danny for exposing and then mitigating the ugliness of OpenSocial's PersonKind!

In spite of all the positive feelings I have about the intentions of OpenSocial, I think that I'll take aim at its shortcomings as well.

My goal is to start building a way to be able to embed an app into some of these early-adopter communities. Looking over the Javascript API's Developer's Guide it appears as if I am required to use the Google Gadget API to be able to embed.

I hope that this is not the only way to do it, because the gadgets are not very pretty. This gadgets XML format that is about to be very, very widely used to embed web apps is seriously begging for an organized standardization effort. It looks like something that I half-put together in 1999. For starters, no XSD or XML namespaces are to be found. The xml description and the examples listed throughout the gadgets documentation do not even encourage developers to indicate what sort of XML a passerby is looking at, much less what version of the gadget format it represents. Should a developer (much less an automated process) come across a gadget in the wild, he would have work a while to figure out what the document is and what its elements are used for.

I can momentarily find it in my heart to sympathize with a developer who would choose to skip the XSD creation for something used in a very isolated capacity. But it is absolutely a requirement for a format that is going to be used... just about everywhere! The lack of clarity in the gadget XML format is not worth the bits conserved or the apparent simplicity for less-experienced developers.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
 <ModulePrefs title="List Friends Example">
   <Require feature="opensocial-0.5"/>
 </ModulePrefs>
 <Content type="html">

 <![CDATA[

 <script type="text/javascript">

 /*Request for friend information when the page loads.*/

  function getData() {

    document.getElementById('message').innerHTML = 'Requesting friends...';

    var req = opensocial.newDataRequest();

    req.add(req.newFetchPersonRequest('VIEWER'), 'viewer');

    req.add(req.newFetchPeopleRequest ('VIEWER_FRIENDS'), 'viewerFriends');

    req.send(onLoadFriends);

  };

 /* Parses the response and generates html to list the friends */

  function onLoadFriends(dataResponse) {

    var viewer = dataResponse.get('viewer').getData();

    var html = 'Friends of ' + viewer.getDisplayName(); 

    html += ':<br><ul>';

    var viewerFriends = dataResponse.get('viewerFriends').getData();

    viewerFriends.each(function(person) {

      html += '<li>' + person.getDisplayName() + '</li>';

    });

    html += '</ul>';

    document.getElementById('message').innerHTML = html;

  };

  _IG_RegisterOnloadHandler(getData);

  </script>

  <div id="message"> </div>

  ]]>

  </Content>

</Module>

Source: OpenSocial: List Friends Example

The ModulePrefs, aside from preferences and "Require" dependencies, is used to store metadata for a gadget, including title, author, author_email, and so on (see the XML below). This is beyond silly and gives OpenSocial implementers many reasons to say: we can do better.

One big picture question that is begging to be asked is whether it is realistic or not to expect MySpace, SixApart, and the dozens of other competing communities to fully implement all of the functionality that appears in this API? This is quite a lot of cooperation to expect from everyone involved and I suspect that the various gadget container implementations will begin to remind us of the brower wars of the late 1990s.

Except that this time there isn't an objective party like the W3C in the center of the field. Not yet, anyhow.

Back to creating my OpenSocial UI, the simplest way to display something using one of these gadgets is to supply a url which the javacript of the container app will use to load the external content. This is how the DogstarRadio embed works:

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs 
    title="Now Playing on SIRIUS"
    height="60"
    width="250"
    description="Displays what is currently playing on Sirius Satellite Radio using data from DogstarRadio.com"
    author="DogstarRadio.com"
    author_email="schedule@dogstarradio.com"
    title_url="http://www.DogstarRadio.com"
    screenshot="http://www.DogstarRadio.com/images/now_playing_gadget_screenshot.png"
    thumbnail="http://www.DogstarRadio.com/images/now_playing_gadget_thumbnail.png"
    >
    <Require feature="opensocial-0.5"/>
  </ModulePrefs>
  <Content type="url" href="http://www.dogstarradio.com/sirius_display.php?size=gadget">
  </Content>
</Module>

Source: Ning's OpenSocial Gadgets Directory

Appropriately, there is a size=iphone for this URL. Seeing this, I wonder what the HTTP_USER_AGENT for the XHR client would look like to my embeddable app. I suppose that I could just create a separate controller for all embeddable functionality and then send an initial call to my hosted app containing metadata about the OpenSocial container and embedding member.

To accomplish this I can use the Remote Content APIs, a means to supply the embedding app and its OpenSocial hooks with data returned from the external app. This is one of the most interesting parts of the system. Of course it might also be the most dangerous.

While these methods will encourage more javascript code and UI to be placed into the horrid Module XML, I expect them to be a boon to developers stumped by browser cross-domain security restictions.