DOM Coercion Rules

In order of precedence, createDOM coerces given arguments to DOM nodes using the following rules:

1. Functions are called with a this of the parent node and their return value is subject to the following rules (even this one).
2. undefined and null are ignored.
3. Iterables (see MochiKit.Iter) are flattened (as if they were passed in-line as nodes) and each return value is subject to all of these rules.
4. Values that look like DOM nodes (objects with a .nodeType > 0) are .appendChild'ed to the created DOM fragment.
5. Strings are wrapped up with document.createTextNode
6. Objects that are not strings are run through the domConverters MochiKit.Base.AdapterRegistry (see registerDOMConverter). The value returned by the adapter is subject to these same rules (e.g. adapters are allowed to return a string, which will be coerced into a text node).
7. If no adapter is available, .toString() is used to create a text node.

Creating DOM Element Trees

createDOM provides you with an excellent facility for creating DOM trees that is easy on the wrists. One of the best ways to understand how to use it is to take a look at an example:

var rows = [
    ["dataA1", "dataA2", "dataA3"],
    ["dataB1", "dataB2", "dataB3"]
];
row_display = function (row) {
    return TR(null, map(partial(TD, null), row));
}
var newTable = TABLE({'class': 'prettytable'},
    THEAD(null,
        row_display(["head1", "head2", "head3"])),
    TFOOT(null,
        row_display(["foot1", "foot2", "foot3"])),
    TBODY(null,
        map(row_display, rows)));

This will create a table with the following visual layout (if it were inserted into the document DOM):

head1	head2	head3
dataA1	dataA2	dataA3
dataB1	dataB2	dataB3
foot1	foot2	foot3

Corresponding to the following HTML:

<table class="prettytable">
    <thead>
        <tr>
            <td>head1</td>
            <td>head2</td>
            <td>head3</td>
        </tr>
    </thead>
    <tfoot>
        <tr>
            <td>foot1</td>
            <td>foot2</td>
            <td>foot3</td>
        </tr>
    </tfoot>
    <tbody>
        <tr>
            <td>dataA1</td>
            <td>dataA2</td>
            <td>dataA3</td>
        </tr>
        <tr>
            <td>dataB1</td>
            <td>dataB2</td>
            <td>dataB3</td>
        </tr>
    </tbody>
</table>

DOM Context

In order to prevent having to pass a window and/or document variable to every MochiKit.DOM function (e.g. when working with a child window), MochiKit.DOM maintains a context variable for each of them. They are managed with the withWindow and withDocument functions, and can be acquired with currentWindow() and currentDocument()

For example, if you are creating DOM nodes in a child window, you could do something like this:

withWindow(child, function () {
    var doc = currentDocument();
    appendChildNodes(doc.body, H1(null, "This is in the child!"));
});

Note that withWindow(win, ...) also implies withDocument(win.document, ...).

Element Visibility

The hideElement and showElement functions are provided as a convenience, but only work for elements that are display: block. For a general solution to showing, hiding, and checking the explicit visibility of elements, we recommend using a solution that involves a little CSS. Here's an example:

<style type="text/css">
    .invisible { display: none; }
</style>

<script type="text/javascript">
    function toggleVisible(elem) {
        toggleElementClass("invisible", elem);
    }

    function makeVisible(elem) {
        removeElementClass(elem, "invisible");
    }

    function makeInvisible(elem) {
        addElementClass(elem, "invisible");
    }

    function isVisible(elem) {
        // you may also want to check for
        // getElement(elem).style.display == "none"
        return !hasElementClass(elem, "invisible");
    };
</script>

MochiKit doesn't ship with such a solution, because there is no reliable and portable method for adding CSS rules on the fly with JavaScript.

Functions

$(id[, ...]):

An alias for getElement(id[, ...])

addElementClass(element, className):

Ensure that the given element has className set as part of its class attribute. This will not disturb other class names. element is looked up with getElement, so string identifiers are also acceptable.

addLoadEvent(func):

This will stack window.onload functions on top of each other. Each function added will be called after onload in the order that they were added.

addToCallStack(target, path, func[, once]):

Set the property path of target to a function that calls the existing function at that property (if any), then calls func.

If target[path]() returns exactly false, then func will not be called.

If once is true, then target[path] is set to null after the function call stack has completed.

If called several times for the same target[path], it will create a stack of functions (instead of just a pair).

appendChildNodes(node[, childNode[, ...]]):

Append children to a DOM element using the DOM Coercion Rules.

node:

