Introduction

Despite its evils, the load-traverse-modify model of JavaScript development is often unavoidable. For example, since form submit events don't bubble, reglib lacks a reg.submit() method. Form elements must therefore be hunted down and wrestled to the ground in order to get them to submit. reglib offers tools to make this as (relatively) painless as possible.

load-traverse-modify methods

reg.setup(selectorString, setupFunction)

Calling this method queries the DOM for elements matching selectorString, and runs setupFunction against those elements. See ReglibSelectors for more info on selector syntax.

Important: the query does not run when you call reg.setup(), but rather when the onload event fires (or DOMContentLoaded fires, whichever comes first). When you call reg.setup() you're queuing up a to-do list of items to search for when it comes time to scan the DOM.

Here's an example, and roughly equivalent code in JQuery for reference:

// reglib
reg.setup('form.foo',function(){
    addEvent(this, 'submit', function(e){
        ...validate the form...
        if (!isValid) {
            alert("foo form is not valid");
            cancelDefault(e);
        }
    });
});

// JQuery
$(document).ready(function(){
    $('form.foo').submit(function(e){
        ...validate the form...
        if (!isValid) {
            alert("foo form is not valid");
            e.preventDefault();
        }
    });
});

Note: additions to the DOM by setupFunction will not be included in the DOM scan. For example:

reg.setup('p',function(){
    document.body.appendChild(reg.newElement('p',null,'this is a paragraph'));
    this.style.backgroundColor = 'red';
});

Will result in a bunch of non-red paragraphs appearing at the end of the page.

reg.rerun(el)

If el was added after the onload event fired, you can use this method to re-execute the reg.setup() to-do list against el (and its descendants) to make sure it too gets the behavior it needs.

var johnnyComeLately = elem('div');
johnnyComeLately.innerHTML = threeHundredKilobytesOfHtml;
document.body.appendChild(johnnyComeLately);
reg.rerun(johnnyComeLately);

reg.preSetup(function) and reg.postSetup(function)

These both also create to-do lists of actions to perform when the onload event fires. Unlike reg.setup() however, they don't run against specific nodes, they just blindly run onload. This makes for a grand total of three to-do lists that need to be executed onload. The reg.preSetup() list goes first, the reg.setup() list goes second, the reg.postSetup() goes third. This guaranteed ordering can come in handy.

reg.preSetup() and reg.postSetup() are often preferable to reg.setup():

// this works, but it's wasteful because
// it initiates a DOM crawl. this is O(N) where
// N is the number of elements in the document
reg.setup('#foo', function(){
    ...do something with this...
});

// this does the same thing, but
// is O(1) rather than O(N)
reg.postSetup(function(){
    var el = document.getElementById('foo');
    if (!el) { return; }
    ...do something with el...
});