Orkut Application Platform

On-Site Application Developer Guide: Photos, Part 1

The OpenSocial 0.8 API does not include access to the user's photos. However, since that's a very important feature on Orkut, the Orkut API implements the albums and photos API defined by OpenSocial 0.9.

Contents

Permission

Before your application can gain access to the user's photos, the user has to explicitly give your application permission to do so. This is not one of the default permissions, so the user will have to do it specifically. To do that on a regular application in production, all the user has to do is click the "Settings" button on the application's frame and check the "Allow access to my photos" checkbox, as illustrated below:



Giving an application permission to access photos

However, this will not work in the sandbox for an application in development. That is because the application your are developing is not officially online on Orkut, so this dialog box will be unable to make changes to the permission settings (you will see an error message saying your application is "not whitelisted").

Instead, what you must do to grant the photos permission to an application in the sandbox is the following procedure:

  1. Run the application
  2. Copy the URL to the clipboard or a text file
  3. Click the Remove button on the application frame
  4. Confirm removal of the application.
  5. Paste the previous URL into the browser's URL bar and hit ENTER.
  6. You will be directed to a screen offering to install the application. In this screen, check the "Allow access to my photos" permission on the right-hand side before clicking "Add Application"
  7. Click the "Add Application" button.

What will I have access to?

The API only allows you to access the albums and photos tagged as public (shared with all users on Orkut). You cannot access any albums or photos that have more restricted access settings such as those that the user shared with specific friends or groups of friends.

Listing Albums

Photos are a particular type of "media item" (currently, the only type supported), so you will see the term "media item" being used in several method names. Media items are grouped into albums, each of which has a title, a description and a thumbnail. So before we work with individual photos, we first have to say a few words about API access to albums.

You can request the list of albums the user has with a FetchAlbumsRequest, as illustrated in the example below:

function init() {
   var req = opensocial.newDataRequest();
   var idspec = opensocial.newIdSpec({'userId':'VIEWER'});
   req.add(req.newFetchAlbumsRequest(idspec),'albums');
   req.send(callback);
}

function callback(resp) {
   if (resp.hadError()) {
      debug.say("*** error: " + resp.getErrorMessage());
      // ...handle error here...
      return;
   }

   debug.say("Response received successfully. Listing albums.");
   var albums = resp.get('albums').getData().asArray();
   debug.say(albums.length + " albums returned.");
   for (var i in albums) {
      debug.say("Album ID " + albums[i].getId());

      var title = albums[i].getField(opensocial.Album.Field.TITLE);
      var desc = albums[i].getField(opensocial.Album.Field.DESCRIPTION);
      var itemcount = albums[i].getField(opensocial.Album.Field.MEDIA_ITEM_COUNT);
      var thumb = albums[i].getField(opensocial.Album.Field.THUMBNAIL_URL);

      debug.say("  title: " + title);
      debug.say("  description: " + desc);
      debug.say("  media items: " + itemcount);
      debug.say("  thumb: " + thumb);

   }
}

gadgets.util.registerOnLoadHandler(init);

Notice that you have to use the IdSpec in "object format" for this call, since using it in scalar format (opensocial.IdSpec.PersonId.VIEWER) will not work. When you receive the response, you must call get('albums') to retrieve the response to the albums request, then getData() to get its data as an OpenSocial Collection. After that, we call asArray() to convert it to a Javascript array and iterate through it. Each item in that collection is an OpenSocial Album object, so we can call getField() to retrieve its fields.

Creating an Album

To create a new album, you can use a CreateAlbumRequest. Here is an example that creates a new album called 'My new album':

function init() {
   var req = opensocial.newDataRequest();
   var params = {};
   params[opensocial.Album.Field.TITLE] = 'album title';

   var album = new opensocial.Album(params);
   var idspec = opensocial.newIdSpec({"userId" : "VIEWER"}); 
   req.add(req.newCreateAlbumRequest(idspec, album), "album");
   req.send(callback);
   debug.say("Request sent. Waiting for reply...");
}

function callback(resp) {
   debug.say("Album reply.");
   if (resp.hadError()) {
      debug.say("*** Error: " + resp.getErrorMessage());
      // ...handle error here...
      return;
   }
   debug.say("Success.");
   var album = resp.get("album").getData();
   debug.say("Album " + album.id + " created.");
};

gadgets.util.registerOnLoadHandler(init);

Note: Orkut does not support setting the album's description upon creation, so setting opensocial.Album.Field.DESCRIPTION during creation will have no effect. If you wish to set a description, you will have to issue an UpdateAlbumRequest after creation.

Updating an Album

