<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>MochiKit.DOM - painless DOM manipulation API</title>
<link rel="stylesheet" href="../../../include/css/documentation.css" type="text/css" />
<script type="text/javascript" src="../../../packed/lib/MochiKit/MochiKit.js"></script>
<script type="text/javascript" src="../../js/toc.js"></script>
</head>
<body>
<a href="http://mochikit.com"><img id="mainlink" src="../../../include/_img/g_logo_doc.gif" alt="MochiKit" /></a>
<a class='indexlink' href='index.html'>Back to docs index</a>
<div class="document">
<div class="section">
<h1><a id="name" name="name">Name</a></h1>
<p>MochiKit.DOM - painless DOM manipulation API</p>
</div>
<div class="section">
<h1><a id="synopsis" name="synopsis">Synopsis</a></h1>
<pre class="literal-block">
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);
</pre>
</div>
<div class="section">
<h1><a id="description" name="description">Description</a></h1>
<p>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.</p>
<p>MochiKit.DOM takes much of its inspiration from Nevow's <a class="footnote-reference" href="#id5" id="id1" name="id1">[1]</a> stan
<a class="footnote-reference" href="#id6" id="id2" name="id2">[2]</a>. This means you choose a tag, give it some attributes, then
stuff it full of <em>whatever objects you want</em>. 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 <tt class="docutils literal"><span class="pre">Array</span></tt>-like objects should be
expanded, and stupid <tt class="docutils literal"><span class="pre">null</span></tt> values should be skipped.</p>
<p>Hell, it will let you return strings from functions, and use iterators
from <a class="mochiref reference" href="Iter.html">MochiKit.Iter</a>. If that's not enough, just teach it
new tricks with <a class="mochiref reference" href="#fn-registerdomconverter">registerDOMConverter</a>. If you have never
used an API like this for creating DOM elements, you've been wasting
your damn time. Get with it!</p>
</div>
<div class="section">
<h1><a id="dependencies" name="dependencies">Dependencies</a></h1>
<ul class="simple">
<li><a class="mochiref reference" href="Base.html">MochiKit.Base</a></li>
<li><a class="mochiref reference" href="Style.html">MochiKit.Style</a> (optional since MochiKit 1.4 for
backwards-compatibility)</li>
<li><a class="mochiref reference" href="Iter.html">MochiKit.Iter</a> (optional since MochiKit 1.4)</li>
</ul>
</div>
<div class="section">
<h1><a id="overview" name="overview">Overview</a></h1>
<div class="section">
<h2><a id="dom-coercion-rules" name="dom-coercion-rules">DOM Coercion Rules</a></h2>
<p>In order of precedence, <a class="mochiref reference" href="#fn-createdom">createDOM</a> coerces given arguments
to DOM nodes using the following rules:</p>
<ol class="arabic simple">
<li>Functions are called with a <tt class="docutils literal"><span class="pre">this</span></tt> and first argument of the
parent node and their return value is subject to the following
rules (even this one).</li>
<li><tt class="docutils literal"><span class="pre">undefined</span></tt> and <tt class="docutils literal"><span class="pre">null</span></tt> are ignored.</li>
<li>If <a class="mochiref reference" href="Iter.html">MochiKit.Iter</a> is loaded, iterables are flattened
(as if they were passed in-line as nodes) and each return value is
subject to these rules.</li>
<li>Values that look like DOM nodes (objects with a <tt class="docutils literal"><span class="pre">.nodeType</span> <span class="pre">></span> <span class="pre">0</span></tt>)
are <tt class="docutils literal"><span class="pre">.appendChild</span></tt>'ed to the created DOM fragment.</li>
<li>Strings are wrapped up with <tt class="docutils literal"><span class="pre">document.createTextNode</span></tt></li>
<li>Objects that have a <tt class="docutils literal"><span class="pre">.dom(node)</span></tt> or <tt class="docutils literal"><span class="pre">.__dom__(node)</span></tt> method
are called with the parent node and their result is coerced using
these rules. (MochiKit 1.4+).</li>
<li>Objects that are not strings are run through the <tt class="docutils literal"><span class="pre">domConverters</span></tt>
<a class="mochiref reference" href="Base.html#fn-adapterregistry">MochiKit.Base.AdapterRegistry</a> (see
<a class="mochiref reference" href="#fn-registerdomconverter">registerDOMConverter</a>). 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).</li>
<li>If no adapter is available, <tt class="docutils literal"><span class="pre">.toString()</span></tt> is used to create a
text node.</li>
</ol>
</div>
<div class="section">
<h2><a id="creating-dom-element-trees" name="creating-dom-element-trees">Creating DOM Element Trees</a></h2>
<p><a class="mochiref reference" href="#fn-createdom">createDOM</a> 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:</p>
<pre class="literal-block">
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)));
</pre>
<p>This will create a table with the following visual layout (if it were
inserted into the document DOM):</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">head1</th>
<th class="head">head2</th>
<th class="head">head3</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>dataA1</td>
<td>dataA2</td>
<td>dataA3</td>
</tr>
<tr><td>dataB1</td>
<td>dataB2</td>
<td>dataB3</td>
</tr>
<tr><td>foot1</td>
<td>foot2</td>
<td>foot3</td>
</tr>
</tbody>
</table>
</blockquote>
<p>Corresponding to the following HTML:</p>
<pre class="literal-block">
<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>
</pre>
</div>
<div class="section">
<h2><a id="dom-context" name="dom-context">DOM Context</a></h2>
<p>In order to prevent having to pass a <tt class="docutils literal"><span class="pre">window</span></tt> and/or <tt class="docutils literal"><span class="pre">document</span></tt>
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 <a class="mochiref reference" href="#fn-withwindow">withWindow</a> and
<a class="mochiref reference" href="#fn-withdocument">withDocument</a> functions, and can be acquired with
<a class="mochiref reference" href="#fn-currentwindow">currentWindow()</a> and <a class="mochiref reference" href="#fn-currentdocument">currentDocument()</a></p>
<p>For example, if you are creating DOM nodes in a child window, you
could do something like this:</p>
<pre class="literal-block">
withWindow(child, function () {
var doc = currentDocument();
appendChildNodes(doc.body, H1(null, "This is in the child!"));
});
</pre>
<p>Note that <a class="mochiref reference" href="#fn-withwindow">withWindow(win, ...)</a> also implies
<a class="mochiref reference" href="#fn-withdocument">withDocument(win.document, ...)</a>.</p>
</div>
<div class="section">
<h2><a id="dom-gotchas" name="dom-gotchas">DOM Gotchas</a></h2>
<dl class="docutils">
<dt>Performance Tradeoff:</dt>
<dd>DOM is much easier to get correct and more flexible than working
directly with markup as strings. Modifying <tt class="docutils literal"><span class="pre">innerHTML</span></tt> is still
the fastest way to make document changes.</dd>
<dt>Internet Explorer:</dt>
<dd>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
<a class="mochiref reference" href="Signal.html#fn-connect">MochiKit.Signal.connect</a> for all of your event handling
needs. Additionally, when creating tables with DOM, it is required
to use a <tt class="docutils literal"><span class="pre">TBODY</span></tt> tag (see <a class="reference" href="#creating-dom-element-trees">Creating DOM Element Trees</a> for an
example of this).</dd>
</dl>
</div>
</div>
<div class="section">
<h1><a id="api-reference" name="api-reference">API Reference</a></h1>
<div class="section">
<h2><a id="functions" name="functions">Functions</a></h2>
<p>
<a name="fn-$"></a>
<a class="mochidef reference" href="#fn-$">$(id[, ...])</a>:</p>
<blockquote>
<p>An alias for <a class="mochiref reference" href="#fn-getelement">getElement(id[, ...])</a></p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-addelementclass"></a>
<a class="mochidef reference" href="#fn-addelementclass">addElementClass(element, className)</a>:</p>
<blockquote>
<p>Ensure that the given <tt class="docutils literal"><span class="pre">element</span></tt> has <tt class="docutils literal"><span class="pre">className</span></tt> set as part of
its class attribute. This will not disturb other class names.
<tt class="docutils literal"><span class="pre">element</span></tt> is looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>, so string
identifiers are also acceptable.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-addloadevent"></a>
<a class="mochidef reference" href="#fn-addloadevent">addLoadEvent(func)</a>:</p>
<blockquote>
<p>Note that <a class="mochiref reference" href="#fn-addloadevent">addLoadEvent</a> can not be used in combination
with <a class="mochiref reference" href="Signal.html">MochiKit.Signal</a> if the <tt class="docutils literal"><span class="pre">onload</span></tt> event is
connected. Once an event is connected with
<a class="mochiref reference" href="Signal.html">MochiKit.Signal</a>, no other APIs may be used for that
same event.</p>
<p>This will stack <tt class="docutils literal"><span class="pre">window.onload</span></tt> functions on top of each other.
Each function added will be called after <tt class="docutils literal"><span class="pre">onload</span></tt> in the order
that they were added.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-addtocallstack"></a>
<a class="mochidef reference" href="#fn-addtocallstack">addToCallStack(target, path, func[, once])</a>:</p>
<blockquote>
<p>Note that <a class="mochiref reference" href="#fn-addtocallstack">addToCallStack</a> is not compatible with
<a class="mochiref reference" href="Signal.html">MochiKit.Signal</a>. Once an event is connected with
<a class="mochiref reference" href="Signal.html">MochiKit.Signal</a>, no other APIs may be used for that
same event.</p>
<p>Set the property <tt class="docutils literal"><span class="pre">path</span></tt> of <tt class="docutils literal"><span class="pre">target</span></tt> to a function that calls
the existing function at that property (if any), then calls
<tt class="docutils literal"><span class="pre">func</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">target[path]()</span></tt> returns exactly <tt class="docutils literal"><span class="pre">false</span></tt>, then <tt class="docutils literal"><span class="pre">func</span></tt>
will not be called.</p>
<p>If <tt class="docutils literal"><span class="pre">once</span></tt> is <tt class="docutils literal"><span class="pre">true</span></tt>, then <tt class="docutils literal"><span class="pre">target[path]</span></tt> is set to <tt class="docutils literal"><span class="pre">null</span></tt>
after the function call stack has completed.</p>
<p>If called several times for the same <tt class="docutils literal"><span class="pre">target[path]</span></tt>, it will
create a stack of functions (instead of just a pair).</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-appendchildnodes"></a>
<a class="mochidef reference" href="#fn-appendchildnodes">appendChildNodes(node[, childNode[, ...]])</a>:</p>
<blockquote>
<p>Append children to a DOM element using the <a class="reference" href="#dom-coercion-rules">DOM Coercion Rules</a>.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>A reference to the DOM element to add children to (if a string
is given, <a class="mochiref reference" href="#fn-getelement">getElement(node)</a> will be used to locate
the node)</dd>
<dt><tt class="docutils literal"><span class="pre">childNode</span></tt>...:</dt>
<dd>All additional arguments, if any, will be coerced into DOM
nodes that are appended as children using the <a class="reference" href="#dom-coercion-rules">DOM Coercion
Rules</a>.</dd>
<dt><em>returns</em>:</dt>
<dd>The given DOM element</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-insertsiblingnodesbefore"></a>
<a class="mochidef reference" href="#fn-insertsiblingnodesbefore">insertSiblingNodesBefore(node[, siblingNode[, ...]])</a>:</p>
<blockquote>
<p>Insert children into the DOM structure using the <a class="reference" href="#dom-coercion-rules">DOM Coercion
Rules</a>.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>A reference to the DOM element you want to insert children
before (if a string is given, <a class="mochiref reference" href="#fn-getelement">getElement(node)</a>
will be used to locate the node)</dd>
<dt><tt class="docutils literal"><span class="pre">siblingNode</span></tt>...:</dt>
<dd>All additional arguments, if any, will be coerced into DOM
nodes that are inserted as siblings using the <a class="reference" href="#dom-coercion-rules">DOM Coercion
Rules</a>.</dd>
<dt><em>returns</em>:</dt>
<dd>The parent of the given DOM element</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-insertsiblingnodesafter"></a>
<a class="mochidef reference" href="#fn-insertsiblingnodesafter">insertSiblingNodesAfter(node[, siblingNode[, ...]])</a>:</p>
<blockquote>
<p>Insert children into the DOM structure using the <a class="reference" href="#dom-coercion-rules">DOM Coercion
Rules</a>.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>A reference to the DOM element you want to insert children
after (if a string is given, <a class="mochiref reference" href="#fn-getelement">getElement(node)</a>
will be used to locate the node)</dd>
<dt><tt class="docutils literal"><span class="pre">siblingNode</span></tt>...:</dt>
<dd>All additional arguments, if any, will be coerced into DOM
nodes that are inserted as siblings using the <a class="reference" href="#dom-coercion-rules">DOM Coercion
Rules</a>.</dd>
<dt><em>returns</em>:</dt>
<dd>The parent of the given DOM element</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-createdom"></a>
<a class="mochidef reference" href="#fn-createdom">createDOM(name[, attrs[, node[, ...]]])</a>:</p>
<blockquote>
<p>Create a DOM fragment in a really convenient manner, much like
Nevow`s <a class="footnote-reference" href="#id5" id="id3" name="id3">[1]</a> stan <a class="footnote-reference" href="#id6" id="id4" name="id4">[2]</a>.</p>
<p>Partially applied versions of this function for common tags are
available as aliases:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">A</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BUTTON</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BR</span></tt></li>
<li><tt class="docutils literal"><span class="pre">CANVAS</span></tt></li>
<li><tt class="docutils literal"><span class="pre">DD</span></tt></li>
<li><tt class="docutils literal"><span class="pre">DIV</span></tt></li>
<li><tt class="docutils literal"><span class="pre">DL</span></tt></li>
<li><tt class="docutils literal"><span class="pre">DT</span></tt></li>
<li><tt class="docutils literal"><span class="pre">FIELDSET</span></tt></li>
<li><tt class="docutils literal"><span class="pre">FORM</span></tt></li>
<li><tt class="docutils literal"><span class="pre">H1</span></tt></li>
<li><tt class="docutils literal"><span class="pre">H2</span></tt></li>
<li><tt class="docutils literal"><span class="pre">H3</span></tt></li>
<li><tt class="docutils literal"><span class="pre">H4</span></tt></li>
<li><tt class="docutils literal"><span class="pre">H5</span></tt></li>
<li><tt class="docutils literal"><span class="pre">H6</span></tt></li>
<li><tt class="docutils literal"><span class="pre">HR</span></tt></li>
<li><tt class="docutils literal"><span class="pre">IMG</span></tt></li>
<li><tt class="docutils literal"><span class="pre">INPUT</span></tt></li>
<li><tt class="docutils literal"><span class="pre">LABEL</span></tt></li>
<li><tt class="docutils literal"><span class="pre">LEGEND</span></tt></li>
<li><tt class="docutils literal"><span class="pre">LI</span></tt></li>
<li><tt class="docutils literal"><span class="pre">OL</span></tt></li>
<li><tt class="docutils literal"><span class="pre">OPTGROUP</span></tt></li>
<li><tt class="docutils literal"><span class="pre">OPTION</span></tt></li>
<li><tt class="docutils literal"><span class="pre">P</span></tt></li>
<li><tt class="docutils literal"><span class="pre">PRE</span></tt></li>
<li><tt class="docutils literal"><span class="pre">SELECT</span></tt></li>
<li><tt class="docutils literal"><span class="pre">SPAN</span></tt></li>
<li><tt class="docutils literal"><span class="pre">STRONG</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TABLE</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TBODY</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TD</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TEXTAREA</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TFOOT</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TH</span></tt></li>
<li><tt class="docutils literal"><span class="pre">THEAD</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TR</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TT</span></tt></li>
<li><tt class="docutils literal"><span class="pre">UL</span></tt></li>
</ul>
<p>See <a class="reference" href="#creating-dom-element-trees">Creating DOM Element Trees</a> for a comprehensive example.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">name</span></tt>:</dt>
<dd>The kind of fragment to create (e.g. 'span'), such as you
would pass to <tt class="docutils literal"><span class="pre">document.createElement</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">attrs</span></tt>:</dt>
<dd><p class="first">An object whose properties will be used as the attributes
(e.g. <tt class="docutils literal"><span class="pre">{'style':</span> <span class="pre">'display:block'}</span></tt>), or <tt class="docutils literal"><span class="pre">null</span></tt> if no
attributes need to be set.</p>
<p>See <a class="mochiref reference" href="#fn-updatenodeattributes">updateNodeAttributes</a> for more information.</p>
<p class="last">For convenience, if <tt class="docutils literal"><span class="pre">attrs</span></tt> is a string, <tt class="docutils literal"><span class="pre">null</span></tt> is used
and the string will be considered the first <tt class="docutils literal"><span class="pre">node</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">node</span></tt>...:</dt>
<dd>All additional arguments, if any, will be coerced into DOM
nodes that are appended as children using the <a class="reference" href="#dom-coercion-rules">DOM Coercion
Rules</a>.</dd>
<dt><em>returns</em>:</dt>
<dd>A DOM element</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-createdomfunc"></a>
<a class="mochidef reference" href="#fn-createdomfunc">createDOMFunc(tag[, attrs[, node[, ...]]])</a>:</p>
<blockquote>
<p>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.</p>
<p>See <a class="mochiref reference" href="#fn-createdom">createDOM</a> for more detailed descriptions of the
arguments.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">tag</span></tt>:</dt>
<dd>The name of the tag</dd>
<dt><tt class="docutils literal"><span class="pre">attrs</span></tt>:</dt>
<dd>Optionally specify the attributes to apply</dd>
<dt><tt class="docutils literal"><span class="pre">node</span></tt>...:</dt>
<dd>Optionally specify any children nodes it should have</dd>
<dt><em>returns</em>:</dt>
<dd>function that takes additional arguments and calls
<a class="mochiref reference" href="#fn-createdom">createDOM</a></dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-currentdocument"></a>
<a class="mochidef reference" href="#fn-currentdocument">currentDocument()</a>:</p>
<blockquote>
<p>Return the current <tt class="docutils literal"><span class="pre">document</span></tt> <a class="reference" href="#dom-context">DOM Context</a>. This will always
be the same as the global <tt class="docutils literal"><span class="pre">document</span></tt> unless
<a class="mochiref reference" href="#fn-withdocument">withDocument</a> or <a class="mochiref reference" href="#fn-withwindow">withWindow</a> is currently
executing.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-currentwindow"></a>
<a class="mochidef reference" href="#fn-currentwindow">currentWindow()</a>:</p>
<blockquote>
<p>Return the current <tt class="docutils literal"><span class="pre">window</span></tt> <a class="reference" href="#dom-context">DOM Context</a>. This will always be
the same as the global <tt class="docutils literal"><span class="pre">window</span></tt> unless <a class="mochiref reference" href="#fn-withwindow">withWindow</a> is
currently executing.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-emithtml"></a>
<a class="mochidef reference" href="#fn-emithtml">emitHTML(dom[, lst])</a>:</p>
<blockquote>
<p>Convert a DOM tree to an <tt class="docutils literal"><span class="pre">Array</span></tt> of HTML string fragments. This should
be used for debugging/testing purposes only.</p>
<p>The DOM property <tt class="docutils literal"><span class="pre">innerHTML</span></tt> or <tt class="docutils literal"><span class="pre">cloneNode(true)</span></tt> method should
be used for most purposes.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-escapehtml"></a>
<a class="mochidef reference" href="#fn-escapehtml">escapeHTML(s)</a>:</p>
<blockquote>
<p>Make a string safe for HTML, converting the usual suspects (<tt class="docutils literal"><span class="pre"><</span></tt>,
<tt class="docutils literal"><span class="pre">></span></tt>, <tt class="docutils literal"><span class="pre">"</span></tt>, <tt class="docutils literal"><span class="pre">&</span></tt>) to their HTML character entity equivalents.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-focusonload"></a>
<a class="mochidef reference" href="#fn-focusonload">focusOnLoad(element)</a>:</p>
<blockquote>
<p>Note that <a class="mochiref reference" href="#fn-focusonload">focusOnLoad</a> can not be used in combination
with <a class="mochiref reference" href="Signal.html">MochiKit.Signal</a> if the <tt class="docutils literal"><span class="pre">onload</span></tt> event is
connected. Once an event is connected with
<a class="mochiref reference" href="Signal.html">MochiKit.Signal</a>, no other APIs may be used for that
same event.</p>
<p>This adds an onload event to focus the given element.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-formcontents"></a>
<a class="mochidef reference" href="#fn-formcontents">formContents(elem=document.body)</a>:</p>
<blockquote>
<p>Search the DOM tree, starting at <tt class="docutils literal"><span class="pre">elem</span></tt>, for any elements with a
<tt class="docutils literal"><span class="pre">name</span></tt> and <tt class="docutils literal"><span class="pre">value</span></tt> attribute. Return a 2-element <tt class="docutils literal"><span class="pre">Array</span></tt> of
<tt class="docutils literal"><span class="pre">names</span></tt> and <tt class="docutils literal"><span class="pre">values</span></tt> suitable for use with
<a class="mochiref reference" href="Base.html#fn-querystring">MochiKit.Base.queryString</a>.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-getelement"></a>
<a class="mochidef reference" href="#fn-getelement">getElement(id[, ...])</a>:</p>
<blockquote>
<p>A small quick little function to encapsulate the
<tt class="docutils literal"><span class="pre">getElementById</span></tt> method. It includes a check to ensure we can
use that method.</p>
<p>If the id isn't a string, it will be returned as-is.</p>
<p>Also available as <a class="mochiref reference" href="#fn-$">$(...)</a> for convenience and
compatibility with other JavaScript frameworks.</p>
<p>If multiple arguments are given, an <tt class="docutils literal"><span class="pre">Array</span></tt> will be returned.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-getelementsbytagandclassname"></a>
<a class="mochidef reference" href="#fn-getelementsbytagandclassname">getElementsByTagAndClassName(tagName, className, parent=document)</a>:</p>
<blockquote>
<p>Returns an array of elements in <tt class="docutils literal"><span class="pre">parent</span></tt> that match the tag name
and class name provided. If <tt class="docutils literal"><span class="pre">parent</span></tt> is a string, it will be
looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>.</p>
<p>If <tt class="docutils literal"><span class="pre">tagName</span></tt> is <tt class="docutils literal"><span class="pre">null</span></tt> or <tt class="docutils literal"><span class="pre">"*"</span></tt>, all elements will be
searched for the matching class.</p>
<p>If <tt class="docutils literal"><span class="pre">className</span></tt> is <tt class="docutils literal"><span class="pre">null</span></tt>, all elements matching the provided
tag are returned.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-getfirstelementbytagandclassname"></a>
<a class="mochidef reference" href="#fn-getfirstelementbytagandclassname">getFirstElementByTagAndClassName(tagName, className, parent=document)</a>:</p>
<blockquote>
<p>Return the first element in <tt class="docutils literal"><span class="pre">parent</span></tt> that matches the tag name
and class name provided. If <tt class="docutils literal"><span class="pre">parent</span></tt> is a string, it will be
looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>.</p>
<p>If <tt class="docutils literal"><span class="pre">tagName</span></tt> is <tt class="docutils literal"><span class="pre">null</span></tt> or <tt class="docutils literal"><span class="pre">"*"</span></tt>, all elements will be searched
for the matching class.</p>
<p>If <tt class="docutils literal"><span class="pre">className</span></tt> is <tt class="docutils literal"><span class="pre">null</span></tt>, the first element matching the provided
tag will be returned.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-getfirstparentbytagandclassname"></a>
<a class="mochidef reference" href="#fn-getfirstparentbytagandclassname">getFirstParentByTagAndClassName(elem, tagName='*', className=null)</a>:</p>
<blockquote>
<p>Returns the first parent of <tt class="docutils literal"><span class="pre">elem</span></tt> that matches the tag name and class
name provided. If <tt class="docutils literal"><span class="pre">elem</span></tt> is a string, it will be looked up using
<a class="mochiref reference" href="#fn-getelement">getElement</a>.</p>
<p>If <tt class="docutils literal"><span class="pre">tagName</span></tt> is <tt class="docutils literal"><span class="pre">null</span></tt> or <tt class="docutils literal"><span class="pre">"*"</span></tt>, all elements will be searched
for the matching class.</p>
<p>If <tt class="docutils literal"><span class="pre">className</span></tt> is <tt class="docutils literal"><span class="pre">null</span></tt>, the first element matching the provided
tag name will be returned.</p>
<p>If no match is found, <tt class="docutils literal"><span class="pre">null</span></tt> will be returned.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-getnodeattribute"></a>
<a class="mochidef reference" href="#fn-getnodeattribute">getNodeAttribute(node, attr)</a>:</p>
<blockquote>
<p>Get the value of the given attribute for a DOM element without
ever raising an exception (will return <tt class="docutils literal"><span class="pre">null</span></tt> on exception).</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>A reference to the DOM element to update (if a string is
given, <a class="mochiref reference" href="#fn-getelement">getElement(node)</a> will be used to locate the
node)</dd>
<dt><tt class="docutils literal"><span class="pre">attr</span></tt>:</dt>
<dd><p class="first">The name of the attribute</p>
<p class="last">Note that it will do the right thing for IE, so don't do
the <tt class="docutils literal"><span class="pre">class</span></tt> -> <tt class="docutils literal"><span class="pre">className</span></tt> hack yourself.</p>
</dd>
<dt><em>returns</em>:</dt>
<dd>The attribute's value, or <tt class="docutils literal"><span class="pre">null</span></tt></dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-haselementclass"></a>
<a class="mochidef reference" href="#fn-haselementclass">hasElementClass(element, className[, ...])</a>:</p>
<blockquote>
<p>Return <tt class="docutils literal"><span class="pre">true</span></tt> if <tt class="docutils literal"><span class="pre">className</span></tt> is found on the <tt class="docutils literal"><span class="pre">element</span></tt>.
<tt class="docutils literal"><span class="pre">element</span></tt> is looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>, so string
identifiers are also acceptable.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-ischildnode"></a>
<a class="mochidef reference" href="#fn-ischildnode">isChildNode(node, maybeParent)</a>:</p>
<blockquote>
<p>Determine whether <tt class="docutils literal"><span class="pre">node</span></tt> is a child node or decendant node of
<tt class="docutils literal"><span class="pre">maybeParent</span></tt>. Returns <tt class="docutils literal"><span class="pre">true</span></tt> if so, and <tt class="docutils literal"><span class="pre">false</span></tt> if not.
A node is considered a child node of itself for the purposes of
this function.</p>
<p>If either <tt class="docutils literal"><span class="pre">node</span></tt> or <tt class="docutils literal"><span class="pre">maybeParent</span></tt> are strings, the related
nodes will be looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-registerdomconverter"></a>
<a class="mochidef reference" href="#fn-registerdomconverter">registerDOMConverter(name, check, wrap[, override])</a>:</p>
<blockquote>
<p>Register an adapter to convert objects that match <tt class="docutils literal"><span class="pre">check(obj,</span>
<span class="pre">ctx)</span></tt> to a DOM element, or something that can be converted to a
DOM element (i.e. number, bool, string, function, iterable).</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-removeelement"></a>
<a class="mochidef reference" href="#fn-removeelement">removeElement(node)</a>:</p>
<blockquote>
<p>Remove and return <tt class="docutils literal"><span class="pre">node</span></tt> from a DOM tree.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>the DOM element (or string id of one) to be removed</dd>
<dt><em>returns</em></dt>
<dd>The removed element</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-removeelementclass"></a>
<a class="mochidef reference" href="#fn-removeelementclass">removeElementClass(element, className)</a>:</p>
<blockquote>
<p>Ensure that the given <tt class="docutils literal"><span class="pre">element</span></tt> does not have <tt class="docutils literal"><span class="pre">className</span></tt> set
as part of its class attribute. This will not disturb other class
names. <tt class="docutils literal"><span class="pre">element</span></tt> is looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>, so
string identifiers are also acceptable.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-removeemptytextnodes"></a>
<a class="mochidef reference" href="#fn-removeemptytextnodes">removeEmptyTextNodes(node)</a>:</p>
<blockquote>
<p>Remove all text node children that contain only whitespace from
<tt class="docutils literal"><span class="pre">node</span></tt>. Useful in situations where such empty text nodes can
interfere with DOM traversal.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>the DOM element (or string id of one) to remove whitespace child
nodes from.</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-replacechildnodes"></a>
<a class="mochidef reference" href="#fn-replacechildnodes">replaceChildNodes(node[, childNode[, ...]])</a>:</p>
<blockquote>
<p>Remove all children from the given DOM element, then append any
given childNodes to it (by calling <a class="mochiref reference" href="#fn-appendchildnodes">appendChildNodes</a>).</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>A reference to the DOM element to add children to (if a string
is given, <a class="mochiref reference" href="#fn-getelement">getElement(node)</a> will be used to locate
the node)</dd>
<dt><tt class="docutils literal"><span class="pre">childNode</span></tt>...:</dt>
<dd>All additional arguments, if any, will be coerced into DOM
nodes that are appended as children using the <a class="reference" href="#dom-coercion-rules">DOM Coercion
Rules</a>.</dd>
<dt><em>returns</em>:</dt>
<dd>The given DOM element</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-scrapetext"></a>
<a class="mochidef reference" href="#fn-scrapetext">scrapeText(node[, asArray=false])</a>:</p>
<blockquote>
<p>Walk a DOM tree in-order and scrape all of the text out of it as a
<tt class="docutils literal"><span class="pre">string</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">asArray</span></tt> is <tt class="docutils literal"><span class="pre">true</span></tt>, then an <tt class="docutils literal"><span class="pre">Array</span></tt> will be returned
with each individual text node. These two are equivalent:</p>
<pre class="literal-block">
assert( scrapeText(node) == scrapeText(node, true).join("") );
</pre>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-setelementclass"></a>
<a class="mochidef reference" href="#fn-setelementclass">setElementClass(element, className)</a>:</p>
<blockquote>
<p>Set the entire class attribute of <tt class="docutils literal"><span class="pre">element</span></tt> to <tt class="docutils literal"><span class="pre">className</span></tt>.
<tt class="docutils literal"><span class="pre">element</span></tt> is looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>, so string
identifiers are also acceptable.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-setnodeattribute"></a>
<a class="mochidef reference" href="#fn-setnodeattribute">setNodeAttribute(node, attr, value)</a>:</p>
<blockquote>
<p>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
<a class="mochiref reference" href="#fn-updatenodeattributes">updateNodeAttributes</a>.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>A reference to the DOM element to update (if a string is
given, <a class="mochiref reference" href="#fn-getelement">getElement(node)</a> will be used to locate the
node)</dd>
<dt><tt class="docutils literal"><span class="pre">attr</span></tt>:</dt>
<dd><p class="first">The name of the attribute</p>
<p>Note that it will do the right thing for IE, so don't do the
<tt class="docutils literal"><span class="pre">class</span></tt> -> <tt class="docutils literal"><span class="pre">className</span></tt> hack yourself.</p>
<p class="last">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).</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">value</span></tt>:</dt>
<dd>The value of the attribute, may be an object to be merged
(e.g. for setting style).</dd>
<dt><em>returns</em>:</dt>
<dd>The given DOM element or <tt class="docutils literal"><span class="pre">null</span></tt> on failure</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-swapdom"></a>
<a class="mochidef reference" href="#fn-swapdom">swapDOM(dest, src)</a>:</p>
<blockquote>
<p>Replace <tt class="docutils literal"><span class="pre">dest</span></tt> in a DOM tree with <tt class="docutils literal"><span class="pre">src</span></tt>, returning <tt class="docutils literal"><span class="pre">src</span></tt>.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">dest</span></tt>:</dt>
<dd>a DOM element (or string id of one) to be replaced</dd>
<dt><tt class="docutils literal"><span class="pre">src</span></tt>:</dt>
<dd>the DOM element (or string id of one) to replace it with, or
<tt class="docutils literal"><span class="pre">null</span></tt> if <tt class="docutils literal"><span class="pre">dest</span></tt> is to be removed (replaced with nothing).</dd>
<dt><em>returns</em>:</dt>
<dd>a DOM element (<tt class="docutils literal"><span class="pre">src</span></tt>)</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-swapelementclass"></a>
<a class="mochidef reference" href="#fn-swapelementclass">swapElementClass(element, fromClass, toClass)</a>:</p>
<blockquote>
<p>If <tt class="docutils literal"><span class="pre">fromClass</span></tt> is set on <tt class="docutils literal"><span class="pre">element</span></tt>, replace it with
<tt class="docutils literal"><span class="pre">toClass</span></tt>. This will not disturb other classes on that element.
<tt class="docutils literal"><span class="pre">element</span></tt> is looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>, so string
identifiers are also acceptable.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-toggleelementclass"></a>
<a class="mochidef reference" href="#fn-toggleelementclass">toggleElementClass(className[, element[, ...]])</a>:</p>
<blockquote>
<p>Toggle the presence of a given <tt class="docutils literal"><span class="pre">className</span></tt> in the class
attribute of all given elements. All elements will be looked up
with <a class="mochiref reference" href="#fn-getelement">getElement</a>, so string identifiers are acceptable.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-tohtml"></a>
<a class="mochidef reference" href="#fn-tohtml">toHTML(dom)</a>:</p>
<blockquote>
<p>Convert a DOM tree to a HTML string using <a class="mochiref reference" href="#fn-emithtml">emitHTML</a>.
This should be used for debugging/testing purposes only.</p>
<p>The DOM property <tt class="docutils literal"><span class="pre">innerHTML</span></tt> or <tt class="docutils literal"><span class="pre">cloneNode(true)</span></tt> method should
be used for most purposes.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-updatenodeattributes"></a>
<a class="mochidef reference" href="#fn-updatenodeattributes">updateNodeAttributes(node, attrs)</a>:</p>
<blockquote>
<p>Update the attributes of a DOM element from a given object.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>A reference to the DOM element to update (if a string is
given, <a class="mochiref reference" href="#fn-getelement">getElement(node)</a> will be used to locate the
node)</dd>
<dt><tt class="docutils literal"><span class="pre">attrs</span></tt>:</dt>
<dd><p class="first">An object whose properties will be used to set the attributes
(e.g. <tt class="docutils literal"><span class="pre">{'class':</span> <span class="pre">'invisible'}</span></tt>), or <tt class="docutils literal"><span class="pre">null</span></tt> if no
attributes need to be set. If an object is given for the
attribute value (e.g. <tt class="docutils literal"><span class="pre">{'style':</span> <span class="pre">{'display':</span> <span class="pre">'block'}}</span></tt>)
then <a class="mochiref reference" href="Base.html#fn-updatetree">MochiKit.Base.updatetree</a> will be used to set
that attribute.</p>
<p>Note that it will do the right thing for IE, so don't do the
<tt class="docutils literal"><span class="pre">class</span></tt> -> <tt class="docutils literal"><span class="pre">className</span></tt> hack yourself, and it deals with
setting "on..." event handlers correctly.</p>
<p class="last">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).</p>
</dd>
<dt><em>returns</em>:</dt>
<dd>The given DOM element</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-withwindow"></a>
<a class="mochidef reference" href="#fn-withwindow">withWindow(win, func)</a>:</p>
<blockquote>
<p>Call <tt class="docutils literal"><span class="pre">func</span></tt> with the <tt class="docutils literal"><span class="pre">window</span></tt> <a class="reference" href="#dom-context">DOM Context</a> set to <tt class="docutils literal"><span class="pre">win</span></tt>
and the <tt class="docutils literal"><span class="pre">document</span></tt> <a class="reference" href="#dom-context">DOM Context</a> set to <tt class="docutils literal"><span class="pre">win.document</span></tt>. When
<tt class="docutils literal"><span class="pre">func()</span></tt> returns or throws an error, the <a class="reference" href="#dom-context">DOM Context</a> will be
restored to its previous state.</p>
<p>The return value of <tt class="docutils literal"><span class="pre">func()</span></tt> is returned by this function.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-withdocument"></a>
<a class="mochidef reference" href="#fn-withdocument">withDocument(doc, func)</a>:</p>
<blockquote>
<p>Call <tt class="docutils literal"><span class="pre">func</span></tt> with the <tt class="docutils literal"><span class="pre">doc</span></tt> <a class="reference" href="#dom-context">DOM Context</a> set to <tt class="docutils literal"><span class="pre">doc</span></tt>.
When <tt class="docutils literal"><span class="pre">func()</span></tt> returns or throws an error, the <a class="reference" href="#dom-context">DOM Context</a>
will be restored to its previous state.</p>
<p>The return value of <tt class="docutils literal"><span class="pre">func()</span></tt> is returned by this function.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1+</dd>
</dl>
</blockquote>
</div>
<div class="section">
<h2><a id="style-functions" name="style-functions">Style Functions</a></h2>
<p>These functions were previously available in MochiKit.DOM, but have been
moved to <a class="mochiref reference" href="Style.html">MochiKit.Style</a> in recent versions. Function aliases
remain for backwards compability.</p>
<p>
<a name="fn-computedstyle"></a>
<a class="mochidef reference" href="#fn-computedstyle">computedStyle(htmlElement, cssProperty, mozillaEquivalentCSS)</a>:</p>
<blockquote>
<p>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.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">cssProperty</span></tt>:</dt>
<dd>MochiKit 1.3.1 expects camel case, e.g. <tt class="docutils literal"><span class="pre">backgroundColor</span></tt>.
MochiKit 1.4+ expects CSS selector case, e.g. <tt class="docutils literal"><span class="pre">background-color</span></tt>,
but will accept camel case for backwards-compatibility.</dd>
<dt><tt class="docutils literal"><span class="pre">mozillaEquivalentCSS</span></tt>:</dt>
<dd>MochiKit 1.3.1 expects selector case.
MochiKit 1.4+ ignores this argument.</dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, deprecated in favor of
<a class="mochiref reference" href="Style.html#fn-getstyle">MochiKit.Style.getStyle</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-elementdimensions"></a>
<a class="mochidef reference" href="#fn-elementdimensions">elementDimensions(element)</a>:</p>
<blockquote>
<p>Return the absolute pixel width and height (including padding and border,
but not margins) of <tt class="docutils literal"><span class="pre">element</span></tt> as an object with <tt class="docutils literal"><span class="pre">w</span></tt> and <tt class="docutils literal"><span class="pre">h</span></tt>
properties, or <tt class="docutils literal"><span class="pre">undefined</span></tt> if <tt class="docutils literal"><span class="pre">element</span></tt> is not in the document.
<tt class="docutils literal"><span class="pre">element</span></tt> may be specified as a string to be looked up with
<a class="mochiref reference" href="#fn-getelement">getElement</a>, a DOM element, or trivially as an object with
<tt class="docutils literal"><span class="pre">w</span></tt> and/or <tt class="docutils literal"><span class="pre">h</span></tt> properties.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, deprecated in favor of
<a class="mochiref reference" href="Style.html#fn-getelementdimensions">MochiKit.Style.getElementDimensions</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-elementposition"></a>
<a class="mochidef reference" href="#fn-elementposition">elementPosition(element[, relativeTo={x: 0, y: 0}])</a>:</p>
<blockquote>
<p>Return the absolute pixel position of <tt class="docutils literal"><span class="pre">element</span></tt> in the document
as an object with <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">y</span></tt> properties, or <tt class="docutils literal"><span class="pre">undefined</span></tt> if
<tt class="docutils literal"><span class="pre">element</span></tt> is not in the document. <tt class="docutils literal"><span class="pre">element</span></tt> may be specified
as a string to be looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>, a DOM
element, or trivially as an object with <tt class="docutils literal"><span class="pre">x</span></tt> and/or <tt class="docutils literal"><span class="pre">y</span></tt>
properties.</p>
<p>If <tt class="docutils literal"><span class="pre">relativeTo</span></tt> is given, then its coordinates are subtracted from
the absolute position of <tt class="docutils literal"><span class="pre">element</span></tt>, e.g.:</p>
<pre class="literal-block">
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) );
</pre>
<p><tt class="docutils literal"><span class="pre">relativeTo</span></tt> may be specified as a string to be looked up with
<a class="mochiref reference" href="#fn-getelement">getElement</a>, a DOM element, or trivially as an object
with <tt class="docutils literal"><span class="pre">x</span></tt> and/or <tt class="docutils literal"><span class="pre">y</span></tt> properties.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, deprecated in favor of
<a class="mochiref reference" href="Style.html#fn-getelementposition">MochiKit.Style.getElementPosition</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-getviewportdimensions"></a>
<a class="mochidef reference" href="#fn-getviewportdimensions">getViewportDimensions()</a>:</p>
<blockquote>
<p>Return the pixel width and height of the viewport as an object
with <tt class="docutils literal"><span class="pre">w</span></tt> and <tt class="docutils literal"><span class="pre">h</span></tt> properties. <tt class="docutils literal"><span class="pre">element</span></tt> is looked up with
<a class="mochiref reference" href="#fn-getelement">getElement</a>, so string identifiers are also acceptable.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, moved to
<a class="mochiref reference" href="Style.html#fn-getviewportdimensions">MochiKit.Style.getViewportDimensions</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-hideelement"></a>
<a class="mochidef reference" href="#fn-hideelement">hideElement(element, ...)</a>:</p>
<blockquote>
<p>Partial form of <a class="mochiref reference" href="#fn-setdisplayforelement">setDisplayForElement</a>, specifically:</p>
<pre class="literal-block">
partial(setDisplayForElement, "none")
</pre>
<p>For information about the caveats of using a <tt class="docutils literal"><span class="pre">style.display</span></tt>
based show/hide mechanism, and a CSS based alternative, see
<a class="reference" href="Style.html#element-visibility">Element Visibility</a>.</p>
</blockquote>
<blockquote>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, moved to
<a class="mochiref reference" href="Style.html#fn-hideelement">MochiKit.Style.hideElement</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-makeclipping"></a>
<a class="mochidef reference" href="#fn-makeclipping">makeClipping(element)</a>:</p>
<blockquote>
<p>Ensure that <tt class="docutils literal"><span class="pre">element.style.overflow</span> <span class="pre">=</span> <span class="pre">'hidden'</span></tt>. If <tt class="docutils literal"><span class="pre">element</span></tt> is a
string, then it will be looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>.</p>
<p>Returns the original values of <tt class="docutils literal"><span class="pre">overflow</span></tt>, <tt class="docutils literal"><span class="pre">overflow-y</span></tt> and
<tt class="docutils literal"><span class="pre">overflow-y</span></tt> so that they may be restored with
<a class="mochiref reference" href="#fn-undoclipping">undoClipping(element, overflow)</a>.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+, moved to
<a class="mochiref reference" href="Style.html#fn-makeclipping">MochiKit.Style.makeClipping</a> in 1.4.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-makepositioned"></a>
<a class="mochidef reference" href="#fn-makepositioned">makePositioned(element)</a>:</p>
<blockquote>
<p>Ensure that <tt class="docutils literal"><span class="pre">element.style.position</span></tt> is set to <tt class="docutils literal"><span class="pre">"relative"</span></tt> if it
is not set or is <tt class="docutils literal"><span class="pre">"static"</span></tt>. If <tt class="docutils literal"><span class="pre">element</span></tt> is a
string, then it will be looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+, moved to
<a class="mochiref reference" href="Style.html#fn-makepositioned">MochiKit.Style.makePositioned</a> in 1.4.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-setelementdimensions"></a>
<a class="mochidef reference" href="#fn-setelementdimensions">setElementDimensions(element, dimensions[, units='px'])</a>:</p>
<blockquote>
<p>Sets the dimensions of <tt class="docutils literal"><span class="pre">element</span></tt> in the document from an object
with <tt class="docutils literal"><span class="pre">w</span></tt> and <tt class="docutils literal"><span class="pre">h</span></tt> properties.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>A reference to the DOM element to update (if a string is
given, <a class="mochiref reference" href="#fn-getelement">getElement(node)</a> will be used to locate the
node)</dd>
<dt><tt class="docutils literal"><span class="pre">dimensions</span></tt>:</dt>
<dd>An object with <tt class="docutils literal"><span class="pre">w</span></tt> and <tt class="docutils literal"><span class="pre">h</span></tt> properties</dd>
<dt><tt class="docutils literal"><span class="pre">units</span></tt>:</dt>
<dd>Optionally set the units to use, default is <tt class="docutils literal"><span class="pre">px</span></tt></dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, moved to
<a class="mochiref reference" href="Style.html#fn-setelementdimensions">MochiKit.Style.setElementDimensions</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-setelementposition"></a>
<a class="mochidef reference" href="#fn-setelementposition">setElementPosition(element, position[, units='px'])</a>:</p>
<blockquote>
<p>Sets the absolute position of <tt class="docutils literal"><span class="pre">element</span></tt> in the document from an
object with <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">y</span></tt> properties.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">node</span></tt>:</dt>
<dd>A reference to the DOM element to update (if a string is
given, <a class="mochiref reference" href="#fn-getelement">getElement(node)</a> will be used to locate the
node)</dd>
<dt><tt class="docutils literal"><span class="pre">position</span></tt>:</dt>
<dd>An object with <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">y</span></tt> properties</dd>
<dt><tt class="docutils literal"><span class="pre">units</span></tt>:</dt>
<dd>Optionally set the units to use, default is <tt class="docutils literal"><span class="pre">px</span></tt></dd>
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, moved to
<a class="mochiref reference" href="Style.html#fn-setelementposition">MochiKit.Style.setElementPosition</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-setdisplayforelement"></a>
<a class="mochidef reference" href="#fn-setdisplayforelement">setDisplayForElement(display, element[, ...])</a>:</p>
<blockquote>
<p>Change the <tt class="docutils literal"><span class="pre">style.display</span></tt> for the given element(s). Usually
used as the partial forms:</p>
<ul class="simple">
<li><a class="mochiref reference" href="#fn-showelement">showElement(element, ...)</a></li>
<li><a class="mochiref reference" href="#fn-hideelement">hideElement(element, ...)</a></li>
</ul>
<p>Elements are looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>, so string
identifiers are acceptable.</p>
<p>For information about the caveats of using a <tt class="docutils literal"><span class="pre">style.display</span></tt>
based show/hide mechanism, and a CSS based alternative, see
<a class="reference" href="Style.html#element-visibility">Element Visibility</a>.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, moved to
<a class="mochiref reference" href="Style.html#fn-setdisplayforelement">MochiKit.Style.setDisplayForElement</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-setopacity"></a>
<a class="mochidef reference" href="#fn-setopacity">setOpacity(element, opacity)</a>:</p>
<blockquote>
<p>Sets <tt class="docutils literal"><span class="pre">opacity</span></tt> for <tt class="docutils literal"><span class="pre">element</span></tt>. Valid <tt class="docutils literal"><span class="pre">opacity</span></tt> values range
from 0 (invisible) to 1 (opaque). <tt class="docutils literal"><span class="pre">element</span></tt> is looked up with
<a class="mochiref reference" href="#fn-getelement">getElement</a>, so string identifiers are also acceptable.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, moved to
<a class="mochiref reference" href="Style.html#fn-setopacity">MochiKit.Style.setOpacity</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-showelement"></a>
<a class="mochidef reference" href="#fn-showelement">showElement(element, ...)</a>:</p>
<blockquote>
<p>Partial form of <a class="mochiref reference" href="#fn-setdisplayforelement">setDisplayForElement</a>, specifically:</p>
<pre class="literal-block">
partial(setDisplayForElement, "block")
</pre>
<p>For information about the caveats of using a <tt class="docutils literal"><span class="pre">style.display</span></tt>
based show/hide mechanism, and a CSS based alternative, see
<a class="reference" href="Style.html#element-visibility">Element Visibility</a>.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.3.1, moved to
<a class="mochiref reference" href="Style.html#fn-showelement">MochiKit.Style.showElement</a> in 1.4+</dd>
</dl>
</blockquote>
<p>
<a name="fn-undoclipping"></a>
<a class="mochidef reference" href="#fn-undoclipping">undoClipping(element, overflow)</a>:</p>
<blockquote>
<p>Restore the setting of <tt class="docutils literal"><span class="pre">element.style.overflow</span></tt> set by
<a class="mochiref reference" href="#fn-makeclipping">makeClipping(element)</a>. If <tt class="docutils literal"><span class="pre">element</span></tt> is a string, then
it will be looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+, moved to
<a class="mochiref reference" href="Style.html#fn-undoclipping">MochiKit.Style.undoClipping</a> in 1.4.1+</dd>
</dl>
</blockquote>
<p>
<a name="fn-undopositioned"></a>
<a class="mochidef reference" href="#fn-undopositioned">undoPositioned(element)</a>:</p>
<blockquote>
<p>Restore the setting of <tt class="docutils literal"><span class="pre">element.style.position</span></tt> set by
<a class="mochiref reference" href="#fn-makepositioned">makePositioned(element)</a>. If <tt class="docutils literal"><span class="pre">element</span></tt> is a string, then
it will be looked up with <a class="mochiref reference" href="#fn-getelement">getElement</a>.</p>
<dl class="docutils">
<dt><em>Availability</em>:</dt>
<dd>Available in MochiKit 1.4+, moved to
<a class="mochiref reference" href="Style.html#fn-undopositioned">MochiKit.Style.undoPositioned</a> in 1.4.1+</dd>
</dl>
</blockquote>
</div>
<div class="section">
<h2><a id="style-objects" name="style-objects">Style Objects</a></h2>
<p>These objects are available in MochiKit 1.3.1, but have been moved to
<a class="mochiref reference" href="Style.html">MochiKit.Style</a> in 1.4+.</p>
<p>
<a name="fn-coordinates"></a>
<a class="mochidef reference" href="#fn-coordinates">Coordinates(x, y)</a>:</p>
<blockquote>
<p>Constructs an object with <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">y</span></tt> properties. <tt class="docutils literal"><span class="pre">obj.toString()</span></tt>
returns something like <tt class="docutils literal"><span class="pre">{x:</span> <span class="pre">0,</span> <span class="pre">y:</span> <span class="pre">42}</span></tt> for debugging.</p>
<p><em>Availability</em>:
Available in MochiKit 1.3.1, moved to
<a class="mochiref reference" href="Style.html#fn-coordinates">MochiKit.Style.Coordinates</a> in 1.4+</p>
</blockquote>
<p>
<a name="fn-dimensions"></a>
<a class="mochidef reference" href="#fn-dimensions">Dimensions(w, h)</a>:</p>
<blockquote>
<p>Constructs an object with <tt class="docutils literal"><span class="pre">w</span></tt> and <tt class="docutils literal"><span class="pre">h</span></tt> properties. <tt class="docutils literal"><span class="pre">obj.toString()</span></tt>
returns something like <tt class="docutils literal"><span class="pre">{w:</span> <span class="pre">0,</span> <span class="pre">h:</span> <span class="pre">42}</span></tt> for debugging.</p>
<p><em>Availability</em>:
Available in MochiKit 1.3.1, moved to
<a class="mochiref reference" href="Style.html#fn-dimensions">MochiKit.Style.Dimensions</a> in 1.4+</p>
</blockquote>
</div>
</div>
<div class="section">
<h1><a id="see-also" name="see-also">See Also</a></h1>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id5">[1]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> Nevow, a web application construction kit for Python:
<a class="reference" href="http://divmod.org/trac/wiki/DivmodNevow">http://divmod.org/trac/wiki/DivmodNevow</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id6">[2]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id4">2</a>)</em> 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:
<a class="reference" href="http://divmod.org/trac/wiki/DivmodNevow">http://divmod.org/trac/wiki/DivmodNevow</a></td></tr>
</tbody>
</table>
</div>
<div class="section">
<h1><a id="authors" name="authors">Authors</a></h1>
<ul class="simple">
<li>Bob Ippolito <<a class="reference" href="mailto:bob@redivi.com">bob@redivi.com</a>></li>
</ul>
</div>
<div class="section">
<h1><a id="copyright" name="copyright">Copyright</a></h1>
<p>Copyright 2005 Bob Ippolito <<a class="reference" href="mailto:bob@redivi.com">bob@redivi.com</a>>. This program is
dual-licensed free software; you can redistribute it and/or modify it
under the terms of the <a class="reference" href="http://www.opensource.org/licenses/mit-license.php">MIT License</a> or the <a class="reference" href="http://www.opensource.org/licenses/afl-2.1.php">Academic Free License
v2.1</a>.</p>
</div>
</div>
</body>
</html>
