2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.net/yui/license.txt
8 YUI.add('dom-base', function(Y) {
12 * The DOM utility provides a cross-browser abtraction layer
13 * normalizing DOM tasks, and adds extra helper functionality
14 * for other common tasks.
21 * Provides DOM helper methods.
25 var NODE_TYPE = 'nodeType',
26 OWNER_DOCUMENT = 'ownerDocument',
27 DEFAULT_VIEW = 'defaultView',
28 PARENT_WINDOW = 'parentWindow',
30 PARENT_NODE = 'parentNode',
31 FIRST_CHILD = 'firstChild',
32 PREVIOUS_SIBLING = 'previousSibling',
33 NEXT_SIBLING = 'nextSibling',
34 CONTAINS = 'contains',
35 COMPARE_DOCUMENT_POSITION = 'compareDocumentPosition',
37 documentElement = document.documentElement,
39 re_tag = /<([a-z]+)/i;
43 * Returns the HTMLElement with the given ID (Wrapper for document.getElementById).
45 * @param {String} id the id attribute
46 * @param {Object} doc optional The document to search. Defaults to current document
47 * @return {HTMLElement | null} The HTMLElement with the id, or null if none found.
49 byId: function(id, doc) {
50 doc = doc || Y.config.doc;
52 return doc.getElementById(id);
56 children: function(node, tag) {
60 ret = Y.Selector.query('> ' + tag, node);
66 firstByTag: function(tag, root) {
68 root = root || Y.config.doc;
70 if (tag && root.getElementsByTagName) {
71 ret = root.getElementsByTagName(tag)[0];
78 * Returns the text content of the HTMLElement.
80 * @param {HTMLElement} element The html element.
81 * @return {String} The text content of the element (includes text of any descending elements).
83 getText: (documentElement.textContent !== undefined) ?
87 ret = element.textContent;
90 } : function(element) {
93 ret = element.innerText;
99 * Sets the text content of the HTMLElement.
101 * @param {HTMLElement} element The html element.
102 * @param {String} content The content to add.
104 setText: (documentElement.textContent !== undefined) ?
105 function(element, content) {
107 element.textContent = content;
109 } : function(element, content) {
111 element.innerText = content;
116 * Finds the previous sibling of the element.
118 * @deprecated Use elementByAxis
119 * @param {HTMLElement} element The html element.
120 * @param {Function} fn optional An optional boolean test to apply.
121 * The optional function is passed the current DOM node being tested as its only argument.
122 * If no function is given, the first sibling is returned.
123 * @param {Boolean} all optional Whether all node types should be scanned, or just element nodes.
124 * @return {HTMLElement | null} The matching DOM node or null if none found.
126 previous: function(element, fn, all) {
127 return Y.DOM.elementByAxis(element, PREVIOUS_SIBLING, fn, all);
131 * Finds the next sibling of the element.
133 * @deprecated Use elementByAxis
134 * @param {HTMLElement} element The html element.
135 * @param {Function} fn optional An optional boolean test to apply.
136 * The optional function is passed the current DOM node being tested as its only argument.
137 * If no function is given, the first sibling is returned.
138 * @param {Boolean} all optional Whether all node types should be scanned, or just element nodes.
139 * @return {HTMLElement | null} The matching DOM node or null if none found.
141 next: function(element, fn, all) {
142 return Y.DOM.elementByAxis(element, NEXT_SIBLING, fn, all);
146 * Finds the ancestor of the element.
148 * @deprecated Use elementByAxis
149 * @param {HTMLElement} element The html element.
150 * @param {Function} fn optional An optional boolean test to apply.
151 * The optional function is passed the current DOM node being tested as its only argument.
152 * If no function is given, the parentNode is returned.
153 * @param {Boolean} all optional Whether all node types should be scanned, or just element nodes.
154 * @return {HTMLElement | null} The matching DOM node or null if none found.
156 // TODO: optional stopAt node?
157 ancestor: function(element, fn, all) {
158 return Y.DOM.elementByAxis(element, PARENT_NODE, fn, all);
162 * Searches the element by the given axis for the first matching element.
163 * @method elementByAxis
164 * @param {HTMLElement} element The html element.
165 * @param {String} axis The axis to search (parentNode, nextSibling, previousSibling).
166 * @param {Function} fn optional An optional boolean test to apply.
167 * @param {Boolean} all optional Whether all node types should be returned, or just element nodes.
168 * The optional function is passed the current HTMLElement being tested as its only argument.
169 * If no function is given, the first element is returned.
170 * @return {HTMLElement | null} The matching element or null if none found.
172 elementByAxis: function(element, axis, fn, all) {
173 while (element && (element = element[axis])) { // NOTE: assignment
174 if ( (all || element[TAG_NAME]) && (!fn || fn(element)) ) {
182 * Determines whether or not one HTMLElement is or contains another HTMLElement.
184 * @param {HTMLElement} element The containing html element.
185 * @param {HTMLElement} needle The html element that may be contained.
186 * @return {Boolean} Whether or not the element is or contains the needle.
188 contains: function(element, needle) {
191 if ( !needle || !element || !needle[NODE_TYPE] || !element[NODE_TYPE]) {
193 } else if (element[CONTAINS]) {
194 if (Y.UA.opera || needle[NODE_TYPE] === 1) { // IE & SAF contains fail if needle not an ELEMENT_NODE
195 ret = element[CONTAINS](needle);
197 ret = Y.DOM._bruteContains(element, needle);
199 } else if (element[COMPARE_DOCUMENT_POSITION]) { // gecko
200 if (element === needle || !!(element[COMPARE_DOCUMENT_POSITION](needle) & 16)) {
209 * Determines whether or not the HTMLElement is part of the document.
211 * @param {HTMLElement} element The containing html element.
212 * @param {HTMLElement} doc optional The document to check.
213 * @return {Boolean} Whether or not the element is attached to the document.
215 inDoc: function(element, doc) {
216 doc = doc || element[OWNER_DOCUMENT];
218 if (!id) { // TODO: remove when done?
219 id = element.id = Y.guid();
222 return !! (doc.getElementById(id));
226 * Creates a new dom node using the provided markup string.
228 * @param {String} html The markup used to create the element
229 * @param {HTMLDocument} doc An optional document context
231 create: function(html, doc) {
232 if (typeof html === 'string') {
233 html = Y.Lang.trim(html); // match IE which trims whitespace from innerHTML
236 if (!doc && Y.DOM._cloneCache[html]) {
237 return Y.DOM._cloneCache[html].cloneNode(true); // NOTE: return
240 doc = doc || Y.config.doc;
241 var m = re_tag.exec(html),
242 create = Y.DOM._create,
243 custom = Y.DOM.creators,
247 if (m && custom[m[1]]) {
248 if (typeof custom[m[1]] === 'function') {
249 create = custom[m[1]];
255 nodes = create(html, doc, tag).childNodes;
257 if (nodes.length === 1) { // return single node, breaking parentNode ref from "fragment"
258 ret = nodes[0].parentNode.removeChild(nodes[0]);
259 } else { // return multiple nodes as a fragment
260 ret = Y.DOM._nl2frag(nodes, doc);
264 Y.DOM._cloneCache[html] = ret.cloneNode(true);
269 _nl2frag: function(nodes, doc) {
273 if (nodes && (nodes.push || nodes.item) && nodes[0]) {
274 doc = doc || nodes[0].ownerDocument;
275 ret = doc.createDocumentFragment();
277 if (nodes.item) { // convert live list to static array
278 nodes = Y.Array(nodes, 0, true);
281 for (i = 0, len = nodes.length; i < len; i++) {
282 ret.appendChild(nodes[i]);
284 } // else inline with log for minification
289 CUSTOM_ATTRIBUTES: (!documentElement.hasAttribute) ? { // IE < 8
298 * Provides a normalized attribute interface.
299 * @method setAttibute
300 * @param {String | HTMLElement} el The target element for the attribute.
301 * @param {String} attr The attribute to set.
302 * @param {String} val The value of the attribute.
304 setAttribute: function(el, attr, val, ieAttr) {
305 if (el && el.setAttribute) {
306 attr = Y.DOM.CUSTOM_ATTRIBUTES[attr] || attr;
307 el.setAttribute(attr, val, ieAttr);
313 * Provides a normalized attribute interface.
314 * @method getAttibute
315 * @param {String | HTMLElement} el The target element for the attribute.
316 * @param {String} attr The attribute to get.
317 * @return {String} The current value of the attribute.
319 getAttribute: function(el, attr, ieAttr) {
320 ieAttr = (ieAttr !== undefined) ? ieAttr : 2;
322 if (el && el.getAttribute) {
323 attr = Y.DOM.CUSTOM_ATTRIBUTES[attr] || attr;
324 ret = el.getAttribute(attr, ieAttr);
327 ret = ''; // per DOM spec
333 isWindow: function(obj) {
334 return obj.alert && obj.document;
338 div: document.createElement('div')
341 _create: function(html, doc, tag) {
344 var frag = Y.DOM._fragClones[tag];
346 frag = frag.cloneNode(false);
348 frag = Y.DOM._fragClones[tag] = doc.createElement(tag);
350 frag.innerHTML = html;
354 _removeChildNodes: function(node) {
355 while (node.firstChild) {
356 node.removeChild(node.firstChild);
363 * Inserts content in a node at the given location
365 * @param {HTMLElement} node The node to insert into
366 * @param {String} content The content to be inserted
367 * @param {String} where Where to insert the content; default is after lastChild
369 addHTML: function(node, content, where) {
370 if (typeof content === 'string') {
371 content = Y.Lang.trim(content); // match IE which trims whitespace from innerHTML
374 var newNode = Y.DOM._cloneCache[content],
375 nodeParent = node.parentNode;
378 newNode = newNode.cloneNode(true);
380 if (content.nodeType) { // domNode
382 } else { // create from string and cache
383 newNode = Y.DOM.create(content);
388 if (where.nodeType) { // insert regardless of relationship to node
389 // TODO: check if node.contains(where)?
390 where.parentNode.insertBefore(newNode, where);
394 while (node.firstChild) {
395 node.removeChild(node.firstChild);
397 node.appendChild(newNode);
400 nodeParent.insertBefore(newNode, node);
403 if (node.nextSibling) { // IE errors if refNode is null
404 nodeParent.insertBefore(newNode, node.nextSibling);
406 nodeParent.appendChild(newNode);
410 node.appendChild(newNode);
414 node.appendChild(newNode);
424 getValue: function(node) {
425 var ret = '', // TODO: return null?
428 if (node && node[TAG_NAME]) {
429 getter = Y.DOM.VALUE_GETTERS[node[TAG_NAME].toLowerCase()];
438 return (typeof ret === 'string') ? ret : '';
441 setValue: function(node, val) {
444 if (node && node[TAG_NAME]) {
445 setter = Y.DOM.VALUE_SETTERS[node[TAG_NAME].toLowerCase()];
456 * Brute force version of contains.
457 * Used for browsers without contains support for non-HTMLElement Nodes (textNodes, etc).
458 * @method _bruteContains
460 * @param {HTMLElement} element The containing html element.
461 * @param {HTMLElement} needle The html element that may be contained.
462 * @return {Boolean} Whether or not the element is or contains the needle.
464 _bruteContains: function(element, needle) {
466 if (element === needle) {
469 needle = needle.parentNode;
474 // TODO: move to Lang?
476 * Memoizes dynamic regular expressions to boost runtime performance.
479 * @param {String} str The string to convert to a regular expression.
480 * @param {String} flags optional An optinal string of flags.
481 * @return {RegExp} An instance of RegExp
483 _getRegExp: function(str, flags) {
485 Y.DOM._regexCache = Y.DOM._regexCache || {};
486 if (!Y.DOM._regexCache[str + flags]) {
487 Y.DOM._regexCache[str + flags] = new RegExp(str, flags);
489 return Y.DOM._regexCache[str + flags];
492 // TODO: make getDoc/Win true privates?
494 * returns the appropriate document.
497 * @param {HTMLElement} element optional Target element.
498 * @return {Object} The document for the given element or the default document.
500 _getDoc: function(element) {
501 element = element || {};
503 return (element[NODE_TYPE] === 9) ? element : // element === document
504 element[OWNER_DOCUMENT] || // element === DOM node
505 element.document || // element === window
506 Y.config.doc; // default
510 * returns the appropriate window.
513 * @param {HTMLElement} element optional Target element.
514 * @return {Object} The window for the given element or the default window.
516 _getWin: function(element) {
517 var doc = Y.DOM._getDoc(element);
518 return doc[DEFAULT_VIEW] || doc[PARENT_WINDOW] || Y.config.win;
521 _batch: function(nodes, fn, arg1, arg2, arg3, etc) {
522 fn = (typeof name === 'string') ? Y.DOM[fn] : fn;
527 Y.each(nodes, function(node) {
528 if ((result = fn.call(Y.DOM, node, arg1, arg2, arg3, etc)) !== undefined) {
529 ret[ret.length] = result;
534 return ret.length ? ret : nodes;
537 _testElement: function(element, tag, fn) {
538 tag = (tag && tag !== '*') ? tag.toUpperCase() : null;
539 return (element && element[TAG_NAME] &&
540 (!tag || element[TAG_NAME].toUpperCase() === tag) &&
541 (!fn || fn(element)));
546 _IESimpleCreate: function(html, doc) {
547 doc = doc || Y.config.doc;
548 return doc.createElement(html);
554 var creators = Y.DOM.creators,
555 create = Y.DOM.create,
556 re_tbody = /(?:\/(?:thead|tfoot|tbody|caption|col|colgroup)>)+\s*<tbody/,
558 TABLE_OPEN = '<table>',
559 TABLE_CLOSE = '</table>';
563 // TODO: thead/tfoot with nested tbody
564 // IE adds TBODY when creating TABLE elements (which may share this impl)
565 tbody: function(html, doc) {
566 var frag = create(TABLE_OPEN + html + TABLE_CLOSE, doc),
567 tb = frag.children.tags('tbody')[0];
569 if (frag.children.length > 1 && tb && !re_tbody.test(html)) {
570 tb[PARENT_NODE].removeChild(tb); // strip extraneous tbody
575 script: function(html, doc) {
576 var frag = doc.createElement('div');
578 frag.innerHTML = '-' + html;
579 frag.removeChild(frag[FIRST_CHILD]);
585 Y.mix(Y.DOM.VALUE_GETTERS, {
586 button: function(node) {
587 return (node.attributes && node.attributes.value) ? node.attributes.value.value : '';
591 Y.mix(Y.DOM.VALUE_SETTERS, {
592 // IE: node.value changes the button text, which should be handled via innerHTML
593 button: function(node, val) {
594 var attr = node.attributes.value;
596 attr = node[OWNER_DOCUMENT].createAttribute('value');
597 node.setAttributeNode(attr);
605 if (Y.UA.gecko || Y.UA.ie) {
607 option: function(html, doc) {
608 return create('<select>' + html + '</select>', doc);
611 tr: function(html, doc) {
612 return create('<tbody>' + html + '</tbody>', doc);
615 td: function(html, doc) {
616 return create('<tr>' + html + '</tr>', doc);
619 tbody: function(html, doc) {
620 return create(TABLE_OPEN + html + TABLE_CLOSE, doc);
627 thead: creators.tbody,
628 tfoot: creators.tbody,
629 caption: creators.tbody,
630 colgroup: creators.tbody,
632 optgroup: creators.option
636 Y.mix(Y.DOM.VALUE_GETTERS, {
637 option: function(node) {
638 var attrs = node.attributes;
639 return (attrs.value && attrs.value.specified) ? node.value : node.text;
642 select: function(node) {
643 var val = node.value,
644 options = node.options;
646 if (options && val === '') {
649 val = Y.DOM.getValue(options[node.selectedIndex], 'value');
659 var addClass, hasClass, removeClass;
663 * Determines whether a DOM element has the given className.
665 * @param {HTMLElement} element The DOM element.
666 * @param {String} className the class name to search for
667 * @return {Boolean} Whether or not the element has the given class.
669 hasClass: function(node, className) {
670 var re = Y.DOM._getRegExp('(?:^|\\s+)' + className + '(?:\\s+|$)');
671 return re.test(node.className);
675 * Adds a class name to a given DOM element.
677 * @param {HTMLElement} element The DOM element.
678 * @param {String} className the class name to add to the class attribute
680 addClass: function(node, className) {
681 if (!Y.DOM.hasClass(node, className)) { // skip if already present
682 node.className = Y.Lang.trim([node.className, className].join(' '));
687 * Removes a class name from a given element.
688 * @method removeClass
689 * @param {HTMLElement} element The DOM element.
690 * @param {String} className the class name to remove from the class attribute
692 removeClass: function(node, className) {
693 if (className && hasClass(node, className)) {
694 node.className = Y.Lang.trim(node.className.replace(Y.DOM._getRegExp('(?:^|\\s+)' +
695 className + '(?:\\s+|$)'), ' '));
697 if ( hasClass(node, className) ) { // in case of multiple adjacent
698 removeClass(node, className);
704 * Replace a class with another class for a given element.
705 * If no oldClassName is present, the newClassName is simply added.
706 * @method replaceClass
707 * @param {HTMLElement} element The DOM element.
708 * @param {String} oldClassName the class name to be replaced
709 * @param {String} newClassName the class name that will be replacing the old class name
711 replaceClass: function(node, oldC, newC) {
712 addClass(node, newC);
713 removeClass(node, oldC);
717 * If the className exists on the node it is removed, if it doesn't exist it is added.
718 * @method toggleClass
719 * @param {HTMLElement} element The DOM element.
720 * @param {String} className the class name to be toggled
722 toggleClass: function(node, className) {
723 if (hasClass(node, className)) {
724 removeClass(node, className);
726 addClass(node, className);
731 hasClass = Y.DOM.hasClass;
732 removeClass = Y.DOM.removeClass;
733 addClass = Y.DOM.addClass;
737 }, '3.0.0' ,{requires:['oop']});