Jeremy Chone on web.dev

Asynch JS - The power of $.Deferred

2012-08-29T00:00:00Z

One of the most important aspects about building smooth and responsive HTML5 applications is the synchronization between all the different parts of the application such as data fetching, processing, animations, and user interface elements.

The main difference with a desktop or a native environment is that browsers do not give access to the threading model and provide a single thread for everything accessing the user interface (i.e. the DOM). This means that all the application logic accessing and modifying the user interface elements is always in the same thread, hence the importance of keeping all the application work units as small and efficient as possible and taking advantage of any asynchronous capabilities the browser offers as much as possible.

Browser Asynchronous APIs #

Luckily, Browsers provide a number of asynchronous APIs such as the commonly used XHR (XMLHttpRequest or 'AJAX') APIs, as well as IndexedDB, SQLite, HTML5 Web workers, and the HTML5 GeoLocation APIs to name a few. Even some DOM related actions are exposed asynchronously, such CSS3 animation via the transitionEnd events.

The way browsers expose asynchronous programming to the application logic is via events or callbacks.
In event-based asynchronous APIs, developers register an event handler for a given object (e.g. HTML Element or other DOM objects) and then call the action. The browser will perform the action usually in a different thread, and trigger the event in the main thread when appropriate.

For example, code using the XHR API, an event based asynchronous API, would look like this:

// Create the XHR object to do GET to /data resource  
var xhr = new XMLHttpRequest();
xhr.open("GET","data",true);

// register the event handler
xhr.addEventListener('load',function(){
if(xhr.status === 200){
alert("We got data: " + xhr.response);
}
},false)

// perform the work
xhr.send();

The CSS3 transitionEnd event is another example of a event based asynchronous API.

// get the html element with id 'flyingCar'  
var flyingCarElem = document.getElementById("flyingCar");

// register an event handler 
// ('transitionEnd' for FireFox, 'webkitTransitionEnd' for webkit) 
flyingCarElem.addEventListener("transitionEnd",function(){
// will be called when the transition has finished.
alert("The car arrived");
});

// add the CSS3 class that will trigger the animation
// Note: some browers delegate some transitions to the GPU , but 
//       developer does not and should not have to care about it.
flyingCarElemen.classList.add('makeItFly')

Other browser APIs, such as SQLite and HTML5 Geolocation, are callback based, meaning that the developer passes a function as argument that will get called back by the underlying implementation with the corresponding resolution.

For example, for HTML5 Geolocation, the code looks like this:

// call and pass the function to callback when done.
navigator.geolocation.getCurrentPosition(function(position){  
        alert('Lat: ' + position.coords.latitude + ' ' +  
                'Lon: ' + position.coords.longitude);  
});

In this case, we just call a method and pass a function that will get called back with the requested result. This allows the browser to implement this functionality synchronously or asynchronously and give a single API to the developer regardless of the implementation details.

Making Applications Asynchronous-Ready #

Beyond the browser’s built-in asynchronous APIs, well architected applications should expose their low level APIs in an asynchronous fashion as well, especially when they do any sort of I/O or computational heavy processing. For example, APIs to get data should be asynchronous, and should NOT look like this:

// WRONG: this will make the UI freeze when getting the data  
var data = getData();
alert("We got data: " + data);

This API design requires the getData() to be blocking, which will freeze the user interface until the data is fetched. If the data is local in the JavaScript context then this might not be an issue, however if the data needs to be fetched from the network or even locally in a SQLite or index store this could have dramatic impact on the user experience.

The right design is to proactively make all application API that could take some time to process, asynchronous from the beginning as retrofitting synchronous application code to be asynchronous can be a daunting task.

For example the simplistic getData() API would become something like:

getData(function(data){
alert("We got data: " + data);
});

The nice thing about this approach is that this forces the application UI code to be asynchronous-centric from the beginning and allows the underlying APIs to decide if they need to be asynchronous or not in a later stage.

Note that not all the application API need or should be asynchronous. The rule of thumb is that any API that does any type of I/O or heavy processing (anything that can take longer than 15ms) should be exposed asynchronously from the start even if the first implementation is synchronous.

Handling Failures #

