Tuesday, December 18, 2007

opensocial.Person, How To Get Data.

This Article will briefly review the options for getting data from the opensocial.Person object.

isOwner() and isViewer() Two simple but very useful methods are isOwner() and isViewer().

Both of these methods return boolean values that describe whether or not the Person is the OWNER or VIEWER of the application.

In the end, these boolean values can be spoofed. We recommend caution be taken when using isOwner() and isViewer() in conjunction with any important items.


        // example of isOwner()
        
        if( viewer.isOwner() ){
            // do something
        }

getId() The Id referenced here is a unique user identification String. It is expected that each user across a specific container will have a different unique identifier.


        // example of getId()
        
        var viewerId = viewer.getId();

getDisplayName() This method does exactly what it says. It will return the Person's display name.

The display name is (as far as we can tell) the First and Last name in a single String.


        // example of getDisplayName()
        
        alert( viewer.getDisplayName() );

getField() getField() is the most powerful method of the opensocial.Person object. It can be used to return one of (4) fields.

opensocial.Person.Field.ID: returns the person's unique ID. (The same as .getId)
opensocial.Person.Field.NAME: currently returns the same as getDisplayName()
opensocial.Person.Field.PROFILE_URL: returns the URL to the person's profile.
opensocial.Person.Field.THUMBNAIL_URL: returns the URL to the person's profile image.

Each of the above can be passed as arguments to the getField() method. This list is expected to grow, so you should check the API to see if new options have become available.

Note that currently, PROFILE_URL returns an incomplete URI. You'll need to get the server root URL (eg http://sandbox.orkut.com/) by using an alternate method and prepend that to the PROFILE_URL.

Google has noted that, in the future, PROFILE_URL will return a complete URI.

It may be beneficial (especially if your building a large app) to create a temporary getRoot function that can be altered when the PROFILE_URL return value is fixed. You could check for 'http://' in the returned value and prepend the server root if necessary.


        // examples of getField()
        
        var name = viewer.getField( opensocial.Person.Field.NAME );
        var id = viewer.getField( opensocial.Person.Field.ID );
        var pUrl = viewer.getField( opensocial.Person.Field.PROFILE_URL );
        var iUrl = viewer.getField( opensocial.Person.Field.THUMBNAIL_URL );
        
        // note that pURL is incomplete. On Orkut, there is a temporary fix for this...
        
        pUrl = _args()['parent'] + pUrl;
    
        // OR possibly set up a temporary function to handle PROFILE_URL return values
        
        function getRoot( PROFILE_URL ){
            if( PROFILE_URL.indexOf( 'http://' ) >= 0 ) return PROFILE_URL;
            return _args()['parent'] + pUrl; 
        }
        
        // now we can say...
        
        pUrl = getRoot( pUrl );
        
        // pUrl is now a full URI

If you need help getting the opensocial.Person object, please see either our VIEWER and OWNER Tutorial or our Getting Friends Tutorial.