Welcome to the $dom documentation

Overview

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

Notes

This project is made of different modules with different maturity:

Every software contains bugs. Even if it has been tested a lot, please report back any problem you would encounter.
Please tell me if you're using $dom in your project, I'd be very happy to know it.
More information can be found on the $dom page on github.

Change log

v0.9.2

project hosted on github
fixed a bug when the Array prototype was modified
fixed a bug where 'first' and 'last' were incorrect
Removed isIE variable -- now we do feature sniffing instead
Reorganized somewhat the code
resolved jshint error reports
now we compress with uglifyjs
added 'is', 'empty' functions
event object now has preventDefault and stopPropagation on IE
animation functions now use requestAnimationFrame on all supporting browsers
add unit testing (still incomplete)
add different flavors of the library
add a chaining API (à la jQuery) (consider beta quality)
add a debug flavor (still incomplete)
out of beta for the main library! Yay!

v0.9.1b

Added $dom.create( selector, document ) for creating DOM nodes from CSS selectors.
Fixed bug with $dom.style(elm, "width") in IE.
Recompressed with Googles closure compiler.
Updated documentation and fixed some typo's.

v0.9b

Initial release.

License

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.

Introduction to the chaining API

Syntax

$dom.Get("#id")
    .addClass("active")
    .append(
        $dom.Create("p.text")
            .text("lorem ipsum")
    );

Notes

Since version 0.9.2, $dom supports a chaining API. Basically, this API allows a more natural way to use the library, that was popularized by the famous jQuery library.

This API comes on top of the legacy API. This means that you can use both API at the same time. You can feed the chaining API with DOM elements that you got from the legacy API or native DOM functions.

The chaining API makes it also a lot easier to manipulate many elements in the same time. Of course, it is easier doesn't mean it performs well, you should always be aware of what really happens behind the curtain.

Nearly all functions of the legacy API are callable in a chaining context. The exceptions are:

$dom.get, $dom.create which are replaced by the factory methods with a capitalized letter: $dom.Get, $dom.Create and $dom.From. Of course, you can still use the legacy methods, which returns normal DOM Node objects.
$dom.onready because the use case of calling this on a DOM element is not so useful.
$dom.text has different semantics when called on a chaining object: it appends the string parameter as a text node. See the documentation for .text() for more informations.

Some useful functions in a chaining context were added:

.append() and .appendTo() to add elements to other elements
.dom() to get back the wrapped DOM objects
.size() to get the size of the collection
.each() to apply a function on all elements in the collection

$dom.Get or $dom.select

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

A $dom object wrapping an array of elements.

Notes

This method will return a $dom object wrapping 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.

The $dom object has all the methods of the chaining API.

Supported selector formats

div: Type selector
#myid: ID selector
.class1: Class selector
.class1.class2: Multipe class selector
#id.class2: ID and 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");
// Get and select are synonyms
var $nodes = $dom.select("h1 ~ p");
var $nodes = $dom.select("a.external", frames["testframe"].contentDocument.document);

Working example

<html>
<head>
	<script type="text/javascript" src="dollardom.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
			$links.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.From or $dom.from

Syntax

var results = $dom.From( element )

Parameters

element: A DOM element or an array of DOM elements

Return Value

A $dom object wrapping the element or elements that were passed to the method.

Notes

The $dom object has all the methods of the chaining API.

Examples

Syntax examples

var $nodes = $dom.From(document.getElementById('test'));

$dom.Create or $dom.element

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 object wrapping 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
div#myid: ID selector
div.class1: Class selector
div.class1.class2: Multipe class selector
div#id.class2: ID and Class selector

Examples

Syntax examples

