- The Book of Dojo
- Quick Installation
- Hello World
- Debugging Tutorial
- Introduction
- Part 1: Life With Dojo
- Part 2: Dijit
- Part 3: JavaScript With Dojo and Dijit
- Part 4: Testing, Tuning and Debugging
- Part 5: DojoX
- The Dojo Book, 0.4
Simple Connections with dojo.connect
Submitted by MattBowen on Mon, 07/23/2007 - 03:05.
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
<head>
<title>Dojo Events are Great</title>
<script src="dojo/dojo.js" type="text/javascript"></script>
<script type="text/javascript">
function foo() { console.debug("A click upon your houses!"); }
function globalGuy() { console.debug("Global Guy fired!"); }
var someObject = {
bar: function() { console.debug("Bar fired!"); return 7; },
baz: function() { console.debug("Baz fired!"); return 14; }
}
var anotherObject = {
afterBaz: function () { console.debug("afterBaz fired!"); }
}
</script>
<body>
<a id="firstLink" href="http://dojotoolkit.org/">Dojo</a> is an excellent tool kit.
</body>
<title>Dojo Events are Great</title>
<script src="dojo/dojo.js" type="text/javascript"></script>
<script type="text/javascript">
function foo() { console.debug("A click upon your houses!"); }
function globalGuy() { console.debug("Global Guy fired!"); }
var someObject = {
bar: function() { console.debug("Bar fired!"); return 7; },
baz: function() { console.debug("Baz fired!"); return 14; }
}
var anotherObject = {
afterBaz: function () { console.debug("afterBaz fired!"); }
}
</script>
<body>
<a id="firstLink" href="http://dojotoolkit.org/">Dojo</a> is an excellent tool kit.
</body>
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.
firstLinkNode = dojo.byId("firstLink");
Now, to fire foo when a user clicks #firstLink, and I have the node, so I just need to use dojo.connect for the heavy lifting.
firstLinkConnections = [];
firstLinkConnections[0] = dojo.connect(firstLinkNode, 'onclick', foo);
firstLinkConnections[0] = dojo.connect(firstLinkNode, 'onclick', foo);
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:
firstLinkConnections[0] = dojo.connect(firstLinkNode, 'onclick', null, foo);
and
firstLinkConnections[0] = dojo.connect(firstLinkNode, 'onclick', null, "foo");
Now, if I also want to connect someObject.bar() to #firstLink, I can do that.
firstLinkConnections[1] = dojo.connect(firstLinkNode, 'onclick', someObject, "bar");
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:
objectConnections = [];
objectConnections[0] = dojo.connect(someObject, "baz", anotherObject, "afterBaz");
objectConnections[0] = dojo.connect(someObject, "baz", anotherObject, "afterBaz");
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:
objectConnections[1] = dojo.connect(foo, globalGuy);
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:
objectConnections[2] = dojo.connect(foo, anotherObject, "afterBaz");
objectConnections[3] = dojo.connect(someObject, "baz", globalGuy);
objectConnections[3] = dojo.connect(someObject, "baz", globalGuy);
Disconnecting
To disconnect listeners from events, you simply pass the connection handle (the return value of dojo.connect to dojo.disconnect. To disconnect globalGuy from someObject.baz, I use the following code:dojo.disconnect(objectConnections[3]);
- Printer-friendly version
- Login or register to post comments
- Subscribe post
Dojo.connect context type
In the description of the Dojo.connect signature
Context of Linked Method [string or null],
should be [Object or null]
(see http://redesign.dojotoolkit.org/?q=jsdoc/dojo/HEAD/object/dojo.connect)