ACME Shared State

Google's Shared Spaces does a couple different things. It provides a container to run gadgets. It also implements a back-end that shares state information between gadgets being run by different users.

This API does only the second part - sharing state.

Using the API is very simple. First, load up the JavaScript code:

<script src="http://acme.com/javascript/acme.namespace.jsm" type="text/javascript"></script>
<script src="http://acme.com/javascript/acme.utils.jsm" type="text/javascript"></script>
<script src="http://acme.com/sharedstate/acme.sharedstate.jsm" type="text/javascript"></script>

Next create a new shared state object. You give it two arguments: a state identifier, which should be unique to your app, and a callback routine that will handle state changes.

var ss = new acme.sharedstate.SharedState( 'yourstateid', YourStateChangeHandler );

When a state change arrives, the callback routine is invoked and gets passed one parameter, the new state. This is just a JavaScript object, i.e. name/value pairs.

function YourStateChangeHandler( state ) { [...] }

The state object always includes a "timestamp" variable, which is generated by the server so clock skew between different clients is not an issue.

To change the shared state, call SubmitDelta and pass it a JavaScript object with the new name/value pairs.

ss.SubmitDelta( { name1: 'value1', name2: 'value2' } );

Finally, to make sure everything gets saved properly when your window closes, you should call the Cleanup routine from an onbeforeunload handler.

window.onbeforeunload = YourCleanup;
function YourCleanup() { ss.Cleanup(); }

Here are a couple examples of the shared state API in action:

• Shared Scratchpad
• Fridge Poetry
• Talkomatic

Back to ACME Labs.