Updated Nov 09, 2008 by gregreimer

DomFunctions

reglib DOM functions

This page lists reglib's DOM convenience functions:

Introduction

reglib has a whole raft of DOM convenience functions. These can be called directly off the reg object or they can be imported to the global namespace:

reg.importAll();
// now you can say var p = newElement('p')
// instead of var p = reg.newElement('p')

Many of these functions also have shorthand aliases to save typing:

var p = elem('p'); // instead of var p = newElement('p')

Functions for working with class attributes

These functions are predicated upon the notion of the "class list". An element's class list is represented in the attribute as a space-separated set of values. For example class="foo bar" represents a class list of ["foo","bar"]. Since it's an unordered set, class="foo bar", class="bar foo" and class="foo bar foo" are all treated as having the indentical class list of ["foo","bar"].

`reg.addClassName()`

reg.addClassName(el, cName);
acn(el, cName); // alias

Adds cName to the the class list of el. If the class list of el already contains cName, the function just returns silently.

`reg.getElementsByClassName()`

reg.getElementsByClassName(cName[, ctxNode[, tagName]]);
gebcn(cName[, ctxNode[, tagName]]); // alias

Returns an array of all elements whose class lists contain cName. cName can optionally contain a space-separated class list. If so, only elements containing all classes are returned. If ctxNode is present, just the subtree of ctxNode is searched, otherwise the entire document is searched. If tagName is present, only elements of that tag name are returned. The list returned is not live, so mutations to the DOM after this function is called will not be reflected in the returned list. This function relies on native node.getElementsByClassName() implementations when possible, otherwise falling back on slower search methods.

`reg.hasClassName()`

reg.hasClassName(el, cName);
hcn(el, cName); // alias

Returns true if the class list of el contains cName, otherwise returns false.

`reg.matchClassName()`

reg.matchClassName(el, regexp);
mcn(el, regexp); // alias

Returns true if the class list of el contains a value matching regexp, otherwise returns false. regexp is tested against individual items in the class list, not the entire class attribute value, so if the class attribute is class="foo bar baz", then reg.matchClassName(el, /^bar$/) returns true. This function is much slower than reg.hasClassName().

`reg.removeClassName()`

reg.removeClassName(el, cName);
rcn(el, cName); // alias

Removes cName from the the class list of el. If the class list of el doesn't contain cName, the function just returns silently.

`reg.switchClassName()`

reg.switchClassName(el, cName1, cName2);
scn(el, cName1, cName2); // alias

Toggles the presence of cName1 and cName2 so that if el starts out having cName1 in its class list, it will be replaced by cName2, and vice versa. If neither are present, cName1 is added. If both are present, cName2 is removed.

`reg.toggleClassName()`

reg.toggleClassName(el, cName);
tcn(el, cName); // alias

If the class list of el contains cName it's removed, otherwise it's added.

Functions using CSS selectors

`reg.elementMatchesSelector()`

reg.elementMatchesSelector(el, selString);
matches(el, selString); // alias

Returns true if el matches selString. Identical to new reg.Selector(selString).matches(el).

`reg.getElementsBySelector()`

reg.getElementsBySelector(selString[, ctxNode]);
gebs(selString[, ctxNode]); // alias

Returns an array of elements matching selString. If ctxNode is present, just the subtree of ctxNode is searched, otherwise the entire document is searched. The list returned is not live, so mutations to the DOM after this function is called will not be reflected in the returned list. This function relies on native node.querySelectorAll() implementations whenever possible, otherwise falling back on slower search methods.

`reg.getParent()`

reg.getParent(el, selString);

Returns the nearest ancestor node to el matching selString, or null if no matching node is found:

<!-- in the html -->
<div class="baz">
  <div class="foo bar">
    <div class="foo">
      <div class="foo">
        <span id="blah"/>
      </div>
    </div>
  </div>
</div>

// in the JavaScript
var span = document.getElementById('blah');
var c = reg.getParent(span, 'div.baz > div.foo').className;
// c equals "foo bar"

Other functions

`reg.elementText()`

reg.elementText(el);
elemText(el); // alias

Returns the sum total of the values of the text nodes within el. For example:

<!-- in the html -->
<h1 id="title">Get it <em>now</em>!</h1>

// in the JavaScript
var h1 = document.getElementById('title');
var txt = elemText(h1);
// txt equals "Get it now!"

h1.innerHTML would have returned the EM tags, which may not have been desirable.

`reg.getElementById()`

reg.getElementById(id);
gebi(id); // alias

Just a wrapper for document.getElementById(). It would be pointless to have this function except that its alias, gebi(), can save a lot of typing.

`reg.getElementsByTagName()`

reg.getElementsByTagName(tagName[, ctxNode]);
gebtn(tagName[, ctxNode]); // alias

Just a wrapper for document.getElementsByTagName(). It would be pointless to have this function except that its alias, gebtn(), can save a lot of typing.

`reg.innerWrap()`

reg.innerWrap(el, wrapperEl);

Makes wrapperEl the one and only child of el. All of the children of el become children of wrapperEl.

`reg.insertAfter()`

reg.insertAfter(insertMe, afterThis);

Inserts insertMe after afterThis in the DOM. This function only exists to fill a gap in the DOM spec, namely the lack if Node.insertAfter(insertMe, afterThis).

`reg.newElement()`

reg.newElement(tagName[, attObj[, contents]]);
elem(tagName[, attObj[, contents]]); // alias

Creates a new element. tagName will be the tag name of the element, or it can contain class and id notation:

var div1 = elem('div');         // div1 equals <div/>
var div2 = elem('div.foo');     // div2 equals <div class="foo"/>
var div3 = elem('div#bar');     // div3 equals <div id="bar"/>
var div4 = elem('div.foo#bar'); // div4 equals <div id="bar" class="foo"/>

If attObj is provided, it will be used as attribute names and values:

var img = elem('img',{'src':'image.jpg','alt':'Hello'});
// img equals <img src="image.jpg" alt="Hello"/>

contents can be either a string, an element, or an array of strings or elements. Strings become text node children of the returned element, elements become child elements of the returned element:

var now = elem('em',null,'now');
var p = elem('p',null,["Get it ",now,'!']);
// p equals <p>Get it <em>now</em>!</p>

For example of how much typing this function saves, look at this example of elem() versus document.createElement() and friends:

var icon = elem('img.icon', {alt:'',src:'secure.gif'});
var para = elem('p.intro',null,["Security ",icon]);

var icon = document.createElement('img');
icon.alt = "";
icon.src = 'secure.gif';
var para = document.createElement('p');
para.appendChild(document.createTextNode('Security '));
para.appendChild(icon);

`reg.nextElement()`

reg.nextElement(el);
nextElem(el); // alias

Returns the next sibling element of el, or null if not found. Differes from Node.nextSibling because it skips text nodes and returns only element nodes, i.e. nodes where nodeType == 1.

`reg.outerWrap()`

reg.outerWrap(el, wrapperEl);

Removes el from its parent and adds it as a child of wrapperEl.

`reg.previousElement()`

reg.previousElement(el);
prevElem(el); // alias

Returns the previous sibling element of el, or null if not found. Differes from Node.previousSibling because it skips text nodes and returns only element nodes, i.e. nodes where nodeType == 1.