$dom Javascript library v0.9.3 documentation

Overview

General

DOM Traversal

CSS / Animation

Welcome to the $dom documentation

Overview

$dom is a tiny Javascript library for selecting, traversing and animating DOM elements.

Notes

This project is in beta testing phase:

Change log

v0.9.2b

v0.9.3

v0.9.1b

v0.9b

License

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

Syntax

$dom.onready( function )

Parameters

function
A function reference.

Return Value

Nothing

Notes

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.

Examples

Working example

<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>		

$dom.get

Syntax

var results = $dom.get( query [, document] )

Parameters

query [optional]
A selector string
document [optional]
A document object to use as the start point - useful for working inside iframes.

Return Value

Array of elements.

Notes

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.

Supported selector formats

div
Type selector
#myid
ID selector
.class1
Class selector
.class1.class2
Multipe class selector

Supported combinator formats

div p
Descendant combinator - matches all descendants of the current selector.
div > p
Child combinator - matches the immediate children of the current selector.
div ~ p
General sibling combinator - matches all siblings following the current selector.
div + p
Adjacent sibling combinator - matches the sibling that immediately follows the current selector.

Examples

Syntax examples

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 );

Working example

<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>		

$dom.descendants

Syntax

var results = $dom.descendants( element [, query] )

Parameters

element
A element to use as the start point.
query [Optional]
A selector string.

Return Value

Array of element.

Notes

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.

Supported selector formats

div
Type selector
#myid
ID selector
.class1
Class selector
.class1.class2
Multipe class selector

Supported combinator formats

div p
Descendant combinator - matches all descendants of the current selector.
div > p
Child combinator - matches the immediate children of the current selector.
div ~ p
General sibling combinator - matches all siblings following the current selector.
div + p
Adjacent sibling combinator - matches the sibling that immediately follows the current selector.

Examples

Syntax examples

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 );

Working example

<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>		

$dom.first

Syntax

var results = $dom.first( element [, query] )

Parameters

element
A element to use as the start point.
query [Optional]
The selector string of the first sibling element you wish to find.

Return Value

Returns a single element or null

Notes

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.

Supported selector formats

div
Type selector
#myid
ID selector
.class1
Class selector
.class1.class2
Multipe class selector

Examples

Syntax examples

var node = $dom.first( document.body, "head" );
var node = $dom.first( $dom.get("li")[4], "li" );
var node = $dom.first( $dom.get("li") );

Working example

<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>

$dom.last

Syntax

var results = $dom.last( element [, query] )

Parameters

element
A element to use as the start point.
query [Optional]
The selector string of the last sibling element you wish to find.

Return Value

Returns a single element or null

Notes

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.

Supported selector formats

div
Type selector
#myid
ID selector
.class1
Class selector
.class1.class2
Multipe class selector

Examples

Syntax examples

var node = $dom.last( $dom.get("li")[4], "li" );
var node = $dom.last( $dom.get("li") );

Working example

<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>

$dom.next

Syntax

var results = $dom.next( element [, query] )

Parameters

element
A element to use as the start point.
query [Optional]
The selector string of the next sibling element you wish to find.

Return Value

Returns a single element or null

Notes

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.

Supported selector formats

div
Type selector
#myid
ID selector
.class1
Class selector
.class1.class2
Multipe class selector

Examples

Syntax examples

var node = $dom.next( $dom.get("li")[0], "li" );
var node = $dom.next( $dom.get("li")[0] );

Working example

<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>

$dom.previous

Syntax

var results = $dom.previous( element [, query] )

Parameters

element
A element to use as the start point.
query [Optional]
The selector string of the sibling element you wish to find.

Return Value

Returns a single element or null

Notes

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.

Supported selector formats

div
Type selector
#myid
ID selector
.class1
Class selector
.class1.class2
Multipe class selector

Examples

Syntax examples

var node = $dom.previous( document.body, "head" );
var node = $dom.previous( $dom.get("li")[4], "li" );
var node = $dom.previous( $dom.get("p") );

Working example

<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>

$dom.style

Syntax

To read a style value

styleValue = $dom.style( element, styleName )

To set a style value

$dom.style( element, styleName, styleValue )

or...

$dom.style( element, styles )

Parameters

element
The element to get/set style of.
propertyName
The CSS name of the property to get/set (i.e. "background-color", "font-family").
propertyValue
The value to apply to the property.
styles
An style object to apply (see notes).

Return Value

When reading an elements style a string is returned otherwise nothing is returned.

Notes

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.

Setting multiple properties

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);

Examples

Syntax examples

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" } );

Working example

<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

Syntax

$dom.addClass( element, className )

Parameters

element
The element to add the class to.
className
The class name to add.

Return Value

Nothing

Notes

This method will add the passed className to the specified elements class attribute.

Examples

<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

Syntax

$dom.removeClass( element, className )

Parameters

element
The element to remove the class from.
className
The class name to remove.

Return Value

Nothing

Notes

This method will remove the passed className from the specified elements class attribute.

Examples

<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

Syntax

$dom.toggleClass( element, className, classOn )

Parameters

element
The element to toggle.
className
String - The class name to toggle.
classOn
Boolean - Used to determine if the class is added or removed.

Return Value

Nothing

Notes

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.

Examples

<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

Syntax

$dom.hasClass( element, className )

Parameters

element
The element to check.
className
String - The class name to test for.

Return Value

Boolean

Notes

This method checks the specified elements class attribute for the passed className. If className is found then true is returned otherwise false is returned.

Examples

<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

Syntax

To perform a transform

$dom.transform( element, styles[, duration, callback] )

To test if an element is transforming

isTransforming = $dom.transform( element )

Parameters

element
The element to check.
styles
Object - The styles you wish to animate.
duration [Optional]
Integer - Period of the transition (in milliseconds).
callback [Optional]
Function - A function that will be called on completion/stopping of the animation.

Return Value

When testing for a transformation isTransforming is a boolean value otherwise nothing is returned.

Notes

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.

Using the callback method

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!")
	}
}		

Examples

Working example

<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>

Working example with callback

<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>

$dom.ancestor

Syntax

ancestorElement = $dom.ancestor( element [, query] )

Parameters

element
The element to start from.
query [Optional]
The selector string of the ancestor element you wish to find.

Return Value

Returns a single element or null

Notes

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.

Supported selector formats

div
Type selector
#myid
ID selector
.class1
Class selector
.class1.class2
Multipe class selector

Examples

<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

Syntax

$dom.create( selector [, document] )

Parameters

selector
A simple selector string
document [optional]
The document to create the object in - useful for working inside iframes.

Return Value

A DOM node

Notes

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,.

Supported selector formats

div
Type selector
#myid
ID selector
.class1
Class selector
.class1.class2
Multipe class selector

Examples

Syntax examples

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" );

Working example

<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>