Event.observe(element, eventName, handler) → Element

• element (Element | String) – The DOM element to observe, or its ID.
• eventName (String) – The name of the event, in all lower case, without the "on" prefix — e.g., "click" (not "onclick").
• handler (Function) – The function to call when the event occurs.

Registers an event handler on a DOM element. Aliased as Element#observe.

Event.observe smooths out a variety of differences between browsers and provides some handy additional features as well. Key features in brief: * Several handlers can be registered for the same event on the same element. * Prototype figures out whether to use addEventListener (W3C standard) or attachEvent (MSIE); you don't have to worry about it. * The handler is passed an extended Event object (even on MSIE). * The handler's context (this value) is set to the extended element being observed (even if the event actually occurred on a descendent element and bubbled up). * Prototype handles cleaning up the handler when leaving the page (important for MSIE memory leak prevention). * Event.observe makes it possible to stop observing the event easily via Event.stopObserving. * Adds support for mouseenter / mouseleave events in all browsers.

Although you can use Event.observe directly and there are times when that's the most convenient or direct way, it's more common to use its alias Element#observe. These two statements have the same effect:

Event.observe('foo', 'click', myHandler);
$('foo').observe('click', myHandler);

The examples in this documentation use the Element#observe form.

The Handler

Signature:

function handler(event) {
  // `this` = the element being observed
}

So for example, this will turn the background of the element 'foo' blue when it's clicked:

$('foo').observe('click', function(event) {
  this.setStyle({backgroundColor: 'blue'});
});

Note that we used this to refer to the element, and that we received the event object as a parameter (even on MSIE).

It's All About Timing

One of the most common errors trying to observe events is trying to do it before the element exists in the DOM. Don't try to observe elements until after the dom:loaded event or window load event has been fired.

Preventing the Default Event Action and Bubbling

If we want to stop the event (e.g., prevent its default action and stop it bubbling), we can do so with the extended event object's Event#stop method:

$('foo').observe('click', function(event) {
  event.stop();
});

Finding the Element Where the Event Occurred

Since most events bubble from descendant elements up through the hierarchy until they're handled, we can observe an event on a container rather than individual elements within the container. This is sometimes called "event delegation". It's particularly handy for tables:

<table id='records'>
  <thead>
    <tr><th colspan='2'>No record clicked</th></tr>
  </thead>
  <tbody>
    <tr data-recnum='1'><td>1</td><td>First record</td></tr>
    <tr data-recnum='2'><td>2</td><td>Second record</td></tr>
    <tr data-recnum='3'><td>3</td><td>Third record</td></tr>
  </tbody>
</table>

Instead of observing each cell or row, we can simply observe the table:

$('records').observe('click', function(event) {
  var clickedRow = event.findElement('tr');
  if (clickedRow) {
    this.down('th').update("You clicked record #" + clickedRow.readAttribute("data-recnum"));
  }
});

When any row in the table is clicked, we update the table's first header cell saying which record was clicked. Event#findElement finds the row that was clicked, and this refers to the table we were observing.

Stopping Observing the Event

If we don't need to observe the event anymore, we can stop observing it with Event.stopObserving or its Element#stopObserving alias.

Using an Instance Method as a Handler

If we want to use an instance method as a handler, we will probably want to use Function#bind to set the handler's context; otherwise, the context will be lost and this won't mean what we expect it to mean within the handler function. E.g.:

var MyClass = Class.create({
  initialize: function(name, element) {
    this.name = name;
    element = $(element);
    if (element) {
      element.observe(this.handleClick.bind(this));
    }
  },
  handleClick: function(event) {
    alert("My name is " + this.name);
  },
});

Without the Function#bind, when handleClick was triggered by the event, this wouldn't refer to the instance and so the alert wouldn't show the name. Because we used Function#bind, it works correctly. See Function#bind for details. There's also Function#bindAsEventListener, which is handy for certain very specific situations. (Normally, Function#bind is all you need.)

Side Notes

Although Prototype smooths out most of the differences between browsers, the fundamental behavior of a browser implementation isn't changed. For example, the timing of the change or blur events varies a bit from browser to browser.

Changes in 1.6.x

Prior to Prototype 1.6, Event.observe supported a fourth argument (useCapture), a boolean that indicated whether to use the browser's capturing phase or its bubbling phase. Since MSIE does not support the capturing phase, we removed this argument from 1.6, lest it give users the false impression that they can use the capturing phase in all browsers.

1.6 also introduced setting the this context to the element being observed, automatically extending the Event object, and the Event#findElement method.