jQuery Pocket Reference

Advanced Event Handler Registration

We’ve seen that jQuery defines quite a few simple methods for registering event handlers. Each of these simply invokes the single, more complex method bind() to bind a handler for a named event type to each of the elements in the jQuery object. Using bind() directly allows you to use advanced event registration features that are not available through the simpler methods.^[2]

In its simplest form, bind() expects an event type string as its first argument and an event handler function as its second. The simple event registration methods use this form of bind(). The call $('p').click(f), for example, is equivalent to:

$('p').bind('click', f);

bind() can also be invoked with three arguments. In this form, the event type is the first argument and the handler function is the third. You can pass any value between those two and jQuery will set the data property of the Event object to the value you specify before it invokes the handler. It is sometimes useful to pass additional data to your handlers in this way without having to use closures.

There are other advanced features of bind() as well. If the first argument is a space-separated list of event types, the handler function will be registered for each of the named event types. The call $('a').hover(f) (see Simple Event Handler Registration), for example, is the same as:

$('a').bind('mouseenter mouseleave', f);

Another important feature of bind() is that it allows you to specify a namespace (or namespaces) for your event handlers when you register them. This allows you to define groups of handlers, which comes in handy if you later want to trigger or de-register the handlers in a particular namespace. Handler namespaces are especially useful for programmers who are writing libraries or modules of reusable jQuery code. Event namespaces look like CSS class selectors. To bind an event handler in a namespace, add a period and the namespace name to the event type string:

// Bind f as a mouseover handler in namespace "myMod"
$('a').bind('mouseover.myMod', f);

You can even assign a handler to multiple namespaces, like this:

// Bind f as a mouseout handler in two namespaces
$('a').bind('mouseout.myMod.yourMod', f);

The final feature of bind() is that the first argument can be an object that maps event names to handler functions. To reuse the hover() method example, the call $('a').hover(f,g) is the same as:

$('a').bind({mouseenter:f, mouseleave:g});

When you use this form of bind(), the property names in the object you pass can be space-separated strings of event types and can include namespaces. If you specify a second argument after the first object argument, that value is used as the data argument for each of the event bindings.

jQuery has another event handler registration method: one(). This method is invoked and works just like bind(), except that the event handler you register will automatically de-register itself after it is invoked. As the method name implies, this means that event handlers registered with one() will never be triggered more than once.

One feature that bind() and one() do not have is the ability to register capturing event handlers as you can with addEventListener(). IE (until IE9) does not support capturing handlers, and jQuery does not attempt to simulate that feature.

---

^[2] jQuery uses the term “bind” for event handler registration. ECMAScript 5, and a number of JavaScript frameworks, define a bind() method on functions, and use the term for the association of functions with objects on which they are to be invoked. jQuery’s version of the Function.bind() method is a utility function named jQuery.proxy(), which you can read about in Chapter 7.