Some of the oldest code in the toolkit was written to smooth out inconsistencies with the underlying event model amongst different browsers. This section provides a brief overview of the events that you can count on being normalized when you use Dojo to develop an application. The basis of standardization is the W3C model.

dojo.fixEvent(/*DOMEvent*/ evt, /*DOMNode*/ sender) //Returns DOMEvent

/* ... snip ... */
  if (evt.keyCode == dojo.keys.ENTER && evt.shiftKey) {
    /* ... */
  }
/* ... snip ... */

Direct communication channels are constructed by explicitly chaining together functions and/or DOM events so that when one executes, another is automatically invoked afterward. For example, each time an object changes via a "setter" method, you may want to automatically trigger a change in the application's visual interface. Or, perhaps each time one object changes, you might want to automatically update a derived property on another object. The possibilities are endless.

The two primary methods involved in a direct communication scheme are dojo.connect and dojo.disconnect. In short, you use dojo.connect to chain together a series of events. Each call to dojo.connect returns a handle that you should keep and explicitly pass to dojo.disconnect whenever you are ready to dispose of the connection. Conveniently, all handles are disconnected automatically when the page unloads, but manual management of the handles may be necessary for preventing memory leaks in long-running applications that invoke a lot of connections that are used temporarily. (This is particularly the case on IE.) Coming up is the API that was introduced in Chapter 1, Toolkit Overview.

Setting up and tearing down connections is easy. Here's the basic API:

/* Set up a connection */
dojo.connect(/*Object|null*/ obj,
            /*String*/ event,
            /*Object|null*/ context,
            /*String|Function*/ method) // Returns a Handle

/* Tear down a connection */
dojo.disconnect(/*Handle*/handle);

Let's take a look at an example that illustrates a kind of problem that dojo.connect would be suitable for helping us to solve:

function Foo(  ) {
    this.greet = function(  ) { console.log("Hi, I'm Foo"); }
}

function Bar(  ) {
    this.greet = function(  ) { console.log("Hi, I'm Bar"); }
}

foo = new Foo;
bar  = new Bar;

foo.greet(  );

//bar should greet foo back without foo
//ever having to know that bar exists.

As it turns out, we can solve this little conundrum with one line of code. Modify the previous listing like so, and test this out in Firebug:

function Foo(  ) {
    this.greet = function(  ) { console.log("Hi, I'm foo"); }
}

function Bar(  ) {
    this.greet = function(  ) { console.log("Hi, I'm bar"); }
}

foo = new Foo;
bar  = new Bar;

//Anytime foo.greet fires, fire bar.greet afterward...
var handle = dojo.connect(foo, "greet", bar, "greet"); //set up the connection

foo.greet(  ); //bar automatically greets back now!

The payout for writing that one line of code was pretty high, don't you think? Notice that the second and fourth parameters to dojo.connect are string literals for their respective contexts and that a handle is returned that can later be used to tear down the connection. In general, you always want to tear down the connection at some point, whether it be to accomplish some kind of functional requirement in your design, or when you're performing some final cleanup—such as when an object is destroyed or the page is unloaded. Here's how:

var handle = dojo.connect(foo, "greet", bar, "greet");
foo.greet(  );

dojo.disconnect(handle);

foo.greet(  ); //silent treatment this time

In addition to dojo.connect accomplishing so much with so little effort, notice how clean and maintainable the source code remains. No boilerplate, no spaghetti code, no wiring up your own solution, no maintenance nightmare.

Firing methods off in response to happenings in the page is really useful, but sooner or later you'll need to pass around some arguments. As it turns out, one additional feature of connect is that it automatically passes the arguments from the first context's function to the second context's function. Here's an example that shows how:

function Foo(  ) {
    this.greet = function(greeting) { console.log("Hi, I'm Foo.", greeting); };
}

function Bar(  ) {
    this.greet = function(greeting) { console.log("Hi, I'm Bar.", greeting); };
}

foo = new Foo;
bar = new Bar;

var handle= dojo.connect(foo, "greet", bar, "greet");
foo.greet("Nice to meet you");

As you might imagine, having the arguments get passed around automatically is quite handy, and this is especially the case when a function is connected to a DOM event such as a mouse click because it gives the function instant access to all of the important particulars of the event such as the target, the mouse coordinates, and so on. Let's investigate with yet another example:

//Note that the third argument is skipped altogether since the handler is a
//standalone anonymous function. Using null to placehold the third parameter would
//have produced the very same effect.

dojo.connect(
    dojo.byId("foo"), //Some DOM element
    "onmouseover",
    function(evt) {
      console.log(evt);
    });

If you set up a sample page, wire up the connection, and watch the Firebug console, you'll see that the entire event object is available to the event-handling function, empowering you with just about everything you'd ever need to know about what just happened.

"But it's so easy to specify handlers for DOM events. Why would I even bother with learning another fancy library function?" you wonder. Yes, it may not take a brain surgeon to put together some simple event handlers, but what about when you have a complex application that may need to handle lots of sophisticated event handling based on user preferences, custom events, or some other event-driven behavior? Sure, you could handle all of this work manually, but would you be able to connect or disconnect in one line of code with a single consistent interface that's already been written and battle-tested?

Finally, note that while the examples only illustrated one event being chained to another one, there's no reason you couldn't wire up any arbitrary number of ordinary functions, object methods, and DOM events to fire in succession.

dojo.stopEvent(/*DOMEvent*/evt)

var foo = dojo.byId("foo"); //some anchor element

dojo.connect(foo, "onclick", function(evt) {
    console.log("anchor clicked");
    dojo.stopEvent(evt); //suppress browser navigation and squash any event bubbling
});

