dom.rst

Ajax下日志框架

    currently executing.


:mochidef:`elementDimensions(element)`:

    Return the absolute pixel width and height 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.


: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.


:mochidef:`emitHTML(dom[, lst])`:

    Convert a DOM tree to an ``Array`` of HTML string fragments

    You probably want to use :mochiref:`toHTML` instead.


:mochidef:`escapeHTML(s)`:

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


:mochidef:`focusOnLoad(element)`:

    Add an onload event to focus the given element
       

:mochidef:`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
    :mochiref:`MochiKit.Base.queryString`.


: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.


: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.


: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``


: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.


: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.


: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`_.


: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).


:mochidef:`removeElement(node)`:

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

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

    *returns*
        The removed element


: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.


: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


: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("") );


: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`_.


: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.
        

: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``


: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``


: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.

    ``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


: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.


: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`_.


: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``)


: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.


: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.


:mochidef:`toHTML(dom)`:

    Convert a DOM tree to a HTML string using :mochiref:`emitHTML`


: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.

    *returns*:
        The given DOM element


: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.


: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.


See Also
========

.. [1] Nevow, a web application construction kit for Python: http://nevow.com/
.. [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 Divmod project page for some
       examples: http://nevow.com/Nevow2004Tutorial.html


Authors
=======

- Bob Ippolito <[e-mail]>


Copyright
=========

Copyright 2005 Bob Ippolito <[e-mail]>. 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