Simple Connections with dojo.connect

Dojo provides a pair of functions to handle many of your event-handling needs: dojo.connect and dojo.disconnect. With dojo.connect, you can link one function to fire when another does, handling DOM events and custom functions with a single mechanism. Additionally, dojo.connect allows you to connect as many functions to an event as necessary. With dojo.disconnect, you can cancel a connection, assuming you've kept some reference to it.

How does it work?

Imagine that you're hungry and have decided to cook a pizza in your oven. The pizza will take 17 minutes, so you set a timer. You have better things to do than sit around your kitchen hanging out by the timer though, so you get your brother and tell him, "When you hear the oven timer, take the pizza out of the oven and bring me a slice." Your brother can only keep track of one thing at a time, and you don't want your house to burn down, so you tell your sister, "When you hear the over timer, turn off the oven." Because you're a little worried that your dirty oven might start to smoke, you tell them both, "If you hear the smoke alarm, come get me and then go outside." After you get your pizza, you tell your brother and sister that they don't have to worry about the oven alarm now and that they can go play until you call for them again. You then set the oven alarm to wake you up from a nap.

In this example, your siblings are functions. Your telling them to respond to certain events, such as "onPizzaDone" and "onHouseOnFire" performs the same function as dojo.connect — it sets up your siblings (functions) to listen for an event and perform their tasks when they receive notice. The various alarms are similar to event objects; they inform your siblings of important details about the situation (such as what is beeping). Telling your siblings that they don't need to worry about the oven alarm anymore is similar to dojo.disconnect; the next time the oven alarm goes off, it means that you need to wake up, and you don't want your brother hunting for a pizza needlessly, so you've told him to stop listening to that event.

Syntax

Dojo.connect takes a variety of forms of arguments, depending on how you are planning to use it. This section will cover those various forms, based on use cases for them. You can think of it as a more in-depth version of the overview from Functions Used Everywhere.

Dojo.connect has the following signature (acceptable types in square brackets):

handle = dojo.connect(Scope of Event [object or null], Event [string], Context of Linked Method [string or null], Linked Method [string or function], Don't Fix Flag [boolean])

All of the options for calling dojo.event are explored further below.

Example Code for Reference

Connecting to a DOM Event

To connect a function to a DOM event with Dojo, you first need to get the node that you want to connect to. Here, I'll use the venerable dojo.byId.

In this example, I passed dojo.connect the object I want my function to listen to (in this case, a DOM node), the name of the function that should trigger my function's call (in this case, the "onclick" event), and the name of my function. Note that I keep a reference to the connection by setting firstLinkConnections[0] to the return value of dojo.connect. This will allow me to disconnect the listener later, if I desire. Now, when a user clicks "Dojo," a message appears in the log Because my function is global in scope, I can pass it directly to connect. The following, however, are equivalent:

and

Now, if I also want to connect someObject.bar() to #firstLink, I can do that.

Because I've used Dojo's event handling, I can connect an arbitrary number of functions to fire on an event.

A note about the event names: In most cases, event names now are lower case, except in special cases (e.g., some Mozilla DOM events). Dojo will add "on" to your event name if you leave it off (e.g., 'click' and 'onclick' are the same thing to dojo). Dojo responds to all of the usual events (e.g., onclick, onmouseover, etc.) and the onkeypress event for capturing typing.

A note about return values: Any value returned by a function called by dojo.connect will be lost.

Connecting Functions to One Another

Connecting functions to one another is even simpler than connecting them to DOM events; because you already have a reference to the function, you don't need to do any byId or query work. To have anotherObject.afterBaz fire after someObject.baz fires, use the following:

In the above code, the first argument is the context of "baz," the second argument is the event (in this case, when baz fires), the third argument is the context of your listener function, and the fourth argument is the listener function itself. Connecting two global functions is even easier:

Now, whenever foo is called, globalGuy will also fire. As you might expect, connecting a method to a global function, or vice versa, is logical and simple:

Disconnecting

Event Object

When you connect a function to a DOM event with dojo.connect, dojo passes your function a normalized event object. This means that, regardless of the client's browser, you can count on a set of standard attributes about the event and a set of methods to manipulate the event.

Syntax

Assume that your function has been called by dojo.connect and takes an argument named event

Dojo provides the following attributes with an event object:

• event.target — the element that generated the event
• event.currentTarget — the current target
• event.layerX — the x coordinate, relative to the event.currentTarget
• event.layerY — the y coordinate, relative to the event.currentTarget
• event.pageX — the x coordinate, relative to the view port
• event.pageY — the y coordinate, relative to the view port
• event.relatedTarget — For onmouseover and onmouseout, the object that the mouse pointer is moving to or out of
• event.charCode — For keypress events, the character code of the key pressed

Dojo provides the following methods with an event object:

• event.preventDefault — prevent an event's default behavior (e.g., a link from loading a new page)
• event.stopPropagation — prevent an event from triggering a parent node's event

Additionally, dojo.stopEvent(event) will prevent both default behavior any any propagation (bubbling) of an event.

Example Code for Reference

Using a Dojo Event Object

In the example code, we have two functions that are connected to two different events. Echo sends the key code of any key typed in the text input field to the console. It does so by using the charCode property of the normalized event object. Foo is connected to the #link and cause it to send "The link was clicked" to the console instead of changing the browser's location; by using the preventDefault method of the normalized event object, connections to change the default behavior of DOM objects.

Now, imagine that you want to detect for the down arrow key in the text box. To do this, we just need to attach a new event listener to the text box and check to see if each keycode is the keycode for the down arrow. And how do you know what the keycode for the down arrow is, you may ask? Well, Dojo provides constants for every non-alpha-numeric key (see: Key code constants). In our case, we are interested in dojo.keys.DOWN_ARROW. So, assuming that you want to just log when the down arrow is pressed, the following code should do the job: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}

