Please Note: The 0.7 version of the Opensocial API removed instanceAppData from the specification. As such, the information contained in this tutorial is no longer applicable. Saturday, December 15, 2007

How to update InstanceAppData.

This tutorial walks through the steps taken to create an appInstanceData object for easy setting and retrieval of App Instance Data.

Please see here if your interested only in Retrieving Instance App Data >>>

Also, you can just download the entire instanceAppData Object.

Instance Data: Instance App Data is a data store that is available to only a single running instance of an application. An instance of an application can be defined as a copy of the application running on a single page.

Note that this is a relationship between the application and the page it is running on. If the application is moved to another page, the instance data for the previous page will not be available. Also, any other applications on a page will not have access to this applications App Instance Data.

This makes App Instance Data extremely useful for storing items that relate only to 'this' app running under 'this' page.

The Goal... We want to create an object that makes setting and getting App Instance Data a whole lot easier. The object should have the following method definitions:

get: A method that returns Instance App Data as a Map Object.
set: A method that sets Instance App Data of type String or Array without having to specify.

In order to store the Array data, we'll need to convert it to a JSON String. Google has noted that future API versions will include functionality for JSON conversion, but for now we'll use the JSON parser and stringifier functions (available here) for the conversion functionality.

Note that this object requires JSON conversion functionality (available here).

Setting Instance App Data: To begin, we'll create an object called instanceAppData and give it an init() method. The init() method will instantiate a single local variable: an opensocial.DataRequest Object.


        var instanceAppData = {
                    reqObj:null
                    ,init:function(){
                        if(!this.reqObj) this.reqObj = opensocial.newDataRequest();
                    }
        }

Now we can start building the setter method, which we'll call set(). This method should take (4) arguments:

data: The data to store. This can be either a String or an Array.
key: What to call the data. We'll use this to retrieve it.
callBack: A function to fire when the data has been stored sucessfully.
error: A function to fire in case of an error storing data.

Inside of the function, we need to first make sure our reqObj variable has been initialized. We'll call the init() function for this.

The JSON.stringify method won't throw any errors if we pass it either a String or an Array, so we don't need to do anything to the data before we convert it.

We can just run it through our stringify method(available here) to convert it to a JSON String. If anything does go wrong, we'll use our 'error' function to exit.

        var instanceAppData = {
                    reqObj:null
                    ,init:function(){
                        if( !this.reqObj ) this.reqObj = opensocial.newDataRequest();
                    }
                    ,set:function( data, key, callBack, error ){
                        this.init();
                        try{
                             JSON.stringify( data );
                        }catch(e){
                             error(e);
                             return;                        
                        }
                    }
        }

Now we can add() a newUpdateInstanceAppDataRequest() to our opensocial.DataRequest Object before we send() it.

We need to get a reference to our Object (to 'this') so we can pass function references around without worrying about 'this' changing. We'll do this by using the line: var _self = this;. Now we can pass '_self' around without it ever changing.

The send() method takes a function as an argument. So we'll need to create a function that handles the returned data and pass that to the send() method. We also need to pass along our custom callBack and error functions.

        var instanceAppData = {
                    reqObj:null
                    ,init:function(){
                        if( !this.reqObj ) this.reqObj = opensocial.newDataRequest();
                    }
                    ,set:function( data, key, callBack, error ){
                        this.init();
                        try{
                             JSON.stringify( data );
                        }catch(e){
                             error(e);
                             return;                        
                        }
                        this.reqObj.add( this.reqObj.newUpdateInstanceAppDataRequest( key , data ) , 'update' );
                        var _self = this;
                        this.reqObj.send( function( ret ){
                                    _self.setRet( callBack, error, ret );                                                           
                        });
                   }
        }

Now we need to create the setRet() function to handle the data object that is returned from the send() function.

All we want to do is check to see if any errors occurred, and fire either our error function or our callBack function accordingly.

        var instanceAppData = {
                    reqObj:null
                    ,init:function(){
                        if( !this.reqObj ) this.reqObj = opensocial.newDataRequest();
                    }
                    ,set:function( data, key, callBack, error ){
                        this.init();
                        try{
                             JSON.stringify( data );
                        }catch(e){
                             error(e);
                             return;                        
                        }
                        this.reqObj.add( this.reqObj.newUpdateInstanceAppDataRequest( key , data ) , 'update' );
                        var _self = this;
                        this.reqObj.send( function( ret ){
                                    _self.setRet( callBack, error, ret );                                                           
                        });
                   }
                   ,setRet:function( callBack, error, ret ){
                        if( ret.hadError() || ret.get('update').hadError() ){ 
                            error( ret.getError() );
                            return;
                        }
                        callBack();
                   }
        }

Set Some Data: We're ready to use this object to set Instance App Data by calling a single method.

Below is the call to update an App Instance Data variable with the name 'myData' and the value 'This is myData.' Once 'myData' is updated, I want to set an Array of values and call it myData2.


         // setting some data, then setting some more data
        instanceAppData.set(
            'This is myData.'
            ,'myData'
            ,setMoreData // callback function
            ,function(e){ alert(e); }
        );
        
        function setMoreData(){
            instanceAppData.set(
                ['This is a data array - first value.', 'This is a data array - second value.']
                ,'myData2'
                ,function(){ alert('Data Set'); } // callback function
                ,function(e){ alert(e); }
            );       
        }

That's all there is to it, now we can work on Retrieving Instance App Data >>>

Or you can jump ahead and just download the entire instanceAppData Object.