Tuesday, December 18, 2007

Getting VIEWER_FRIENDS and OWNER_FRIENDS.

This tutorial will show you how to use the newFetchPeople request method to get the App Owner's friends, and App Viewer's friends.

If your looking to get the OWNER or VIEWER of the App, please see our VIEWER and OWNER Tutorial.

For information on getting data from the opensocial.Person object, please reference our opensocial.Person Tutorial.

Getting Started To begin, we'll need to instantiate an opensocial.DataRequest object. I'll call mine reqObj.


        var reqObj = opensocial.newDataRequest();

The newFetchPeopleRequest method takes an argument of either 'OWNER_FRIENDS' or 'VIEWER_FRIENDS' or an array containing both. Expect that in the future, additional group references will be able to be sent into this method.

We'll add the requests for both 'OWNER_FRIENDS' and 'VIEWER_FRIENDS' separately. I'll label them 'oF' and 'vF' respectively so we can find them later.

        var reqObj = opensocial.newDataRequest();
        
        reqObj.add( reqObj.newFetchPeopleRequest( 'OWNER_FRIENDS' ), 'oF' );
        reqObj.add( reqObj.newFetchPersonRequest( 'VIEWER_FRIENDS' ), 'vF' );

Now all we need to do is send our Data Request. The send method takes a function as an argument, so I'll pass in a reference to the function we'll create to handle the returned data.

        var reqObj = opensocial.newDataRequest();
        
        reqObj.add( reqObj.newFetchPeopleRequest( 'OWNER_FRIENDS' ), 'oF' );
        reqObj.add( reqObj.newFetchPersonRequest( 'VIEWER_FRIENDS' ), 'vF' );
        
        reqObj.send( handleDataReturn );

Handling The Returned Object Now we'll define our function for handling the returned data. The send method will pass an argument to our custom function containing the data we requested, so we'll need to define that argument so we have access to it.

We'll also do some error handling using the boolean hadError() functions.

        var reqObj = opensocial.newDataRequest();
        
        reqObj.add( reqObj.newFetchPeopleRequest( 'OWNER_FRIENDS' ), 'oF' );
        reqObj.add( reqObj.newFetchPersonRequest( 'VIEWER_FRIENDS' ), 'vF' );
        
        reqObj.send( handleDataReturn );
        
        function handleDataReturn( returnedDataObject ){
            if( returnedDataObject.hadError() || returnedDataObject.get('oF').hadError() || returnedDataObject.get('vF').hadError() ){
                // handle the error
                return; // exit
            }
        }

Now we're ready to assign the data to variables. Note that the returned data type is not an Array (as you may expect), but is of the type opensocial.Collection. We'll look at that further later.

        var reqObj = opensocial.newDataRequest();
        
        reqObj.add( reqObj.newFetchPeopleRequest( 'OWNER_FRIENDS' ), 'oF' );
        reqObj.add( reqObj.newFetchPersonRequest( 'VIEWER_FRIENDS' ), 'vF' );
        
        reqObj.send( handleDataReturn );
        
        function handleDataReturn( returnedDataObject ){
            if( returnedDataObject.hadError() || returnedDataObject.get('oF').hadError() || returnedDataObject.get('vF').hadError() ){
                // handle the error
                return; // exit
            }
            var vF = returnedDataObject.get('vF');
            var oF = returnedDataObject.get('oF'); // both are now opensocial.Collection objects         
   }

The opensocial.Collection Object Both of the variables we defined above are of the type opensocial.Collection containing a 'collection' of opensocial.Person(s).

To turn the opensocial.Collection object into an array, just use the asArray() function. Then you can itterate through the list of opensocial.Person(s).

Another (easier) method for itteration is the each() method, which calls a custom function for every Person in the collection, passing the function the Person object for each individual as an argument.


    
        // turn the data into an array
        
        vF_Array = vF.asArray();
        oF_Array = oF.asArray();
        
        // use the .each() method to itterate through the collection
        
        vF.each( function( Person ){
            alert( Person.getField( opensocial.Person.Field.NAME ) );
            // do more stuff with this Person
        });

For additional information on how to get information from the opensocial.Person object, please see our opensocial.Person Tutorial.

Please also see our Viewer and Owner Tutorial.