Bookmark and Share

The DOM Event Model

Review the W3C DOM2 Event standard recommendation.

Event Capture

You can also catch events during the capture phase using the event listener detailed previously. The capture phase compliments the bubble phase. The capture phase runs first. The event flows down from the root of the document tree to the target element, then it bubbles back up.

In this phase, outer elements will receive the event before it reaches its intended target. This can be useful if you want to intercept an event for some element even if it was initially targeted at one of its children or other descendants.

Browser Compatibility

As mentioned earlier, only Netscape 6 currently implements the Event Listener interface. Internet Explore does support similar functionality for mouse event's via its setCapture() and releaseCapture() methods. See Microsoft's documentation for details.

It should be noted that the term "event capture" is often used loosely to describe the act of setting an event handler or listener, during either phase. Here it specifically means intercepting an event during this downward phase of the event flow, before it reaches its intended target.

Event Flow Example

The full process can be illustrated with a demo. Below is a set of nested DIV tags The onclick event is caught for each element both on the capture phase (if supported by the browser) and the bubble phase. Click anywhere on the boxes and the path of the event will be traced in the text box below it.

DIV A
DIV B
DIV C

Clicking on the innermost DIV fires six event handlers, three going down the document tree and three as it bubble back up. In this example, the same function happens to be used for all six. but each could be assigned a unique handler function.

In the trace, the "Target" element is the one that the event initiates from while the "Current" element is the one that has the event listener attached. Both of these values are derived using the Event object passed to the handler.

Netscape 6.0 appears to have a bug. If you click on the text within any DIV above instead of an empty area, the event is not caught on the capture phase, only on the bubble phase. This is corrected in version 6.1.

It should be pointed out that this event flow occurs for every event whether or not you have handlers set for them. For example, if you want to catch an onclick event anywhere on a page, you do not need to assign a handler to .onclick for every element. You can simply set it for the document object and it will execute when it bubbles up from any object on the page, or capture it before it hits any element.

Now that you understand how events flow and know how to capture them, what can you do with them?

The Event Object

Within an event handler, you can do pretty much anything you want with your script code. Chances are, you'll want to perform some action related to that event depending on one or more factors.

Recall that event handlers are passed one argument, an Event object. It provides several properties describing the event and its current state. You can use these to determine where an event originated from and where it currently is in the event flow. Or use the methods it provides to stop the event from flowing on and/or cancel the event.

Event Properties and Methods
Property Name Description
bubbles A Boolean value indicating whether or not the event bubbles.
cancelable A Boolean value indicating whether or not the event can be canceled.
currentTarget The node that this event handler is assigned to.
eventPhase An integer value indicating which phase of the event flow this event is being processed in. One of CAPTURING_PHASE (1), AT_TARGET (2) or BUBBLING_PHASE (3).
target The node that the event originated from.
timeStamp The time the event occurred.
type A string indicating the type of event, such as "mouseover", "click", etc.
Method Name Description
preventDefault() Can be used to cancel the event, if it is cancelable. This prevents the browser from performing any default action for the event, such as loading a URL when a hypertext link is clicked. Note that the event will continue propagating along the normal event flow.
stopPropagation() Stops the event flow. This can be used on either the capture or bubble phase.

Note that using preventDefault() or stopPropagation() affects only the current, active instance of an event.

Internet Explorer

As mentioned earlier, IE does not currently support the W3C Event model. Instead of passing an Event object to a handler function, it provides a single, global object named window.event which contains much of the same information.

Unfortunately, the property names defined for this object do not match the standard model. Below is a table of equivalent properties in these two models.

Internet Explorer Equivalents
W3C Standard IE window.event Notes
currentTarget none See below.
eventPhase none Not applicable in IE.
target srcElement The node that the event originated from.
timeStamp none Not available in IE.
type type Equivalent to the standard.
preventDefault() returnValue Set to false to cancel any default action for the event.
stopPropagation() cancelBubble Set to true to prevent the event from bubbling.

To get the equivalent of the currentTarget property in IE, use the this keyword as an argument when setting the event handler in a tag.

<a href="..." onmouseover="myHandler(event, this);">...</a>

function myHandler(event, link) {
  ...
}

Note that cancelBubble and returnValue are Boolean properties, not method calls. Setting an appropriate value on these is equivalent to calling stopPropagation() or preventDefault() respectively.

These properties are common to all event types. Some additional properties are available for specific events related to the mouse and keyboard.