One catch of asynchronous programing is that the traditional try/catch way to handle failures does not really work anymore, as errors usually happen in another thread. Consequently, the callee needs to have a structured way to notify the caller when something goes wrong during the processing.

In an event-based asynchronous API this is often accomplished by the application code querying the event or object when receiving the event. For callback based asynchronous APIs, the best practice is to have a second argument that takes a function that would be called in case of a failure with the appropriate error information as argument.

Our getData call would look like this:

// getData(successFunc,failFunc);  
getData(function(data){
alert("We got data: " + data);
}, function(ex){
alert("oops, some problem occured: " + ex);
});

Putting it together with $.Deferred #

One limitation of the above callback approach is that it can become really cumbersome to write even moderately advanced synchronization logic.

For example, if you need to wait for two asynchronous API to be done before doing a third one, code complexity can rise quickly.

// first do the get data.   
getData(function(data){
// then get the location
getLocation(function(location){
alert("we got data: " + data + " and location: " + location);
},function(ex){
alert("getLocation failed: "  + ex);
});
},function(ex){
alert("getData failed: " + ex);
});

Things can even get more complex when the application needs to make the same call from multiple parts of the application, as every call will have to perform these multi step calls, or the application will have to implement its own caching mechanism.

Luckily, there is a relatively old pattern, called Promises (kind of similar to Future in Java) and a robust and modern implementation in jQuery core called $.Deferred that provides a simple and powerful solution to asynchronous programing.

To make it simple, the Promises pattern defines that the asynchronous API returns a Promise object which is kind of a “Promise that the result will be resolved with the corresponding data.” To get the resolution, the caller gets the Promise object and calls a done(successFunc(data)) which will tell the Promise object to call this successFunc when the “data” is resolved.

So, the getData call example above becomes like this:

// get the promise object for this API  
var dataPromise = getData();

// register a function to get called when the data is resolved
dataPromise.done(function(data){
alert("We got data: " + data);
});

// register the failure function
dataPromise.fail(function(ex){
alert("oops, some problem occured: " + ex);
});

// Note: we can have as many dataPromise.done(...) as we want. 
dataPromise.done(function(data){
alert("We asked it twice, we get it twice: " + data);
});

Here, we get the dataPromise object first and then call the .done method to register a function we want to get called back when the data gets resolved. We can also call the .fail method to handle the eventual failure. Note that we can have as many .done or .fail calls as we need since the underlying Promise implementation (jQuery code) will handle the registration and callbacks.

With this pattern, it is relatively easy to implement more advanced synchronization code, and jQuery already provides the most common one such a $.when.

For example, the nested getData/getLocation callback above would become something like:

// assuming both getData and getLocation return their respective Promise
var combinedPromise = $.when(getData(), getLocation())

// function will be called when both getData and getLocation resolve
combinePromise.done(function(data,location){
alert("We got data: " + dataResult + " and location: " + location);
});

And the beauty of it all is that jQuery.Deferred makes it very easy for developers to implement the asynchronous function. For example, the getData could look something like this:

function getData(){
// 1) create the jQuery Deferred object that will be used
var deferred = $.Deferred();

// ---- AJAX Call ---- //
XMLHttpRequest xhr = new XMLHttpRequest();
xhr.open("GET","data",true);

// register the event handler
xhr.addEventListener('load',function(){
if(xhr.status === 200){
    // 3.1) RESOLVE the DEFERRED (this will trigger all the done()...)
    deferred.resolve(xhr.response);
}else{
    // 3.2) REJECT the DEFERRED (this will trigger all the fail()...)
    deferred.reject("HTTP error: " + xhr.status);
}
},false) 

// perform the work
xhr.send();
// Note: could and should have used jQuery.ajax. 
// Note: jQuery.ajax return Promise, but it is always a good idea to wrap it
//       with application semantic in another Deferred/Promise  
// ---- /AJAX Call ---- //

// 2) return the promise of this deferred
return deferred.promise();
}

So, when the getData() is called, it first creates a new jQuery.Deferred object (1) and then returns its Promise (2) so that the caller can register its done and fail functions. Then, when the XHR call returns, it either resolves the deferred (3.1) or reject it (3.2). Doing the deferred.resolve will trigger all the done(…) functions and other promise functions (e.g., then and pipe) and calling deferred.reject will call all the fail() functions.

