Orkut Application Platform

On-Site Application Developer Guide: Patterns

Before we dive into the specifics of each aspect of the API, let's quickly look at some common patterns that will be used frequently.

Contents

Initialization

First of all, since you cannot reliably use window.onload on applications, a common pattern is to use the Gadgets API's registerOnLoadHandler method to register Javascript code that should execute as soon as the application is finished loading. As an example, consider the following code:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs 
     title="Your Title Here"
     author="Your Name Here"
     author_email="your_email_here@your_domain_here.com"
     description="Description of your application goes here"
     screenshot="http://full/url/to/a/screenshot/of/your/app.png"
     thumbnail="http://full/url/to/a/thumbnail/of/your/app.png">

    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html">
    <![CDATA[
      <br> <br> <br>
      <big>Hello, world!</big>

      <script type="text/javascript">

      gadgets.util.registerOnLoadHandler(init);
      function init() {
         alert("Initializing!");
      }
      </script>
    ]]>
  </Content>
</Module>

This code registers the init() function as a handler for the load event. The effect is that the "Initializing" popup is shown as soon as the application is done loading.

You should only attempt to do anything in your application after the application is finished loading, since the APIs or the HTML DOM may be in an inconsistent state before that. Also, you should never try to override window.onload, since that function is used by the framework.

Note: From now on in this guide, we will only show the HTML and Javascript code that goes inside the <Content> tag (more specifically, inside the <![CDATA[ and ]]> markers) instead of showing the full XML. If you are using OrkDevApp (see Setting up the Development Environment for more information about how to install it), all you have to do is copy and paste that code into the box and it will work. If you are developing your application, don't forget to add the XML boilerplate above to the code we give you, and also don't forget to remove or replace the debug.* calls with something appropriate to your application.

OpenSocial Data Requests

Requests to the OpenSocial API are performed through batches called data requests. You can put one or more individual requests inside a data request, each tagged with an identifier. This can be better explained through an example:

function init() {
   // create a new OpenSocial data request
   var req = opensocial.newDataRequest();

   // this specifies which person we are retrieving (the viewer)
   var who = opensocial.IdSpec.PersonId.VIEWER;

   // add a "fetch person request" to our data request;
   // "mydata" is the name that should be associated to 
   // this piece of data in the response
   req.add(req.newFetchPersonRequest(who), "mydata");

   // send the request, and specify a callback
   req.send(callback);
   debug.say("Request sent. Waiting for reply...");
}

// This callback is called when the request finishes loading
function callback(data) {
   // Did an error occur?
   if (data.hadError()) { 
      debug.say("*** Error.");
      // handle error (for instance, log it)
      return;
   }

   // fetch the viewer data from the "mydata" result
   var viewer = data.get("mydata").getData();

   // show it on the debug console
   debug.say("Hello, " + viewer.getDisplayName() + "!");
}

// Register our onLoad handler through the Gadgets API
gadgets.util.registerOnLoadHandler(init);

In this example, req is an OpenSocial data request. In this case, we are adding a single request to it: a Fetch Person Request, which we create with the newFetchPersonRequest method. This request is asking the server to return information about a person (in this case, the viewer of the application). We give that request the "mydata" ID (second parameter to req.add()). Then, we send the request using the send() method, which takes a reference to a callback function as parameter. When our callback is called, we retrieve the data using the same ID we used in the request ("mydata").

Here is an example that requests two bits of data in the same request. For brevity, we're omitting the comments:

function init() {
   var req = opensocial.newDataRequest();
   req.add(req.newFetchPersonRequest(
              opensocial.IdSpec.PersonId.VIEWER), "myviewer");
   req.add(req.newFetchPersonRequest(
              opensocial.IdSpec.PersonId.OWNER), "myowner");
   req.send(callback);
   debug.say("Request sent. Waiting for reply...");
}

function callback(data) {
   if (data.hadError()) { 
      debug.say("Error!");
      // ... further error handling ...
      return; 
   }
   var viewer = data.get("myviewer").getData();
   var owner = data.get("myowner").getData();
   debug.say("Viewer is " + viewer.getDisplayName());
   debug.say("Owner is " + owner.getDisplayName());
}

gadgets.util.registerOnLoadHandler(init);

In OpenSocial, we specify people and groups of people through OpenSocial IdSpecs. The constants opensocial.IdSpec.PersonId.VIEWER specify the viewer of the application (the user that's currently logged in and running it) and opensocial.IdSpec.PersonId.OWNER specifies the owner of the application, that is, the user on whose profile the application is installed.

Later we will see how IdSpecs can also specify groups of people, not only single individuals.

Note: On some calls we need to specify these ID's differently (through an IdSpec object rather than those constants), but we will give more details when we get to those cases.

Error Handling

You probably noticed that in the snippets of code we gave above, we only printed "Error" on the debug console (which is only available in OrkDevApp). That's probably not very helpful in a production application: instead, you should probably retrieve the exact error message and do something with it (log it, for instance). We will give more details about this in our section about Handling Errors.

In our examples, in order to conserve space and maintain simplicity, we will typically only print "Error" in case of errors and include a comment saying "handle error here". In a production application you should, naturally, replace this with proper error handling.

What's Next?

Now that we've shown some common code patterns, let's move on to our discussion on requesting people data.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.