Prototype JavaScript framework - Event

extend

2007-12-05T01:22:00Z

Event.extend(event)

Extends event with all of the methods contained in Event.Methods.

Note that all events inside handlers that were registered using Event.observe or Element#observe will be extended automatically.

You need only call Event.extend manually if you register a handler a different way (e.g., the onclick attribute). We really can’t encourage that sort of thing, though.

unloadCache

2007-01-08T17:35:00Z

Event.unloadCache()

Unregisters all event handlers registered through observe. Automatically wired for you. Not available since 1.6.

Backwards incompatibility notice:
This method is removed in the 1.6 release. Remove calls to it from any script you currently use.

The sad tale of MSIE, event handlers and memory leaks

There is a significant issue with MSIE, which is that under a variety of conditions, it just will not release event handlers when the page unloads. These handlers will stay in RAM, filling it up slowly, clogging the browser’s arteries. This is known as a memory leak.

Of course, manually keeping tabs on all the handlers you register (which you do through observe, being such a nice person) is pretty tedious. And boring. It would be, in short, the essence of un-cool.

Which is why Prototype takes care of it for you. It keeps tabs, and when unloadCache is called, it unregisters everything and frees references, which is akin to sending a big pink lavender-perfumed invitation to the garbage collector.

You don’t even need to know this

What’s even better is, Prototype automatically hooks unloadCache to page unloading, exclusively for MSIE. So you don’t have anything to do. It’s all taken care of. We just though you’d like to know. Go do something productive, some value-added JavaScript code for instance. We’re not here to hinder you with automatable details.

Event

2006-12-05T21:44:00Z

♪ What a wonderful mess (it would be) ♫

Event management is one of the really sore spots of cross-browser scripting.

True, the prominent issue is: everybody does it the W3C way, and MSIE does it another way altogether. But there are quite a few subtler, sneakier issues here and there waiting to bite your ankle, such as the keypress/keydown issue with KHTML-based browsers (Konqueror and Safari). Also, MSIE has a tendency to leak memory when it comes to discarding event handlers.

Prototype to the rescue!

Of course, Prototype smooths it over so well you’ll forget these troubles even exist. Enter the Event namespace. It is replete with methods (listed at the top and bottom of this page), that all take the current event object as an argument, and happily produce the information you’re requesting, across all major browsers.

Event also provides a standardized list of key codes you can use with keyboard-related events. The following constants are defined in the namespace: KEY_BACKSPACE, KEY_TAB, KEY_RETURN, KEY_ESC, KEY_LEFT, KEY_UP, KEY_RIGHT, KEY_DOWN, KEY_DELETE, KEY_HOME, KEY_END, KEY_PAGEUP, KEY_PAGEDOWN. The names are self-explanatory.

The functions you’re most likely to use a lot are observe, element and stop. As for the others, your mileage may vary; it’s all about what your web app does.

Instance methods on event objects
1.6

As of Prototype 1.6, all methods on the Event object are now also available as instance methods on the event object itself:

Before

$('foo').observe('click', respondToClick);

function respondToClick(event) {
  var element = Event.element(event);
  element.addClassName('active');
}

After

$('foo').observe('click', respondToClick);

function respondToClick(event) {
  var element = event.element();
  element.addClassName('active');
}

These methods are added to the event object through Event.extend, in the same way that Element methods are added to DOM nodes through Element.extend. Events are extended automatically when handlers are registered with Prototype’s Event.observe method; if you’re using a different method of event registration, for whatever reason, you’ll need to extend these events manually with Event.extend.

pointerY

2006-11-18T21:14:00Z

Event.pointerY(event) -> Number

Returns the absolute vertical position for a mouse event.

Note: the position is absolute on the page, not on the viewport: scrolling down increases the returned value for events on the same viewport location.

stop

2006-11-18T21:14:00Z

Event.stop(event)

Stops the event’s propagation and prevents its default action from being triggered eventually.

There are two aspects to how your browser handles an event once it fires up:

The browser usually triggers event handlers on the actual element the event occurred on, then on its parent element, and so on and so forth, until the document’s root element is reached. This is called event bubbling, and is the most common form of event propagation. You may very well want to stop this propagation when you just handled an event, and don’t want it to keep bubbling up (or see no need for it).
Once your code got a chance to process the event, the browser handles it as well, if that event has a default behavior. For instance, clicking on links navigates to them; submitting forms sends them over to the server side; hitting the Return key in a single-line form field submits it; etc. You may very well want to prevent this default behavior if you do your own handling.