Use Cases #

Here are some good use cases where Deferred can be very useful:

Data Access: Exposing data access APIs as $.Deferred is often the right design. This is obvious for remote data, as synchronous remote calls would completely ruin the user experience, but is also true for local data as often the lower level APIs (e.g., SQLite and IndexedDB) are asynchronous themselves. The Deferred API''s $.when and .pipe are extremely powerful to synchronize and chain asynchronous sub-queries.

UI Animations: Orchestrating one or more animations with transitionEnd events can be quite tedious, especially when the animations are a mixed of CSS3 animation and JavaScript (as it is often the case). Wrapping the animation functions as Deferred can significantly reduce the code complexity and improve flexibility. Even a simple generic wrapper function like cssAnimation(className) that will return the Promise object that gets resolved on transitionEnd could be of a great help.

UI Component Display: This is a little bit more advanced, but advanced HTML Component frameworks should use the Deferred as well. Without going too much into the details (this will be the subject of another post), when an application needs to display different parts of the user interface, having the lifecycle of those components encapsulated in Deferred allows greater control of the timing.

Any browser asynchronous API: For normalization purpose, it is often a good idea to wrap the browser API calls as Deferred. This takes literally 4 to 5 lines of code each, but will greatly simplify any application code. As show in the above getData/getLocation pseudo code, this allows the applications code to have one asynchronous model across all types of API (browsers, application specifics, and compound).

Caching: This is kind of a side benefit, but can be very useful in some occasion. Because the Promise APIs (e.g., .done(…) and .fail(…)) can be called before or after the asynchronous call is performed, the Deferred object can be used as a caching handle for an asynchronous call. For example, a CacheManager could just keep track of Deferred for given requests, and return the Promise of the matching Deferred if it has not be invalidated. The beauty is that the caller does not have to know if the call has already been resolved or is in the process of being resolved, its callback function will get called exactly the same way.

Conclusion #

While the $.Deferred concept is simple, it can take time to get a good handle on it. However, given the nature of the browser environment, mastering asynchronous programing in JavaScript is a must for any serious HTML5 application developer and the Promise pattern (and the jQuery implementation) are tremendous tools to make asynchronous programming reliable and powerful.

Case Study - HTML5 MathBoard

2011-10-28T00:00:00Z

Introduction #

MathBoard on iPad, a PalaSoftware application, is a highly polished application with many subtle but natural animations and a unique realistic look and feel. The goal was to do the highest fidelity port of the iPad application to HTML5.

N2N-Apps is a Software Development company focusing on building next generation of Web and Mobile application with HTML5 technology. The company was funded in 2010 by Jeremy Chone whom, after 11 years of engineering and management experience from Netscape, Oracle, and Adobe, decided to share its expertise with businesses to build high-quality Web and Mobile applications. N2N-Apps focuses on quality and speed of delivery.

Download MathBoard for the Chrome Web Store Download MathBoard for the Chrome Web Store (free version)

Requirements #

The key requirements for this HTML5 porting project were the following:

High fidelity port of the original iPad application look and feel and user interface.
Adapt to the target form factor (i.e. PC/Mac with keyboard/mouse vs touch screen).
Implement 100% of the applicable features.
Target principally HTML5 browsers.
Make the application "server-less" so that the application runs entirely on the client and could be hosted on a static server or Google Chrome packaged application.
Make a 1.0 version with all the features but the problem solver in less than a month.

Architecture #

Given the requirements, we decided to go with the following architecture:

HTML5: Since we do not have any HTML4 support requirements, we decided to go with HTML5 as the base.
jQuery: While HTML5 has many of the advanced selectors that make jQuery so great, we decided to stick with jQuery anyway as it gave us a very robust and mature way to manipulate the DOM and related events. jQuery also has the benefit of being more DOM centric, which tends to make the design and implementation of an application closer to HTML.
SnowUI: jQuery provides a great API and best practice to work with the DOM, however, for the HTML5 MathBoard application we needed an MVC or MVP style framework to orchestrate all of the different views. SnowUI is a simple yet powerful MVC framework on top of jQuery. It provides a DOM centric MVC mechanism and a flexible way to build custom components while leaving the opportunity for the application developer to use any widget/controls library or custom code he or she deems optimal.

