Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / CompositeElementLite.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-CompositeElementLite'>/**
19 </span> * @class Ext.CompositeElementLite
20  * &lt;p&gt;This class encapsulates a &lt;i&gt;collection&lt;/i&gt; of DOM elements, providing methods to filter
21  * members, or to perform collective actions upon the whole set.&lt;/p&gt;
22  * &lt;p&gt;Although they are not listed, this class supports all of the methods of {@link Ext.Element} and
23  * {@link Ext.fx.Anim}. The methods from these classes will be performed on all the elements in this collection.&lt;/p&gt;
24  * Example:&lt;pre&gt;&lt;code&gt;
25 var els = Ext.select(&quot;#some-el div.some-class&quot;);
26 // or select directly from an existing element
27 var el = Ext.get('some-el');
28 el.select('div.some-class');
29
30 els.setWidth(100); // all elements become 100 width
31 els.hide(true); // all elements fade out and hide
32 // or
33 els.setWidth(100).hide(true);
34 &lt;/code&gt;&lt;/pre&gt;
35  */
36 Ext.CompositeElementLite = function(els, root){
37 <span id='Ext-CompositeElementLite-property-elements'>    /**
38 </span>     * &lt;p&gt;The Array of DOM elements which this CompositeElement encapsulates. Read-only.&lt;/p&gt;
39      * &lt;p&gt;This will not &lt;i&gt;usually&lt;/i&gt; be accessed in developers' code, but developers wishing
40      * to augment the capabilities of the CompositeElementLite class may use it when adding
41      * methods to the class.&lt;/p&gt;
42      * &lt;p&gt;For example to add the &lt;code&gt;nextAll&lt;/code&gt; method to the class to &lt;b&gt;add&lt;/b&gt; all
43      * following siblings of selected elements, the code would be&lt;/p&gt;&lt;code&gt;&lt;pre&gt;
44 Ext.override(Ext.CompositeElementLite, {
45     nextAll: function() {
46         var els = this.elements, i, l = els.length, n, r = [], ri = -1;
47
48 //      Loop through all elements in this Composite, accumulating
49 //      an Array of all siblings.
50         for (i = 0; i &lt; l; i++) {
51             for (n = els[i].nextSibling; n; n = n.nextSibling) {
52                 r[++ri] = n;
53             }
54         }
55
56 //      Add all found siblings to this Composite
57         return this.add(r);
58     }
59 });&lt;/pre&gt;&lt;/code&gt;
60      * @property {HTMLElement} elements
61      */
62     this.elements = [];
63     this.add(els, root);
64     this.el = new Ext.Element.Flyweight();
65 };
66
67 Ext.CompositeElementLite.prototype = {
68     isComposite: true,
69
70     // private
71     getElement : function(el){
72         // Set the shared flyweight dom property to the current element
73         var e = this.el;
74         e.dom = el;
75         e.id = el.id;
76         return e;
77     },
78
79     // private
80     transformElement : function(el){
81         return Ext.getDom(el);
82     },
83
84 <span id='Ext-CompositeElementLite-method-getCount'>    /**
85 </span>     * Returns the number of elements in this Composite.
86      * @return Number
87      */
88     getCount : function(){
89         return this.elements.length;
90     },
91 <span id='Ext-CompositeElementLite-method-add'>    /**
92 </span>     * Adds elements to this Composite object.
93      * @param {HTMLElement[]/Ext.CompositeElement} els Either an Array of DOM elements to add, or another Composite object who's elements should be added.
94      * @return {Ext.CompositeElement} This Composite object.
95      */
96     add : function(els, root){
97         var me = this,
98             elements = me.elements;
99         if(!els){
100             return this;
101         }
102         if(typeof els == &quot;string&quot;){
103             els = Ext.Element.selectorFunction(els, root);
104         }else if(els.isComposite){
105             els = els.elements;
106         }else if(!Ext.isIterable(els)){
107             els = [els];
108         }
109
110         for(var i = 0, len = els.length; i &lt; len; ++i){
111             elements.push(me.transformElement(els[i]));
112         }
113         return me;
114     },
115
116     invoke : function(fn, args){
117         var me = this,
118             els = me.elements,
119             len = els.length,
120             e,
121             i;
122
123         for(i = 0; i &lt; len; i++) {
124             e = els[i];
125             if(e){
126                 Ext.Element.prototype[fn].apply(me.getElement(e), args);
127             }
128         }
129         return me;
130     },
131 <span id='Ext-CompositeElementLite-method-item'>    /**
132 </span>     * Returns a flyweight Element of the dom element object at the specified index
133      * @param {Number} index
134      * @return {Ext.Element}
135      */
136     item : function(index){
137         var me = this,
138             el = me.elements[index],
139             out = null;
140
141         if(el){
142             out = me.getElement(el);
143         }
144         return out;
145     },
146
147     // fixes scope with flyweight
148     addListener : function(eventName, handler, scope, opt){
149         var els = this.elements,
150             len = els.length,
151             i, e;
152
153         for(i = 0; i&lt;len; i++) {
154             e = els[i];
155             if(e) {
156                 Ext.EventManager.on(e, eventName, handler, scope || e, opt);
157             }
158         }
159         return this;
160     },
161 <span id='Ext-CompositeElementLite-method-each'>    /**
162 </span>     * &lt;p&gt;Calls the passed function for each element in this composite.&lt;/p&gt;
163      * @param {Function} fn The function to call. The function is passed the following parameters:&lt;ul&gt;
164      * &lt;li&gt;&lt;b&gt;el&lt;/b&gt; : Element&lt;div class=&quot;sub-desc&quot;&gt;The current Element in the iteration.
165      * &lt;b&gt;This is the flyweight (shared) Ext.Element instance, so if you require a
166      * a reference to the dom node, use el.dom.&lt;/b&gt;&lt;/div&gt;&lt;/li&gt;
167      * &lt;li&gt;&lt;b&gt;c&lt;/b&gt; : Composite&lt;div class=&quot;sub-desc&quot;&gt;This Composite object.&lt;/div&gt;&lt;/li&gt;
168      * &lt;li&gt;&lt;b&gt;idx&lt;/b&gt; : Number&lt;div class=&quot;sub-desc&quot;&gt;The zero-based index in the iteration.&lt;/div&gt;&lt;/li&gt;
169      * &lt;/ul&gt;
170      * @param {Object} [scope] The scope (&lt;i&gt;this&lt;/i&gt; reference) in which the function is executed. (defaults to the Element)
171      * @return {Ext.CompositeElement} this
172      */
173     each : function(fn, scope){
174         var me = this,
175             els = me.elements,
176             len = els.length,
177             i, e;
178
179         for(i = 0; i&lt;len; i++) {
180             e = els[i];
181             if(e){
182                 e = this.getElement(e);
183                 if(fn.call(scope || e, e, me, i) === false){
184                     break;
185                 }
186             }
187         }
188         return me;
189     },
190
191 <span id='Ext-CompositeElementLite-method-fill'>    /**
192 </span>    * Clears this Composite and adds the elements passed.
193     * @param {HTMLElement[]/Ext.CompositeElement} els Either an array of DOM elements, or another Composite from which to fill this Composite.
194     * @return {Ext.CompositeElement} this
195     */
196     fill : function(els){
197         var me = this;
198         me.elements = [];
199         me.add(els);
200         return me;
201     },
202
203 <span id='Ext-CompositeElementLite-method-filter'>    /**
204 </span>     * Filters this composite to only elements that match the passed selector.
205      * @param {String/Function} selector A string CSS selector or a comparison function.
206      * The comparison function will be called with the following arguments:&lt;ul&gt;
207      * &lt;li&gt;&lt;code&gt;el&lt;/code&gt; : Ext.Element&lt;div class=&quot;sub-desc&quot;&gt;The current DOM element.&lt;/div&gt;&lt;/li&gt;
208      * &lt;li&gt;&lt;code&gt;index&lt;/code&gt; : Number&lt;div class=&quot;sub-desc&quot;&gt;The current index within the collection.&lt;/div&gt;&lt;/li&gt;
209      * &lt;/ul&gt;
210      * @return {Ext.CompositeElement} this
211      */
212     filter : function(selector){
213         var els = [],
214             me = this,
215             fn = Ext.isFunction(selector) ? selector
216                 : function(el){
217                     return el.is(selector);
218                 };
219
220         me.each(function(el, self, i) {
221             if (fn(el, i) !== false) {
222                 els[els.length] = me.transformElement(el);
223             }
224         });
225
226         me.elements = els;
227         return me;
228     },
229
230 <span id='Ext-CompositeElementLite-method-indexOf'>    /**
231 </span>     * Find the index of the passed element within the composite collection.
232      * @param el {Mixed} The id of an element, or an Ext.Element, or an HtmlElement to find within the composite collection.
233      * @return Number The index of the passed Ext.Element in the composite collection, or -1 if not found.
234      */
235     indexOf : function(el){
236         return Ext.Array.indexOf(this.elements, this.transformElement(el));
237     },
238
239 <span id='Ext-CompositeElementLite-method-replaceElement'>    /**
240 </span>    * Replaces the specified element with the passed element.
241     * @param {String/HTMLElement/Ext.Element/Number} el The id of an element, the Element itself, the index of the element in this composite
242     * to replace.
243     * @param {String/Ext.Element} replacement The id of an element or the Element itself.
244     * @param {Boolean} domReplace (Optional) True to remove and replace the element in the document too.
245     * @return {Ext.CompositeElement} this
246     */
247     replaceElement : function(el, replacement, domReplace){
248         var index = !isNaN(el) ? el : this.indexOf(el),
249             d;
250         if(index &gt; -1){
251             replacement = Ext.getDom(replacement);
252             if(domReplace){
253                 d = this.elements[index];
254                 d.parentNode.insertBefore(replacement, d);
255                 Ext.removeNode(d);
256             }
257             Ext.Array.splice(this.elements, index, 1, replacement);
258         }
259         return this;
260     },
261
262 <span id='Ext-CompositeElementLite-method-clear'>    /**
263 </span>     * Removes all elements.
264      */
265     clear : function(){
266         this.elements = [];
267     }
268 };
269
270 Ext.CompositeElementLite.prototype.on = Ext.CompositeElementLite.prototype.addListener;
271
272 <span id='Ext-CompositeElementLite-method-importElementMethods'>/**
273 </span> * @private
274  * Copies all of the functions from Ext.Element's prototype onto CompositeElementLite's prototype.
275  * This is called twice - once immediately below, and once again after additional Ext.Element
276  * are added in Ext JS
277  */
278 Ext.CompositeElementLite.importElementMethods = function() {
279     var fnName,
280         ElProto = Ext.Element.prototype,
281         CelProto = Ext.CompositeElementLite.prototype;
282
283     for (fnName in ElProto) {
284         if (typeof ElProto[fnName] == 'function'){
285             (function(fnName) {
286                 CelProto[fnName] = CelProto[fnName] || function() {
287                     return this.invoke(fnName, arguments);
288                 };
289             }).call(CelProto, fnName);
290
291         }
292     }
293 };
294
295 Ext.CompositeElementLite.importElementMethods();
296
297 if(Ext.DomQuery){
298     Ext.Element.selectorFunction = Ext.DomQuery.select;
299 }
300
301 <span id='Ext-Element-method-select'>/**
302 </span> * Selects elements based on the passed CSS selector to enable {@link Ext.Element Element} methods
303  * to be applied to many related elements in one statement through the returned {@link Ext.CompositeElement CompositeElement} or
304  * {@link Ext.CompositeElementLite CompositeElementLite} object.
305  * @param {String/HTMLElement[]} selector The CSS selector or an array of elements
306  * @param {HTMLElement/String} root (optional) The root element of the query or id of the root
307  * @return {Ext.CompositeElementLite/Ext.CompositeElement}
308  * @member Ext.Element
309  * @method select
310  */
311 Ext.Element.select = function(selector, root){
312     var els;
313     if(typeof selector == &quot;string&quot;){
314         els = Ext.Element.selectorFunction(selector, root);
315     }else if(selector.length !== undefined){
316         els = selector;
317     }else{
318         //&lt;debug&gt;
319         Ext.Error.raise({
320             sourceClass: &quot;Ext.Element&quot;,
321             sourceMethod: &quot;select&quot;,
322             selector: selector,
323             root: root,
324             msg: &quot;Invalid selector specified: &quot; + selector
325         });
326         //&lt;/debug&gt;
327     }
328     return new Ext.CompositeElementLite(els);
329 };
330 <span id='Ext-method-select'>/**
331 </span> * Selects elements based on the passed CSS selector to enable {@link Ext.Element Element} methods
332  * to be applied to many related elements in one statement through the returned {@link Ext.CompositeElement CompositeElement} or
333  * {@link Ext.CompositeElementLite CompositeElementLite} object.
334  * @param {String/HTMLElement[]} selector The CSS selector or an array of elements
335  * @param {HTMLElement/String} root (optional) The root element of the query or id of the root
336  * @return {Ext.CompositeElementLite/Ext.CompositeElement}
337  * @member Ext
338  * @method select
339  */
340 Ext.select = Ext.Element.select;
341 </pre>
342 </body>
343 </html>