Events.js

A super-awesome JavaScript event handler library

Author: James Brumond
Version: 0.2.3-beta

Copyright 2011 James Brumond
Dual licensed under MIT and GPL

Features

• Simple, easy-to-use API
• Event namespacing
• Cross-browser support for some commonly unsupported events (hashchange, mouseenter, mouseleave)
• System for defining custom events
• Keystroke handling support
• Very lightweight (only 4.2 KB minified and gziped)

Samples

(function() {

    // Wait for the DOM to load before adding our hover events
    Events.ready(function() {
        var elem = document.getElementById('myElement');
        // Do something when we hover over the element
        Events.bind(elem, 'mouseenter', function(e) {
            doSomethingCool();
        });
        // And when we leave...
        Events.bind(elem, 'mouseleave', function(e) {
            undoSomethingCool();
        });
    });

    // Add a keyboard alternative:
    // When the user hits Ctrl+A, call our cool function;
    // when Alt+A is pressed, call our uncool function
    Events.bind(document, 'keystroke.Ctrl+A', function(e) {
        doSomethingCool();
    });
    Events.bind(document, 'keystroke.Alt+A', function(e) {
        undoSomethingCool();
    });

}());

API

Functions

string Events.version ( void )

Gets the current version string for Events.js.

void Events.ready ( function callback )

If the DOM has already loaded, the function is called immediately. If not, the function is called on the window.onload event.

Events.ready(function() {
    // Do something when the DOM is ready
});

void Events.bind ( object target, string event, function callback )

Bind an event function to the given target.

Events.bind(window, 'load', function(e) {
    // Do something on page load
});

void Events.unbind ( object target[, string event ])

Unbind event functions from the given target. If no event is given, all events will be unbound.

Events.unbind(window, 'load');

void Events.invoke ( object target[, string event[, object info ]])

Invoke an event. If given, the properties of the info object will be passed on to the event object.

Events.invoke(window, 'load');

object Events.buildEventObject ( string type[, object info[, object extra ]])

Create an event object. type is the event type, such as “load” or “mouseover”. info is information about the event such as the mouse position during the event. Which values are needed changes based on the event type. extra is for any other values you may want to add onto the event object.

var myOnloadEvent = Events.createEventObject('load');
var myKeypressEvent = Events.createEventObject('keypress', {
    ctrlKey: true
});

boolean Events.specialEvents.exists ( string event )

Tests if a special event has been defined.

if (Events.specialEvents.exists('mouseenter')) {
    Events.bind(myElement, 'mouseenter', function() {
        doSomethingCool();
    });
}

void Events.specialEvents.add ( string event, object definition )

Creates a special event. Special events can be defined in two different ways.

First, you can give an attachesTo event and an eventTest function. In this format, whenever the attachesTo event is fired, the eventTest function will be run, and if it returns true, the special event is fired.

var mouseIsClicked = false;
Events.specialEvents.add('drag', {
    attachesTo: 'mousemove',
    eventTest: function(evt) {
        return mouseIsClicked;
    }
});

The second format gives you a little more direct control. You provide bind, unbind, and invoke functions which are called at the appropriate times, and your functions then do all the direct event handling.

Events.specialEvents.add('drop', {
    bind: function(target, func) {
        Events.bind(target, 'mouseup', func);
    },
    unbind: function(target, func) {
        Events.unbind(target, 'mouseup');
    },
    invoke: function(target) {
        Events.invoke(target, 'mouseup');
    }
});

void Events.specialEvents.edit ( string event, object definition )

Edit an already defined special event. This function uses the same format as the add() function above.

void Events.specialEvents.del ( string event )

Remove a special event definition.

Events.specialEvents.del('mouseenter');

void Events.log ( mixed item[, … ])

A standardized abstraction of console.log(). Prepends a human-readable timestamp to the output.

Events.bind(window, 'load', function(e) {
    Events.log('window onload event fired');
});
// Outputs something like:
// [Sun Apr 10 2011 07:02:39 GMT-0700 (PDT)] - window onload event fired

Namespacing

Adding namespacing to your events is easy. You just append the namespace you wish to use wherever you use the event name. For example, if you want to namespace the events used in a hover event, you could do it like this:

Events.bind(myElement, 'mouseenter.myNamespace', function() {
    // Do something ...
});
Events.bind(myElement, 'mouseleave.myNamespace', function() {
    // Undo something ...
});

Special Events

Special events are a way of adding non-supported or custom events. For example, the mouseenter and mouseleave events are IE proprietary. Therefore, in order to make them cross-browser compatible, they were implemented as special events. The hashchange event is also handled with specialEvents. The specific function definitions for dealing with special events are above in the Functions section.

Keystroke Handling

Events.js also has support for a custom event called “keystroke”. When using this event, the first namespace is the key combination to respond to. For example, to respond to Ctrl+Shift+D, you would bind to the event “keystroke.Ctrl+Shift+D”. Like this:

Events.bind(document, 'keystroke.Ctrl+Shift+D', function(e) {
    doSomethingCool();
});

The key combinations are case insensitive. The following keys are supported:

• Modifiers (ctrl, shift, alt, meta)
• Alpha-numeric characters (a-z, 0-9)
• Function Keys (F1 – F12)
• Special Keys
  • esc
  • escape
  • tab
  • space
  • return
  • enter
  • backspace
  • scrolllock (scroll_lock, scroll)
  • capslock (caps_lock, caps)
  • numlock (num_lock, num)
  • pause
  • break
  • insert
  • home
  • delete
  • end
  • pageup (page_up, pu)
  • pagedown (page_down, pd)
  • left
  • up
  • right
  • down
• Symbols
  

  `~!@#$%^&*()-_=+;:'",<.>/?\|