var bar = dojo.byId("bar"); //some form element

dojo.connect(bar, "onsubmit", function(evt) {
    console.log("form submitted");
    evt.preventDefault(  ); //suppress browser navigation but allow event bubbling
});

var handle = dojo.connect(
    dojo.byId("foo"),  //some div element
    "onmouseover",
    function(evt) {
      //some handler goes here...
      dojo.disconnect(handle);
    }
);

/* The following code does not work as expected! */
for (var i=0; i < 10; i++) {
  var foo = dojo.byId("foo"+i);
  var handle = dojo.connect(foo, "onmouseover", function(evt) {
    console.log(i);
    dojo.disconnect(handle);
  });
}

for (var i=0; i < 10; i++) {
   (function(  ) {
       var foo = dojo.byId("foo"+i);
       var current_i = i; //trap in closure
       var handle = dojo.connect(foo, "onmouseover",
         function(evt) {
           console.log(current_i);
           dojo.disconnect(handle);
         }
       );
   })(  ); // execute anonymous function immediately
}

While there are plenty of times when the direct "chained" style of communication provided by dojo.connect is exactly what you'll need to solve a problem, there are also a lot of times when you'll want a much more indirect "broadcast" style of communication in which various widgets communicate anonymously. For these circumstances, you might instead use dojo.publish and dojo.subscribe.

A classic example is a JavaScript object that needs to communicate with other objects in a one-to-many type relationship. Instead of setting up and managing multiple dojo.connect connections for what seems like one cohesive action, it's considerably simpler to have one widget publish a notification that an event has transpired (optionally passing along data with it) and other widgets can subscribe to this notification and automatically take action accordingly. The beauty of the approach is that the object performing the broadcast doesn't need to know anything whatsoever about the other objects—or even if they exist, for that matter. Another classic example for this kind of communication involves portlets—pluggable interface components (http://en.wikipedia.org/wiki/Portlet) that are managed within a web portal, kind of like a dashboard.

In many situations, you can achieve exactly the same functionality with pub/sub style communication as you could by establishing connections, so the decision to use pub/sub may often boil down to pragmatism, the specific problem being solved, and overall convenience of one approach over another.

As a starting point for determining which style of communication to use, consider the following issues:

Without further delay, here's the pub/sub API. Note that in the case of dojo.subscribe, you may omit the context parameter and the function will internally normalize the arguments on your behalf (just as was the case with dojo.connect ):

dojo.publish(/*String*/topic, /*Array*/args)
dojo.subscribe(/*String*/topic, /*Object|null*/context,
   /*String|Function*/method) //Returns a Handle
dojo.unsubscribe(/*Handle*/handle)

Let's get to work with a simple example involving dojo.subscribe and dojo.publish :

function Foo(topic) {

  this.topic = topic;

  this.greet = function(  ) {
    console.log("Hi, I'm Foo");

    /* Foo directly publishes information, but not to a specific destination... */
    dojo.publish(this.topic);
  }

}

function Bar(topic) {

  this.topic = topic;

  this.greet = function(  ) {
    console.log("Hi, I'm Bar");
  }

  / * Bar directly subscribes to information, but not from a specific source */
  dojo.subscribe(this.topic, this, "greet");

}

var foo = new Foo("/dtdg/salutation");
var bar = new Bar("/dtdg/salutation");

foo.greet(  ); //Hi, I'm Foo...Hi, I'm Bar

As you can see, whereas connect involves a connection from a specific source to a specific destination, publish/subscribe involves a broadcast that could be sent from any source and could be received by any destination that cares to respond to it in some way. Some amazing power comes built-in with a very loosely coupled architecture because with minimal effort and great simplicity comes the ability to have what amounts to an application that is conceptually a collection of coherent plug-ins.

Let's illustrate how to unsubscribe with an interesting variation on Bar 's implementation. Let's have Bar respond to the topic that Foo publishes only a single time:

function Bar(topic) {

    this.topic = topic;

    this.greet = function(  ) {
        console.log("Hi, I'm bar");
        dojo.unsubscribe(this.handle);

        //yackety yack, don't talk back
    }

    this.handle = dojo.subscribe(this.topic, this, "greet");
}

Note that you can also send along an array of arguments by providing an additional second argument to publish that is an Array of values, which gets passed to the subscribe handler as named parameters.

For a final rendition of our example, let's say you are not able to reliably change Foo 's greet method to include a dojo.publish call because an external constraint exists that prohibits it; perhaps it is code that you do not own or should not be mucking with, for example. Not to worry—we'll use another function, dojo.connectPublisher, to take care of the publishing for us each time a particular event occurs:

function Foo(  ) {
  this.greet = function(  ) {
    console.log("Hi, I'm foo");
  }
}

function Bar(  ) {
  this.greet = function(  ) {
    console.log("Hi, I'm bar");
  }

}

var foo = new Foo;
var bar = new Bar;

var topic = "/dtdg/salutation";
dojo.subscribe(topic, bar, "greet");
dojo.connectPublisher(topic, foo, "greet");

foo.greet(  );

In this final example, the primary takeaway is that the dojo.connectPublisher call allowed us to achieve the same result as adding a dojo.publish call to its greet method, but without mangling its source code to achieve that result. In this regard, foo is an indirect sender of the notification and is not even aware that any communication is going on at all. Bar, on the other hand, as a subscriber of the notification, did require explicit knowledge of the communications scheme. This is essentially the opposite of a typical dojo.connect call in which the object that provides the context for a connection has explicit knowledge about some other object or function that provides the "target" of the connection.

After reading this chapter, you should:

Next up is AJAX and server communication.