Page Load / Unload

To perform any DOM scripting, one needs a DOM to work with. Otherwise, you don't have nodes to attach your events to or manipulate, and the results of your program can be undesirable (e.g., no output for no obvious reason, or events attached to the document root).

Dojo elegantly solves this problem with dojo.addOnLoad, which we introduced back in Functions Used Everywhere. Better yet, dojo.addOnLoad starts your scripts after the DOM has loaded but before all of the page elements have loaded. That means your script doesn't have to wait for images and other large resources before it manipulates page structure. This can significantly improve the perceived performance of your scripts.

Like other event handlers, you register a function with addOnLoad - either a function literal, or a function name as a string. You can also pass an object and a method name (as a string) to call an object-oriented method.

Acting in parallel to dojo.addOnLoad is dojo.addOnUnload , which runs functions when the page is being "unloaded" (e.g., when the user clicks a link off of the current page). This gives you the opportunity to send notifications to your web application or clean up unavoidable memory leaks.

dojo.addOnLoad and Cross-Domain Loading

Dojo.addOnLoad() is doubly-important when using cross-domain resources. Non-DOM-related Dojo functions can be called anytime from a locally-installed Dojo build, as in:

In a local Dojo build, dojo.require loads the dojox.uuid code right away. In Cross-Domain Dojo, this is not guaranteed due to browser security rules. But this code works fine on either:

We highly recommend initializing your code with dojo.addOnLoad. Semantically, it's no different than bare code, and it allows you to switch from XDomain to local Dojo and back.

Publish and Subscribe Events

In addition to the simple event system created by dojo.connect, dojo offers support for anonymous publication and subscription of objects, via dojo.publish and dojo.subcribe. These methods allow a function to broadcast objects to any other function that has subscribed. This is dojo's topic system, and it makes it very easy to allow separate components to communicate without explicit knowledge of one another's internals.

There are three functions that you need to understand to use dojo's topic system: dojo.publish, dojo.subscribe, and dojo.unsubscribe Dojo.publish calls any functions that are connected to the topic via dojo.subscribe, passing to those subscribed functions arguments that are published (see syntax for details). As one might expect, dojo.unsubscribe will cause a previously subscribed function to no longer be called when dojo.publish is called in the future

How does it work?

Imagine that you run a running a conference, and there will be updates throughout the day. You could collect contact information for everyone at the beginning of the day, along with each person's interests. However, this would be a lot of logistical work. Instead, you decide to use your facility's Public Address System. When there is an update to the schedule, you announce "This is an update to the schedule: the Dojo training is full and we have added yet a third time slot for it tomorrow." When there is meal information, you announce "This is an update about food: we will be serving free ice cream in the main hall in five minutes." This way, anyone interested in your information can pay attention to any updates that could change their behavior. You don't need to know who is subscribing, and they don't need to fill out a bunch of paper work — it's a win-win.

Syntax

dojo.publish

dojo.subscribe

dojo.unsubscribe

Example Code for Reference

Subscribing and Publishing Topics

To connect globalGuy to the topic "globalEvents" and someObject.bar to "fullNames", you simply use dojo.subscribe, as follows:

Note that the following alternative form would also work:

To publish information to both of these topics, you pass dojo.publish the topic names and arrays of the arguments that you want to pass to subscribed functions, as follows

To disconnect someObject.bar from its topic, you use dojo.disconnect, as follows: