In this chapter, I describe the jQuery support for events. If you are unfamiliar with events, then I provided a brief overview of how they work and how they are propagated through the DOM (Domain Object Model) in Chapter 2. jQuery provides some useful event-related features, of which my favorite is the ability to automatically associate event handler functions with elements as they are added to the DOM. Table 9-1 provides the summary for this chapter.

Registering a Function to Handle Multiple Event Types

A common technique is to use a single function to handle two or more kinds of event. These events are usually related in some way, such as the mouseenter and mouseout events. When using the bind method, you can specify multiple event types in the first argument, separated by a space. Listing 9-2 demonstrates this method.

Listing 9-2.  Registering a Function to Handle Multiple Event Types

...
<script type="text/javascript">
    $(document).ready(function() {
  
        function handleMouse(e) {
            var cssData = {
                "border": "thick solid red",
                "opacity": "0.5"
            }
            if (event.type == "mouseout") {
                cssData.border = "";
                cssData.opacity = "";
            }
            $(this).css(cssData);
        }
    
        $("img").bind("mouseenter mouseout", handleMouse);
          
    });
</script>
...

In this script, I have used a single call to the bind method to specify that the mouseenter and mouseout events should be handled by the handleMouse function for all of the img elements in the document. Of course, you can also use a single function and chain the bind calls, as follows:

...
$("img").bind("mouseenter", handleMouse).bind("mouseout", handleMouse);
...

You can also register handlers using a map object. The properties of the object are the names of the events, and their values are the functions that will be invoked when the events are triggered. Listing 9-3 shows the use of a map object with the bind method.

Listing 9-3.  Using a Map Object to Register Event Handlers

...
<script type="text/javascript">
    $(document).ready(function() {
      
        $("img").bind({
            mouseenter: function() {
                $(this).css("border", "thick solid red");
            },
            mouseout: function() {
                $(this).css("border", "");
            }
        });
          
    });
</script>
...

In Listing 9-3, I have defined the handler functions inline, as part of the map object. The bind method uses the functions I specify as handlers for the events that correspond to the property names in the map object.

Providing Data to the Event Handler Function

You can pass an object to the bind method, which jQuery will then make available to the handler function through the Event.data property. This can be useful when using a single function to handle events from different sets of elements. The data value can help determine what kind of response is required. Listing 9-4 shows how to define and use the data value.

Listing 9-4.  Passing Data to the Event Handler Function via the bind Method

...
<script type="text/javascript">
    $(document).ready(function() {
  
        function handleMouse(e) {
            var cssData = {
                "border": "thick solid " + e.data,
            }
            if (event.type == "mouseout") {
                cssData.border = "";
            }
            $(this).css(cssData);
              
        }
    
        $("img:odd").bind("mouseenter mouseout", "red", handleMouse);
        $("img:even").bind("mouseenter mouseout", "blue", handleMouse);
    });
</script>
...

I use the optional argument to the bind method to specify which color border should be displayed when the mouseenter event is triggered. For the odd-numbered img elements, the border will be red and for the even-numbered it will be blue. In the event handler function I use the Event.data property to read the data and use it to create the value for the CSS (Cascading Style Sheet) border property. You can see the effect in Figure 9-1.

Suppressing the Default Action

As I mentioned in Chapter 2, some events have a default action when they are triggered on certain elements. A good example occurs when the user clicks a button whose type attribute is submit. If the button is contained in a form element, the default action is for the browser to submit the form. To prevent the default action from being performed, you can call the preventDefault method on the Event object, as shown in Listing 9-5.

Listing 9-5.  Preventing the Default Action on an Event

...
<script type="text/javascript">
    $(document).ready(function() {
      
        $("button:submit").bind("click", function(e) {
            e.preventDefault();
        });
          
    });
</script>
...

This script sets up a handler function for the click event on all button elements whose type attribute is set to submit. The function only contains a call to the preventDefault method, which means that clicking the buttons won’t do anything at all, since the default action is disabled and the handler function doesn’t set up any alternatives.

Usually you want to suppress the default action so you can perform some other activity instead—for example, to stop the browser from submitting the form because you want to do it with Ajax (which is the topic of Chapters 14 and 15). Instead of writing a one-line function as I did in Listing 9-5, you can use a different version of the bind method, as shown in Listing 9-6.

Listing 9-6.  Using the bind Method to Create a Handler That Prevents the Default Action

...
<script type="text/javascript">
    $(document).ready(function() {
        $("button:submit").bind("click", false);
    });
</script>
...

The first argument is the event or events whose default action you want to suppress, and the second argument allows you to specify whether the event should be prevented from bubbling up the DOM (I explain event bubbling in Chapter 2).

Removing Event Handler Functions

The unbind method removes a handler function from an element. You can unbind all of the handlers associated with all events for all elements in a jQuery object by calling the unbind method with no arguments, as shown in Listing 9-7.

Listing 9-7.  Unbinding All Event Handlers

...
<script type="text/javascript">
    $(document).ready(function() {
  
        function handleMouse(e) {
            var cssData = {
                "border": "thick solid red",
                "opacity": "0.5"
            }
            if (event.type == "mouseout") {
                cssData.border = "";
                cssData.opacity = "";
            }
            $(this).css(cssData);
        }
  
        $("img").bind("mouseenter mouseout", handleMouse);
          
        $("img[src*=rose]").unbind();
          
    });
</script>
...

In Listing 9-7, I bind a handler for the mouseenter and mouseout events for all of the img elements and then use the unbind method to remove all of the handlers for the img element whose src attribute contains rose. You can be more selective by passing the events you want to unbind as an argument to the unbind method, as shown in Listing 9-8.

Listing 9-8.  Selectively Unbinding Events

...
<script type="text/javascript">
    $(document).ready(function() {
  
        function handleMouse(e) {
            var cssData = {
                "border": "thick solid red",
                "opacity": "0.5"
            }
            if (event.type == "mouseout") {
                cssData.border = "";
                cssData.opacity = "";
            }
            $(this).css(cssData);
        }
  
        $("img").bind("mouseenter mouseout", handleMouse);
          
        $("img[src*=rose]").unbind("mouseout");
          
    });
</script>
...

In this script I unbind only the mouseout event, leaving the handler for the mouseenter event untouched.

...
<script type="text/javascript">
    $(document).ready(function() {
  
        var handledCount = 0;
  
        function handleMouseEnter(e) {
            $(this).css("border", "thick solid red");
        }
        function handleMouseExit(e) {
            $(this).css("border", "");
            handledCount ++;
            if (handledCount == 2) {
                $(this).unbind(e);
            }
        }
        $("img").bind("mouseenter", handleMouseEnter).bind("mouseout", handleMouseExit)
    });
</script>
...

Executing a Handler Once

The one method lets you register an event handler that will be executed only once for an element and then removed. Listing 9-10 provides an example.

Listing 9-10.  Using the one Method to Register a Single-Shot Event Handler Function

...
<script type="text/javascript">
    $(document).ready(function() {
  
        function handleMouseEnter(e) {
            $(this).css("border", "thick solid red");
        };
          
        function handleMouseOut(e) {
            $(this).css("border", "");
        };
  
        $("img").one("mouseenter", handleMouseEnter).one("mouseout", handleMouseOut);
          
    });
</script>
...

I have used the one method to register handlers for the mouseenter and mouseout events. The handler functions will be called when the user moves the mouse in and out of one of the img elements, and then the function will be unbound (but just for that element; the others will still have the handlers until the mouse is moved over them).

Limiting DOM Traversal for Live Event Handlers

One problem with the on method is that the events have to propagate all the way up to the document element before your handler functions are executed. You can take a more direct approach by using the delegate method , which allows you to specify where the event listener will be located in the document. Listing 9-15 provides an example.

Listing 9-15.  Using the delegate Method

...
<script type="text/javascript">
    $(document).ready(function() {
          
        $("#row1").delegate("img", {
            mouseenter: function() {
                $(this).css("border", "thick solid red");
            },
            mouseout: function() {
                $(this).css("border", "");
            }
        });
  
        $("#row1").append($("<div class='dcell'/>")
            .append("<img src='carnation.png'/>")
            .append("<label for='carnation'>Carnation:</label>")
            .append("<input name='carnation' value='0' required />"));
  
        $("#row2").append($("<div class='dcell'/>")
            .append("<img src='lily.png'/>")
            .append("<label for='lily'>Lily:</label>")
            .append("<input name='lily' value='0' required />"));
    });
     
</script>
...

