old_sql 1.16.0 → 1.17.0

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

@@ -1,1143 +0,0 @@
-.. 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