var node = $dom.Create( "div" );
var node = $dom.Create( "div#test" );
// Create and element are synonyms
var node = $dom.element( "div.alt" );
var node = $dom.element( "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="dollardom.js"></script>
	<script type="text/javascript">
		$dom.onready( function() {
			$dom.Create("div.panel.red").appendTo(document.body);
			$dom.From(document.body).append($dom.Create("div.panel.blue"));
		});
	</script>
</head>

<body>
	<h1>Test of $dom.Create</h1>
</body>
</html>

.append

Syntax

var $nodes = domObject.append( element )

Parameters

element: A $dom Object, a DOM element or an array of DOM elements

Return Value

The $dom object itself.

Example

Syntax example

$dom.Get("#id-list").append($dom.create("div.panel.red"));

.appendTo

Syntax

var $nodes = domObject.appendTo( element )

Parameters

element: A $dom Object or a DOM element

Return Value

The $dom object itself.

Examples

Syntax examples

$dom.Create("div.panel.red").appendTo(document.body);
$dom.Create("div.panel.blue").appendTo($dom.get("#id-list"));
$dom.Create("div.panel.green").appendTo(document.getElementById('id-list'));

.dom

Syntax

var nodes = domObject.dom( [ index ] )

Parameters

index [optional]: Index in the internal list of the element to be returned. The first item has index 0.

Return Value

Either the complete array of wrapped DOM elements, or only one if index is given.

If index is greater or equal to the number of elements, then it returns undefined.

Examples

Syntax examples

var nodes = $dom.Get("a").dom();
var firstLink = $dom.Get("a").dom(0);

.each

Syntax

var $nodes = domObject.each( func )

Parameters

func: This function will be applied to each item in the internal array. This function must take an argument which will be the DOM element.

Return Value

The $dom object.

Notes

Depending on the browser, the function can get extra parameters. You should not depend on these parameters as your code won't be cross browser anymore.

Example

Syntax example

$dom.Get("a").each(function(elt) {
	// do something with DOM element elt
});

.size

Syntax

var size = domObject.size()

Return Value

The total number of elements wrapped in the $dom object.

Examples

Syntax examples

var numberOfLinks = $dom.Get("a").size();

.text

Syntax

var $nodes = domObject.text( string )

Parameters

string: This text will be added as a text node to the elements represented by the $dom object.

Return Value

The $dom object.

Notes

It is important to use this method if you know the content you want to append is text, especially if this text comes from user input.

Be careful because the method has not the same behaviour as the jQuery method of the same name, because it doesn't replace the content on the nodes. If you need this behaviour, just call empty before.

Examples

Syntax examples

$dom.Get("a").each(function(elt) {
	$dom.from(elt).text(" [" + elt.href + "]");
});

$dom.text

Syntax

var textNode = $dom.text( string )

Parameters

string: This text will be used to create a text node.

Return Value

A text node element containing the string.

Notes

It is important to use this method if you know the content you want to append is text, especially if this text comes from user input.

Examples

Syntax examples

var links = $dom.get("a");
for (var i = 0, l = links.length; i < l; i++) {
	var link = links[i];
	link.appendChild($dom.text(" [" + link.href + "]));
}

$dom.addEvent

Syntax

$dom.addEvent( element, event-name, function )

Parameters

element: The element where the event will be bound.
event-name: The event to be bound.
function: This function reference will be used as handler.

Return Value

Nothing

Notes

This method will bind the event event-name to the passed element. When this event will be fired, then the function function will be called with one argument: the Event object.

The Event object

This Event object is normalized for browsers who supports only attachEvent (which are Internet Explorer 8 and below):

preventDefault(): call this method to prevent the browser's default action, like following a link.
stopPropagation(): call this method so that this event's propagation will be stopped: no other handlers will be called for this event.
target: contains the DOM element that initiated the event.
currentTarget: contains the DOM element where the handler is bound.

The context this is equal to e.currentTarget.

It is common practice to return false from handler functions to prevent the browser defaul action or stop propagation. However, it is better to use the methods stopPropagation and preventDefault because:

your code is more readable
you can call them first, which means that if your code fails for a reason, it will still obey your wishes
you can decide to only stop propagation or prevent the default action, which you can't do with a return value

Event delegation

The technique known as event delegation is made possible by the way browsers handle DOM events. Basically, all DOM events go first by a capture phase (seldom used) from the root element of the page to the element that triggered the event, and then go back in a bubble phase to the root element.

Any element in the way (which means the element itself or any ancestor) can handle the event, and decide if the event should bubble higher (with stopPropagation).

This technique has several advantages:

If the same behaviour must be attached to the same set of elements, you can instead attach the event handler to an ancestor element. This means better performance.
You can attach the handler once at the startup of your application, even if the elements are not there yet. This means better performance too, and less code.

Combining $dom.addEvent with $dom.is makes it very easy to use event delegation:

$dom.addEvent(ancestor, 'click', function(e) {
	var target = e.target;
	e.preventDefault();

	if ($dom.is(target, 'a')) {
		doSomethingWith(target.href);
	}
});

Examples

Working example

<html>
<head>
	<script type="text/javascript" src="dollardom.js"></script>
	<script type="text/javascript">
		function handler(e) {
			
			if (e.target.href.search(/google/) !== -1) {
				e.preventDefault();
				alert("This link will not be followed !");
			}
		}
		
		$dom.onready( function() {
			var elt = $dom.get("#link")[0];
			$dom.addEvent(elt, "click", handler);
		});
	</script>
</head>

<body>
	<a id="link" href="http://www.google.fr/" >Link to Google</a>
</body>
</html>

$dom.removeEvent

Syntax

$dom.removeEvent( element, event-name, function )

Parameters

element: The element where the event will be unbound.
event-name: The event to be unbound.
function: This function reference that was used in a call to addEvent.

Return Value

Nothing

Notes

This method will remove a handler that was previously bound using addEvent.

$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="dollardom.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
#id.class2: ID and 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="dollardom.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.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
div#myid: ID selector
div.class1: Class selector
div.class1.class2: Multipe class selector
div#id.class2: ID and 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="dollardom.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.create</h1>
</body>
</html>

$dom.is

Syntax

$dom.is( element, selector )

Parameters

element: The element where the event will be bound.
selector: The selector to be tested.

Return Value

A boolean value, true if the element matches the selector.

Notes

Supported selector formats

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

Examples

Working example

<html>
<head>
	<script type="text/javascript" src="dollardom.js"></script>
	<script type="text/javascript">
			
		$dom.onready( function() {
			var elt = $dom.get("#google-link")[0];
			var hasClassLink = $dom.is(elt, ".link"); // should return true
		});

	</script>
</head>

<body>
	<a id="google-link" class='link' href="http://www.google.fr/" >Link to Google</a>
</body>
</html>

$dom.empty

Syntax

$dom.empty( element )

Parameters

element: The element to empty.

Return Value

Nothing

Notes

This method removes all the children of the passed element.

Example

Working example

<html>
<head>
	<script type="text/javascript" src="dollardom.js"></script>
	<script type="text/javascript">
		
		$dom.onready( function() {
			var elt = $dom.get("#link")[0];
			$dom.empty(elt);
		});
	</script>
</head>

<body>
	<div id="link" >
		<a href="http://www.google.fr/" >Link to Google</a>
	</div>
</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="dollardom.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="dollardom.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="dollardom.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="dollardom.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="dollardom.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="dollardom.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="dollardom.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="dollardom.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="dollardom.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="dollardom.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 (alias: $dom.animate)

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="dollardom.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="dollardom.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="dollardom.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 Javascript library v0.9.2b documentation

Overview

General

DOM Traversal

CSS / Animation

Chaining API

Welcome to the $dom documentation

Overview

Notes

Change log

v0.9.2

v0.9.1b

v0.9b

License

Introduction to the chaining API

Syntax

Notes

$dom.Get or $dom.select

Syntax

Parameters

Return Value

Notes

Supported selector formats

Supported combinator formats

Examples

Syntax examples

Working example

$dom.From or $dom.from

Syntax

Parameters

Return Value

Notes

Examples

Syntax examples

$dom.Create or $dom.element

Syntax

Parameters

Return Value

Notes

Supported selector formats

Examples

Syntax examples

Working example

.append

Syntax

Parameters

Return Value

Example

Syntax example

.appendTo

Syntax

Parameters

Return Value

Examples

Syntax examples

.dom

Syntax

Parameters

Return Value

Examples

Syntax examples

.each

Syntax

Parameters

Return Value

Notes

Example

Syntax example

.size

Syntax

Return Value

Examples

Syntax examples

.text

Syntax

Parameters

Return Value

Notes

Examples

Syntax examples