dom.js

This is the basic library. Can be considered a toolkit on its own, as it provides many useful functions and shortcuts.


Functions


$(element)

This function is very popular and appear in almost every JS framework available. It's purpose is to provide a shortcut for longer document.getElementById() function. So, basic usage is:

var object = $("some_id");
alert(object.tagName);

In this example, we assume that there is a HTML node with id "some_id". The $-function converts a string to the object. Note that it is perfectly correct to pass an object reference to $-function, although not very useful.

Due to presence of this function in toolkit, every other function that accepts node reference as argument can also accept its id.

$$(element)

See $v(element).

$v(element)

This function is identical to $$(). They are a shortucut for $().value. You should use them when getting a value of any form element.

Dom.create(tagName, [styleObj])

Used for dynamic creation of HTML nodes. Two parameters are accepted, the first one is mandatory. Example:

var myDiv = Dom.create("div"); var myStyledDiv = Dom.create("div", {color : "#f00", fontWeight : "bold"});

The second (optional) argument styleObj is an object of css properties. For a full list of them, see Mozilla documentation and MSDN. These properties are not the same for these browsers, so specifying a floating element looks like var element = Dom.create("div", {cssFloat:"left", styleFloat:"left"}); - the first declaration is for Gecko, the latter for MSIE.

Dom.text(text)

Creates and returns DOM text node with value of argument text.

Dom.option(name, value, [parent])

Creates and returns DOM <option> node with name of name and value of value. If parent is specified, this function also appends newly created node to that parent. Example:

var s = Dom.create("select"); Dom.option("apples",1,s); Dom.option("bananas",2,s); Dom.option("cherries",3,s);

Dom.hide(element)

Hides specified element by setting its style.visibility property.

Dom.show(element)

Unhides previously hidden element by setting its style.visibility to default value.

Dom.clear(element)

This function clears all child nodes from an element. May be called with either object reference as an argument, or a id-string. So, for instance:

Dom.clear("my_select_element");

removes all options from existing <select> element with id "my_select_element".

Dom.unlink(element)

Unlinks element from DOM tree. Notice that the element is not destroyed as long as it can be referenced.

Dom.isChild(child, parent)

Tests whether a child is a subnode of node parent. The depth is not important here.

Dom.hex2dec(hex_str)

Converts hexadecimal string hex_str to a decimal number. Example:

alert( Dom.hex2dec("fab") ); // 4011

Dom.color(str)

Returns an array of three elements, representing red, green and blue portion of color specified in str. Input should be a valid css color specification, i.e. #02bacf, #ba7 or rgb(150,5,102). Example:

var colors = Dom.color("#abc");
alert("Green part: "+colors[1]);

Dom.isClass(element, className)

HTML elements may be of multiple classes, this function returns true when at least one of element's classes is className. Example:

var div = Dom.create("div"); div.className = "big red fox"; alert( Dom.isClass(div,"fox"); ); // true

Dom.collide(element_1, element_2)

Tests whether two elements overlap. HTML elements have a rectangular shape, so this function basically tests whether intersection of element_1 and element_2 is nonempty.

Dom.attach(element, event, callback)

Attaches function specified with callback to event detected on element. The event is specified without the "on" prefix. Function reference callback will be called with one argument, the event object reference. Example:

Dom.attach("myDiv", "click", function() { alert("!"); });

Dom.detach(element, event, callback)

Removes attached callback from element fired with event. Note that only non-anonymous functions can be detached.

Dom.source(event)

Converts event to reference to element which fired it. This can be useful when multiple elements fire the same callback and one needs to know which element fired it. Example:

var callback = function(event) { var id = Dom.source(event).id; alert("Event fired by " + id); } var div = Dom.create("div"); div.id = "myDiv"; Dom.attach(div, "click", callback);

Dom.style(element, property)

Returns a style property of element. This is different from accessing the element.style.property value, as this function return computed style (i.e. set by stylesheets etc.) instead of a dynamically created one. Example:

var family = Dom.style("elementId", "fontFamily");
alert(family); // returns actual font-family for this element, wherever it is set

Dom.position(element)

Returns x and y coordinates of element's top left corner, relative to page's top left corner. Coordinates are returned in an array of two elements. To count this value, whole tree of offsetParents must be climbed up, so it is not wise to call this function too often. Example:

var coords = Dom.position(div);
alert("x: " + coords[0]+", y:" + coords[1]);

Dom.getLT(element)

Returns x and y coordinates of element's top left corner, relative to its offsetParent, in form of array with two elements.

Dom.getWH(element)

Returns width and height of element (in pixels), in form of array with two elements.

Dom.moveBy(element, dx, dy)

Moves element by dx pixels horizontally and dy pixels vertically.

Dom.resizeBy(element, dx, dy)

Resizes element by dx pixels horizontally and dy pixels vertically.