Here we are again. I just love those CSS Selectors. If you haven’t read Part One of the series linked above, I would encourage it to get a little background on why we’re attempting this approach.

Download the appropriate files:

Get the easy ALL-IN-ONE file: Y2.js (31 KB original source) OR Y2-p.js (11 KB minimized)

Get the files separately (if you want to use a custom selector library, or have already included DomQuery or jQuery): Y2-solo.js (9 KB original source) OR Y2-solo-p.js (4 KB minimized)

Also, first you’ll need to get Jack’s nice DomQuery class.

Download: Jack Slocum’s DomQuery Standalone File (24 KB) 1.0 Alpha 3 – Rev 4
Download: Jack Slocum’s DomQuery Standalone File Packed (7 KB) 1.0 Alpha 3 – Rev 4

You can use the jDomQuery standalone, or any jQuery version, (instead of DomQuery) linked in the previous article, but there is an unresolved bug with the getRegion method since jQuery doesn’t return actual Array’s. But if you’re not using that method, have at it.

What can I do with it?

I have not included ALL functions in this class, only the ones that take nodes in as arguments. If you use these functions, you are encouraged to use the unmodified versions contained in YAHOO.util.Dom. Functions not included here: getClientHeight, getClientWidth, getDocumentHeight, getDocumentScrollLeft, getDocumentScrollTop, getDocumentWidth, getViewportHeight, getViewportWidth.

Let’s see some documentation on this mother (if you’re wondering what the original functions do, see the original documentation).

// this is the test context node we're going to pass in
var context = YAHOO.util.Dom.get('context');

addClass

Adds a CSS class to first matching node.

// returns void
Y2.util.Dom.addClass( 'div div:last', 'myClass');
Y2.util.Dom.addClass('div div:last', context, 'myClassContext');

addClassAll

Adds a CSS class to all matching nodes.

// returns void
Y2.util.Dom.addClassAll( 'div div:last', 'myClass');
Y2.util.Dom.addClassAll('div div:last', context, 'myClassContext');

hasClass

Tests the first result node returned to see if it has a CSS class.

// returns Booleans.
Y2.util.Dom.hasClass('div div:last', 'myClass');
Y2.util.Dom.hasClass('div div:last', context, 'myClassContext');

hasClassAll

Tests all matching nodes to see if they have a CSS class.

// returns Array of Booleans.
Y2.util.Dom.hasClassAll('div div:last', 'myClass');
Y2.util.Dom.hasClassAll('div div:last', context, 'myClassContext');

removeClass

Removes a CSS class from first matched node.

// returns Boolean (misdocumented on the YAHOO.util.Dom page)
Y2.util.Dom.removeClass('div.third','third');
Y2.util.Dom.removeClass('div.third', context,'third');

removeClassAll

Removes a CSS class from all matched nodes.

// returns Array of Booleans (misdocumented on the YAHOO.util.Dom page)
Y2.util.Dom.removeClassAll('div.third','third');
Y2.util.Dom.removeClassAll('div.third', context,'third');

replaceClass

Replaces a CSS class on first matched node with a new CSS class, or adds it if the old CSS class doesn’t exist.

// returns Boolean (misdocumented on the YAHOO.util.Dom page)
Y2.util.Dom.replaceClass('div.fourth','fourth','third');
Y2.util.Dom.replaceClass('div.fourth', context,'fourth','third');

replaceClassAll

Replaces a CSS class on all matched nodes with a new CSS class, or adds it if the old CSS class doesn’t exist.

// returns Array of Booleans (misdocumented on the YAHOO.util.Dom page)
Y2.util.Dom.replaceClassAll('div.fourth','fourth','third');
Y2.util.Dom.replaceClassAll('div.fourth', context,'fourth','third');

get

Get first matched node.

// returns HTMLElement
Y2.util.Dom.get('div b');
Y2.util.Dom.get('div b', context);

getAll

Get all matched nodes.

// returns Array of HTMLElement
Y2.util.Dom.getAll('div b');
Y2.util.Dom.getAll('div b', context);

batch

Executes a function against first matched node.

