class method Event.observe
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) orattachEvent
(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).
observe
makes it possible to stop observing the event easily viaEvent.stopObserving
.
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;
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
(aka Element#stopObserving
).
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 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 bind
, it
works correctly. See Function#bind
for
details. There's also Function#bindAsEventListener
, which is handy for certain very
specific situations. (Normally, 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, 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.