API Docs for: 3.17.2
Show:

File: dom/js/dom-core.js

  1. var NODE_TYPE = 'nodeType',
  2. OWNER_DOCUMENT = 'ownerDocument',
  3. DOCUMENT_ELEMENT = 'documentElement',
  4. DEFAULT_VIEW = 'defaultView',
  5. PARENT_WINDOW = 'parentWindow',
  6. TAG_NAME = 'tagName',
  7. PARENT_NODE = 'parentNode',
  8. PREVIOUS_SIBLING = 'previousSibling',
  9. NEXT_SIBLING = 'nextSibling',
  10. CONTAINS = 'contains',
  11. COMPARE_DOCUMENT_POSITION = 'compareDocumentPosition',
  12. EMPTY_ARRAY = [],
  13.  
  14. // IE < 8 throws on node.contains(textNode)
  15. supportsContainsTextNode = (function() {
  16. var node = Y.config.doc.createElement('div'),
  17. textNode = node.appendChild(Y.config.doc.createTextNode('')),
  18. result = false;
  19.  
  20. try {
  21. result = node.contains(textNode);
  22. } catch(e) {}
  23.  
  24. return result;
  25. })(),
  26.  
  27. /**
  28. * The DOM utility provides a cross-browser abtraction layer
  29. * normalizing DOM tasks, and adds extra helper functionality
  30. * for other common tasks.
  31. * @module dom
  32. * @main dom
  33. * @submodule dom-base
  34. * @for DOM
  35. *
  36. */
  37.  
  38. /**
  39. * Provides DOM helper methods.
  40. * @class DOM
  41. *
  42. */
  43.  
  44. Y_DOM = {
  45. /**
  46. * Returns the HTMLElement with the given ID (Wrapper for document.getElementById).
  47. * @method byId
  48. * @param {String} id the id attribute
  49. * @param {Object} doc optional The document to search. Defaults to current document
  50. * @return {HTMLElement | null} The HTMLElement with the id, or null if none found.
  51. */
  52. byId: function(id, doc) {
  53. // handle dupe IDs and IE name collision
  54. return Y_DOM.allById(id, doc)[0] || null;
  55. },
  56.  
  57. getId: function(node) {
  58. var id;
  59. // HTMLElement returned from FORM when INPUT name === "id"
  60. // IE < 8: HTMLCollection returned when INPUT id === "id"
  61. // via both getAttribute and form.id
  62. if (node.id && !node.id.tagName && !node.id.item) {
  63. id = node.id;
  64. } else if (node.attributes && node.attributes.id) {
  65. id = node.attributes.id.value;
  66. }
  67.  
  68. return id;
  69. },
  70.  
  71. setId: function(node, id) {
  72. if (node.setAttribute) {
  73. node.setAttribute('id', id);
  74. } else {
  75. node.id = id;
  76. }
  77. },
  78.  
  79. /*
  80. * Finds the ancestor of the element.
  81. * @method ancestor
  82. * @param {HTMLElement} element The html element.
  83. * @param {Function} fn optional An optional boolean test to apply.
  84. * The optional function is passed the current DOM node being tested as its only argument.
  85. * If no function is given, the parentNode is returned.
  86. * @param {Boolean} testSelf optional Whether or not to include the element in the scan
  87. * @return {HTMLElement | null} The matching DOM node or null if none found.
  88. */
  89. ancestor: function(element, fn, testSelf, stopFn) {
  90. var ret = null;
  91. if (testSelf) {
  92. ret = (!fn || fn(element)) ? element : null;
  93.  
  94. }
  95. return ret || Y_DOM.elementByAxis(element, PARENT_NODE, fn, null, stopFn);
  96. },
  97.  
  98. /*
  99. * Finds the ancestors of the element.
  100. * @method ancestors
  101. * @param {HTMLElement} element The html element.
  102. * @param {Function} fn optional An optional boolean test to apply.
  103. * The optional function is passed the current DOM node being tested as its only argument.
  104. * If no function is given, all ancestors are returned.
  105. * @param {Boolean} testSelf optional Whether or not to include the element in the scan
  106. * @return {Array} An array containing all matching DOM nodes.
  107. */
  108. ancestors: function(element, fn, testSelf, stopFn) {
  109. var ancestor = element,
  110. ret = [];
  111.  
  112. while ((ancestor = Y_DOM.ancestor(ancestor, fn, testSelf, stopFn))) {
  113. testSelf = false;
  114. if (ancestor) {
  115. ret.unshift(ancestor);
  116.  
  117. if (stopFn && stopFn(ancestor)) {
  118. return ret;
  119. }
  120. }
  121. }
  122.  
  123. return ret;
  124. },
  125.  
  126. /**
  127. * Searches the element by the given axis for the first matching element.
  128. * @method elementByAxis
  129. * @param {HTMLElement} element The html element.
  130. * @param {String} axis The axis to search (parentNode, nextSibling, previousSibling).
  131. * @param {Function} [fn] An optional boolean test to apply.
  132. * @param {Boolean} [all] Whether text nodes as well as element nodes should be returned, or
  133. * just element nodes will be returned(default)
  134. * The optional function is passed the current HTMLElement being tested as its only argument.
  135. * If no function is given, the first element is returned.
  136. * @return {HTMLElement | null} The matching element or null if none found.
  137. */
  138. elementByAxis: function(element, axis, fn, all, stopAt) {
  139. while (element && (element = element[axis])) { // NOTE: assignment
  140. if ( (all || element[TAG_NAME]) && (!fn || fn(element)) ) {
  141. return element;
  142. }
  143.  
  144. if (stopAt && stopAt(element)) {
  145. return null;
  146. }
  147. }
  148. return null;
  149. },
  150.  
  151. /**
  152. * Determines whether or not one HTMLElement is or contains another HTMLElement.
  153. * @method contains
  154. * @param {HTMLElement} element The containing html element.
  155. * @param {HTMLElement} needle The html element that may be contained.
  156. * @return {Boolean} Whether or not the element is or contains the needle.
  157. */
  158. contains: function(element, needle) {
  159. var ret = false;
  160.  
  161. if ( !needle || !element || !needle[NODE_TYPE] || !element[NODE_TYPE]) {
  162. ret = false;
  163. } else if (element[CONTAINS] &&
  164. // IE < 8 throws on node.contains(textNode) so fall back to brute.
  165. // Falling back for other nodeTypes as well.
  166. (needle[NODE_TYPE] === 1 || supportsContainsTextNode)) {
  167. ret = element[CONTAINS](needle);
  168. } else if (element[COMPARE_DOCUMENT_POSITION]) {
  169. // Match contains behavior (node.contains(node) === true).
  170. // Needed for Firefox < 4.
  171. if (element === needle || !!(element[COMPARE_DOCUMENT_POSITION](needle) & 16)) {
  172. ret = true;
  173. }
  174. } else {
  175. ret = Y_DOM._bruteContains(element, needle);
  176. }
  177.  
  178. return ret;
  179. },
  180.  
  181. /**
  182. * Determines whether or not the HTMLElement is part of the document.
  183. * @method inDoc
  184. * @param {HTMLElement} element The containing html element.
  185. * @param {HTMLElement} doc optional The document to check.
  186. * @return {Boolean} Whether or not the element is attached to the document.
  187. */
  188. inDoc: function(element, doc) {
  189. var ret = false,
  190. rootNode;
  191.  
  192. if (element && element.nodeType) {
  193. (doc) || (doc = element[OWNER_DOCUMENT]);
  194.  
  195. rootNode = doc[DOCUMENT_ELEMENT];
  196.  
  197. // contains only works with HTML_ELEMENT
  198. if (rootNode && rootNode.contains && element.tagName) {
  199. ret = rootNode.contains(element);
  200. } else {
  201. ret = Y_DOM.contains(rootNode, element);
  202. }
  203. }
  204.  
  205. return ret;
  206.  
  207. },
  208.  
  209. allById: function(id, root) {
  210. root = root || Y.config.doc;
  211. var nodes = [],
  212. ret = [],
  213. i,
  214. node;
  215.  
  216. if (root.querySelectorAll) {
  217. ret = root.querySelectorAll('[id="' + id + '"]');
  218. } else if (root.all) {
  219. nodes = root.all(id);
  220.  
  221. if (nodes) {
  222. // root.all may return HTMLElement or HTMLCollection.
  223. // some elements are also HTMLCollection (FORM, SELECT).
  224. if (nodes.nodeName) {
  225. if (nodes.id === id) { // avoid false positive on name
  226. ret.push(nodes);
  227. nodes = EMPTY_ARRAY; // done, no need to filter
  228. } else { // prep for filtering
  229. nodes = [nodes];
  230. }
  231. }
  232.  
  233. if (nodes.length) {
  234. // filter out matches on node.name
  235. // and element.id as reference to element with id === 'id'
  236. for (i = 0; node = nodes[i++];) {
  237. if (node.id === id ||
  238. (node.attributes && node.attributes.id &&
  239. node.attributes.id.value === id)) {
  240. ret.push(node);
  241. }
  242. }
  243. }
  244. }
  245. } else {
  246. ret = [Y_DOM._getDoc(root).getElementById(id)];
  247. }
  248.  
  249. return ret;
  250. },
  251.  
  252.  
  253. isWindow: function(obj) {
  254. return !!(obj && obj.scrollTo && obj.document);
  255. },
  256.  
  257. _removeChildNodes: function(node) {
  258. while (node.firstChild) {
  259. node.removeChild(node.firstChild);
  260. }
  261. },
  262.  
  263. siblings: function(node, fn) {
  264. var nodes = [],
  265. sibling = node;
  266.  
  267. while ((sibling = sibling[PREVIOUS_SIBLING])) {
  268. if (sibling[TAG_NAME] && (!fn || fn(sibling))) {
  269. nodes.unshift(sibling);
  270. }
  271. }
  272.  
  273. sibling = node;
  274. while ((sibling = sibling[NEXT_SIBLING])) {
  275. if (sibling[TAG_NAME] && (!fn || fn(sibling))) {
  276. nodes.push(sibling);
  277. }
  278. }
  279.  
  280. return nodes;
  281. },
  282.  
  283. /**
  284. * Brute force version of contains.
  285. * Used for browsers without contains support for non-HTMLElement Nodes (textNodes, etc).
  286. * @method _bruteContains
  287. * @private
  288. * @param {HTMLElement} element The containing html element.
  289. * @param {HTMLElement} needle The html element that may be contained.
  290. * @return {Boolean} Whether or not the element is or contains the needle.
  291. */
  292. _bruteContains: function(element, needle) {
  293. while (needle) {
  294. if (element === needle) {
  295. return true;
  296. }
  297. needle = needle.parentNode;
  298. }
  299. return false;
  300. },
  301.  
  302. // TODO: move to Lang?
  303. /**
  304. * Memoizes dynamic regular expressions to boost runtime performance.
  305. * @method _getRegExp
  306. * @private
  307. * @param {String} str The string to convert to a regular expression.
  308. * @param {String} flags optional An optinal string of flags.
  309. * @return {RegExp} An instance of RegExp
  310. */
  311. _getRegExp: function(str, flags) {
  312. flags = flags || '';
  313. Y_DOM._regexCache = Y_DOM._regexCache || {};
  314. if (!Y_DOM._regexCache[str + flags]) {
  315. Y_DOM._regexCache[str + flags] = new RegExp(str, flags);
  316. }
  317. return Y_DOM._regexCache[str + flags];
  318. },
  319.  
  320. // TODO: make getDoc/Win true privates?
  321. /**
  322. * returns the appropriate document.
  323. * @method _getDoc
  324. * @private
  325. * @param {HTMLElement} element optional Target element.
  326. * @return {Object} The document for the given element or the default document.
  327. */
  328. _getDoc: function(element) {
  329. var doc = Y.config.doc;
  330. if (element) {
  331. doc = (element[NODE_TYPE] === 9) ? element : // element === document
  332. element[OWNER_DOCUMENT] || // element === DOM node
  333. element.document || // element === window
  334. Y.config.doc; // default
  335. }
  336.  
  337. return doc;
  338. },
  339.  
  340. /**
  341. * returns the appropriate window.
  342. * @method _getWin
  343. * @private
  344. * @param {HTMLElement} element optional Target element.
  345. * @return {Object} The window for the given element or the default window.
  346. */
  347. _getWin: function(element) {
  348. var doc = Y_DOM._getDoc(element);
  349. return doc[DEFAULT_VIEW] || doc[PARENT_WINDOW] || Y.config.win;
  350. },
  351.  
  352. _batch: function(nodes, fn, arg1, arg2, arg3, etc) {
  353. fn = (typeof fn === 'string') ? Y_DOM[fn] : fn;
  354. var result,
  355. i = 0,
  356. node,
  357. ret;
  358.  
  359. if (fn && nodes) {
  360. while ((node = nodes[i++])) {
  361. result = result = fn.call(Y_DOM, node, arg1, arg2, arg3, etc);
  362. if (typeof result !== 'undefined') {
  363. (ret) || (ret = []);
  364. ret.push(result);
  365. }
  366. }
  367. }
  368.  
  369. return (typeof ret !== 'undefined') ? ret : nodes;
  370. },
  371.  
  372. generateID: function(el) {
  373. var id = el.id;
  374.  
  375. if (!id) {
  376. id = Y.stamp(el);
  377. el.id = id;
  378. }
  379.  
  380. return id;
  381. }
  382. };
  383.  
  384.  
  385. Y.DOM = Y_DOM;
  386.