gator.js

creating a gator instance

The methods that do event delegation are prototype methods on the Gator object. To instantiate a Gator object call the function directly:

Gator(element);

or use the new keyword

new Gator(element);

attaching events

Attaching events uses the Gator.on method. The on method accepts 3 arguments:

eventType

Any browser event that you would normally pass to addEventListener.

You can also pass in an array of multiple event types, for example ['mousedown', 'mouseup']

selector

A CSS selector for elements to look for within the outer element*.

callback

A callback function to fire when the event occurs. The callback gets passed a single argument containing the browser Event object. The callback is invoked in the context of the selector passed in. That means in the example above if you reference this in your callback this corresponds to the td element.

*Note that when using the legacy plugin you can only use a single class name, id, or tag name for the selector argument.

Suppose you wanted to add a click event to every td inside of a table

var table = document.getElementsByTagName('table')[0];
Gator(table).on('click', 'td', _doStuff);

This example will fire even if you click on an element inside of a td. For example if you click on a span inside of a td it will trigger the event as if you clicked on the td and this in the callback will still reference the td. You can use e.target to see what element was actually clicked on.

As a convenience you can leave out the selector argument to bind an event directly to the original element

Gator(document).on('click', function(e) {
    console.log('clicked on document');
})

If you bind multiple callbacks to the same event/element/selector group they will be fired in the order they were bound.

No matter how many callbacks you bind to an element in Gator only one event listener will be attached to the actual DOM element. Take the code on this page for example

Gator(document).on('click', '.expand', _handleExpandClick);
Gator(document).on('click', 'pre', _selectCode);
Gator(document).on('click', function() {
    selected = false;
});

Even though there are 3 click handlers document.addEventListener('click'... is only called once.

removing events

Removing events uses the Gator.off method. This method accepts the same arguments as Gator.on.

In Javascript when you want to remove an event you have to pass a reference to the original callback you passed to the event. Gator keeps track of that internally so in most cases you don't have to worry about it.

Let's say you have the following events set up

var gator = new Gator(document);
gator.on('mousedown', _documentDown);
gator.on('mousedown', 'ul', _ulDown);
gator.on('mousedown', 'li', _liDown);
gator.on('mousedown', 'li', _otherLiDown);

If you want to remove all events from document

Gator(document).off();

If you want to remove all mousedown events

Gator(document).off('mousedown');

If you want to remove all mousedown events on li elements

Gator(document).off('mousedown', 'li');

If you want to remove a single mousedown event on li elements pass a reference to the original callback

Gator(document).off('mousedown', 'li', _otherLiDown);

event bubbling

When using event delegation there is not really a concept of event bubbling because the event has already reached a higher level element by the time it is captured.

That being said, Gator internally mimics traditional events bubbling. This allows you to use e.preventDefault() and e.stopPropagation() as you normally would in your callback functions.

As an added convenience if you return false in your callback it is a shortcut for calling e.preventDefault() followed by e.stopPropagation().

Using the previous example if you wanted to stop the mousedown event from getting back to the document you could do this in your ul handler

var _ulDown = function(e) {
    e.stopPropagation();
};