Because stopping one of those aspects means, in 99.9% of the cases, preventing the other one as well, Prototype bundles both in this stop function. Calling it on an event object stop propagation and prevents the default behavior.

Example

Here’s a simple code that prevents a form from being sent to the server side if a certain field is empty.


Event.observe('signinForm', 'submit', function(event) {
  var login = $F('login').strip();
  if ('' == login) {
    Event.stop(event);
    // Display the issue one way or another
  }
});

findElement

2006-11-18T21:14:00Z

Event.findElement(event, tagName) -> Element

Returns the first DOM element with a given tag name, upwards from the one on which the event occurred.

Sometimes, you’re not interested in the actual element that got hit by the event. Sometimes you’re interested in its “closest element,” (either the original one, or its container, or its container’s container, etc.), defined by its tag (e.g., <p>). This is what findElement is for.

The provided tag name will be compared in a case-insensitive manner.

If no matching element is found, the document itself (HTMLDocument node) is returned.

Example

Here’s a simple code that lets you click everywhere on the page and hides the closest-fitting paragraph around your click (if any).


Event.observe(document.body, 'click', function(event) {
  var elt = Event.findElement(event, 'P');
  if (elt != document)
    $(elt).hide();
});

For more complex searches, you’ll need to get the actual element and use up on it, which lets you express your request with CSS syntax, and also search farther than the first match (plus, the result is extension-guaranteed):


Event.observe(document.body, 'click', function(event) {
  // First element from event source with 'container' among its CSS classes
  var elt = $(Event.element(event)).up('.container');
  // Or: second DIV from the event source
  // elt = $(Event.element(event)).up('div', 1);
  // Or: second DIV with 'holder' among its CSS classes...
  // elt = $(Event.element(event)).up('div.holder', 1);
  elt.hide();
});

isLeftClick

2006-11-18T21:13:00Z

Event.isLeftClick(event) -> Boolean

Determines whether a button-related mouse event was about the “left” (primary, actually) button.

Note: this is not an absolute left, but “left for default” (right-handed). On systems configured for left-handed users, where the primary button is the right one (from an absolute perspective), this function examines the proper button.

pointerX

2006-11-18T21:13:00Z

Event.pointerX(event) -> Number

Returns the absolute horizontal position for a mouse event.

Note: the position is absolute on the page, not on the viewport: scrolling right increases the returned value for events on the same viewport location.

stopObserving

2006-11-18T21:12:00Z

Event.stopObserving(element, eventName, handler[, useCapture = false])

Unregisters an event handler.

This function is called with exactly the same argument semantics as observe. It unregisters an event handler, so the handler is not called anymore for this element+event pair.

Why won't it stop observing!?

For stopObserving to work, you must pass exactly the same arguments as those you did to the corresponding observe call. Complying with this seems straightforward enough, but there is a common pattern where code is not what it seems to be:


var obj = {
  …
  fx: function(event) {
    …
  }
};

Event.observe(elt, 'click', obj.fx.bindAsEventListener(obj));
…

// THIS IS WRONG, DON'T DO IT!
Event.stopObserving(elt, 'click', obj.fx.bindAsEventListener(obj)); // Won't work!

Here, although it may seem fine at first glance, you must remember that bindAsEventListener returns a fresh anonymous function that wraps your method. This means that every call to it returns a new function. Therefore, the code above requests stopping on another function than was used when setting up observation. No match is found, and the original observer is left untroubled.

To avoid this, you need to "cache" the bound functions (which is, for instance, what script.aculo.us does in many of its classes), like th is:


var obj = {
  …
  fx: function(event) {
    …
  },
};

obj.bfx = obj.fx.bindAsEventListener(obj);

Event.observe(elt, 'click', obj.bfx);
…
Event.stopObserving(elt, 'click', obj.bfx);

element

2006-11-18T21:12:00Z

Event.element(event) -> Element

Returns the DOM element on which the event occurred.

Note that from v1.5.1, the element returned by Event.element is already extended.

Example

Here’s a simple code that lets you click everywhere on the page and, if you click directly on paragraphs, hides them.