iPad to PC considerations #

When porting the application to HTML5 for PC usage, we had to make several modifications to the design and user-interaction of the application.

Screen orientation #

The iPad MathBoard is exclusively vertically oriented, which was not optimal for PC displays as they are generally used in a horizontal fashion. Consequently, we reorganized the UI design and moved the settings panel to the right side, on a sliding view (animated by CSS3 transitions).

iPad vs. HTML5 screen orientation

Input: keyboard/mouse vs. touch #

Another key difference between the iPad and Web version is the input interface. On the iPad you have only the touch interface, on the PC you need take into consideration both mouse and keyboard.

The MathBoard input controls on the iPad are highly polished. We wanted the same high fidelity representation in the Web interface. The solution was adding support for keyboard shortcuts and replicating UI controls using CSS positioning. The port to HTML5 was pixel perfect:

iPad vs. HTML5 Version Settings

As in the iPad interface, we allow the user to click on the left and right arrow to change the value of a control. The vertical line can also be dragged to quickly change values. A repeat behavior was implemented for click and keydown so that users can accelerate the value change when the mouse or the keyboard is pressed.

TAB support was added to move from one input field to another and the ← and → arrows cycles through values.

One feature in the iPad version that didn't make much sense for the PC interface was the drawing board. While it could have been fancy to implement it, drawing numbers with a mouse is not very practical. Instead, we decided to spend more time polishing the keyboard interface than implementing the drawing board.

HTML5 features #

In the Web version of MathBoard, we use many HTML5 features:

Local storage #

MathBoard allow users to save their quiz to later replay them. HTML5 MathBoard implements this feature using HTML5 localStorage using the SnowUI DAO interface.

localStorage was a natural choice since the data was simple enough and did not require advanced indexing. We store all quizzes in one JSON format that we JSON.stringify as text.

The snowUI DAO is a simple CRUD interface wrapper which allows the UI to fetch data without having to worry about how it's actually stored. The DAO implementation takes care of the storage particulars.

In MathBoard, the storage requirements were very simple. We needed to store only the user settings and the quiz data. Both where stored as JSON strings in localStorage.

So, for example, the DAO for the setting value looked like this:

snow.dm.registerDao('settingValue', (function() {

  var _settingValues = null;

  function SettingValueDao() {};

  // ------ DAO CRUD Interface ------ //
  // get
  SettingValueDao.prototype.get = function(objectType, id) {
    return $.extend({},getSettingValues()[id]);
  };

  // find, remove

  // save
  SettingValueDao.prototype.save = function(objectType, data) {
    var storeValue = getSettingValues('settingValue')[data.id];
    if (!storeValue) {
      storeValue = {};
      getSettingValues()[data.id] = storeValue;
    }

    $.extend(storeValue, data);
    saveSettingValues();
  };
  // ------ /DAO CRUD Interface ------ //

  function getSettingValues() {
    if (_settingValues == null) {
      var settingValuesString = localStorage.getItem('settingValues');
      if (settingValuesString) {
        _settingValues = JSON.parse(settingValuesString);
      } else{
        _settingValues = {};
      }
    }

    return _settingValues;
  }

  function saveSettingValues(){
    var settingValues = getSettingValues();
    if (settingValues != null) {
      localStorage.removeItem('settingValues');
      localStorage.setItem('settingValues', JSON.stringify(settingValues)); 
    }
  }

  return new SettingValueDao();
})());

Once this DAO is registered for the settingValue, the UI can make the following call without needing to worry about the store logic:

var addition = snow.dm.get('settingValue', 'operator_addition');
addition.value = true; // to check the addition checkbox
snow.dm.save('settingValue', addition);

CSS3 fonts #

MathBoard uses custom fonts. Thanks to CSS3 font support, it was trivial to include the 'Chalkduster' true type font into our application:

@font-face {
  font-family: Chalkduster;
  src: url(Chalkduster.ttf);
}

