The event module

Event handling is tricky in JavaScript. IE, Netscape (up to v4) and others all have significantly different event-handling models, none of which conform to the standard DOM Level 2 Events specification (as implemented in, say, Mozilla).

This module presents a ‘listener-style’ interface to event handling that works in Netscape 3+, IE4+, Opera, Mozilla, Konqueror, iCab, Oregano and probably more. Naturally not all browsers will dispatch all types of events on all types of elements so it won’t automatically guarantee compatibility for you but it’s a good start.

With listener-style events you are not limited to one event handler per element. Instead, every function that is interested in certain events is registered as a listener on the object it is interested in; an event can call any number of interested listener functions. This makes it much easier to write modular JavaScript, where each bit of functionality is contained in its own script, and takes responsibility for listening to objects it is interested in, without worrying about overwriting other scripts’ event handlers. Also it helps keep scripting content out of HTML, resulting in cleaner, more maintainable code.

Since version 0.8, a binding interface is also provided. You can request a function be called for every element in the document, or for each element of a certain tag name. Your function can then check each element and add listeners to it if necessary. By using bindings like this, you don’t have to worry about whether the whole document has been loaded when your script first runs.

Interface

event_addListener(source, type, listener)

Add a listener to an object. Afterwards, every time the specified event happens on that object, your listener function will be called. type must be an event name in a string, eg. 'click'. Adding the same (source, type, listener) a second time has no effect, the listener will not be called twice.

event_removeListener(source, type, listener)

Remove a listener. The function will no longer be called when the event happens. Trying to remove a listener which isn’t attached to an object has no effect. It is also safe to remove a listener from inside listener code.

event_addBinding(selector, binding)

Asks the event module to call the binding function back once for every element in the document that matches the selector, as soon as that element has loaded (which might be straight away). The function receives one argument, which is the element node.

selector should be a tag name, or '*' for all elements. On older browsers that do not support DHTML, the only tags you can get are 'img', 'a' and 'form' - any other tag names will result in the binding function not being called. (In Netscape 4, you can also request 'div' to get layer objects.)

Listener functions

The listener function will be called with the arguments (source, type) when the event occurs. If this function returns false, the default action is stopped - a form-submit event listener returning false will stop the form being submitted, a link-click event listener returning false will stop the link being followed, etc.

If there is more than one listener function and both return a value (true or false), the one to be registered last will ‘win’. If a listener function returns without a value, it does not affect whether the default action is prevented.

Latest version

Version 0.9: module, example page.

and@doxdesk.com