Event.observe(document.body, 'click', function(event) {
  var element = Event.element(event);
  if ('P' == element.tagName)
    element.hide();
});

Note for Prototype 1.5.0

Note that prior to version 1.5.1, if the browser does not support native DOM extensions (see this page for further details), the element returned by Event.element might very well not be extended. If you intend to use methods from Element.Methods on it, you need to wrap the call in the $() function like so:


Event.observe(document.body, 'click', function(event) {
  var element = $(Event.element(event));
  /* ...  */
});

observe

2006-11-18T21:10:00Z

Event.observe(element, eventName, handler[, useCapture = false])

Registers an event handler on a DOM element.

An important note

First, if you're coming from a background where you'd use HTML event attributes (e.g. <body onload="return myFunction()">) or DOM Level-0 event properties (e.g. window.onload = myFunction;), you must shed those vile ways :-) and understand what observe does.

It does not replace existing handlers for that same element+event pair. It adds to the list of handlers for that pair. Using observe will never incapacitate earlier calls.

What are those arguments about?

The DOM element you want to observe; as always in Prototype, this can be either an actual DOM reference, or the ID string for the element.
The standardized event name, as per the DOM level supported by your browser (usually DOM Level 2 Events, see section 1.6 for event names and details). This can be as simple as 'click'.
The handler function. This can be an anonymous function you create on-the-fly, a vanilla function, a bound event listener, it's up to you.
Optionally, you can request capturing instead of bubbling. The details are in the DOM spec referred to above. Note that capturing is not supported on several major browsers, and is seldom what you need, anyway. Most often, you won't even provide this argument.

The requirement people too often forget…

To register a function as an event handler, the DOM element that you want to observe must already exist in the DOM (in other words, it must have appeared in the source, or been dynamically created and inserted, before your handler-registration script line runs).

A simple example

Let us assume the following (X)HTML fragment:


<form id="signinForm" method="post" action="/auth/signin">
…
</form>

Here's how to register your function checkForm on form submission:


Event.observe('signinForm', 'submit', checkForm);

Of course, you'd want this line of code to run once the form exists in the DOM; but putting inline scripts in the document is pretty obtrusive, so instead we'll go for a simple approach that waits till the page is fully loaded:


Event.observe(window, 'load', function() {
  Event.observe('signinForm', 'submit', checkForm);
});

Just a little wrapping…

Note that if your page is heavy, you might want to run this code before the page is fully loaded: just wait until the DOM is loaded, that will be enough. There is currently no standard event for this, but here is a helpful article you can use.

The tricky case of methods that need `this`

Passing your event handler as a function argument, you lose its binding. That is, you lose its ability to know what this means to the original function. If you're passing in a method that does need to use the this reference (for instance, to access fields of its container object), you're in trouble.

Or not.

This is an issue specifically addressed by Prototype's bindAsEventListener function. Check it out if you don't know it already. Usage is simple:


var Checks = {
  // some stuff our 'generic' function needs

  generic: function(event) {
    // Some generic, all-purpose checking (e.g. empty required fields)
  }
};

Event.observe('signinForm', 'submit', Checks.generic.bindAsEventListener(Checks));

Prototype JavaScript framework - Event

extend

unloadCache

The sad tale of MSIE, event handlers and memory leaks

You don’t even need to know this

Event

♪ What a wonderful mess (it would be) ♫

Prototype to the rescue!

Instance methods on event objects
1.6

Before

After

pointerY

stop

Example

findElement

Example

See also

isLeftClick

pointerX

stopObserving

Why won't it stop observing!?

See also

element

Example

See also

Note for Prototype 1.5.0

observe

An important note

What are those arguments about?

The requirement people too often forget…

A simple example

The tricky case of methods that need `this`

See also

Prototype JavaScript framework - Event

extend

unloadCache

The sad tale of MSIE, event handlers and memory leaks

You don’t even need to know this

Event

♪ What a wonderful mess (it would be) ♫

Prototype to the rescue!

Instance methods on event objects 1.6

Before

After

pointerY

stop

Example

findElement

Example

See also

isLeftClick

pointerX

stopObserving

Why won't it stop observing!?

See also

element

Example

See also

Note for Prototype 1.5.0

observe

An important note

What are those arguments about?

The requirement people too often forget…

A simple example

The tricky case of methods that need this

See also

Instance methods on event objects
1.6

The tricky case of methods that need `this`