DOM Events and Javascript

Basic event handling

The syntax for working with events looks like the code below.

Event.observe(element, name, observer, [useCapture]);

Assuming for a moment that we want to observe when a link was clicked, we could do the following:

// <a id="clicker" href="http://foo.com">Click me</a>
Event.observe('clicker', 'click', function(event)
{
    alert('clicked!');
});

If we wanted to get the element that fired the event, we'd do this:

Event.observe('clicker', 'click', function(event)
{
    alert(Event.element(event));
});

Observing keystrokes

If we wanted to observe keystrokes for the entire document, we could do the following:

Event.observe(document, 'keypress', function(event)
{
    if(Event.keyCode(event) == Event.KEY_TAB)
        alert('Tab Pressed');
});

And lets say we wanted to keep track of what has been typed :

Event.observe('search', 'keypress', function(event)
{
    Element.update('search-results', $F(Event.element(event)));
});

Prototype defines properties inside the event object for some of the more common keys, so feel free to dig around in Prototype to see which ones those are.

A final note on keypress events; If you'd like to detect a left click you can use Event.isLeftClick(event).

Getting the coordinates of the mouse pointer

Drag and drop, dynamic element resizing, games, and much more all require the ability to track the X and Y location of the mouse. Prototype makes this fairly simple. The code below tracks the X and Y position of the mouse and spits out those values into an input box named mouse.

Event.observe(document, 'mousemove', function(event)
{
    $('mouse').value = "X: " + Event.pointerX(event) +
                       "px Y: " + Event.pointerY(event) + "px";
});

If we wanted to observe the mouse location when it was hovering over a certain element, we'd just change the document argument to the id or element that was relevant.

Stopping Propagation

Event.stop(event) will stop the propagation of an event .

Events, Binding, and Objects

Everything has been fairly straight forward so far, but things start getting a little trickier when you need to work with events in and object-oriented environment. You have to deal with binding and funky looking syntax that might take a moment to get your head around.

Lets look at some code so you can get a better understanding of what I'm talking about.

EventDispenser = Class.create();
EventDispenser.prototype =
{
  initialize: function(list)
  {
    this.list = list;
 
    // Observe clicks on our list items
    $$(this.list + " li").each(function(item)
    {
        Event.observe(item, 'click', this.showTagName.bindEvent(this));
    }.bind(this));
 
    // Observe when a key on the keyboard is pressed.
    // In the observer, we check for
    // the tab key and alert a message if it is pressed.
    Event.observe(document, 'keypress', this.onKeyPress.bindEvent(this));
 
    // Observe our fake live search box.  When a user types
    // something into the box, the observer will take that
    // value(-1) and update our search-results div with it.
    Event.observe('search', 'keypress', this.onSearch.bindEvent(this));
 
    Event.observe(document, 'mousemove', this.onMouseMove.bindEvent(this));
  },
 
  // Arbitrary functions to respond to events
  showTagName: function(event)
  {
    alert(Event.element(event).tagName);
  },
 
  onKeyPress: function(event)
  {
    var code = event.keyCode;
    if(code == Event.KEY_TAB)
        alert('Tab key was pressed');
  },
 
  onSearch: function(event)
  {
    Element.update('search-results', $F(Event.element(event)));
  },
 
  onMouseMove: function(event)
  {
    $('mouse').value = "X: " + Event.pointerX(event) +
                "px Y: " + Event.pointerY(event) + "px";
  }
}

Whoa! What's going on here? Well, we've defined our a custom class EventDispenser. We're going to be using this class to setup events for our document. Most of this code is a rewrite of the code we looked at earlier except this time, we are working from inside an object.

Looking at the initialize method, we can really see how things are different now. Take a look at the code below:

// Observe clicks on our list items
$$(this.list + " li").each(function(item)
{
    Event.observe(item, 'click', this.showTagName.bindEvent(this));
}.bind(this));

We've got iterators, binding and all sorts of stuff going on. Lets break down what this chunk of code is doing.

First we are hunting for a collection of elements based on it's CSS selector. This uses the Prototype selector function $$(). After we've found the list items we are dealing with we send those into an each iteration where we will add our observers.

Event.observe(item, 'click', this.showTagName.bindEvent(this));

Now looking at the code above, you'll notice the bindEvent function. This takes the method before it showTagName and treats it as the method that will be triggered when, in this case, someone clicks one of our list items.

You'll also notice we pass this as an argument to the bindEvent function. This simply allows us to reference the object in context EventDispenser inside our function showTagName(event). If the showTagName function requires additional parameters, you can attach them to the later parameters of bindEvent. For example

this.showTagName.bindEvent(this, param1, param2);
 
//where the showTagName function is defined as
showTime : function (event, param1, param2) { ... }

Moving on, you'll see bind(this) attached to our iterator function. This really has nothing to do with events, it is only here to allow me to use this inside the iterator. If we did not use bind(this), I could not reference the method showTagName inside the iterator.

Ok, so we'll move on to looking at our methods that actually get called when an event occurs. Since we've been dealing with showTagName, lets look at it.

showTagName: function(event)
{
    alert(Event.element(event).tagName);
}

As you can see, this function accepts one argument--the event. In order for us to get the element which fired the event we need to pass that argument to Event.element. Now we can manipulate it at will.

This covers the most confusing parts of our code. The text above is also relevant to the remaining parts of our code. If there is anything about this you don't understand, feel free to ask questions in the forum.

Removing Event Listeners

This one threw me for a loop the first time I tried to use it. I tried something similar to what I did in the Event.observe call with the exception of using stopObserving, but nothing seemed to change. In other words, the code below does NOT work.

$$(this.list + " li").each(function(item)
{
    Event.stopObserving(item, 'click', this.showTagName);
}.bind(this));

What's the deal here? The reason this does not work is because there is no pointer to the observer. This means that when we passed this.showTagName in the Event.observe method before hand, we passed it as an anonymous function. We can't reference an anonymous function because it simply does not have a pointer.

So how do we get the job done? All we need to do is give the observing function a pointer, or the jargon free version: Set a variable that points to this.showTagName. Ok, lets change our code a bit.

this.showTagObserver = this.showTagName.bindEvent(this);
 
// Observe clicks on our list items
$$(this.list + " li").each(function(item)
{
    Event.observe(item, 'click', this.showTagObserver);
}.bind(this));

Now we can remove the event listeners from our list like this:

$$(this.list + " li").each(function(item)
{
    Event.stopObserving(item, 'click', this.showTagObserver);
}.bind(this));