Event Listening Made Easy with Dojo.connect | WebReference | WebReference

Event Listening Made Easy with Dojo.connect | WebReference

By Rob Gravelle


[next]

The Dojo libraries abstract away all of the difficulty of cross-browser event mechanisms by offering programmers a single coherent event system. While Dojo offers a variety of options for binding code to triggered events, you'll find that most of your event-handling needs can be met using dojo.connect and dojo.disconnect. With dojo.connect, you can execute any number of functions in response to DOM and widget events as well as other functions.

Dojo.connect Function Syntax

Dojo.connect() accepts a variety of argument types and combinations in order to provide flexibility of application. Here is the dojo.connect() method signature with acceptable types enclosed within square brackets:

  • handle = dojo.connect(
    • Source Object [object or null]: The event source object. Defaults to dojo.global if null. If obj is a DOM node, the connection is delegated to the DOM event manager (unless dontFix is true).
    • Event [string]: The event name. Can also identify a function as in obj[event] or obj.event(). DOM names do not explicitly require the "on" prefix. Thus, onchange and change will both work.
    • Context of Linked Method [string or null]: The object that the this pointer will reference within the linked method. If context is null and method is a function, then method inherits the context of event. If the linked method parameter is a string then the context must be the source object for method (context[method]). Finally, if context is null or omitted, dojo.global is used.
    • Linked Method [string or function]: A function reference, or name of a function to connect to the source event (the listener function). The function identified by this argument fires after the source event does. The method receives the same arguments as the event.
    • Don't Fix Flag [boolean]: Optional. If the source object is a DOM node, set dontFix to true to prevent delegation of this connection to the DOM event manager.
    )

Here is some code that calls the sayThanks() function whenever the submitButton is clicked:

You can pass null for the this pointer since the sayThanks() function has a global scope. Heck, you can omit it entirely if you want, as with any null arguments. It is equivalent to passing the dojo.global object (the Dojo equivalent of the global window object).

Once you're done with a connection, it is a good practice to disconnect it using the handle that was returned from the dojo.connect() call:

Sometimes you should pass along an object to connect() so that you can reference some of its properties and/or methods. Here's an example of that:

Having many connections lying around can make tidying up a potentially error-prone affair. An easy way to keep track of all your connections is to store them in an array:

Connecting to a Function

You are by no means limited to listening for DOM node and widget events. You can also react to functions. That's because functions are objects in JavaScript, just like nodes and widgets are. In fact, connecting to a function is even simpler than connecting to DOM events because you don't have to fetch it using a helper function such as byId() or query(). To have anotherObject.responseFunction() fire after anObject.sourceFunction() fires, use the following code:


[next]