old_sql 1.12.0 → 1.13.0

data/public/javascripts/old_sql/MochiKit-1.4.2/doc/rst/MochiKit/DOM.rst

@@ -0,0 +1,1143 @@
+.. title:: MochiKit.DOM - painless DOM manipulation API
+
+Name
+====
+
+MochiKit.DOM - painless DOM manipulation API
+
+
+Synopsis
+========
+
+::
+
+    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)));
+    // put that in your document.createElement and smoke it!
+    swapDOM(oldTable, newTable);
+
+
+Description
+===========
+
+As you probably know, the DOM APIs are some of the most painful
+Java-inspired APIs you'll run across from a highly dynamic
+language. Don't worry about that though, because they provide a
+reasonable basis to build something that sucks a lot less.
+
+MochiKit.DOM takes much of its inspiration from Nevow's [1]_ stan
+[2]_.  This means you choose a tag, give it some attributes, then
+stuff it full of *whatever objects you want*. MochiKit.DOM isn't
+stupid, it knows that a string should be a text node, and that you
+want functions to be called, and that ``Array``-like objects should be
+expanded, and stupid ``null`` values should be skipped.
+
+Hell, it will let you return strings from functions, and use iterators
+from :mochiref:`MochiKit.Iter`. If that's not enough, just teach it
+new tricks with :mochiref:`registerDOMConverter`. If you have never
+used an API like this for creating DOM elements, you've been wasting
+your damn time. Get with it!
+
+
+Dependencies
+============
+
+- :mochiref:`MochiKit.Base`
+- :mochiref:`MochiKit.Style` (optional since MochiKit 1.4 for
+  backwards-compatibility)
+- :mochiref:`MochiKit.Iter` (optional since MochiKit 1.4)
+
+
+Overview
+========
+
+DOM Coercion Rules
+------------------
+
+In order of precedence, :mochiref:`createDOM` coerces given arguments
+to DOM nodes using the following rules:
+
+1.  Functions are called with a ``this`` and first argument of the
+    parent node and their return value is subject to the following
+    rules (even this one).
+2.  ``undefined`` and ``null`` are ignored.
+3.  If :mochiref:`MochiKit.Iter` is loaded, iterables are flattened
+    (as if they were passed in-line as nodes) and each return value is
+    subject to 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 have a ``.dom(node)`` or ``.__dom__(node)`` method
+    are called with the parent node and their result is coerced using
+    these rules.  (MochiKit 1.4+).
+7.  Objects that are not strings are run through the ``domConverters``
+    :mochiref:`MochiKit.Base.AdapterRegistry` (see
+    :mochiref:`registerDOMConverter`).  The adapted value is subject
+    to these same rules (e.g.  if the adapter returns a string, it
+    will be coerced to a text node).
+8.  If no adapter is available, ``.toString()`` is used to create a
+    text node.
+
+
+Creating DOM Element Trees
+--------------------------
+
+:mochiref:`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 :mochiref:`withWindow` and
+:mochiref:`withDocument` functions, and can be acquired with
+:mochiref:`currentWindow()` and :mochiref:`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 :mochiref:`withWindow(win, ...)` also implies
+:mochiref:`withDocument(win.document, ...)`.
+
+
+DOM Gotchas
+-----------
+
+Performance Tradeoff:
+    DOM is much easier to get correct and more flexible than working
+    directly with markup as strings. Modifying ``innerHTML`` is still
+    the fastest way to make document changes.
+
+Internet Explorer:
+    Internet Explorer's DOM implementation is quite poor in comparison
+    to the other popular implementations. In order to avoid memory
+    leaks due to circular references, you should use
+    :mochiref:`MochiKit.Signal.connect` for all of your event handling
+    needs. Additionally, when creating tables with DOM, it is required
+    to use a ``TBODY`` tag (see `Creating DOM Element Trees`_ for an
+    example of this).
+
+
+API Reference
+=============
+
+Functions
+---------
+
+:mochidef:`$(id[, ...])`:
+
+    An alias for :mochiref:`getElement(id[, ...])`
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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 :mochiref:`getElement`, so string
+    identifiers are also acceptable.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`addLoadEvent(func)`:
+
+    Note that :mochiref:`addLoadEvent` can not be used in combination
+    with :mochiref:`MochiKit.Signal` if the ``onload`` event is
+    connected.  Once an event is connected with
+    :mochiref:`MochiKit.Signal`, no other APIs may be used for that
+    same event.
+
+    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.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`addToCallStack(target, path, func[, once])`:
+
+    Note that :mochiref:`addToCallStack` is not compatible with
+    :mochiref:`MochiKit.Signal`. Once an event is connected with
+    :mochiref:`MochiKit.Signal`, no other APIs may be used for that
+    same event.
+
+    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).
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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, :mochiref:`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
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+:mochidef:`insertSiblingNodesBefore(node[, siblingNode[, ...]])`:
+
+    Insert children into the DOM structure using the `DOM Coercion
+    Rules`_.
+
+    ``node``:
+        A reference to the DOM element you want to insert children
+        before (if a string is given, :mochiref:`getElement(node)`
+        will be used to locate the node)
+
+    ``siblingNode``...:
+        All additional arguments, if any, will be coerced into DOM
+        nodes that are inserted as siblings using the `DOM Coercion
+        Rules`_.
+
+    *returns*:
+        The parent of the given DOM element
+
+    *Availability*:
+        Available in MochiKit 1.4+
+
+
+:mochidef:`insertSiblingNodesAfter(node[, siblingNode[, ...]])`:
+
+    Insert children into the DOM structure using the `DOM Coercion
+    Rules`_.
+
+    ``node``:
+        A reference to the DOM element you want to insert children
+        after (if a string is given, :mochiref:`getElement(node)`
+        will be used to locate the node)
+
+    ``siblingNode``...:
+        All additional arguments, if any, will be coerced into DOM
+        nodes that are inserted as siblings using the `DOM Coercion
+        Rules`_.
+
+    *returns*:
+        The parent of the given DOM element
+
+    *Availability*:
+        Available in MochiKit 1.4+
+
+
+:mochidef:`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``
+    - ``DD``
+    - ``DIV``
+    - ``DL``
+    - ``DT``
+    - ``FIELDSET``
+    - ``FORM``
+    - ``H1``
+    - ``H2``
+    - ``H3``
+    - ``H4``
+    - ``H5``
+    - ``H6``
+    - ``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 :mochiref:`updateNodeAttributes` for more information.
+
+        For convenience, if ``attrs`` is a string, ``null`` is used
+        and the string will be considered the first ``node``.
+
+    ``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
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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 :mochiref:`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
+        :mochiref:`createDOM`
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`currentDocument()`:
+
+    Return the current ``document`` `DOM Context`_. This will always
+    be the same as the global ``document`` unless
+    :mochiref:`withDocument` or :mochiref:`withWindow` is currently
+    executing.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`currentWindow()`:
+
+    Return the current ``window`` `DOM Context`_. This will always be
+    the same as the global ``window`` unless :mochiref:`withWindow` is
+    currently executing.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`emitHTML(dom[, lst])`:
+
+    Convert a DOM tree to an ``Array`` of HTML string fragments. This should
+    be used for debugging/testing purposes only.
+
+    The DOM property ``innerHTML`` or ``cloneNode(true)`` method should
+    be used for most purposes.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`escapeHTML(s)`:
+
+    Make a string safe for HTML, converting the usual suspects (``<``,
+    ``>``, ``"``, ``&``) to their HTML character entity equivalents.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`focusOnLoad(element)`:
+
+    Note that :mochiref:`focusOnLoad` can not be used in combination
+    with :mochiref:`MochiKit.Signal` if the ``onload`` event is
+    connected.  Once an event is connected with
+    :mochiref:`MochiKit.Signal`, no other APIs may be used for that
+    same event.
+
+    This adds an onload event to focus the given element.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`formContents(elem=document.body)`:
+
+    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
+    :mochiref:`MochiKit.Base.queryString`.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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 :mochiref:`$(...)` for convenience and
+    compatibility with other JavaScript frameworks.
+
+    If multiple arguments are given, an ``Array`` will be returned.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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 :mochiref:`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.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`getFirstElementByTagAndClassName(tagName, className, parent=document)`:
+
+    Return the first element in ``parent`` that matches the tag name
+    and class name provided. If ``parent`` is a string, it will be 
+    looked up with :mochiref:`getElement`.
+
+    If ``tagName`` is ``null`` or ``"*"``, all elements will be searched
+    for the matching class.
+
+    If ``className`` is ``null``, the first element matching the provided
+    tag will be returned.
+
+    *Availability*:
+        Available in MochiKit 1.4+
+
+
+:mochidef:`getFirstParentByTagAndClassName(elem, tagName='*', className=null)`:
+
+    Returns the first parent of ``elem`` that matches the tag name and class
+    name provided. If ``elem`` is a string, it will be looked up using
+    :mochiref:`getElement`.
+
+    If ``tagName`` is ``null`` or ``"*"``, all elements will be searched
+    for the matching class.
+
+    If ``className`` is ``null``, the first element matching the provided
+    tag name will be returned.
+
+    If no match is found, ``null`` will be returned.
+
+    *Availability*:
+        Available in MochiKit 1.4+
+
+
+:mochidef:`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, :mochiref:`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``
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`hasElementClass(element, className[, ...])`:
+
+    Return ``true`` if ``className`` is found on the ``element``.
+    ``element`` is looked up with :mochiref:`getElement`, so string
+    identifiers are also acceptable.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`isChildNode(node, maybeParent)`:
+
+    Determine whether ``node`` is a child node or decendant node of
+    ``maybeParent``. Returns ``true`` if so, and ``false`` if not.
+    A node is considered a child node of itself for the purposes of
+    this function.
+
+    If either ``node`` or ``maybeParent`` are strings, the related
+    nodes will be looked up with :mochiref:`getElement`.
+
+    *Availability*:
+        Available in MochiKit 1.4+
+
+
+:mochidef:`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).
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`removeElement(node)`:
+
+    Remove and return ``node`` from a DOM tree.
+
+    ``node``:
+        the DOM element (or string id of one) to be removed
+
+    *returns*
+        The removed element
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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 :mochiref:`getElement`, so
+    string identifiers are also acceptable.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`removeEmptyTextNodes(node)`:
+
+    Remove all text node children that contain only whitespace from
+    ``node``. Useful in situations where such empty text nodes can
+    interfere with DOM traversal.
+    
+    ``node``:
+        the DOM element (or string id of one) to remove whitespace child
+        nodes from.
+
+    *Availability*:
+        Available in MochiKit 1.4+
+
+
+:mochidef:`replaceChildNodes(node[, childNode[, ...]])`:
+
+    Remove all children from the given DOM element, then append any
+    given childNodes to it (by calling :mochiref:`appendChildNodes`).
+
+    ``node``:
+        A reference to the DOM element to add children to (if a string
+        is given, :mochiref:`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
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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("") );
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`setElementClass(element, className)`:
+
+    Set the entire class attribute of ``element`` to ``className``.
+    ``element`` is looked up with :mochiref:`getElement`, so string
+    identifiers are also acceptable.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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
+    :mochiref:`updateNodeAttributes`.
+
+    ``node``:
+        A reference to the DOM element to update (if a string is
+        given, :mochiref:`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.
+
+        Also note that the DOM element object property with the same
+        name will also be set if not already identical to the attribute
+        value. This is needed to compensate for weird attributes that
+        distinguish between the property and attribute values (i.e. the
+        "value" attribute for fields).
+
+    ``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
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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``)
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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 :mochiref:`getElement`, so string
+    identifiers are also acceptable.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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 :mochiref:`getElement`, so string identifiers are acceptable.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`toHTML(dom)`:
+
+    Convert a DOM tree to a HTML string using :mochiref:`emitHTML`.
+    This should be used for debugging/testing purposes only.
+
+    The DOM property ``innerHTML`` or ``cloneNode(true)`` method should
+    be used for most purposes.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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, :mochiref:`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 :mochiref:`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.
+
+        Also note that the DOM element object property with the same
+        name will also be set if not already identical to the attribute
+        value. This is needed to compensate for weird attributes that
+        distinguish between the property and attribute values (i.e. the
+        "value" attribute for fields).
+
+    *returns*:
+        The given DOM element
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+:mochidef:`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.
+
+    *Availability*:
+        Available in MochiKit 1.3.1+
+
+
+Style Functions
+---------------
+
+These functions were previously available in MochiKit.DOM, but have been
+moved to :mochiref:`MochiKit.Style` in recent versions. Function aliases
+remain for backwards compability.
+
+
+:mochidef:`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.
+    
+    ``cssProperty``:
+        MochiKit 1.3.1 expects camel case, e.g. ``backgroundColor``.
+        MochiKit 1.4+ expects CSS selector case, e.g. ``background-color``,
+        but will accept camel case for backwards-compatibility.
+        
+    ``mozillaEquivalentCSS``:
+        MochiKit 1.3.1 expects selector case.
+        MochiKit 1.4+ ignores this argument.
+
+    *Availability*:
+        Available in MochiKit 1.3.1, deprecated in favor of
+        :mochiref:`MochiKit.Style.getStyle` in 1.4+
+
+
+:mochidef:`elementDimensions(element)`:
+
+    Return the absolute pixel width and height (including padding and border,
+    but not margins) of ``element`` as an object with ``w`` and ``h``
+    properties, or ``undefined`` if ``element`` is not in the document.
+    ``element`` may be specified as a string to be looked up with
+    :mochiref:`getElement`, a DOM element, or trivially as an object with
+    ``w`` and/or ``h`` properties.
+
+    *Availability*:
+        Available in MochiKit 1.3.1, deprecated in favor of
+        :mochiref:`MochiKit.Style.getElementDimensions` in 1.4+
+
+
+:mochidef:`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 :mochiref:`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
+    :mochiref:`getElement`, a DOM element, or trivially as an object
+    with ``x`` and/or ``y`` properties.
+
+    *Availability*:
+        Available in MochiKit 1.3.1, deprecated in favor of
+        :mochiref:`MochiKit.Style.getElementPosition` in 1.4+
+
+
+:mochidef:`getViewportDimensions()`:
+
+    Return the pixel width and height of the viewport as an object
+    with ``w`` and ``h`` properties. ``element`` is looked up with
+    :mochiref:`getElement`, so string identifiers are also acceptable.
+
+    *Availability*:
+        Available in MochiKit 1.3.1, moved to
+        :mochiref:`MochiKit.Style.getViewportDimensions` in 1.4+
+
+
+:mochidef:`hideElement(element, ...)`:
+
+    Partial form of :mochiref:`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`_.
+
+.. _`Element Visibility`: Style.html#element-visibility
+
+    *Availability*:
+        Available in MochiKit 1.3.1, moved to 
+        :mochiref:`MochiKit.Style.hideElement` in 1.4+
+
+
+:mochidef:`makeClipping(element)`:
+
+    Ensure that ``element.style.overflow = 'hidden'``. If ``element`` is a
+    string, then it will be looked up with :mochiref:`getElement`.
+
+    Returns the original values of ``overflow``, ``overflow-y`` and
+    ``overflow-y`` so that they may be restored with
+    :mochiref:`undoClipping(element, overflow)`.
+
+    *Availability*:
+        Available in MochiKit 1.4+, moved to 
+        :mochiref:`MochiKit.Style.makeClipping` in 1.4.1+
+
+
+:mochidef:`makePositioned(element)`:
+
+    Ensure that ``element.style.position`` is set to ``"relative"`` if it
+    is not set or is ``"static"``. If ``element`` is a
+    string, then it will be looked up with :mochiref:`getElement`.
+
+    *Availability*:
+        Available in MochiKit 1.4+, moved to 
+        :mochiref:`MochiKit.Style.makePositioned` in 1.4.1+
+
+
+:mochidef:`setElementDimensions(element, dimensions[, units='px'])`:
+
+    Sets the dimensions of ``element`` in the document from an object
+    with ``w`` and ``h`` properties.
+
+    ``node``:
+        A reference to the DOM element to update (if a string is
+        given, :mochiref:`getElement(node)` will be used to locate the
+        node)
+
+    ``dimensions``:
+        An object with ``w`` and ``h`` properties
+
+    ``units``:
+        Optionally set the units to use, default is ``px``
+
+    *Availability*:
+        Available in MochiKit 1.3.1, moved to 
+        :mochiref:`MochiKit.Style.setElementDimensions` in 1.4+
+
+
+:mochidef:`setElementPosition(element, position[, units='px'])`:
+
+    Sets the absolute position of ``element`` in the document from an
+    object with ``x`` and ``y`` properties.
+
+    ``node``:
+        A reference to the DOM element to update (if a string is
+        given, :mochiref:`getElement(node)` will be used to locate the
+        node)
+
+    ``position``:
+        An object with ``x`` and ``y`` properties
+
+    ``units``:
+        Optionally set the units to use, default is ``px``
+
+    *Availability*:
+        Available in MochiKit 1.3.1, moved to 
+        :mochiref:`MochiKit.Style.setElementPosition` in 1.4+
+
+
+:mochidef:`setDisplayForElement(display, element[, ...])`:
+
+    Change the ``style.display`` for the given element(s). Usually
+    used as the partial forms:
+
+    - :mochiref:`showElement(element, ...)`
+    - :mochiref:`hideElement(element, ...)`
+
+    Elements are looked up with :mochiref:`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`_.
+
+    *Availability*:
+        Available in MochiKit 1.3.1, moved to 
+        :mochiref:`MochiKit.Style.setDisplayForElement` in 1.4+
+
+
+:mochidef:`setOpacity(element, opacity)`:
+
+    Sets ``opacity`` for ``element``. Valid ``opacity`` values range
+    from 0 (invisible) to 1 (opaque). ``element`` is looked up with
+    :mochiref:`getElement`, so string identifiers are also acceptable.
+
+    *Availability*:
+        Available in MochiKit 1.3.1, moved to 
+        :mochiref:`MochiKit.Style.setOpacity` in 1.4+
+
+
+:mochidef:`showElement(element, ...)`:
+
+    Partial form of :mochiref:`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`_.
+
+    *Availability*:
+        Available in MochiKit 1.3.1, moved to 
+        :mochiref:`MochiKit.Style.showElement` in 1.4+
+
+
+:mochidef:`undoClipping(element, overflow)`:
+
+    Restore the setting of ``element.style.overflow`` set by
+    :mochiref:`makeClipping(element)`. If ``element`` is a string, then
+    it will be looked up with :mochiref:`getElement`.
+
+    *Availability*:
+        Available in MochiKit 1.4+, moved to 
+        :mochiref:`MochiKit.Style.undoClipping` in 1.4.1+
+
+
+:mochidef:`undoPositioned(element)`:
+
+    Restore the setting of ``element.style.position`` set by
+    :mochiref:`makePositioned(element)`. If ``element`` is a string, then
+    it will be looked up with :mochiref:`getElement`.
+
+    *Availability*:
+        Available in MochiKit 1.4+, moved to 
+        :mochiref:`MochiKit.Style.undoPositioned` in 1.4.1+
+
+
+Style Objects
+-------------
+
+These objects are available in MochiKit 1.3.1, but have been moved to 
+:mochiref:`MochiKit.Style` in 1.4+.
+
+:mochidef:`Coordinates(x, y)`:
+
+    Constructs an object with ``x`` and ``y`` properties. ``obj.toString()`` 
+    returns something like ``{x: 0, y: 42}`` for debugging.
+
+    *Availability*:
+    Available in MochiKit 1.3.1, moved to 
+    :mochiref:`MochiKit.Style.Coordinates` in 1.4+
+
+:mochidef:`Dimensions(w, h)`:
+
+    Constructs an object with ``w`` and ``h`` properties. ``obj.toString()`` 
+    returns something like ``{w: 0, h: 42}`` for debugging.
+
+    *Availability*:
+    Available in MochiKit 1.3.1, moved to 
+    :mochiref:`MochiKit.Style.Dimensions` in 1.4+
+
+
+
+See Also
+========
+
+.. [1] Nevow, a web application construction kit for Python:
+       http://divmod.org/trac/wiki/DivmodNevow
+.. [2] nevow.stan is a domain specific language for Python (read as
+       "crazy getitem/call overloading abuse") that Donovan and I
+       schemed up at PyCon 2003 at this super ninja Python/C++
+       programmer's (David Abrahams) hotel room. Donovan later
+       inflicted this upon the masses in Nevow. Check out the Nevow
+       Guide for some examples:
+       http://divmod.org/trac/wiki/DivmodNevow
+
+
+Authors
+=======
+
+- Bob Ippolito <bob@redivi.com>
+
+
+Copyright
+=========
+
+Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is
+dual-licensed free software; you can redistribute it and/or modify it
+under the terms of the `MIT License`_ or the `Academic Free License
+v2.1`_.
+
+.. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
+.. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php