$dom is a tiny Javascript library for selecting, traversing and animating DOM elements.
This project is in beta testing phase:
$dom.create( selector, document )
for creating DOM nodes from CSS selectors.$dom.style(elm, "width")
in IE.Copyright (c) 2009, 2010, 2011 Keith Clark
Copyright 2011 Julien Wajsberg
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
$dom.onready( function )
Nothing
This method will execute the passed function as soon as the DOM is ready. If you call this method multiple times each function will be queued and executed in the order they were added.
<html> <head> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { $dom.style( document.body, "background-color", "#ffff00" ); }); </script> </head> <body> <h1>Test of $dom.onready</h1> </body> </html>
var results = $dom.get( query [, document] )
document
object to use as the start point - useful for working inside iframes.Array of elements
.
This method will return all elements in passed document matching the passed query. If no document is passed the the current document will be used. If no query is passed, all elements are returned.
div
#myid
.class1
.class1.class2
div p
div > p
div ~ p
div + p
var nodes = $dom.get(); var nodes = $dom.get( "#test" ); var nodes = $dom.get( "div#test.panel.main" ); var nodes = $dom.get( "h1 ~ p" ); var nodes = $dom.get( "a.external", frames["testframe"].contentDocument.document );
<html> <head> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find links one level deep in the nav bar var links = $dom.get("#nav > li > a"); // style the links for (var c=0; c<links.length; c++) { $dom.style( links[c], "border", "1px solid #ff0000" ); } }); </script> </head> <body> <ul id="nav"> <li><a href="page1.html">Page 1</a></li> <li><a href="page2.html">Page 2</a></li> <li><a href="page3.html">Page 3</a> <ul> <li><a href="subpage1.html">Sub Page 1</a></li> <li><a href="subpage2.html">Sub Page 2</a></li> </ul> </li> </ul> </body> </html>
var results = $dom.descendants( element [, query] )
element
to use as the start point.Array of element
.
This function searches all the descendant nodes of the passed element. If a selector query is passed then only descendants matching this query will be returned. If no matches are found an empty array is returned.
div
#myid
.class1
.class1.class2
div p
div > p
div ~ p
div + p
var nodes = $dom.descendants( document.body, "#test" ); var nodes = $dom.descendants( document.body, "div#test.panel.main" ); var nodes = $dom.descendants( document.body, "> div" ); var nodes = $dom.descendants( document.body, "div#content ~ div.panel" ); var nodes = $dom.descendants( document.body, "div.tabs > ul ~ .tab" ); var nodes = $dom.descendants( document.body, "#content > ul > li" ); var nodes = $dom.descendants( document.body, "body h1 + p" ); var nodes = $dom.descendants( $dom.get("#content")[0], "> div > h1.main" ); var nodes = $dom.descendants( document.body );
<html> <head> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find the first UL tag var ul = $dom.get("ul")[0]; // find all descendant links var links = $dom.descendants(ul, "a"); // style the links for (var c=0; c<links.length; c++) { $dom.style( links[c], "border", "1px solid #ff0000" ); } // find immediate descendant links var links = $dom.descendants(ul, "> li > a"); // style the links for (var c=0; c<links.length; c++) { $dom.style( links[c], "background-color", "#ffff00" ); } }); </script> </head> <body> <p>This is a <a href="home.html">Link</a>.</p> <ul> <li><a href="page1.html">Page 1</a></li> <li><a href="page2.html">Page 2</a></li> <li><a href="page3.html">Page 3</a> <ul> <li><a href="subpage1.html">Sub Page 1</a></li> <li><a href="subpage2.html">Sub Page 2</a></li> </ul> </li> </ul> </body> </html>
var results = $dom.first( element [, query] )
element
to use as the start point.Returns a single element
or null
This function searches all the sibling nodes that preceed the passed element looking for the first
element that matches the passed query. If a query is not passed passed then the first sibling element will
be returned. If no matches are found an then null
is returned.
div
#myid
.class1
.class1.class2
var node = $dom.first( document.body, "head" ); var node = $dom.first( $dom.get("li")[4], "li" ); var node = $dom.first( $dom.get("li") );
<html> <head> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find the first UL tag var middleLI = $dom.get("li")[2]; // find the first sibling LI and style it var firstLI = $dom.first( middleLI, "li" ); $dom.style( firstLI, "border", "1px solid #ff0000" ); // find the first sibling LI with a class of test and style it var firstLI = $dom.first( middleLI, "li.test" ); $dom.style( firstLI, "border", "1px solid #0000ff" ); }) </script> </head> <body> <ul> <li><a href="page1.html">Page 1</a></li> <li class="test"><a href="page2.html">Page 2</a></li> <li class="test"><a href="page3.html">Page 3</a></li> <li class="test"><a href="page4.html">Page 4</a></li> <li><a href="page5.html">Page 5</a></li> </ul> </body> </html>
var results = $dom.last( element [, query] )
element
to use as the start point.Returns a single element
or null
This function searches all the sibling nodes that follow the passed element looking for the last
element that matches the passed query. If no query is specified then the last sibling element will
be returned. If no matches are found an then null
is returned.
div
#myid
.class1
.class1.class2
var node = $dom.last( $dom.get("li")[4], "li" ); var node = $dom.last( $dom.get("li") );
<html> <head> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find the first UL tag var middleLI = $dom.get("li")[2] // find the first sibling LI and style it var lastLI = $dom.last( middleLI, "li" ); $dom.style( lastLI, "border", "1px solid #ff0000" ); // find the first sibling LI with a class of test and style it var lastLI = $dom.last( middleLI, "li.test" ); $dom.style( lastLI, "border", "1px solid #0000ff" ); }) </script> </head> <body> <ul> <li><a href="page1.html">Page 1</a></li> <li class="test"><a href="page2.html">Page 2</a></li> <li class="test"><a href="page3.html">Page 3</a></li> <li class="test"><a href="page4.html">Page 4</a></li> <li><a href="page5.html">Page 5</a></li> </ul> </body> </html>
var results = $dom.next( element [, query] )
element
to use as the start point.Returns a single element
or null
This function searches all the sibling nodes that follow the passed element looking for an
element that matches the passed query. If a query is not passed passed then the next element will
be returned. If no matches are found an then null
is returned.
div
#myid
.class1
.class1.class2
var node = $dom.next( $dom.get("li")[0], "li" ); var node = $dom.next( $dom.get("li")[0] );
<html> <head> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find the first UL tag var firstLI = $dom.get("li")[0]; // find the next sibling LI and style it var nextLI = $dom.next( firstLI, "li" ); $dom.style( nextLI, "border", "1px solid #ff0000" ); // find the next sibling LI with a class of test and style it var nextLI = $dom.next( firstLI, "li.test" ); $dom.style( nextLI, "border", "1px solid #0000ff" ); }) </script> </head> <body> <ul> <li><a href="page1.html">Page 1</a></li> <li><a href="page2.html">Page 2</a></li> <li class="test"><a href="page3.html">Page 3</a></li> <li class="test"><a href="page4.html">Page 4</a></li> <li class="test"><a href="page5.html">Page 5</a></li> </ul> </body> </html>
var results = $dom.previous( element [, query] )
element
to use as the start point.Returns a single element
or null
This function searches all the sibling nodes that preceed the passed element looking for an
element that matches the passed query. If a query is not passed passed then the previous element will
be returned. If no matches are found an then null
is returned.
div
#myid
.class1
.class1.class2
var node = $dom.previous( document.body, "head" ); var node = $dom.previous( $dom.get("li")[4], "li" ); var node = $dom.previous( $dom.get("p") );
<html> <head> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find the first UL tag var middleLI = $dom.get("li")[2]; // find the first sibling LI and style it var previousLI = $dom.previous( middleLI, "li" ); $dom.style( previousLI, "border", "1px solid #ff0000" ); // find the first sibling LI with a class of test and style it var previousLI = $dom.previous( middleLI, "li.test" ); $dom.style( previousLI, "border", "1px solid #0000ff" ); }) </script> </head> <body> <ul> <li class="test"><a href="page1.html">Page 1</a></li> <li><a href="page2.html">Page 2</a></li> <li><a href="page3.html">Page 3</a></li> <li><a href="page4.html">Page 4</a></li> <li class="test"><a href="page5.html">Page 5</a></li> </ul> </body> </html>
styleValue = $dom.style( element, styleName )
$dom.style( element, styleName, styleValue )
or...
$dom.style( element, styles )
When reading an elements style a string
is returned otherwise nothing is returned.
This method is used to get and set style values for the specified element. If a propertyName is passed without a propertyValue then the resulting property value will be returned. If a propertyValue is passed with a propertyValue then the property will be set to the passed value.
It's possible to set mutiple properties in one statement by passing them as in object notation form:
{ "background-color": "#ff0000", color: "#ffff00", opacity: 0.5 }
So, the following statement:
$dom.style( elm, {"background-color": "#ff0000", color: "#ffff00", opacity: 0.5 })
Is equivilent to:
$dom.style( elm, "background-color", "#ff0000"); $dom.style( elm, "color", "#ffff00"); $dom.style( elm, "opacity", 0.5);
var bgColor = $dom.style( document.body, "background-color"); $dom.style( document.body, "background-color", "#ffcc00" ); $dom.style( document.body, {"background-color": "#ffcc00", "color": "#000", "font-family": "Arial" } );
<html> <head> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find all links var links = $dom.get("a"); // add mouse events to the links for (var c=0; c<links.length; c++) { links[c].onmouseover = function () { $dom.style( this, {"background-color": "#ffcc00", color:"#000"} ); } links[c].onmouseout = function () { $dom.style( this, {"background-color": "", color:""} ); } } }) </script> </head> <body> <ul> <li><a href="page1.html">Page 1</a></li> <li><a href="page2.html">Page 2</a></li> <li><a href="page3.html">Page 3</a></li> <li><a href="page4.html">Page 4</a></li> <li><a href="page5.html">Page 5</a></li> </ul> </body> </html>
$dom.addClass( element, className )
Nothing
This method will add the passed className to the specified elements class
attribute.
<html> <head> <style type="text/css"> .hover { background-color: #00ff00; } </style> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find all links var links = $dom.get("a"); // add mouse events to the links for (var c=0; c<links.length; c++) { links[c].onmouseover = function () { $dom.addClass( this, "hover" ); } links[c].onmouseout = function () { $dom.removeClass( this, "hover" ); } } }) </script> </head> <body> <p>Hover over each link to toggle its class:</p> <ul> <li><a href="page1.html">Page 1</a></li> <li><a href="page2.html">Page 2</a></li> <li><a href="page3.html">Page 3</a></li> <li><a href="page4.html">Page 4</a></li> <li><a href="page5.html">Page 5</a></li> </ul> </body> </html>
$dom.removeClass( element, className )
Nothing
This method will remove the passed className from the specified elements class
attribute.
<html> <head> <style type="text/css"> .hover { background-color: #00ff00; } </style> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find all links var links = $dom.get("a"); // add mouse events to the links for (var c=0; c<links.length; c++) { links[c].onmouseover = function () { $dom.addClass( this, "hover" ); } links[c].onmouseout = function () { $dom.removeClass( this, "hover" ); } } }) </script> </head> <body> <p>Hover over each link to toggle its class:</p> <ul> <li><a href="page1.html">Page 1</a></li> <li><a href="page2.html">Page 2</a></li> <li><a href="page3.html">Page 3</a></li> <li><a href="page4.html">Page 4</a></li> <li><a href="page5.html">Page 5</a></li> </ul> </body> </html>
$dom.toggleClass( element, className, classOn )
Nothing
This method will add or remove the passed className from the specified elements class
attribute. If classOn
evaluates to true
then the className will be added, otherwise it will be removed.
<html> <head> <style type="text/css"> .on { background-color: #00ff00; } </style> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find all links var links = $dom.get("a"); // add mouse events to the links for (var c=0; c<links.length; c++) { links[c].onclick = function () { $dom.toggleClass( this, "on", !$dom.hasClass(this, "on") ); } } }) </script> </head> <body> <p>Click each link to toggle its class:</p> <ul> <li><a href="#">Page 1</a></li> <li><a href="#">Page 2</a></li> <li><a href="#">Page 3</a></li> <li><a href="#">Page 4</a></li> <li><a href="#">Page 5</a></li> </ul> </body> </html>
$dom.hasClass( element, className )
Boolean
This method checks the specified elements class
attribute for the passed
className. If className is found then true
is returned otherwise
false
is returned.
<html> <head> <style type="text/css"> .on { background-color: #00ff00; } </style> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // find all links var links = $dom.get("a"); // add mouse events to the links for (var c=0; c<links.length; c++) { links[c].onclick = function () { $dom.toggleClass( this, "on", !$dom.hasClass(this, "on") ); } } }) </script> </head> <body> <p>Click each link to toggle its class:</p> <ul> <li><a href="#">Page 1</a></li> <li><a href="#">Page 2</a></li> <li><a href="#">Page 3</a></li> <li><a href="#">Page 4</a></li> <li><a href="#">Page 5</a></li> </ul> </body> </html>
$dom.transform( element, styles[, duration, callback] )
isTransforming = $dom.transform( element )
When testing for a transformation isTransforming is a boolean
value otherwise nothing is returned.
This method transforms the specified elements CSS propeties until they match those passed in the styles parameter. The transformation occurs smoothly over the specifed duration.
Once an element has finished it's transformation or if $dom.transform
is called on an element
that is already animating the optional callback method is called.
If a callback method is specified it will be called whenever a transformation ends. The method will
be passed two parameters, the first is a boolean value used to determine if the animation completed (true
)
or if it was cancelled (false
). The second parameter is the element that was being animated.
function( isComplete, elm ) { if (!isComplete) { alert("Animation Cancelled!") } else { alert("Animation Complete!") } }
<html> <head> <style type="text/css"> #panel { width: 150px; background-color: #fd0; border: 1px solid #f00; line-height: 100px; text-align: center; } </style> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { var panel = $dom.get("#panel")[0]; panel.onclick = function() { $dom.transform( this, { width: "300px", "border-width": "5px", "line-height": "300px", "opacity": 0.5 }, 500 ) } }) </script> </head> <body> <div id="panel">Click me!</div> </body> </html>
<html> <head> <style type="text/css"> #panel { width: 150px; background-color: #fd0; border: 1px solid #f00; line-height: 100px; text-align: center; } </style> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { var panel = $dom.get("#panel")[0]; panel.onclick = function() { $dom.transform( this, { width: "300px", "border-width": "5px", "line-height": "300px", "opacity": 0.5 }, 500, function(isComplete, elm) { if (isComplete) { alert("finished"); } } ) } }) </script> </head> <body> <div id="panel">Click me!</div> </body> </html>
ancestorElement = $dom.ancestor( element [, query] )
element
to start from.Returns a single element
or null
This function searches for the nearest ancestor of the passed element matching the passed query.
If a query is not passed then the elements immediate parent is returned. If no matches were found null
is returned.
div
#myid
.class1
.class1.class2
<head> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { // select all links var links = $dom.get("a"); // get the first link var firstLink = links[0]; // find the immediate ancestor var liElement = $dom.ancestor( firstLink ); // find the UL ancestor var ulElement = $dom.ancestor( firstLink, "ul" ); // style the ancestors $dom.style( liElement, "border", "1px solid #ff0000" ); $dom.style( ulElement, "border", "1px solid #33ff33" ); }); </script> </head> <body> <ul> <li><a href="page1.html">Page 1</a></li> <li><a href="page2.html">Page 2</a></li> <li><a href="page3.html">Page 3</a></li> </ul> </body>
$dom.create( selector [, document] )
document
to create the object in - useful for working inside iframes.A DOM node
This method will create a new DOM element based on the passed selector. A tag name must always be passed but an optional ID and class list can also be defined,.
div
#myid
.class1
.class1.class2
var node = $dom.create( "div" ); var node = $dom.create( "div#test" ); var node = $dom.create( "div.alt" ); var node = $dom.create( "div#test.alt" ); var node = $dom.create( "div#test.alt.more" );
<html> <head> <style type="text/css"> .panel { width: 150px; height: 100px; border: 2px solid #000; } .red { background: #f00 } .blue { background: #00f; } </style> <script type="text/javascript" src="$dom.js"></script> <script type="text/javascript"> $dom.onready( function() { document.body.appendChild( $dom.create( "div.panel.red" ) ); document.body.appendChild( $dom.create( "div.panel.blue" ) ); }); </script> </head> <body> <h1>Test of $dom.onready</h1> </body> </html>