Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / Element.traversal.html
1 <html>
2 <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
4   <title>The source code</title>
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 </head>
8 <body  onload="prettyPrint();">
9     <pre class="prettyprint lang-js">/*!
10  * Ext JS Library 3.2.1
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.com/license
14  */
15 /**
16  * @class Ext.Element
17  */
18 Ext.Element.addMethods(function(){
19         var PARENTNODE = 'parentNode',
20                 NEXTSIBLING = 'nextSibling',
21                 PREVIOUSSIBLING = 'previousSibling',
22                 DQ = Ext.DomQuery,
23                 GET = Ext.get;
24         
25         return {
26                 <div id="method-Ext.Element-findParent"></div>/**
27              * Looks at this node and then at parent nodes for a match of the passed simple selector (e.g. div.some-class or span:first-child)
28              * @param {String} selector The simple selector to test
29              * @param {Number/Mixed} maxDepth (optional) The max depth to search as a number or element (defaults to 50 || document.body)
30              * @param {Boolean} returnEl (optional) True to return a Ext.Element object instead of DOM node
31              * @return {HTMLElement} The matching DOM node (or null if no match was found)
32              */
33             findParent : function(simpleSelector, maxDepth, returnEl){
34                 var p = this.dom,
35                         b = document.body, 
36                         depth = 0,                      
37                         stopEl;         
38             if(Ext.isGecko && Object.prototype.toString.call(p) == '[object XULElement]') {
39                 return null;
40             }
41                 maxDepth = maxDepth || 50;
42                 if (isNaN(maxDepth)) {
43                     stopEl = Ext.getDom(maxDepth);
44                     maxDepth = Number.MAX_VALUE;
45                 }
46                 while(p && p.nodeType == 1 && depth < maxDepth && p != b && p != stopEl){
47                     if(DQ.is(p, simpleSelector)){
48                         return returnEl ? GET(p) : p;
49                     }
50                     depth++;
51                     p = p.parentNode;
52                 }
53                 return null;
54             },
55         
56             <div id="method-Ext.Element-findParentNode"></div>/**
57              * Looks at parent nodes for a match of the passed simple selector (e.g. div.some-class or span:first-child)
58              * @param {String} selector The simple selector to test
59              * @param {Number/Mixed} maxDepth (optional) The max depth to
60                     search as a number or element (defaults to 10 || document.body)
61              * @param {Boolean} returnEl (optional) True to return a Ext.Element object instead of DOM node
62              * @return {HTMLElement} The matching DOM node (or null if no match was found)
63              */
64             findParentNode : function(simpleSelector, maxDepth, returnEl){
65                 var p = Ext.fly(this.dom.parentNode, '_internal');
66                 return p ? p.findParent(simpleSelector, maxDepth, returnEl) : null;
67             },
68         
69             <div id="method-Ext.Element-up"></div>/**
70              * Walks up the dom looking for a parent node that matches the passed simple selector (e.g. div.some-class or span:first-child).
71              * This is a shortcut for findParentNode() that always returns an Ext.Element.
72              * @param {String} selector The simple selector to test
73              * @param {Number/Mixed} maxDepth (optional) The max depth to
74                     search as a number or element (defaults to 10 || document.body)
75              * @return {Ext.Element} The matching DOM node (or null if no match was found)
76              */
77             up : function(simpleSelector, maxDepth){
78                 return this.findParentNode(simpleSelector, maxDepth, true);
79             },
80         
81             <div id="method-Ext.Element-select"></div>/**
82              * Creates a {@link Ext.CompositeElement} for child nodes based on the passed CSS selector (the selector should not contain an id).
83              * @param {String} selector The CSS selector
84              * @return {CompositeElement/CompositeElementLite} The composite element
85              */
86             select : function(selector){
87                 return Ext.Element.select(selector, this.dom);
88             },
89         
90             <div id="method-Ext.Element-query"></div>/**
91              * Selects child nodes based on the passed CSS selector (the selector should not contain an id).
92              * @param {String} selector The CSS selector
93              * @return {Array} An array of the matched nodes
94              */
95             query : function(selector){
96                 return DQ.select(selector, this.dom);
97             },
98         
99             <div id="method-Ext.Element-child"></div>/**
100              * Selects a single child at any depth below this element based on the passed CSS selector (the selector should not contain an id).
101              * @param {String} selector The CSS selector
102              * @param {Boolean} returnDom (optional) True to return the DOM node instead of Ext.Element (defaults to false)
103              * @return {HTMLElement/Ext.Element} The child Ext.Element (or DOM node if returnDom = true)
104              */
105             child : function(selector, returnDom){
106                 var n = DQ.selectNode(selector, this.dom);
107                 return returnDom ? n : GET(n);
108             },
109         
110             <div id="method-Ext.Element-down"></div>/**
111              * Selects a single *direct* child based on the passed CSS selector (the selector should not contain an id).
112              * @param {String} selector The CSS selector
113              * @param {Boolean} returnDom (optional) True to return the DOM node instead of Ext.Element (defaults to false)
114              * @return {HTMLElement/Ext.Element} The child Ext.Element (or DOM node if returnDom = true)
115              */
116             down : function(selector, returnDom){
117                 var n = DQ.selectNode(" > " + selector, this.dom);
118                 return returnDom ? n : GET(n);
119             },
120         
121                  <div id="method-Ext.Element-parent"></div>/**
122              * Gets the parent node for this element, optionally chaining up trying to match a selector
123              * @param {String} selector (optional) Find a parent node that matches the passed simple selector
124              * @param {Boolean} returnDom (optional) True to return a raw dom node instead of an Ext.Element
125              * @return {Ext.Element/HTMLElement} The parent node or null
126                  */
127             parent : function(selector, returnDom){
128                 return this.matchNode(PARENTNODE, PARENTNODE, selector, returnDom);
129             },
130         
131              <div id="method-Ext.Element-next"></div>/**
132              * Gets the next sibling, skipping text nodes
133              * @param {String} selector (optional) Find the next sibling that matches the passed simple selector
134              * @param {Boolean} returnDom (optional) True to return a raw dom node instead of an Ext.Element
135              * @return {Ext.Element/HTMLElement} The next sibling or null
136                  */
137             next : function(selector, returnDom){
138                 return this.matchNode(NEXTSIBLING, NEXTSIBLING, selector, returnDom);
139             },
140         
141             <div id="method-Ext.Element-prev"></div>/**
142              * Gets the previous sibling, skipping text nodes
143              * @param {String} selector (optional) Find the previous sibling that matches the passed simple selector
144              * @param {Boolean} returnDom (optional) True to return a raw dom node instead of an Ext.Element
145              * @return {Ext.Element/HTMLElement} The previous sibling or null
146                  */
147             prev : function(selector, returnDom){
148                 return this.matchNode(PREVIOUSSIBLING, PREVIOUSSIBLING, selector, returnDom);
149             },
150         
151         
152             <div id="method-Ext.Element-first"></div>/**
153              * Gets the first child, skipping text nodes
154              * @param {String} selector (optional) Find the next sibling that matches the passed simple selector
155              * @param {Boolean} returnDom (optional) True to return a raw dom node instead of an Ext.Element
156              * @return {Ext.Element/HTMLElement} The first child or null
157                  */
158             first : function(selector, returnDom){
159                 return this.matchNode(NEXTSIBLING, 'firstChild', selector, returnDom);
160             },
161         
162             <div id="method-Ext.Element-last"></div>/**
163              * Gets the last child, skipping text nodes
164              * @param {String} selector (optional) Find the previous sibling that matches the passed simple selector
165              * @param {Boolean} returnDom (optional) True to return a raw dom node instead of an Ext.Element
166              * @return {Ext.Element/HTMLElement} The last child or null
167                  */
168             last : function(selector, returnDom){
169                 return this.matchNode(PREVIOUSSIBLING, 'lastChild', selector, returnDom);
170             },
171             
172             matchNode : function(dir, start, selector, returnDom){
173                 var n = this.dom[start];
174                 while(n){
175                     if(n.nodeType == 1 && (!selector || DQ.is(n, selector))){
176                         return !returnDom ? GET(n) : n;
177                     }
178                     n = n[dir];
179                 }
180                 return null;
181             }   
182     }
183 }());</pre>    
184 </body>
185 </html>