// returns single return value from the function
Y2.util.Dom.batch('div.second b', function(el){return el;});
Y2.util.Dom.batch('div b', context, function(el){return el;});

batchAll

Executes a function against all matched nodes.

// returns Array of return values from the function
Y2.util.Dom.batchAll('div.second b', function(el){return el;});
Y2.util.Dom.batchAll('div b', context, function(el){return el;});

generateId

Generates and assigns a unique ID attribute if not present on first matched element.

// returns String (new ID attribute)
Y2.util.Dom.generateId('div.first');
Y2.util.Dom.generateId('div.third', context);

generateIdAll

Generates and assigns a unique ID attribute if not present on matched elements.

// returns Array of String (new ID attributes)
Y2.util.Dom.generateIdAll('div.first');
Y2.util.Dom.generateIdAll('div.third', context);

getChildren

Gets all HTMLElement children of the first matched node (does not include text nodes or whitespace)

// returns Array of HTMLElement
Y2.util.Dom.getChildren('div.second');
Y2.util.Dom.getChildren('div.second', context);

getChildrenBy

Returns all HTMLElement children of the first matched node that pass a Boolean function test. (does not include text nodes or whitespace)

// returns Array of HTMLElement
Y2.util.Dom.getChildrenBy('div.second', function(el){return el.getAttribute('id')=='theMiddleB';});
Y2.util.Dom.getChildrenBy('div.second', context, function(el){return el.getAttribute('id')=='theMiddleB';});

getAncestorBy