And, since this font was the default for almost all the text in the application, we made it the default for body.

body {
  background: #333333;
  font-family: Chalkduster;
  color: #ffffff;
}

CSS3 gradient, shadow, rounded corners #

All gradient, shadow, transparency, and rounded corners are done with CSS3. This was a real game saver compared to the traditional .png way of doing user interfaces.

We also used advanced CSS3 properties to customize the look and feel of the scrollbar to make it more subtle (see http://webkit.org/blog/363/styling-scrollbars/ for styling scroll bars on WebKit browsers).

CSS3 transitions #

For HTML5 MathBoard, we replicated all of the iPad's animations and even added a new one for the sliding right panel. Thanks to CSS3 transitions, adding animations was trivial and allowed for the best performance.

We had three main animations in the applications.

1.) The sliding right pane #

The first animation is on the right pane (#rightPane), which slides closed when the user starts a new quiz and slides open when the user ends a quiz. To create this effect, we used the following CSS transition and triggered it via JavaScript. The default style of the rightPane is open:

#rightPane {
  /* look and feel, and layout property */
  position: absolute;
  width: 370px;
  height: 598px;
  top: 28px;
  left: 720px; /* open */
  -webkit-transition: all .6s ease-in-out;
}

When the user starts a quiz, our JavaScript logic moves the panel:

var $rightPane = $('#rightPane');
var left = $rightPane.position().left - 400;
setTimeout(function() {
  $rightPane.css('left', left + 'px');
}, 0);

A few notes on this implementation:

Given that the application sizes are fixed, we could have used a CSS class '.close' and hardcode the close position the same way we hardcode the open one.
We could also have used CSS 'translate', which would have been more performant than animating the pane's 'left' property. This is especially true for mobile devices (such as iOS) where 3D transforms are hardware accelerated.
The setTimeout is not strictly necessary in this case since the original position was set prior to the modification. However, it allows the browser to make the animation smoother by displaying the quiz just before sliding the rightPane in.

2.) Settings dialog box animation #

When the user clicks on a setting in the right, the settings dialog appears from the bottom of the screen and scrolls down to the appropriate section.

To accomplish this, we had a similar transition to the right pane. The only thing that took some time was to resolve the jerkiness on first appearance of the dialog. To instruct the browser to cache the dialog UI, we ended up displaying it once and scrolling to it. At first, we tried with display: none. This approach was wrong because the browser assumed the dialog does not need to be shown. The solution was to display the settings with a z-index: -1 at initialization, making it invisible to the user but visible to the browser.

3.) Quiz success or incorrect message animation #

The third animation is actually two in one. When the 'success' or 'incorrect' message appears, first scale to a point, wait for a little, and finally scale even bigger and disappear. For this, we have two CSS3 animation styles, and orchestrate it via JavaScript on a webkitTransitionEnd event.

.quiz-result > div.anim1 {
  opacity: 0.8;
  -webkit-transform: scale(6,6);
}
.quiz-result > div.anim2{
  opacity: 0;
  -webkit-transform: scale(9,9);
}

setTimeout(function() {
  $msg.addClass("anim1");
  $msg.bind("webkitTransitionEnd", function(){
    if ($msg.hasClass("anim1")) {
      setTimeout(function() {
        $msg.removeClass("anim1");
        $msg.addClass("anim2");
      }, 300);
    } else {
      $msg.remove();
      displayNextItem();
      freezeInput = false;
    }
  });
}, 0);

Audio tag #

When users answer a quiz, the application makes a success or fail sound. The simple choice was to use the audio tag and call play() on them. These audio bits are added to the main page of the application:

<audio id="audioCorrect" src="correct.mp3" preload="auto" autobuffer></audio>
<audio id="audioWrong" src="wrong.mp3" preload="auto" autobuffer></audio>

Conclusion #

HTML5 is truly enabling a new breed of Web, desktop, and mobile applications. CSS3 was instrumental in customizing the look and feel of the application to closely match the high sophistication of MathBoard for iPad, HTML5 storage was a perfect fit for our data persistence, and the simplicity of HTML5 audio allowed us to closely replicate the iPad app.