Your First OpenSocial Application
You are now ready to create your first OpenSocial application. To keep it simple, the application will enumerate only the friends currently belonging to the network of the user accessing the application. As previously sated, because OpenSocial is built on top of the Google Gadgets specifications, the first thing to do is to create an XML application specification file like this basic OpenSocial specification file:
<?xml version="1.0" encoding="UTF-8" ?>
<ModulePrefs title="Opensocial Basic example" >
<Require feature="opensocial-0.7" />
<script src="http://localhost:3000/basic/basic.js" ></script>
Save the above file with the name basic.xml. You'll notice that many things are going in the file. First of all, the XML file that describes the OpenSocial application is just like the one you would use to create a Google Gadget. The ModulePrefs section contains application metadata, such as title and required libraries. Also notice that you request the latest available version of the OpenSocial APIs with the line:
<Require feature="opensocial-0.7" />
Remember to always declare this requirement in your applications; otherwise, you won't be using the OpenSocial APIs.
All the OpenSocial APIs are built around the concept of asynchronous requests performed by the application toward the container. Therefore, the code in Listing 1 is organized around callback functions.
For your application to access some data from the OpenSocial container, you have to create a DataRequest object using the opensocial.newDataRequest() API call each time.
The DataRequest object acts as a container for querying different entities in a single method call. All the queries share a common format and are created in the same way:
- They are created using a specific method that describes the query type and the expected results (a single person or a collection), such as req.newFetchPersonRequest() or req.newFetchPeopleRequest().
- The first parameter always specifies the entity (person or group of persons) the request refers to, such as VIEWER of VIEWER_FRIENDS.
- The query is added to the DataRequest using the red.add() method, along with a key that will be used later to retrieve the response data, such as 'viewer' or 'viewerFiends' in the previous example.
In OpenSocial terminology, VIEWER represents the user logged into the browser who is using the application to navigate through his social network, while VIEWER_FRIENDS refers to the collection of users that compose the VIEWER social network. Other entities, such as OWNER and OWNER_FRIENDS, differentiate special cases (such as when one user is accessing a profile that is not his own), but they are not relevant in the context of this article. Further information about OpenSocial identifiers is available in the official documentation.
Going back to the example, the loadFriends() method requests two entities, the current viewer and its collection of friends, respectively using the req.newFetchPersonRequest() and req.newFetchPeopleRequest() calls. Finally, it sends the request to the server with the req.send(onLoadFriends) method call. This method accepts a parameter that defines the callback function that will handle the server response. In the example, the onLoadFriends() function is the designated callback. This function extracts the results from the response object (using the keys 'viewer' and 'viewerFriends' declared while constructing the request), iterates through the results, and constructs the HTML contents to be shown to the user.
|Figure 4. The Basic Application Loaded Within the Shindig Container: Here is the final result when the application is loaded within the Shindig container.|
Figure 4 shows the final result when the application is loaded within the Shindig container.