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