By "updating an album", what we mean is changing its title and description. Adding or removing photos from an album is not considered an update to the album in our terminology.

To update an album, you can use a UpdateAlbumRequest as illustrated below. You will need to supply the ID of the album you want to update, so in the following example, we show a complete application that allows you to list the albums, display them in a box with their respective thumbnails and allows the user to see and update the album titles and descriptions.

<style type='text/css'>
div#albummenu {
   position: absolute;
   width: 450px;
   height: 400px;
   border: 1px solid black;
   overflow: auto;
}
div#editform {
   margin-left: 480px;
   width: 300px;
   border: 1px solid black;
}
img.albumthumb {
   vertical-align: middle;
   border: 0px;
}
</style>

<div id='albummenu'>Loading...</div>
<div id='editform'>
   Select an album on the left and edit its title
   and description below. Hit 'Save' to commit the change.<hr />
   <table>
      <tr>
         <td>Album ID:</td>
         <td><input type='text' id='album_id' /></td>
      </tr>
      <tr>
         <td>Title:</td>
         <td><input type='text' id='album_title' /></td>
      </tr>
      <tr>
         <td>Description:</td>
         <td><input type='text' id='album_desc' /></td>
      </tr>
   </table>
   <button id='savebutton' onclick='window.onSaveButtonClicked()'>
      Save Changes
   </button><br />
   <span id='statusspan'>Ready.</span>
</div>

<script type='text/javascript'>

var albums = [];

function reloadAlbums() {
   var req = opensocial.newDataRequest();
   var idspec = opensocial.newIdSpec({'userId':'VIEWER'});
   req.add(req.newFetchAlbumsRequest(idspec),'albums');
   req.send(onLoadAlbums);
}

function onLoadAlbums(resp) {
   if (resp.hadError()) {
      debug.say("*** error: " + resp.getErrorMessage());
      try {
         debug.say("*** details: " + resp.get('albums').getErrorMessage());
      } catch (ex) {}
      return;
   }

   var html = [ "<ul>" ];

   debug.say("Response received successfully. Listing albums.");
   albums = resp.get('albums').getData().asArray();
   debug.say(albums.length + " albums returned.");
   for (var i in albums) {
      debug.say("Album ID " + albums[i].getId());

      var title = albums[i].getField(opensocial.Album.Field.TITLE);
      var desc = albums[i].getField(opensocial.Album.Field.DESCRIPTION);
      var itemcount = albums[i].getField(opensocial.Album.Field.MEDIA_ITEM_COUNT);
      var thumb = albums[i].getField(opensocial.Album.Field.THUMBNAIL_URL);

      html.push("<li>");
      html.push("<a href='javascript:void(0)' onclick='window.onAlbumClicked(");
      html.push(i + ")'>");
      html.push("<img class='albumthumb' src='" + thumb + "'>");
      html.push(title + " (" + itemcount + ")<br /></li>");
   }
   html.push("</ul>");
   document.getElementById('albummenu').innerHTML = html.join('');
}

window.onAlbumClicked = function(i) {
   if (i < 0 || i >= albums.length) return;
   document.getElementById('album_id').value = albums[i].getId();
   document.getElementById('album_title').value =
           albums[i].getField(opensocial.Album.Field.TITLE);
   document.getElementById('album_desc').value =
           albums[i].getField(opensocial.Album.Field.DESCRIPTION);
}

window.onSaveButtonClicked = function() {
   document.getElementById('savebutton').style.visibility = 'hidden';
   document.getElementById('statusspan').innerHTML = "Saving... Please wait...";

   var albumId = document.getElementById('album_id').value;
   var title = document.getElementById('album_title').value;
   var desc = document.getElementById('album_desc').value;

   var fields = [];
   fields[opensocial.Album.Field.TITLE] = title;
   fields[opensocial.Album.Field.DESCRIPTION] = desc;

   var idspec = opensocial.newIdSpec({'userId':'VIEWER'});
   var req = opensocial.newDataRequest();
   req.add(req.newUpdateAlbumRequest(idspec, albumId, fields),'update');
   req.send(onSavedAlbum);
}

function onSavedAlbum(resp) {
   if (resp.hadError()) {
      debug.say("*** Error!");
      document.getElementById('statusspan').innerHTML = "ERROR!";
      document.getElementById('savebutton').style.visibility = 'visible';
      return;
   }
   debug.say("Successfully updated.");
   document.getElementById('statusspan').innerHTML = "Saved successfully.";
   document.getElementById('savebutton').style.visibility = 'visible';

   // reload albums
   reloadAlbums();
}

gadgets.util.registerOnLoadHandler(reloadAlbums);
</script>

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.