Updated Dec 07, 2008 by gregreimer

EventDeclaration

Using reglib's event delegation methods

Procedural vs. Declarative Event Handling

Suppose you wanted links with class="popup" to launch in new windows. In JQuery, using the load-traverse-modify methodology, you might do something like this:

// JQuery
$(document).ready(function(){
    $('a.popup').click(function(e){
        window.open(this.href);
        e.preventDefault();
    });
    document.body.innerHTML += "<p>Whoops, I just overwrote all the events I just attached!</p>";
});

This is a decidedly procedural methodology. The downside of it is that the events won't work until the document is ready, i.e. the DOM finishes loading off the network and into memory. The other downside is shown in the code: overwrites to the DOM overwrite the events. Here's the reglib approach:

// reglib
reg.click('a.popup',function(e){
    window.open(this.href);
    return false;
});
addEvent(window, 'load', function(){
    document.body.innerHTML += "<p>I just overwrote the DOM, but all my events still work!</p>";
});

reg.click() does not trigger a procedural scan of the DOM. It just declares how clicks on certain elements should be handled. Not only is the event "live" before the document is ready, but overwriting the DOM doesn't overwrite the events. Internally, this is accomplished through a form of event delegation.

reglib's declarative event handling methods

reg.click(selectorString, clickHandler, mouseDownHandler, mouseUpHandler, doubleClickHandler)

Registers click and other mouse events against selected elements. All functions can optionally be null or undefined. Most common use case is reg.click(sel, clickFunc).

reg.hover(selectorString, mouseOverHandler, mouseOutHandler)

Registers a mouseover and/or mouseout event handler against selected elements. If only a mouseout handler is needed, null can be passed in for the mouseover handler.

reg.focus(selectorString, focusHandler, blurHandler)

Registers a focus and/or blur handler against selected elements. If only a blur handler is needed, null can be passed in for the focus handler.

Note: Even if elements like DIV and UL can't receive focus, reglib can still register focus and blur events against them, as long as they have focusable descendants like A and INPUT. As counterintuitive as it perhaps seems, this code works:

// all forms turn yellow when their inputs have focus
reg.focus('form', function(e){
    this.style.backgroundColor = "#ff0";
}, function(e){
    this.style.backgroundColor = "#fff";
});

reg.key(selectorString, keyDownHandler, keyPressHandler, keyUpHandler)

Registers keyboard event handlers against selected elements. As wildly incompatible as keyboard events are across browsers and platforms, this can sometimes come in handy. Note that reglib makes no attempt to normalize keyboard event behavior across browsers and platforms. keydown is probably the most common event you'd want to handle, but you can pass functions for whichever events you want to handle and null for the rest.

Selector strings

See ReglibSelectors for info on how to write selectors.

Handler functions

Three things to remember about the handler functions:

They take an event object as their only parameter.
The this object always refers to the element matching the selector, even if the event target was an ancestor of that element.
Returning false from them prevents the default action of the event.

Examples

Here are some code examples showing what kinds of things you can do with the reglib event delegation methods.

reg.click()

// in the JavaScript
reg.click('p.foo a', function(e){
    alert(this.nodeName);
    alert(reg.getTarget(e).nodeName);
    return false;
});

<!-- in the html -->
<p class="foo">
    <!-- clicking this link will alert "A" and then alert "EM" and then nothing will happen -->
    <a href="page.html"><em>clickme</em></a>
</p>

reg.hover()

// in the JavaScript
reg.hover('p.foo a', mOver, mOut);
function mOver(e) { reg.addClassName(document.body, 'bar'); }
function mOut(e) { reg.removeClassName(document.body, 'bar'); }

/* in the css */
body.bar { background: yellow; }

<!-- in the html -->
<p class="foo">
    <!-- hovering this makes the whole page yellow -->
    <a href="page.html">hoverme</a>
</p>

reg.focus()

/* in the css */
input.error { border: 2px solid red; }

// in the JavaScript
// we just want to validate the date format onblur,
// no need to handle the focus event, so it can be null
reg.focus('input.date', null, function(e){
    if (!/^\d\d\/\d\d\/\d\d\d\d$/.test(this.value)) {
        alert('invalid date');
        reg.addClassName(this, 'error');
    } else {
        reg.removeClassName(this, 'error');
    }
});

Comment by gtwale, Nov 13, 2008

hi,

I tried the click example but an error occured at line 933 :

// my html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>Document sans nom</title>

reg.click('a',function(e){

alert('hello');

return false;

});

</script>

</head>

<body>

<a href="#">hello</a>

</body>

</html>

// reg1.0.js line 933

var parsedSel = new Selector('a');

firebug alert : "Selector is not defined"

Is there anything I have forget ?

Thanks.

Comment by nik.pasaran, Nov 13, 2008

2gtwale Try reg.importAll() before reg.click

Comment by gtwale, Nov 14, 2008

Thanks, it works well.

But why to have to import these functions in global namespace ?

For example, Selector should be used only in reg namespace, so, we could just write line 933 as :

var parsedSel = new reg.Selector('a');

Sorry, I'm french, but I hope you know what my dirty english means :)

Comment by gregreimer, Nov 14, 2008

This is an error. I've fixed it and uploaded reg1.0.1.js. Thanks for the catch.