In this post we won’t actually write any new code – we will look at the “Social Hello World” gadget and get an understanding of the asynchronous data loading pattern.
The first thing to understand and accept is that all requests are asynchronous. You could so do something evil with setTimer() in JavaScript to fake synchronous requests – but if you did that, my guess is that you would be chided as not knowing the “way of the Gadget”.
The problem is once you go asynchronous, you need to delay real work of making markup and making UI until the message comes back much later. And once you accept the fact that UI change is effectively “event driven”, you really want to batch up all your requests into a single request, send in one large multi-call request and then wait once for all of it and then when it all comes back, put up the UI.
Here is the documentation for osapi.BatchRequest – study it – it is your friend as a gadget writer.
Up to now, we have been doing our hacks to the “Social Hello World” gadget right at the moment of start up. For example in all of the screenshots you will notice that the gadget UI is not present behind the alert box when our alert boxes come up.
This is because the gadget has not started yet – we jumped in right after the title was set and sneaked in our alert boxes that have the effect of (a) showing us if our stuff is working and (b) pausing the code before the gadget has a chance to retrieve its data and generate its markup.
So lets look through the “Social Hello World” gadget. (preferably a clean version without our hacks).
vi ./target/work/webapp/samplecontainer/examples/SocialHelloWorld.xml
If we look down for the following code:
function initData() {
var fields = ['id','age','name','gender','profileUrl','thumbnailUrl'];
var batch = osapi.newBatch();
batch.add('viewer', osapi.people.getViewer({sortBy:'name',fields:fields}));
batch.add('viewerFriends', osapi.people.getViewerFriends({sortBy:'name',fields:fields}));
batch.add('viewerData', osapi.appdata.get({keys:['count']}));
batch.add('viewerFriendData', osapi.appdata.get({groupId:'@friends',keys:['count']}));
batch.execute(render);
}
gadgets.util.registerOnLoadHandler(initData);
This is making a nice batch call and adding a number of service requests to the call which includes all of the data needed to build the initial UI. When it calls batch.execute, it is requesting that the server (in one request) make all the service calls in the order specified, take all the return data, and send it back to us as a single response and when that response is complete call the method render.
If we look at render we see that it takes a response object and starts pulling it apart, setting the local data needed by the Gadget and then later making the UI markup and later putting it in an empty div so the UI appears to the user.
function render(data) {
var viewer = data.viewer;
allPeople = data.viewerFriends.list;
var viewerData = data.viewerData;
viewerCount = getCount(viewerData[viewer.id]);
…
html += '<div class="person">';
html += '<div class="bubble c' + count % numberOfStyles + '">'
+ hellos[count % hellos.length];
html += '<div class="name">' + allPeople[i].name.formatted
+ ' (' + count + ') ' + allPeople[i].gender;
html += '</div></div>';
…
document.getElementById('helloworlds').innerHTML = html;
gadgets.window.adjustHeight();
It pulls out the data (never checking the data.error status), builds some HTML from the data, and puts it in a div and adjusts the height of the div, and voila! there is a user interface.
The batch pattern makes it so we only have to wait for one request and then we do all our work when we receive the “event” that indicates that our data is back from the server and ready to process. The code in the sample gadget is a bit light on error handling but that should not be too hard to imagine.
So now that we understand the batch/asynchronous/render-on-event pattern, we can do some data retrieval of our own in the next post.