In Listing 9-15, I use the delegate method to add the listener to the element whose ID is #row1, and the selector I specified matches the img element. The effect of this is that my handler functions will be executed when a mouseenter or mouseout event that originated from an img element propagates to the row1 element. When I add another img element to row1, it is automatically covered by my call to the delegate method, which is not the case when I add elements to row2.

The main benefit of using the delegate method is speed, which can become an issue if you have a particularly large and complex document and a lot of event handlers. By pushing the point where the events are intercepted down into the documents, you reduce the distance that events have to travel in the DOM before they lead to the handler functions being invoked.

Using an Event Object

You can also use an Event object to trigger other elements’ event handlers. This can be a convenient technique to use inside a handler, as demonstrated in Listing 9-17.

Listing 9-17.  Manually Triggering Event Handles with an Event Object

...
<script type="text/javascript">
    $(document).ready(function() {
          
        $("#row1 img").bind("mouseenter", function() {
            $(this).css("border", "thick solid red");
        });
              
        $("#row2 img").bind("mouseenter", function(e) {
            $(this).css("border", "thick solid blue");
            $("#row1 img").trigger(e);
        });
  
    });
     
</script>
...

In Listing 9-17, I use the bind method to add a red border to the img descendants of the row1 element in response to the mouseenter event. I do the same with a blue border to the row2 img elements, but in the handler, I have added the following statement:

..
$("#row1 img").trigger(e);
...

The effect of this addition is that when the mouse enters one of the row2 img elements, the handler for the same event type is triggered on the row1 img elements as well. You can see the effect in Figure 9-3.

This approach is convenient when you want to trigger the handlers for the event type currently being processed, but you could as easily get the same effect by specifying the event type.

Using the triggerHandler Method

The triggerHandler method invokes the handler functions without performing the event’s default action or allowing the event to bubble up through the DOM. And, unlike the trigger method, triggerHandler invokes the handler function only on the first element in a jQuery object. Listing 9-18 shows the use of this method.

Listing 9-18.  Using the triggerHandler Method

...
<script type="text/javascript">
    $(document).ready(function() {
        $("#row1 img").bind("mouseenter", function() {
            $(this).css("border", "thick solid red");
        });
              
        $("#row2 img").bind("mouseenter", function(e) {
            $(this).css("border", "thick solid blue");
            $("#row1 img").triggerHandler("mouseenter");
        });
    });
</script>
...

You can see the effect of this script in Figure 9-4.

Using the Document Event Shorthand Methods

Table 9-6 describes the jQuery shorthand methods that apply to the document object.

The ready method deserves special mention. It doesn’t correspond directly to a DOM event but is incredibly useful when using jQuery. You can see the different ways you can use the ready method in Chapter 5, where I explain how to defer execution of a script until the DOM is ready and how you can control the execution of the ready event.

Using the Browser Event Shorthand Methods

Table 9-7 describes the browser events, which are usually targeted at the window object (although the error and scroll events are also used with elements as well).

Using the Mouse Event Shorthand Methods

Table 9-8 describes the set of shorthand methods that jQuery provides for dealing with mouse events.

The hover method is a convenient way of binding a handler function to the mouseenter and mouseleave events. If you provide two functions as arguments, then the first is invoked in response to the mouseenter event and the second in response to mouseleave. If you specify only one function, it will be invoked for both events. Listing 9-23 shows the use of the hover method.

Listing 9-23.  Using the hover Method

...
<script type="text/javascript">
    $(document).ready(function() {
  
        $("img").hover(handleMouseEnter, handleMouseLeave);
    
        function handleMouseEnter(e) {
            $(this).css("border", "thick solid red");
        };
        
        function handleMouseLeave(e) {
            $(this).css("border", "");
        }
    });
</script>
...

Using the Form Event Shorthand Methods

Table 9-9 describes the shorthand methods that jQuery provides for dealing with events that are usually associated with forms.

Using the Keyboard Event Shorthand Methods

Table 9-10 describes the shorthand methods that jQuery provides for dealing with keyboard events.

Summary

In this chapter, I showed you the jQuery support for events. As with much of jQuery, the benefit of the event functionality is simplicity and elegance. You can create and manage event handlers with little effort. I particularly like the support for creating live event handlers, such that elements that are added to the DOM that match a particular selector are automatically associated with event handlers. It significantly reduces the amount of time that I spend tracking down problems with event handling in my web applications. In Chapter 10, I describe the jQuery support for effects.