High-Level Data Format Conversion

Dojo relies on JavaScript objects and arrays for most of its internal communication. Unfortunately, the world doesn't work solely in JavaScript and you must convert data formats into JavaScript before Dojo can use them. Specifically:

• HTML Forms keep data for display and entry for the browser. Its contents live in a DOM tree.
• URL Query Parameters are used to pass form data to a server via HTTP GET.
• JSON is a popular XML alternative optimized for performance, and is often used where you can control the web service.

Dojo, being the diplomat that it is, can convert to and from most of these formats. Why not all? Because strictly speaking, the formats are not equivalent. JavaScript and JSON model arrays with ordered indexes, while HTML forms and URL queries model them as unordered collections. To illustrate:

var x = {a: 1, b: [2, 3] };

{"x": {"a": 1, "b": [2, 3] }}

Given those limitations, here are the dojo conversion functions. All are available in Dojo Base, so no required's are necessary.

Communication Between Threads - dojo.Deferred

JavaScript has no threads, and even if it did, threads are hard.  Deferreds are a way of abstracting non-blocking events, such as the final response to an XMLHttpRequest. Deferreds create a promise to return a response a some point in the future and an easy way to register your interest in receiving that response.

How Does it Work?

Imagine a whiteboard in a math classroom.  One professor knows that the maintenance person for this particular classroom is a math genius.  So the professor writes on the board a question:

"What is the Shortest Proof for Fermat's Last Theorem?  Call x.2591 when you have the answer."

That night, the maintenance worker finds the question on the whiteboard.  It's an interesting problem.  So he continues to mop the floors thinking about it.  (Uhh, does this sound like a movie with Ben Affleck and Matt Damon?  Could be...)

Now suppose students would also like the answer.  (It'd make a helluva term paper!)  They scribble notes underneath like "Also call 555-8244.  Also email mathlunkhead@aol.com," etc.

Finally, 8 nights later, the maintenance worker writes down the answer on the whiteboard and calls x.2591, 555-8244, and emails "mathlunkhead@aol.com".

dojo.Deferred is like the whiteboard.  At least one person has a question that needs answering by some other entity.  In Web 2.0 applications, this is often a server process called by XmlHTTPRequest.  Unfortunately, we don't know when the answer will come back.  We can either call the process synchronously (we wait by the whiteboard for the answer) or asynchronously (we leave the room and asked to be called). 

The email addresses and phone numbers symbolize handlers.  A handler is simply a Javascript function called when the answer is complete.  These are split between callbacks and errbacks which handle normal completion and errors respectively. 

Using Deferreds

The most important methods for Deferred users are:    

• addCallback(handler)
• addErrback(handler)
• callback(result)
• errback(result)

In general, when a function returns a Deferred, users then "fill in" the second half of the contract by registering callbacks and error handlers. You may register as many callback and errback handlers as you like and they will be executed in the order registered when a result is provided. Usually this result is provided as the result of an asynchronous operation. The code "managing" the Deferred (the code that made the promise to provide an answer later) will use the callback() and errback() methods to communicate with registered listeners about the result of the operation. At this time, all registered result handlers are called with the most recent result value.

Deferred callback handlers are treated as a chain, and each item in the chain is required to return a value that will be fed into successive handlers. The most minimal callback may be registered like this:

                var d = new dojo.Deferred();
                d.addCallback(function(result){ return result; });

Perhaps the most common mistake when first using Deferreds is to forget to return a value (in most cases, the value you were passed).

The Deferred also keeps track of its current status, which may be one of three states:

• -1: no value yet (initial condition)
• 0: success
• 1: error

A Deferred will be in the error state if one of the following three conditions are met:

1.  The result given to callback or errback is an object whose class or superclass is Error, e.g. "instanceof Error" is true.,
2.  The previous callback or errback raised an exception while executing
3.  The previous callback or errback returned a value whose class or superclass is "Error"

Otherwise, the Deferred will be in the success state. The state of the Deferred determines the next element in the callback sequence to run.

When a callback or errback occurs with the example deferred chain, something equivalent to the following will happen (imagine that exceptions are caught and returned):

                 d.callback(result) or d.errback(result)
                if(!(result instanceof Error)){
                    result = myCallback(result);
                }
                if(result instanceof Error){
                    result = myErrback(result);
                }
                result = myBoth(result);
                if(result instanceof Error){
                    result = myErrback(result);
                }else{
                    result = myCallback(result);
                
}

The result is then stored away in case another step is added to the callback sequence. Since the Deferred already has a value available, any new callbacks added will be called immediately.

There are two other "advanced" details about this implementation that are useful:

• Callbacks are allowed to return Deferred instances themselves, so you can build complicated sequences of events with ease.
• The creator of the Deferred may specify a canceller.  The canceller is a function that will be called if Deferred.cancel is called before the Deferred fires. You can use this to implement clean aborting of an XMLHttpRequest, etc. Note that cancel will fire the deferred with a CancelledError (unless your canceller returns another kind of error), so the errbacks should be prepared to handle that error for cancellable Deferreds.

Deferred objects are often used when making code asynchronous. It may be easiest to write functions in a synchronous manner and then split code using a deferred to trigger a response to a long-lived operation. For example, instead of register a callback function to denote when a rendering operation completes, the function can simply return a deferred:

function renderLotsOfData(data, callback) {
   var success = false;
   try{
      for(var x in data) {
         renderDataitem(data[x]);
     }
     success = true;
   }catch(e){ }
   if(callback){
      callback(success);
   }
}

renderLotsOfData(someDataObj, function(success){
   //handles success or failure
   if (!success){
      promptUserToRecover();
   }
});

NOTE: there's no way to add another callback here!!

Using a Deferred doesn't simplify the sending code any, but it provides a standard interface for callers and senders alike, providing both with a simple way to service multiple callbacks for an operation and freeing both sides from worrying about details such as "did this get called already?". With Deferreds, new callbacks can be added at any time.

function renderLotsOfData(data, callback){
   var d = new dojo.Deferred();
   try {
      for (var x in data) {
         renderDataitem(data[x]);
      }
      d.callback(true);
   } catch(e) { 
      d.errback(new Error("rendering failed"));
   }
   return d;
}

renderLotsOfData(someDataObj).addErrback(function(){
   promptUserToRecover();
});
      

NOTE: addErrback and addCallback both return the Deferred again, so we could chain adding callbacks or save the deferred for later should we need to be notified again.

In this example, renderLotsOfData is syncrhonous and so both versions are pretty artificial. Putting the data display on a timeout helps show why Deferreds rock:

    
                 Deferred style 
                function renderLotsOfData(data, callback){
                    var d = new dojo.Deferred();
                    setTimeout(function(){
                        try{
                            for(var x in data){
                                renderDataitem(data[x]);
                            }
                            d.callback(true);
                        }catch(e){ 
                            d.errback(new Error("rendering failed"));
                        }
                    }, 100);
                    return d;
                }
    
                 using Deferred style
                renderLotsOfData(someDataObj).addErrback(function(){
                    promptUserToRecover();
                });
    
            Note that the caller doesn't have to change his code at all to
            handle the asynchronous case.
 

Author: Alex,  with Good Will Hunting analogy provided by Craig Riecke (and Ben and Matt)

Cookies