A reference to the DOM element to add children to (if a string is given, getElement(node) will be used to locate the node)

childNode...:

All additional arguments, if any, will be coerced into DOM nodes that are appended as children using the DOM Coercion Rules.

returns:

The given DOM element

computedStyle(htmlElement, cssProperty, mozillaEquivalentCSS):

Looks up a CSS property for the given element. The element can be specified as either a string with the element's ID or the element object itself.

createDOM(name[, attrs[, node[, ...]]]):

Create a DOM fragment in a really convenient manner, much like Nevow`s [1] stan [2].

Partially applied versions of this function for common tags are available as aliases:

• A
• BUTTON
• BR
• CANVAS
• DIV
• FIELDSET
• FORM
• H1
• H2
• H3
• HR
• IMG
• INPUT
• LABEL
• LEGEND
• LI
• OL
• OPTGROUP
• OPTION
• P
• PRE
• SELECT
• SPAN
• STRONG
• TABLE
• TBODY
• TD
• TEXTAREA
• TFOOT
• TH
• THEAD
• TR
• TT
• UL

See Creating DOM Element Trees for a comprehensive example.

name:

The kind of fragment to create (e.g. 'span'), such as you would pass to document.createElement.

attrs:

An object whose properties will be used as the attributes (e.g. {'style': 'display:block'}), or null if no attributes need to be set.

See updateNodeAttributes for more information.

node...:

All additional arguments, if any, will be coerced into DOM nodes that are appended as children using the DOM Coercion Rules.

returns:

A DOM element

createDOMFunc(tag[, attrs[, node[, ...]]]):

Convenience function to create a partially applied createDOM function. You'd want to use this if you add additional convenience functions for creating tags, or if you find yourself creating a lot of tags with a bunch of the same attributes or contents.

See createDOM for more detailed descriptions of the arguments.

tag:

The name of the tag

attrs:

Optionally specify the attributes to apply

node...:

Optionally specify any children nodes it should have

returns:

function that takes additional arguments and calls createDOM

currentDocument():

Return the current document DOM Context. This will always be the same as the global document unless withDocument or withWindow is currently executing.

currentWindow():

Return the current window DOM Context. This will always be the same as the global window unless withWindow is currently executing.

elementDimensions(element):

Return the absolute pixel width and height of element as an object with x and y properties, or undefined if element is not in the document. element may be specified as a string to be looked up with getElement, a DOM element, or trivially as an object with w and/or h properties.

elementPosition(element[, relativeTo={x: 0, y: 0}]):

Return the absolute pixel position of element in the document as an object with x and y properties, or undefined if element is not in the document. element may be specified as a string to be looked up with getElement, a DOM element, or trivially as an object with x and/or y properties.

If relativeTo is given, then its coordinates are subtracted from the absolute position of element, e.g.:

var elemPos = elementPosition(elem);
var anotherElemPos = elementPosition(anotherElem);
var relPos = elementPosition(elem, anotherElem);
assert( relPos.x == (elemPos.x - anotherElemPos.x) );
assert( relPos.y == (elemPos.y - anotherElemPos.y) );

relativeTo may be specified as a string to be looked up with getElement, a DOM element, or trivially as an object with x and/or y properties.

emitHTML(dom[, lst]):

Convert a DOM tree to an Array of HTML string fragments

You probably want to use toHTML instead.

escapeHTML(s):

Make a string safe for HTML, converting the usual suspects (lt, gt, quot, apos, amp)

focusOnLoad(element):

Add an onload event to focus the given element

formContents(elem):

Search the DOM tree, starting at elem, for any elements with a name and value attribute. Return a 2-element Array of names and values suitable for use with MochiKit.Base.queryString.

getElement(id[, ...]):

A small quick little function to encapsulate the getElementById method. It includes a check to ensure we can use that method.

If the id isn't a string, it will be returned as-is.

Also available as $(...) for convenience and compatibility with other JavaScript frameworks.

If multiple arguments are given, an Array will be returned.

getElementsByTagAndClassName(tagName, className, parent=document):

Returns an array of elements in parent that match the tag name and class name provided. If parent is a string, it will be looked up with getElement.

If tagName is null or "*", all elements will be searched for the matching class.

If className is null, all elements matching the provided tag are returned.

getNodeAttribute(node, attr):

Get the value of the given attribute for a DOM element without ever raising an exception (will return null on exception).

node:

A reference to the DOM element to update (if a string is given, getElement(node) will be used to locate the node)

attr:

The name of the attribute

Note that it will do the right thing for IE, so don't do the class -> className hack yourself.

returns:

The attribute's value, or null

hasElementClass(element, className[, ...]):

Return true if className is found on the element. element is looked up with getElement, so string identifiers are also acceptable.

hideElement(element, ...):

Partial form of setDisplayForElement, specifically:

partial(setDisplayForElement, "none")

For information about the caveats of using a style.display based show/hide mechanism, and a CSS based alternative, see Element Visibility.

registerDOMConverter(name, check, wrap[, override]):

Register an adapter to convert objects that match check(obj, ctx) to a DOM element, or something that can be converted to a DOM element (i.e. number, bool, string, function, iterable).

removeElement(node):

Remove and return node from a DOM tree. This is technically just a convenience for swapDOM(node, null).

node:

the DOM element (or string id of one) to be removed

returns

The removed element

removeElementClass(element, className):

Ensure that the given element does not have className set as part of its class attribute. This will not disturb other class names. element is looked up with getElement, so string identifiers are also acceptable.

replaceChildNodes(node[, childNode[, ...]]):

Remove all children from the given DOM element, then append any given childNodes to it (by calling appendChildNodes).

node:

A reference to the DOM element to add children to (if a string is given, getElement(node) will be used to locate the node)

childNode...:

All additional arguments, if any, will be coerced into DOM nodes that are appended as children using the DOM Coercion Rules.

returns:

The given DOM element

scrapeText(node[, asArray=false]):

Walk a DOM tree in-order and scrape all of the text out of it as a string.

If asArray is true, then an Array will be returned with each individual text node. These two are equivalent:

assert( scrapeText(node) == scrapeText(node, true).join("") );

setDisplayForElement(display, element[, ...]):

Change the style.display for the given element(s). Usually used as the partial forms:

• showElement(element, ...)
• hideElement(element, ...)

Elements are looked up with getElement, so string identifiers are acceptable.

For information about the caveats of using a style.display based show/hide mechanism, and a CSS based alternative, see Element Visibility.

setElementClass(element, className):

Set the entire class attribute of element to className. element is looked up with getElement, so string identifiers are also acceptable.

setNodeAttribute(node, attr, value):

Set the value of the given attribute for a DOM element without ever raising an exception (will return null on exception). If setting more than one attribute, you should use updateNodeAttributes.

node:

A reference to the DOM element to update (if a string is given, getElement(node) will be used to locate the node)

attr:

The name of the attribute

Note that it will do the right thing for IE, so don't do the class -> className hack yourself.

value:

The value of the attribute, may be an object to be merged (e.g. for setting style).

returns:

The given DOM element or null on failure

showElement(element, ...):

Partial form of setDisplayForElement, specifically:

partial(setDisplayForElement, "block")

For information about the caveats of using a style.display based show/hide mechanism, and a CSS based alternative, see Element Visibility.

swapDOM(dest, src):

Replace dest in a DOM tree with src, returning src.

dest:

a DOM element (or string id of one) to be replaced

src:

the DOM element (or string id of one) to replace it with, or null if dest is to be removed (replaced with nothing).

returns:

a DOM element (src)

swapElementClass(element, fromClass, toClass):

If fromClass is set on element, replace it with toClass. This will not disturb other classes on that element. element is looked up with getElement, so string identifiers are also acceptable.

toggleElementClass(className[, element[, ...]]):

Toggle the presence of a given className in the class attribute of all given elements. All elements will be looked up with getElement, so string identifiers are acceptable.

toHTML(dom):

Convert a DOM tree to a HTML string using emitHTML

updateNodeAttributes(node, attrs):

Update the attributes of a DOM element from a given object.

node:

A reference to the DOM element to update (if a string is given, getElement(node) will be used to locate the node)

attrs:

An object whose properties will be used to set the attributes (e.g. {'class': 'invisible'}), or null if no attributes need to be set. If an object is given for the attribute value (e.g. {'style': {'display': 'block'}}) then MochiKit.Base.updatetree will be used to set that attribute.

Note that it will do the right thing for IE, so don't do the class -> className hack yourself, and it deals with setting "on..." event handlers correctly.

returns:

The given DOM element

withWindow(win, func):

Call func with the window DOM Context set to win and the document DOM Context set to win.document. When func() returns or throws an error, the DOM Context will be restored to its previous state.

The return value of func() is returned by this function.

withDocument(doc, func):

Call func with the doc DOM Context set to doc. When func() returns or throws an error, the DOM Context will be restored to its previous state.

The return value of func() is returned by this function.