Commit | Line | Data |
---|---|---|
6a1aa64f DV |
1 | .. title:: MochiKit.DOM - painless DOM manipulation API |
2 | ||
3 | Name | |
4 | ==== | |
5 | ||
6 | MochiKit.DOM - painless DOM manipulation API | |
7 | ||
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | :: | |
13 | ||
14 | var rows = [ | |
15 | ["dataA1", "dataA2", "dataA3"], | |
16 | ["dataB1", "dataB2", "dataB3"] | |
17 | ]; | |
18 | row_display = function (row) { | |
19 | return TR(null, map(partial(TD, null), row)); | |
20 | } | |
21 | var newTable = TABLE({'class': 'prettytable'}, | |
22 | THEAD(null, | |
23 | row_display(["head1", "head2", "head3"])), | |
24 | TFOOT(null, | |
25 | row_display(["foot1", "foot2", "foot3"])), | |
26 | TBODY(null, | |
27 | map(row_display, rows))); | |
28 | // put that in your document.createElement and smoke it! | |
29 | swapDOM(oldTable, newTable); | |
30 | ||
31 | ||
32 | Description | |
33 | =========== | |
34 | ||
35 | As you probably know, the DOM APIs are some of the most painful | |
36 | Java-inspired APIs you'll run across from a highly dynamic | |
37 | language. Don't worry about that though, because they provide a | |
38 | reasonable basis to build something that sucks a lot less. | |
39 | ||
40 | MochiKit.DOM takes much of its inspiration from Nevow's [1]_ stan | |
41 | [2]_. This means you choose a tag, give it some attributes, then | |
42 | stuff it full of *whatever objects you want*. MochiKit.DOM isn't | |
43 | stupid, it knows that a string should be a text node, and that you | |
44 | want functions to be called, and that ``Array``-like objects should be | |
45 | expanded, and stupid ``null`` values should be skipped. | |
46 | ||
47 | Hell, it will let you return strings from functions, and use iterators | |
48 | from :mochiref:`MochiKit.Iter`. If that's not enough, just teach it | |
49 | new tricks with :mochiref:`registerDOMConverter`. If you have never | |
50 | used an API like this for creating DOM elements, you've been wasting | |
51 | your damn time. Get with it! | |
52 | ||
53 | ||
54 | Dependencies | |
55 | ============ | |
56 | ||
57 | - :mochiref:`MochiKit.Base` | |
58 | - :mochiref:`MochiKit.Style` (optional since MochiKit 1.4 for | |
59 | backwards-compatibility) | |
60 | - :mochiref:`MochiKit.Iter` (optional since MochiKit 1.4) | |
61 | ||
62 | ||
63 | Overview | |
64 | ======== | |
65 | ||
66 | DOM Coercion Rules | |
67 | ------------------ | |
68 | ||
69 | In order of precedence, :mochiref:`createDOM` coerces given arguments | |
70 | to DOM nodes using the following rules: | |
71 | ||
72 | 1. Functions are called with a ``this`` and first argument of the | |
73 | parent node and their return value is subject to the following | |
74 | rules (even this one). | |
75 | 2. ``undefined`` and ``null`` are ignored. | |
76 | 3. If :mochiref:`MochiKit.Iter` is loaded, iterables are flattened | |
77 | (as if they were passed in-line as nodes) and each return value is | |
78 | subject to these rules. | |
79 | 4. Values that look like DOM nodes (objects with a ``.nodeType > 0``) | |
80 | are ``.appendChild``'ed to the created DOM fragment. | |
81 | 5. Strings are wrapped up with ``document.createTextNode`` | |
82 | 6. Objects that have a ``.dom(node)`` or ``.__dom__(node)`` method | |
83 | are called with the parent node and their result is coerced using | |
84 | these rules. (MochiKit 1.4+). | |
85 | 7. Objects that are not strings are run through the ``domConverters`` | |
86 | :mochiref:`MochiKit.Base.AdapterRegistry` (see | |
87 | :mochiref:`registerDOMConverter`). The adapted value is subject | |
88 | to these same rules (e.g. if the adapter returns a string, it | |
89 | will be coerced to a text node). | |
90 | 8. If no adapter is available, ``.toString()`` is used to create a | |
91 | text node. | |
92 | ||
93 | ||
94 | Creating DOM Element Trees | |
95 | -------------------------- | |
96 | ||
97 | :mochiref:`createDOM` provides you with an excellent facility for | |
98 | creating DOM trees that is easy on the wrists. One of the best ways to | |
99 | understand how to use it is to take a look at an example:: | |
100 | ||
101 | var rows = [ | |
102 | ["dataA1", "dataA2", "dataA3"], | |
103 | ["dataB1", "dataB2", "dataB3"] | |
104 | ]; | |
105 | row_display = function (row) { | |
106 | return TR(null, map(partial(TD, null), row)); | |
107 | } | |
108 | var newTable = TABLE({'class': 'prettytable'}, | |
109 | THEAD(null, | |
110 | row_display(["head1", "head2", "head3"])), | |
111 | TFOOT(null, | |
112 | row_display(["foot1", "foot2", "foot3"])), | |
113 | TBODY(null, | |
114 | map(row_display, rows))); | |
115 | ||
116 | ||
117 | This will create a table with the following visual layout (if it were | |
118 | inserted into the document DOM): | |
119 | ||
120 | +--------+--------+--------+ | |
121 | | head1 | head2 | head3 | | |
122 | +========+========+========+ | |
123 | | dataA1 | dataA2 | dataA3 | | |
124 | +--------+--------+--------+ | |
125 | | dataB1 | dataB2 | dataB3 | | |
126 | +--------+--------+--------+ | |
127 | | foot1 | foot2 | foot3 | | |
128 | +--------+--------+--------+ | |
129 | ||
130 | Corresponding to the following HTML:: | |
131 | ||
132 | <table class="prettytable"> | |
133 | <thead> | |
134 | <tr> | |
135 | <td>head1</td> | |
136 | <td>head2</td> | |
137 | <td>head3</td> | |
138 | </tr> | |
139 | </thead> | |
140 | <tfoot> | |
141 | <tr> | |
142 | <td>foot1</td> | |
143 | <td>foot2</td> | |
144 | <td>foot3</td> | |
145 | </tr> | |
146 | </tfoot> | |
147 | <tbody> | |
148 | <tr> | |
149 | <td>dataA1</td> | |
150 | <td>dataA2</td> | |
151 | <td>dataA3</td> | |
152 | </tr> | |
153 | <tr> | |
154 | <td>dataB1</td> | |
155 | <td>dataB2</td> | |
156 | <td>dataB3</td> | |
157 | </tr> | |
158 | </tbody> | |
159 | </table> | |
160 | ||
161 | ||
162 | DOM Context | |
163 | ----------- | |
164 | ||
165 | In order to prevent having to pass a ``window`` and/or ``document`` | |
166 | variable to every MochiKit.DOM function (e.g. when working with a | |
167 | child window), MochiKit.DOM maintains a context variable for each of | |
168 | them. They are managed with the :mochiref:`withWindow` and | |
169 | :mochiref:`withDocument` functions, and can be acquired with | |
170 | :mochiref:`currentWindow()` and :mochiref:`currentDocument()` | |
171 | ||
172 | For example, if you are creating DOM nodes in a child window, you | |
173 | could do something like this:: | |
174 | ||
175 | withWindow(child, function () { | |
176 | var doc = currentDocument(); | |
177 | appendChildNodes(doc.body, H1(null, "This is in the child!")); | |
178 | }); | |
179 | ||
180 | Note that :mochiref:`withWindow(win, ...)` also implies | |
181 | :mochiref:`withDocument(win.document, ...)`. | |
182 | ||
183 | ||
184 | DOM Gotchas | |
185 | ----------- | |
186 | ||
187 | Performance Tradeoff: | |
188 | DOM is much easier to get correct and more flexible than working | |
189 | directly with markup as strings. Modifying ``innerHTML`` is still | |
190 | the fastest way to make document changes. | |
191 | ||
192 | Internet Explorer: | |
193 | Internet Explorer's DOM implementation is quite poor in comparison | |
194 | to the other popular implementations. In order to avoid memory | |
195 | leaks due to circular references, you should use | |
196 | :mochiref:`MochiKit.Signal.connect` for all of your event handling | |
197 | needs. Additionally, when creating tables with DOM, it is required | |
198 | to use a ``TBODY`` tag (see `Creating DOM Element Trees`_ for an | |
199 | example of this). | |
200 | ||
201 | ||
202 | API Reference | |
203 | ============= | |
204 | ||
205 | Functions | |
206 | --------- | |
207 | ||
208 | :mochidef:`$(id[, ...])`: | |
209 | ||
210 | An alias for :mochiref:`getElement(id[, ...])` | |
211 | ||
212 | *Availability*: | |
213 | Available in MochiKit 1.3.1+ | |
214 | ||
215 | ||
216 | :mochidef:`addElementClass(element, className)`: | |
217 | ||
218 | Ensure that the given ``element`` has ``className`` set as part of | |
219 | its class attribute. This will not disturb other class names. | |
220 | ``element`` is looked up with :mochiref:`getElement`, so string | |
221 | identifiers are also acceptable. | |
222 | ||
223 | *Availability*: | |
224 | Available in MochiKit 1.3.1+ | |
225 | ||
226 | ||
227 | :mochidef:`addLoadEvent(func)`: | |
228 | ||
229 | Note that :mochiref:`addLoadEvent` can not be used in combination | |
230 | with :mochiref:`MochiKit.Signal` if the ``onload`` event is | |
231 | connected. Once an event is connected with | |
232 | :mochiref:`MochiKit.Signal`, no other APIs may be used for that | |
233 | same event. | |
234 | ||
235 | This will stack ``window.onload`` functions on top of each other. | |
236 | Each function added will be called after ``onload`` in the order | |
237 | that they were added. | |
238 | ||
239 | *Availability*: | |
240 | Available in MochiKit 1.3.1+ | |
241 | ||
242 | ||
243 | :mochidef:`addToCallStack(target, path, func[, once])`: | |
244 | ||
245 | Note that :mochiref:`addToCallStack` is not compatible with | |
246 | :mochiref:`MochiKit.Signal`. Once an event is connected with | |
247 | :mochiref:`MochiKit.Signal`, no other APIs may be used for that | |
248 | same event. | |
249 | ||
250 | Set the property ``path`` of ``target`` to a function that calls | |
251 | the existing function at that property (if any), then calls | |
252 | ``func``. | |
253 | ||
254 | If ``target[path]()`` returns exactly ``false``, then ``func`` | |
255 | will not be called. | |
256 | ||
257 | If ``once`` is ``true``, then ``target[path]`` is set to ``null`` | |
258 | after the function call stack has completed. | |
259 | ||
260 | If called several times for the same ``target[path]``, it will | |
261 | create a stack of functions (instead of just a pair). | |
262 | ||
263 | *Availability*: | |
264 | Available in MochiKit 1.3.1+ | |
265 | ||
266 | ||
267 | :mochidef:`appendChildNodes(node[, childNode[, ...]])`: | |
268 | ||
269 | Append children to a DOM element using the `DOM Coercion Rules`_. | |
270 | ||
271 | ``node``: | |
272 | A reference to the DOM element to add children to (if a string | |
273 | is given, :mochiref:`getElement(node)` will be used to locate | |
274 | the node) | |
275 | ||
276 | ``childNode``...: | |
277 | All additional arguments, if any, will be coerced into DOM | |
278 | nodes that are appended as children using the `DOM Coercion | |
279 | Rules`_. | |
280 | ||
281 | *returns*: | |
282 | The given DOM element | |
283 | ||
284 | *Availability*: | |
285 | Available in MochiKit 1.3.1+ | |
286 | ||
287 | :mochidef:`insertSiblingNodesBefore(node[, siblingNode[, ...]])`: | |
288 | ||
289 | Insert children into the DOM structure using the `DOM Coercion | |
290 | Rules`_. | |
291 | ||
292 | ``node``: | |
293 | A reference to the DOM element you want to insert children | |
294 | before (if a string is given, :mochiref:`getElement(node)` | |
295 | will be used to locate the node) | |
296 | ||
297 | ``siblingNode``...: | |
298 | All additional arguments, if any, will be coerced into DOM | |
299 | nodes that are inserted as siblings using the `DOM Coercion | |
300 | Rules`_. | |
301 | ||
302 | *returns*: | |
303 | The parent of the given DOM element | |
304 | ||
305 | *Availability*: | |
306 | Available in MochiKit 1.4+ | |
307 | ||
308 | ||
309 | :mochidef:`insertSiblingNodesAfter(node[, siblingNode[, ...]])`: | |
310 | ||
311 | Insert children into the DOM structure using the `DOM Coercion | |
312 | Rules`_. | |
313 | ||
314 | ``node``: | |
315 | A reference to the DOM element you want to insert children | |
316 | after (if a string is given, :mochiref:`getElement(node)` | |
317 | will be used to locate the node) | |
318 | ||
319 | ``siblingNode``...: | |
320 | All additional arguments, if any, will be coerced into DOM | |
321 | nodes that are inserted as siblings using the `DOM Coercion | |
322 | Rules`_. | |
323 | ||
324 | *returns*: | |
325 | The parent of the given DOM element | |
326 | ||
327 | *Availability*: | |
328 | Available in MochiKit 1.4+ | |
329 | ||
330 | ||
331 | :mochidef:`createDOM(name[, attrs[, node[, ...]]])`: | |
332 | ||
333 | Create a DOM fragment in a really convenient manner, much like | |
334 | Nevow`s [1]_ stan [2]_. | |
335 | ||
336 | Partially applied versions of this function for common tags are | |
337 | available as aliases: | |
338 | ||
339 | - ``A`` | |
340 | - ``BUTTON`` | |
341 | - ``BR`` | |
342 | - ``CANVAS`` | |
343 | - ``DIV`` | |
344 | - ``FIELDSET`` | |
345 | - ``FORM`` | |
346 | - ``H1`` | |
347 | - ``H2`` | |
348 | - ``H3`` | |
349 | - ``HR`` | |
350 | - ``IMG`` | |
351 | - ``INPUT`` | |
352 | - ``LABEL`` | |
353 | - ``LEGEND`` | |
354 | - ``LI`` | |
355 | - ``OL`` | |
356 | - ``OPTGROUP`` | |
357 | - ``OPTION`` | |
358 | - ``P`` | |
359 | - ``PRE`` | |
360 | - ``SELECT`` | |
361 | - ``SPAN`` | |
362 | - ``STRONG`` | |
363 | - ``TABLE`` | |
364 | - ``TBODY`` | |
365 | - ``TD`` | |
366 | - ``TEXTAREA`` | |
367 | - ``TFOOT`` | |
368 | - ``TH`` | |
369 | - ``THEAD`` | |
370 | - ``TR`` | |
371 | - ``TT`` | |
372 | - ``UL`` | |
373 | ||
374 | See `Creating DOM Element Trees`_ for a comprehensive example. | |
375 | ||
376 | ``name``: | |
377 | The kind of fragment to create (e.g. 'span'), such as you | |
378 | would pass to ``document.createElement``. | |
379 | ||
380 | ``attrs``: | |
381 | An object whose properties will be used as the attributes | |
382 | (e.g. ``{'style': 'display:block'}``), or ``null`` if no | |
383 | attributes need to be set. | |
384 | ||
385 | See :mochiref:`updateNodeAttributes` for more information. | |
386 | ||
387 | For convenience, if ``attrs`` is a string, ``null`` is used | |
388 | and the string will be considered the first ``node``. | |
389 | ||
390 | ``node``...: | |
391 | All additional arguments, if any, will be coerced into DOM | |
392 | nodes that are appended as children using the `DOM Coercion | |
393 | Rules`_. | |
394 | ||
395 | *returns*: | |
396 | A DOM element | |
397 | ||
398 | *Availability*: | |
399 | Available in MochiKit 1.3.1+ | |
400 | ||
401 | ||
402 | :mochidef:`createDOMFunc(tag[, attrs[, node[, ...]]])`: | |
403 | ||
404 | Convenience function to create a partially applied createDOM | |
405 | function. You'd want to use this if you add additional convenience | |
406 | functions for creating tags, or if you find yourself creating a | |
407 | lot of tags with a bunch of the same attributes or contents. | |
408 | ||
409 | See :mochiref:`createDOM` for more detailed descriptions of the | |
410 | arguments. | |
411 | ||
412 | ``tag``: | |
413 | The name of the tag | |
414 | ||
415 | ``attrs``: | |
416 | Optionally specify the attributes to apply | |
417 | ||
418 | ``node``...: | |
419 | Optionally specify any children nodes it should have | |
420 | ||
421 | *returns*: | |
422 | function that takes additional arguments and calls | |
423 | :mochiref:`createDOM` | |
424 | ||
425 | *Availability*: | |
426 | Available in MochiKit 1.3.1+ | |
427 | ||
428 | ||
429 | :mochidef:`currentDocument()`: | |
430 | ||
431 | Return the current ``document`` `DOM Context`_. This will always | |
432 | be the same as the global ``document`` unless | |
433 | :mochiref:`withDocument` or :mochiref:`withWindow` is currently | |
434 | executing. | |
435 | ||
436 | *Availability*: | |
437 | Available in MochiKit 1.3.1+ | |
438 | ||
439 | ||
440 | :mochidef:`currentWindow()`: | |
441 | ||
442 | Return the current ``window`` `DOM Context`_. This will always be | |
443 | the same as the global ``window`` unless :mochiref:`withWindow` is | |
444 | currently executing. | |
445 | ||
446 | *Availability*: | |
447 | Available in MochiKit 1.3.1+ | |
448 | ||
449 | ||
450 | :mochidef:`emitHTML(dom[, lst])`: | |
451 | ||
452 | Convert a DOM tree to an ``Array`` of HTML string fragments. This should | |
453 | be used for debugging/testing purposes only. | |
454 | ||
455 | The DOM property ``innerHTML`` or ``cloneNode(true)`` method should | |
456 | be used for most purposes. | |
457 | ||
458 | *Availability*: | |
459 | Available in MochiKit 1.3.1+ | |
460 | ||
461 | ||
462 | :mochidef:`escapeHTML(s)`: | |
463 | ||
464 | Make a string safe for HTML, converting the usual suspects (lt, | |
465 | gt, quot, amp) | |
466 | ||
467 | *Availability*: | |
468 | Available in MochiKit 1.3.1+ | |
469 | ||
470 | ||
471 | :mochidef:`focusOnLoad(element)`: | |
472 | ||
473 | Note that :mochiref:`focusOnLoad` can not be used in combination | |
474 | with :mochiref:`MochiKit.Signal` if the ``onload`` event is | |
475 | connected. Once an event is connected with | |
476 | :mochiref:`MochiKit.Signal`, no other APIs may be used for that | |
477 | same event. | |
478 | ||
479 | This adds an onload event to focus the given element. | |
480 | ||
481 | *Availability*: | |
482 | Available in MochiKit 1.3.1+ | |
483 | ||
484 | ||
485 | :mochidef:`formContents(elem=document.body)`: | |
486 | ||
487 | Search the DOM tree, starting at ``elem``, for any elements with a | |
488 | ``name`` and ``value`` attribute. Return a 2-element ``Array`` of | |
489 | ``names`` and ``values`` suitable for use with | |
490 | :mochiref:`MochiKit.Base.queryString`. | |
491 | ||
492 | *Availability*: | |
493 | Available in MochiKit 1.3.1+ | |
494 | ||
495 | ||
496 | :mochidef:`getElement(id[, ...])`: | |
497 | ||
498 | A small quick little function to encapsulate the | |
499 | ``getElementById`` method. It includes a check to ensure we can | |
500 | use that method. | |
501 | ||
502 | If the id isn't a string, it will be returned as-is. | |
503 | ||
504 | Also available as :mochiref:`$(...)` for convenience and | |
505 | compatibility with other JavaScript frameworks. | |
506 | ||
507 | If multiple arguments are given, an ``Array`` will be returned. | |
508 | ||
509 | *Availability*: | |
510 | Available in MochiKit 1.3.1+ | |
511 | ||
512 | ||
513 | :mochidef:`getElementsByTagAndClassName(tagName, className, parent=document)`: | |
514 | ||
515 | Returns an array of elements in ``parent`` that match the tag name | |
516 | and class name provided. If ``parent`` is a string, it will be | |
517 | looked up with :mochiref:`getElement`. | |
518 | ||
519 | If ``tagName`` is ``null`` or ``"*"``, all elements will be | |
520 | searched for the matching class. | |
521 | ||
522 | If ``className`` is ``null``, all elements matching the provided | |
523 | tag are returned. | |
524 | ||
525 | *Availability*: | |
526 | Available in MochiKit 1.3.1+ | |
527 | ||
528 | ||
529 | :mochidef:`getFirstElementByTagAndClassName(tagName, className, parent=document)`: | |
530 | ||
531 | Return the first element in ``parent`` that matches the tag name | |
532 | and class name provided. If ``parent`` is a string, it will be | |
533 | looked up with :mochiref:`getElement`. | |
534 | ||
535 | If ``tagName`` is ``null`` or ``"*"``, all elements will be searched | |
536 | for the matching class. | |
537 | ||
538 | If ``className`` is ``null``, the first element matching the provided | |
539 | tag will be returned. | |
540 | ||
541 | *Availability*: | |
542 | Available in MochiKit 1.4+ | |
543 | ||
544 | ||
545 | :mochidef:`getFirstParentByTagAndClassName(elem, tagName='*', className=null)`: | |
546 | ||
547 | Returns the first parent of ``elem`` matches the tag name and class name | |
548 | provided. If parent is a string, it will be looked up using | |
549 | :mochiref:`getElement`. | |
550 | ||
551 | If ``tagName`` is ``null`` or ``"*"``, all elements will be searched | |
552 | for the matching class. | |
553 | ||
554 | If ``className`` is ``null``, the first element matching the provided | |
555 | tag will be returned. | |
556 | ||
557 | *Availability*: | |
558 | Available in MochiKit 1.4+ | |
559 | ||
560 | ||
561 | :mochidef:`getNodeAttribute(node, attr)`: | |
562 | ||
563 | Get the value of the given attribute for a DOM element without | |
564 | ever raising an exception (will return ``null`` on exception). | |
565 | ||
566 | ``node``: | |
567 | A reference to the DOM element to update (if a string is | |
568 | given, :mochiref:`getElement(node)` will be used to locate the | |
569 | node) | |
570 | ||
571 | ``attr``: | |
572 | The name of the attribute | |
573 | ||
574 | Note that it will do the right thing for IE, so don't do | |
575 | the ``class`` -> ``className`` hack yourself. | |
576 | ||
577 | *returns*: | |
578 | The attribute's value, or ``null`` | |
579 | ||
580 | *Availability*: | |
581 | Available in MochiKit 1.3.1+ | |
582 | ||
583 | ||
584 | :mochidef:`hasElementClass(element, className[, ...])`: | |
585 | ||
586 | Return ``true`` if ``className`` is found on the ``element``. | |
587 | ``element`` is looked up with :mochiref:`getElement`, so string | |
588 | identifiers are also acceptable. | |
589 | ||
590 | *Availability*: | |
591 | Available in MochiKit 1.3.1+ | |
592 | ||
593 | ||
594 | :mochidef:`isChildNode(node, maybeParent)`: | |
595 | ||
596 | Determine whether ``node`` is a child node of ``maybeParent``. | |
597 | Returns ``true`` if so, and ``false`` if not. A node is considered | |
598 | a child node of itself for the purposes of this function. | |
599 | ||
600 | If either ``node`` or ``maybeParent`` are strings, the related | |
601 | nodes will be looked up with :mochiref:`getElement`. | |
602 | ||
603 | *Availability*: | |
604 | Available in MochiKit 1.4+ | |
605 | ||
606 | ||
607 | :mochidef:`isParent(child, element)`: | |
608 | ||
609 | Returns ``true`` if ``element`` contains ``child``. Returns ``false`` | |
610 | if ``element == child`` or ``child`` is not contained in ``element``. | |
611 | If ``child`` or ``element`` are strings, they will be looked up with | |
612 | :mochiref:`getElement`. | |
613 | ||
614 | *Availability*: | |
615 | Available in MochiKit 1.4+ | |
616 | ||
617 | ||
618 | :mochidef:`makeClipping(element)`: | |
619 | ||
620 | Ensure that ``element.style.overflow = 'hidden'``. If ``element`` is a | |
621 | string, then it will be looked up with :mochiref:`getElement`. | |
622 | ||
623 | Returns the original value of ``element.style.overflow``, so that it | |
624 | may be restored with :mochiref:`undoClipping(element, overflow)`. | |
625 | ||
626 | *Availability*: | |
627 | Available in MochiKit 1.4+ | |
628 | ||
629 | ||
630 | :mochidef:`makePositioned(element)`: | |
631 | ||
632 | Ensure that ``element.style.position`` is set to ``"relative"`` if it | |
633 | is not set or is ``"static"``. If ``element`` is a | |
634 | string, then it will be looked up with :mochiref:`getElement`. | |
635 | ||
636 | Returns the original value of ``element.style.position``, so that it | |
637 | may be restored with :mochiref:`undoPositioned(element, position)`. | |
638 | ||
639 | *Availability*: | |
640 | Available in MochiKit 1.4+ | |
641 | ||
642 | ||
643 | :mochidef:`registerDOMConverter(name, check, wrap[, override])`: | |
644 | ||
645 | Register an adapter to convert objects that match ``check(obj, | |
646 | ctx)`` to a DOM element, or something that can be converted to a | |
647 | DOM element (i.e. number, bool, string, function, iterable). | |
648 | ||
649 | *Availability*: | |
650 | Available in MochiKit 1.3.1+ | |
651 | ||
652 | ||
653 | :mochidef:`removeElement(node)`: | |
654 | ||
655 | Remove and return ``node`` from a DOM tree. | |
656 | ||
657 | ``node``: | |
658 | the DOM element (or string id of one) to be removed | |
659 | ||
660 | *returns* | |
661 | The removed element | |
662 | ||
663 | *Availability*: | |
664 | Available in MochiKit 1.3.1+ | |
665 | ||
666 | ||
667 | :mochidef:`removeElementClass(element, className)`: | |
668 | ||
669 | Ensure that the given ``element`` does not have ``className`` set | |
670 | as part of its class attribute. This will not disturb other class | |
671 | names. ``element`` is looked up with :mochiref:`getElement`, so | |
672 | string identifiers are also acceptable. | |
673 | ||
674 | *Availability*: | |
675 | Available in MochiKit 1.3.1+ | |
676 | ||
677 | ||
678 | :mochidef:`removeEmptyTextNodes(node)`: | |
679 | ||
680 | Remove all text node children that contain only whitespace from | |
681 | ``node``. Useful in situations where such empty text nodes can | |
682 | interfere with DOM traversal. | |
683 | ||
684 | ``node``: | |
685 | the DOM element (or string id of one) to remove whitespace child | |
686 | nodes from. | |
687 | ||
688 | *Availability*: | |
689 | Available in MochiKit 1.4+ | |
690 | ||
691 | ||
692 | :mochidef:`replaceChildNodes(node[, childNode[, ...]])`: | |
693 | ||
694 | Remove all children from the given DOM element, then append any | |
695 | given childNodes to it (by calling :mochiref:`appendChildNodes`). | |
696 | ||
697 | ``node``: | |
698 | A reference to the DOM element to add children to (if a string | |
699 | is given, :mochiref:`getElement(node)` will be used to locate | |
700 | the node) | |
701 | ||
702 | ``childNode``...: | |
703 | All additional arguments, if any, will be coerced into DOM | |
704 | nodes that are appended as children using the `DOM Coercion | |
705 | Rules`_. | |
706 | ||
707 | *returns*: | |
708 | The given DOM element | |
709 | ||
710 | *Availability*: | |
711 | Available in MochiKit 1.3.1+ | |
712 | ||
713 | ||
714 | :mochidef:`scrapeText(node[, asArray=false])`: | |
715 | ||
716 | Walk a DOM tree in-order and scrape all of the text out of it as a | |
717 | ``string``. | |
718 | ||
719 | If ``asArray`` is ``true``, then an ``Array`` will be returned | |
720 | with each individual text node. These two are equivalent:: | |
721 | ||
722 | assert( scrapeText(node) == scrapeText(node, true).join("") ); | |
723 | ||
724 | *Availability*: | |
725 | Available in MochiKit 1.3.1+ | |
726 | ||
727 | ||
728 | :mochidef:`setElementClass(element, className)`: | |
729 | ||
730 | Set the entire class attribute of ``element`` to ``className``. | |
731 | ``element`` is looked up with :mochiref:`getElement`, so string | |
732 | identifiers are also acceptable. | |
733 | ||
734 | *Availability*: | |
735 | Available in MochiKit 1.3.1+ | |
736 | ||
737 | ||
738 | :mochidef:`setNodeAttribute(node, attr, value)`: | |
739 | ||
740 | Set the value of the given attribute for a DOM element without | |
741 | ever raising an exception (will return null on exception). If | |
742 | setting more than one attribute, you should use | |
743 | :mochiref:`updateNodeAttributes`. | |
744 | ||
745 | ``node``: | |
746 | A reference to the DOM element to update (if a string is | |
747 | given, :mochiref:`getElement(node)` will be used to locate the | |
748 | node) | |
749 | ||
750 | ``attr``: | |
751 | The name of the attribute | |
752 | ||
753 | Note that it will do the right thing for IE, so don't do the | |
754 | ``class`` -> ``className`` hack yourself. | |
755 | ||
756 | ``value``: | |
757 | The value of the attribute, may be an object to be merged | |
758 | (e.g. for setting style). | |
759 | ||
760 | *returns*: | |
761 | The given DOM element or ``null`` on failure | |
762 | ||
763 | *Availability*: | |
764 | Available in MochiKit 1.3.1+ | |
765 | ||
766 | ||
767 | :mochidef:`swapDOM(dest, src)`: | |
768 | ||
769 | Replace ``dest`` in a DOM tree with ``src``, returning ``src``. | |
770 | ||
771 | ``dest``: | |
772 | a DOM element (or string id of one) to be replaced | |
773 | ||
774 | ``src``: | |
775 | the DOM element (or string id of one) to replace it with, or | |
776 | ``null`` if ``dest`` is to be removed (replaced with nothing). | |
777 | ||
778 | *returns*: | |
779 | a DOM element (``src``) | |
780 | ||
781 | *Availability*: | |
782 | Available in MochiKit 1.3.1+ | |
783 | ||
784 | ||
785 | :mochidef:`swapElementClass(element, fromClass, toClass)`: | |
786 | ||
787 | If ``fromClass`` is set on ``element``, replace it with | |
788 | ``toClass``. This will not disturb other classes on that element. | |
789 | ``element`` is looked up with :mochiref:`getElement`, so string | |
790 | identifiers are also acceptable. | |
791 | ||
792 | *Availability*: | |
793 | Available in MochiKit 1.3.1+ | |
794 | ||
795 | ||
796 | :mochidef:`toggleElementClass(className[, element[, ...]])`: | |
797 | ||
798 | Toggle the presence of a given ``className`` in the class | |
799 | attribute of all given elements. All elements will be looked up | |
800 | with :mochiref:`getElement`, so string identifiers are acceptable. | |
801 | ||
802 | *Availability*: | |
803 | Available in MochiKit 1.3.1+ | |
804 | ||
805 | ||
806 | :mochidef:`toHTML(dom)`: | |
807 | ||
808 | Convert a DOM tree to a HTML string using :mochiref:`emitHTML`. | |
809 | This should be used for debugging/testing purposes only. | |
810 | ||
811 | The DOM property ``innerHTML`` or ``cloneNode(true)`` method should | |
812 | be used for most purposes. | |
813 | ||
814 | *Availability*: | |
815 | Available in MochiKit 1.3.1+ | |
816 | ||
817 | ||
818 | :mochidef:`undoClipping(element, overflow)`: | |
819 | ||
820 | Restore the setting of ``element.style.overflow`` set by | |
821 | :mochiref:`makeClipping(element)`. If ``element`` is a string, then | |
822 | it will be looked up with :mochiref:`getElement`. | |
823 | ||
824 | *Availability*: | |
825 | Available in MochiKit 1.4+ | |
826 | ||
827 | ||
828 | :mochidef:`undoPositioned(element, overflow)`: | |
829 | ||
830 | Restore the setting of ``element.style.position`` set by | |
831 | :mochiref:`makePositioned(element)`. If ``element`` is a string, then | |
832 | it will be looked up with :mochiref:`getElement`. | |
833 | ||
834 | *Availability*: | |
835 | Available in MochiKit 1.4+ | |
836 | ||
837 | ||
838 | :mochidef:`updateNodeAttributes(node, attrs)`: | |
839 | ||
840 | Update the attributes of a DOM element from a given object. | |
841 | ||
842 | ``node``: | |
843 | A reference to the DOM element to update (if a string is | |
844 | given, :mochiref:`getElement(node)` will be used to locate the | |
845 | node) | |
846 | ||
847 | ``attrs``: | |
848 | An object whose properties will be used to set the attributes | |
849 | (e.g. ``{'class': 'invisible'}``), or ``null`` if no | |
850 | attributes need to be set. If an object is given for the | |
851 | attribute value (e.g. ``{'style': {'display': 'block'}}``) | |
852 | then :mochiref:`MochiKit.Base.updatetree` will be used to set | |
853 | that attribute. | |
854 | ||
855 | Note that it will do the right thing for IE, so don't do the | |
856 | ``class`` -> ``className`` hack yourself, and it deals with | |
857 | setting "on..." event handlers correctly. | |
858 | ||
859 | *returns*: | |
860 | The given DOM element | |
861 | ||
862 | *Availability*: | |
863 | Available in MochiKit 1.3.1+ | |
864 | ||
865 | ||
866 | :mochidef:`withWindow(win, func)`: | |
867 | ||
868 | Call ``func`` with the ``window`` `DOM Context`_ set to ``win`` | |
869 | and the ``document`` `DOM Context`_ set to ``win.document``. When | |
870 | ``func()`` returns or throws an error, the `DOM Context`_ will be | |
871 | restored to its previous state. | |
872 | ||
873 | The return value of ``func()`` is returned by this function. | |
874 | ||
875 | *Availability*: | |
876 | Available in MochiKit 1.3.1+ | |
877 | ||
878 | ||
879 | :mochidef:`withDocument(doc, func)`: | |
880 | ||
881 | Call ``func`` with the ``doc`` `DOM Context`_ set to ``doc``. | |
882 | When ``func()`` returns or throws an error, the `DOM Context`_ | |
883 | will be restored to its previous state. | |
884 | ||
885 | The return value of ``func()`` is returned by this function. | |
886 | ||
887 | *Availability*: | |
888 | Available in MochiKit 1.3.1+ | |
889 | ||
890 | ||
891 | Style Functions | |
892 | --------------- | |
893 | ||
894 | These functions are available in MochiKit 1.3.1, but have been moved to | |
895 | :mochiref:`MochiKit.Style` in 1.4+. | |
896 | ||
897 | ||
898 | :mochidef:`computedStyle(htmlElement, cssProperty, mozillaEquivalentCSS)`: | |
899 | ||
900 | Looks up a CSS property for the given element. The element can be | |
901 | specified as either a string with the element's ID or the element | |
902 | object itself. | |
903 | ||
904 | ``cssProperty``: | |
905 | MochiKit 1.3.1 expects camel case, e.g. ``backgroundColor``. | |
906 | MochiKit 1.4+ expects CSS selector case, e.g. ``background-color``, | |
907 | but will accept camel case for backwards-compatibility. | |
908 | ||
909 | ``mozillaEquivalentCSS``: | |
910 | MochiKit 1.3.1 expects selector case. | |
911 | MochiKit 1.4+ ignores this argument. | |
912 | ||
913 | *Availability*: | |
914 | Available in MochiKit 1.3.1, deprecated in favor of | |
915 | :mochiref:`MochiKit.Style.getStyle` in 1.4+ | |
916 | ||
917 | ||
918 | :mochidef:`elementDimensions(element)`: | |
919 | ||
920 | Return the absolute pixel width and height (including padding and border, | |
921 | but not margins) of ``element`` as an object with ``w`` and ``h`` | |
922 | properties, or ``undefined`` if ``element`` is not in the document. | |
923 | ``element`` may be specified as a string to be looked up with | |
924 | :mochiref:`getElement`, a DOM element, or trivially as an object with | |
925 | ``w`` and/or ``h`` properties. | |
926 | ||
927 | *Availability*: | |
928 | Available in MochiKit 1.3.1, deprecated in favor of | |
929 | :mochiref:`MochiKit.Style.getElementDimensions` in 1.4+ | |
930 | ||
931 | ||
932 | :mochidef:`elementPosition(element[, relativeTo={x: 0, y: 0}])`: | |
933 | ||
934 | Return the absolute pixel position of ``element`` in the document | |
935 | as an object with ``x`` and ``y`` properties, or ``undefined`` if | |
936 | ``element`` is not in the document. ``element`` may be specified | |
937 | as a string to be looked up with :mochiref:`getElement`, a DOM | |
938 | element, or trivially as an object with ``x`` and/or ``y`` | |
939 | properties. | |
940 | ||
941 | If ``relativeTo`` is given, then its coordinates are subtracted from | |
942 | the absolute position of ``element``, e.g.:: | |
943 | ||
944 | var elemPos = elementPosition(elem); | |
945 | var anotherElemPos = elementPosition(anotherElem); | |
946 | var relPos = elementPosition(elem, anotherElem); | |
947 | assert( relPos.x == (elemPos.x - anotherElemPos.x) ); | |
948 | assert( relPos.y == (elemPos.y - anotherElemPos.y) ); | |
949 | ||
950 | ``relativeTo`` may be specified as a string to be looked up with | |
951 | :mochiref:`getElement`, a DOM element, or trivially as an object | |
952 | with ``x`` and/or ``y`` properties. | |
953 | ||
954 | *Availability*: | |
955 | Available in MochiKit 1.3.1, deprecated in favor of | |
956 | :mochiref:`MochiKit.Style.getElementPosition` in 1.4+ | |
957 | ||
958 | ||
959 | :mochidef:`getViewportDimensions()`: | |
960 | ||
961 | Return the pixel width and height of the viewport as an object | |
962 | with ``w`` and ``h`` properties. ``element`` is looked up with | |
963 | :mochiref:`getElement`, so string identifiers are also acceptable. | |
964 | ||
965 | *Availability*: | |
966 | Available in MochiKit 1.3.1, moved to | |
967 | :mochiref:`MochiKit.Style.getViewportDimensions` in 1.4+ | |
968 | ||
969 | ||
970 | :mochidef:`hideElement(element, ...)`: | |
971 | ||
972 | Partial form of :mochiref:`setDisplayForElement`, specifically:: | |
973 | ||
974 | partial(setDisplayForElement, "none") | |
975 | ||
976 | For information about the caveats of using a ``style.display`` | |
977 | based show/hide mechanism, and a CSS based alternative, see | |
978 | `Element Visibility`_. | |
979 | ||
980 | .. _`Element Visibility`: Style.html#element-visibility | |
981 | ||
982 | *Availability*: | |
983 | Available in MochiKit 1.3.1, moved to | |
984 | :mochiref:`MochiKit.Style.hideElement` in 1.4+ | |
985 | ||
986 | ||
987 | :mochidef:`setElementDimensions(element, dimensions[, units='px'])`: | |
988 | ||
989 | Sets the dimensions of ``element`` in the document from an object | |
990 | with ``w`` and ``h`` properties. | |
991 | ||
992 | ``node``: | |
993 | A reference to the DOM element to update (if a string is | |
994 | given, :mochiref:`getElement(node)` will be used to locate the | |
995 | node) | |
996 | ||
997 | ``dimensions``: | |
998 | An object with ``w`` and ``h`` properties | |
999 | ||
1000 | ``units``: | |
1001 | Optionally set the units to use, default is ``px`` | |
1002 | ||
1003 | *Availability*: | |
1004 | Available in MochiKit 1.3.1, moved to | |
1005 | :mochiref:`MochiKit.Style.setElementDimensions` in 1.4+ | |
1006 | ||
1007 | ||
1008 | :mochidef:`setElementPosition(element, position[, units='px'])`: | |
1009 | ||
1010 | Sets the absolute position of ``element`` in the document from an | |
1011 | object with ``x`` and ``y`` properties. | |
1012 | ||
1013 | ``node``: | |
1014 | A reference to the DOM element to update (if a string is | |
1015 | given, :mochiref:`getElement(node)` will be used to locate the | |
1016 | node) | |
1017 | ||
1018 | ``position``: | |
1019 | An object with ``x`` and ``y`` properties | |
1020 | ||
1021 | ``units``: | |
1022 | Optionally set the units to use, default is ``px`` | |
1023 | ||
1024 | *Availability*: | |
1025 | Available in MochiKit 1.3.1, moved to | |
1026 | :mochiref:`MochiKit.Style.setElementPosition` in 1.4+ | |
1027 | ||
1028 | ||
1029 | :mochidef:`setDisplayForElement(display, element[, ...])`: | |
1030 | ||
1031 | Change the ``style.display`` for the given element(s). Usually | |
1032 | used as the partial forms: | |
1033 | ||
1034 | - :mochiref:`showElement(element, ...)` | |
1035 | - :mochiref:`hideElement(element, ...)` | |
1036 | ||
1037 | Elements are looked up with :mochiref:`getElement`, so string | |
1038 | identifiers are acceptable. | |
1039 | ||
1040 | For information about the caveats of using a ``style.display`` | |
1041 | based show/hide mechanism, and a CSS based alternative, see | |
1042 | `Element Visibility`_. | |
1043 | ||
1044 | *Availability*: | |
1045 | Available in MochiKit 1.3.1, moved to | |
1046 | :mochiref:`MochiKit.Style.setDisplayForElement` in 1.4+ | |
1047 | ||
1048 | ||
1049 | :mochidef:`setOpacity(element, opacity)`: | |
1050 | ||
1051 | Sets ``opacity`` for ``element``. Valid ``opacity`` values range | |
1052 | from 0 (invisible) to 1 (opaque). ``element`` is looked up with | |
1053 | :mochiref:`getElement`, so string identifiers are also acceptable. | |
1054 | ||
1055 | *Availability*: | |
1056 | Available in MochiKit 1.3.1, moved to | |
1057 | :mochiref:`MochiKit.Style.setOpacity` in 1.4+ | |
1058 | ||
1059 | ||
1060 | :mochidef:`showElement(element, ...)`: | |
1061 | ||
1062 | Partial form of :mochiref:`setDisplayForElement`, specifically:: | |
1063 | ||
1064 | partial(setDisplayForElement, "block") | |
1065 | ||
1066 | For information about the caveats of using a ``style.display`` | |
1067 | based show/hide mechanism, and a CSS based alternative, see | |
1068 | `Element Visibility`_. | |
1069 | ||
1070 | *Availability*: | |
1071 | Available in MochiKit 1.3.1, moved to | |
1072 | :mochiref:`MochiKit.Style.showElement` in 1.4+ | |
1073 | ||
1074 | ||
1075 | Style Objects | |
1076 | ------------- | |
1077 | ||
1078 | These objects are available in MochiKit 1.3.1, but have been moved to | |
1079 | :mochiref:`MochiKit.Style` in 1.4+. | |
1080 | ||
1081 | :mochidef:`Coordinates(x, y)`: | |
1082 | ||
1083 | Constructs an object with ``x`` and ``y`` properties. ``obj.toString()`` | |
1084 | returns something like ``{x: 0, y: 42}`` for debugging. | |
1085 | ||
1086 | *Availability*: | |
1087 | Available in MochiKit 1.3.1, moved to | |
1088 | :mochiref:`MochiKit.Style.Coordinates` in 1.4+ | |
1089 | ||
1090 | :mochidef:`Dimensions(w, h)`: | |
1091 | ||
1092 | Constructs an object with ``w`` and ``h`` properties. ``obj.toString()`` | |
1093 | returns something like ``{w: 0, h: 42}`` for debugging. | |
1094 | ||
1095 | *Availability*: | |
1096 | Available in MochiKit 1.3.1, moved to | |
1097 | :mochiref:`MochiKit.Style.Dimensions` in 1.4+ | |
1098 | ||
1099 | ||
1100 | ||
1101 | See Also | |
1102 | ======== | |
1103 | ||
1104 | .. [1] Nevow, a web application construction kit for Python: | |
1105 | http://divmod.org/trac/wiki/DivmodNevow | |
1106 | .. [2] nevow.stan is a domain specific language for Python (read as | |
1107 | "crazy getitem/call overloading abuse") that Donovan and I | |
1108 | schemed up at PyCon 2003 at this super ninja Python/C++ | |
1109 | programmer's (David Abrahams) hotel room. Donovan later | |
1110 | inflicted this upon the masses in Nevow. Check out the Nevow | |
1111 | Guide for some examples: | |
1112 | http://divmod.org/trac/wiki/DivmodNevow | |
1113 | ||
1114 | ||
1115 | Authors | |
1116 | ======= | |
1117 | ||
1118 | - Bob Ippolito <bob@redivi.com> | |
1119 | ||
1120 | ||
1121 | Copyright | |
1122 | ========= | |
1123 | ||
1124 | Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is | |
1125 | dual-licensed free software; you can redistribute it and/or modify it | |
1126 | under the terms of the `MIT License`_ or the `Academic Free License | |
1127 | v2.1`_. | |
1128 | ||
1129 | .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php | |
1130 | .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php |