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