Returns the first HTMLElement ancestor of the first matched node that passes a Boolean function test. (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getAncestorBy('div.third', function(el){return el.getAttribute('id')=='context';});
Y2.util.Dom.getAncestorBy('div.third', context, function(el){return el.getAttribute('id')=='context';});

getAncestorByClassName

Returns the first HTMLElement ancestor of the first matched node that has a CSS Class. (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getAncestorByClassName('div.third', 'contextClass');
Y2.util.Dom.getAncestorByClassName('div.third', context, 'contextClass');

getAncestorByClassName

Returns the first HTMLElement ancestor of the first matched node that is a certain tag (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getAncestorByTagName('div.third', 'div');
Y2.util.Dom.getAncestorByTagName('div.third', context, 'div');

getFirstChild

Returns the first HTMLElement child of the first matched node (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getFirstChild('div.second');
Y2.util.Dom.getFirstChild('div.second', context);

getFirstChildBy

Returns the first HTMLElement child that passes a boolean function test from the first matched node (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getFirstChildBy('div.second', function(el){ return el.getAttribute('id')=='theMiddleB';});
Y2.util.Dom.getFirstChildBy('div.second', context, function(el){ return el.getAttribute('id')=='theMiddleB';});

getLastChild

Returns the last HTMLElement child of the first matched node (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getLastChild('div.second');
Y2.util.Dom.getLastChild('div.second', context);

getLastChildBy

Returns the last HTMLElement child that passes a boolean function test from the first matched node (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getLastChildBy('div.second', function(el){ return el.getAttribute('id')=='theMiddleB';});
Y2.util.Dom.getLastChildBy('div.second', context, function(el){ return el.getAttribute('id')=='theMiddleB';});

getNextSibling

Returns the next HTMLElement sibling of the first matched node (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getNextSibling('div.second');
Y2.util.Dom.getNextSibling('div.second', context);

getNextSiblingBy

Returns the next HTMLElement sibling that passes a boolean function test from the first matched node (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getNextSiblingBy('div.second',function(el){ return el.getAttribute('class')=='third';});
Y2.util.Dom.getNextSiblingBy('div.second', context, function(el){ return YAHOO.util.Dom.hasClass(el,'third');});

getPreviousSibling

Returns the previous HTMLElement sibling of the first matched node (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getPreviousSibling('div.second');
Y2.util.Dom.getPreviousSibling('div.second', context);

getPreviousSiblingBy

Returns the previous HTMLElement sibling that passes a boolean function test from the first matched node (does not include text nodes or whitespace)

// returns HTMLElement
Y2.util.Dom.getPreviousSiblingBy('div.second',function(el){ return el.getAttribute('class')=='third';});
Y2.util.Dom.getPreviousSiblingBy('div.second', context, function(el){ return YAHOO.util.Dom.hasClass(el,'third');});

getRegion

Gets the Region containing the first matched element.

// returns <a href="http://developer.yahoo.com/yui/docs/YAHOO.util.Region.html">YAHOO.util.Region</a>
Y2.util.Dom.getRegion('div.second');
Y2.util.Dom.getRegion('div.second', context);

getRegionAll

Gets all Regions containing all matched elements.

// returns Array of <a href="http://developer.yahoo.com/yui/docs/YAHOO.util.Region.html">YAHOO.util.Region</a>
Y2.util.Dom.getRegionAll('div.myClass');
Y2.util.Dom.getRegionAll('div.myClass', context);

setStyle

Sets the style for the first matched node

// returns void
Y2.util.Dom.setStyle('div', 'border', '1px');
Y2.util.Dom.setStyle('div', context, 'border', '10px');

setStyleAll

Sets style for all matched nodes

// returns void
Y2.util.Dom.setStyleAll('div', 'border', '1px');
Y2.util.Dom.setStyleAll('div', context, 'border', '10px');

getStyle

Gets a specific style property from the first matched node

// returns String of specific style property
Y2.util.Dom.getStyle('div', 'border');
Y2.util.Dom.getStyle('div', context, 'border');

getStyleAll

Gets a specific style property from all matched nodes

// returns Array of Strings of specific style property
Y2.util.Dom.getStyleAll('div', 'border');
Y2.util.Dom.getStyleAll('div', context, 'border');

setX, setY, setXY

Sets the horizontal placement (X), vertical placement (Y), or both (XY) of the first matched element

// returns void
Y2.util.Dom.setX('div.second', 60);
Y2.util.Dom.setX('div.second', context, 60);
 
Y2.util.Dom.setY('div.second', 60);
Y2.util.Dom.setY('div.second', context, 60);
 
Y2.util.Dom.setXY('div.second', [120,120]);
Y2.util.Dom.setXY('div.second', context, [120,120]);

setXAll, setYAll, setXYAll

Sets the horizontal placement (X), vertical placement (Y), or both (XY) of all matched elements

// returns void
Y2.util.Dom.setXAll('div.second', 60);
Y2.util.Dom.setXAll('div.second', context, 60);
 
Y2.util.Dom.setYAll('div.second', 60);
Y2.util.Dom.setYAll('div.second', context, 60);
 
Y2.util.Dom.setXYAll('div.second', [120,120]);
Y2.util.Dom.setXYAll('div.second', context, [120,120]);

getX, getY, getXY

Gets the horizontal placement (X), vertical placement (Y), or both (XY) of the first matched element

// returns Integer
Y2.util.Dom.getX('div.second');
Y2.util.Dom.getX('div.second', context);
 
Y2.util.Dom.getY('div.second');
Y2.util.Dom.getY('div.second', context);
 
Y2.util.Dom.getXY('div.second');
Y2.util.Dom.getXY('div.second', context);

getXAll, getYAll, getXYAll

Gets the horizontal placement (X), vertical placement (Y), or both (XY) of all matched elements

// returns Array of Integers
Y2.util.Dom.getXAll('div.second');
Y2.util.Dom.getXAll('div.second', context);
 
Y2.util.Dom.getYAll('div.second');
Y2.util.Dom.getYAll('div.second', context);
 
Y2.util.Dom.getXYAll('div.second');
Y2.util.Dom.getXYAll('div.second', context);

inDocument

Find out whether the first matched element is in the current document

// returns Boolean
Y2.util.Dom.inDocument('div.second');
Y2.util.Dom.inDocument('div.second', context);

insertAfter

Take the first matched node of the first selector and insert after the first matched node of the second selector

// Note that this function handles context nodes on the first or second selectors, both, or none.
// returns the moved HTMLElement
Y2.util.Dom.insertAfter('div.third','div.fourth');
Y2.util.Dom.insertAfter('div.third', context,'div.fourth');
Y2.util.Dom.insertAfter('div.third', 'div.fourth', context);
Y2.util.Dom.insertAfter('div.third', context,'div.fourth', context);

insertBefore

Take the first matched node of the first selector and insert before the first matched node of the second selector

// Note that this function handles context nodes on the first or second selectors, both, or none.
// returns the moved HTMLElement
Y2.util.Dom.insertBefore('div.third','div.fourth');
Y2.util.Dom.insertBefore('div.third', context,'div.fourth');
Y2.util.Dom.insertBefore('div.third','div.fourth', context);
Y2.util.Dom.insertBefore('div.third', context,'div.fourth', context);

isAncestor

Find out whether the first matched node of the first selector is an ancestor of the first matched node of the second selector.

// Note that this function handles context nodes on the first or second selectors, both, or none.
// return Boolean
Y2.util.Dom.isAncestor('div.second','b#theFirstB');
Y2.util.Dom.isAncestor('div.second', context,'b#theFirstB');
Y2.util.Dom.isAncestor('div.second','b#theFirstB', context);
Y2.util.Dom.isAncestor('div.second', context,'b#theFirstB', context);

(Documentation is a bitch!)

Additional Information

• Run the test document. (Might convert this to YUI Test framework if there is enough interest in this extension)

The DOM. Arch-nemesis of web developers attempting to support the ultimately tiny (I think it’s down to about 5 or 8% now?) sliver of browser market share that Internet Explorer currently entails. Let’s make it easier on ourselves and make a little package to do it for us. Run a function, pass in an argument with a description of the DOM node(s) we wish to create, and have the package auto-correct any bugs we would have encountered during manual creation, and maybe even have it inserted or appended for us.

But wait, why are we doing this when there are literally 80 billion other DOM element creation classes already out there? It’s all about syntax. The existing packages are incredibly verbose, focusing too much on a complex object structure to describe the nodes, in some cases even having separate objects for attributes inside a single node. Why not use the syntax we’ve already come to love in the various DOM query libraries that are available? Why not use DOMDom? Let’s see a few examples:

Single Node String

'div'

<div></div>

Single Node String with ID and Classes

'div#id1.class1.class2'

<div id="id1" class="class1 class2"></div>

Single Node String for a Form Element

'input[name="myTextBox",type="text",maxlength="5"]'

<input name="myTextBox" maxlength="5" type="text"/>

Single Node String with Style Syntax

'div{height=80px,color=#f90,border=1px solid #000}'

<div style="border: 1px solid #000; height: 80px; color: #f90"></div>

Complex Single Node String with ID, multiple classes, Style, and Namespaced Attribute)

'div#id1.class1.class2[style="width:60px;color:#f90",@class="class4",@att="true",@namespace:att="false"]'

<div id="id1" att="true" namespace:att="false" class="class1 class2 class4" style="width: 60px; color: #f90;"></div>

Multiple Node String: Linear (Parents with one Child)

'div span div'

<div>
     <span>
          <div></div>
     </span>
</div>

Multiple Node String: Non-Linear (Parent with more than one Child)

{ 'div': [ 'span', 'span' ] }

<div>
     <span></span>
     <span></span>
</div>

How Does It Work?

By default, it’s set up to do HTML Fragments (innerHTML) because they are much speedier than the manual DOM element creation (createElement). But if you desire, you can toggle a boolean in the code and it will switch back to DOM element creation. When in DOM element creation mode, it will account for the following browser bugs:

• (IE6) Standardized for attribute representation (pointer to htmlFor)
• (IE6) Standardized case for accesskey, usemap, maxlength, and frameborder attributes.
• (IE6) Standardized checked attribute for radio and checkboxes.
• (IE6) Special consideration for dynamic handling of name and type attributes (on form elements).
• (Firefox) Works with whitespace that is treated as a node.

Syntax

You should already be able to tell how to create a node from the examples above. Here are some more things you might not have guessed:

Creating a node with an id

'div#myId'

Creating a node with CSS classes

'div.class1.class2'

Creating two nodes at the same level

[ 'div', 'div' ]

Creating a node with two children

{ 'div': [ 'div', 'div' ] }

You can mix the {} and [] syntax wherever you like, but if you want a node to have non-linear children, you have to use the {} object notation.

Creating a text node (start the node declaration with a #, you can change this to another non-conflicting character in the code if you like)

'#Any Text Here'

Creating a node with attributes (the @ is optional)

'div[class="class3",style="width:60px;color:#f90",@att="true",@namespace:att="false"]'

Creating a node with a Style Shortcut (mixing with a style attribute is handled properly)

'div{color=#f90,border=1px solid #000}[style="height:80px;background:#fff"]'

A few notes on attributes. Quotes are required on attributes (single or double but be consistent), but are not required in the style shortcut declaration. Quotes are not allowed to be nested inside of attributes (a single quote cannot be inside of a double quote and vice versa).

And of course, all of the above can be mixed together

'div#myId.class1.class2{color=#f90}[customAttr="true",@customAttr2="false"] div#child1 div#child2'

Usage

Appending at the end of a parent’s children:

DOMDom.append( 'div', yourParentNode );

Replacing the children of a parent:

DOMDom.replace( 'div', yourParentNode );

Unshifting (inserting at the beginning of a parent’s children):

DOMDom.unshift( 'div', yourParentNode );

Inserting before a certain integer index of a parent’s children:

DOMDom.insert( 'div', yourParentNode, 2 ); // must have at least 3 children, the index is 0 based, if index is null with unshift by default

Templates

Use <$var> to indicate a variable, in this example <$test>


// "Compile" the template
var str = DOMDom.compile( { 'div.test span': '#Test <$test>' } );

// Use your template in some context, notice the test variable being set.
for( var j = 0; j < 1000; j++ )
{
// knows we're using a compiled template since we're passing in variables as a third argument.
DOMDom.append( str, d, { test: j } );
}


Benchmarks

(If you have Firebug open, make sure it's not on the HTML tab, this will slow down the benchmark significantly)

Most of my work here has been inspired by the DomQuery and DomHelper classes written by JavaScript rock star Jack Slocum (the guy's initials are J.S. for God's sake), so I modeled my benchmark after his benchmark hosted on his website to test the DomHelper class. I'm running the same nodes he's testing on his website, so the results should be comparable. You can test my benchmark for DOMDom here. Here are some results, reporting the average of 3 results with the format of an uncompiled element first and the compiled template in square brackets.

DOMDom Results

Internet Explorer 6: 666 ms [328 ms]
Firefox 2.0.0.4: 1880 ms [666 ms]
Safari 3.0.2 [Windows]: 546 ms [151 ms]
Opera 9.21: 343 ms [140 ms]

Comparative numbers from Jack Slocum's DomHelper

Internet Explorer 6: 2458 ms [677 ms]
Firefox 2.0.0.4: 672 ms [458 ms]
Safari 3.0.2 [Windows]: 291 ms [119 ms]
Opera 9.21: 370 ms [166 ms]

The thing to take away from this is the question of why Satan is haunting my benchmarks? Two 666 averages? Anyway, DOMDom is quite a bit faster in the most popular browser, Internet Explorer, although I haven't tested it on IE7 yet. In Firefox, the opposite is true, with DomHelper taking the lead. Opera is comparable and Safari is faster in DomHelper as well. You can run your own tests using the links above.

Dependencies

This library was built to work with Yahoo User Interface (YUI), but could be trivially ported to another library by changing the function dependencies listed in the ADAPTER variable in the code.

var ADAPTER = {
	setStyle: YAHOO.util.Dom.setStyle,
	addClass: YAHOO.util.Dom.addClass,
	isString: YAHOO.lang.isString,
	isArray: YAHOO.lang.isArray,
	isNumber: YAHOO.lang.isNumber,
	isObject: YAHOO.lang.isObject,
	get: YAHOO.util.Dom.get
}; // to port, change these references

If you're still reading this encyclopedia, here are some links:

• DOWNLOAD DOMDom
• DOWNLOAD DOMDom Minimized with JSMIN (10KB)
• DOWNLOAD DOMDom Minimized with Packer (6KB)
• See the benchmark
• See the test file with a bunch of examples of syntax

-dom suffix denoting condition or state, as in freedom, wisdom, or DOMDom

Update: changed the variable syntax to allow variables inside of nodes (not just text).