3 This file is part of Ext JS 4
5 Copyright (c) 2011 Sencha Inc
7 Contact: http://www.sencha.com/contact
9 GNU General Public License Usage
10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file. Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
16 * @class Ext.CompositeElementLite
17 * <p>This class encapsulates a <i>collection</i> of DOM elements, providing methods to filter
18 * members, or to perform collective actions upon the whole set.</p>
19 * <p>Although they are not listed, this class supports all of the methods of {@link Ext.Element} and
20 * {@link Ext.fx.Anim}. The methods from these classes will be performed on all the elements in this collection.</p>
22 var els = Ext.select("#some-el div.some-class");
23 // or select directly from an existing element
24 var el = Ext.get('some-el');
25 el.select('div.some-class');
27 els.setWidth(100); // all elements become 100 width
28 els.hide(true); // all elements fade out and hide
30 els.setWidth(100).hide(true);
33 Ext.CompositeElementLite = function(els, root){
35 * <p>The Array of DOM elements which this CompositeElement encapsulates. Read-only.</p>
36 * <p>This will not <i>usually</i> be accessed in developers' code, but developers wishing
37 * to augment the capabilities of the CompositeElementLite class may use it when adding
38 * methods to the class.</p>
39 * <p>For example to add the <code>nextAll</code> method to the class to <b>add</b> all
40 * following siblings of selected elements, the code would be</p><code><pre>
41 Ext.override(Ext.CompositeElementLite, {
43 var els = this.elements, i, l = els.length, n, r = [], ri = -1;
45 // Loop through all elements in this Composite, accumulating
46 // an Array of all siblings.
47 for (i = 0; i < l; i++) {
48 for (n = els[i].nextSibling; n; n = n.nextSibling) {
53 // Add all found siblings to this Composite
57 * @property {HTMLElement} elements
61 this.el = new Ext.Element.Flyweight();
64 Ext.CompositeElementLite.prototype = {
68 getElement : function(el){
69 // Set the shared flyweight dom property to the current element
77 transformElement : function(el){
78 return Ext.getDom(el);
82 * Returns the number of elements in this Composite.
85 getCount : function(){
86 return this.elements.length;
89 * Adds elements to this Composite object.
90 * @param {HTMLElement[]/Ext.CompositeElement} els Either an Array of DOM elements to add, or another Composite object who's elements should be added.
91 * @return {Ext.CompositeElement} This Composite object.
93 add : function(els, root){
95 elements = me.elements;
99 if(typeof els == "string"){
100 els = Ext.Element.selectorFunction(els, root);
101 }else if(els.isComposite){
103 }else if(!Ext.isIterable(els)){
107 for(var i = 0, len = els.length; i < len; ++i){
108 elements.push(me.transformElement(els[i]));
113 invoke : function(fn, args){
120 for(i = 0; i < len; i++) {
123 Ext.Element.prototype[fn].apply(me.getElement(e), args);
129 * Returns a flyweight Element of the dom element object at the specified index
130 * @param {Number} index
131 * @return {Ext.Element}
133 item : function(index){
135 el = me.elements[index],
139 out = me.getElement(el);
144 // fixes scope with flyweight
145 addListener : function(eventName, handler, scope, opt){
146 var els = this.elements,
150 for(i = 0; i<len; i++) {
153 Ext.EventManager.on(e, eventName, handler, scope || e, opt);
159 * <p>Calls the passed function for each element in this composite.</p>
160 * @param {Function} fn The function to call. The function is passed the following parameters:<ul>
161 * <li><b>el</b> : Element<div class="sub-desc">The current Element in the iteration.
162 * <b>This is the flyweight (shared) Ext.Element instance, so if you require a
163 * a reference to the dom node, use el.dom.</b></div></li>
164 * <li><b>c</b> : Composite<div class="sub-desc">This Composite object.</div></li>
165 * <li><b>idx</b> : Number<div class="sub-desc">The zero-based index in the iteration.</div></li>
167 * @param {Object} [scope] The scope (<i>this</i> reference) in which the function is executed. (defaults to the Element)
168 * @return {Ext.CompositeElement} this
170 each : function(fn, scope){
176 for(i = 0; i<len; i++) {
179 e = this.getElement(e);
180 if(fn.call(scope || e, e, me, i) === false){
189 * Clears this Composite and adds the elements passed.
190 * @param {HTMLElement[]/Ext.CompositeElement} els Either an array of DOM elements, or another Composite from which to fill this Composite.
191 * @return {Ext.CompositeElement} this
193 fill : function(els){
201 * Filters this composite to only elements that match the passed selector.
202 * @param {String/Function} selector A string CSS selector or a comparison function.
203 * The comparison function will be called with the following arguments:<ul>
204 * <li><code>el</code> : Ext.Element<div class="sub-desc">The current DOM element.</div></li>
205 * <li><code>index</code> : Number<div class="sub-desc">The current index within the collection.</div></li>
207 * @return {Ext.CompositeElement} this
209 filter : function(selector){
212 fn = Ext.isFunction(selector) ? selector
214 return el.is(selector);
217 me.each(function(el, self, i) {
218 if (fn(el, i) !== false) {
219 els[els.length] = me.transformElement(el);
228 * Find the index of the passed element within the composite collection.
229 * @param el {Mixed} The id of an element, or an Ext.Element, or an HtmlElement to find within the composite collection.
230 * @return Number The index of the passed Ext.Element in the composite collection, or -1 if not found.
232 indexOf : function(el){
233 return Ext.Array.indexOf(this.elements, this.transformElement(el));
237 * Replaces the specified element with the passed element.
238 * @param {String/HTMLElement/Ext.Element/Number} el The id of an element, the Element itself, the index of the element in this composite
240 * @param {String/Ext.Element} replacement The id of an element or the Element itself.
241 * @param {Boolean} domReplace (Optional) True to remove and replace the element in the document too.
242 * @return {Ext.CompositeElement} this
244 replaceElement : function(el, replacement, domReplace){
245 var index = !isNaN(el) ? el : this.indexOf(el),
248 replacement = Ext.getDom(replacement);
250 d = this.elements[index];
251 d.parentNode.insertBefore(replacement, d);
254 Ext.Array.splice(this.elements, index, 1, replacement);
260 * Removes all elements.
267 Ext.CompositeElementLite.prototype.on = Ext.CompositeElementLite.prototype.addListener;
271 * Copies all of the functions from Ext.Element's prototype onto CompositeElementLite's prototype.
272 * This is called twice - once immediately below, and once again after additional Ext.Element
273 * are added in Ext JS
275 Ext.CompositeElementLite.importElementMethods = function() {
277 ElProto = Ext.Element.prototype,
278 CelProto = Ext.CompositeElementLite.prototype;
280 for (fnName in ElProto) {
281 if (typeof ElProto[fnName] == 'function'){
283 CelProto[fnName] = CelProto[fnName] || function() {
284 return this.invoke(fnName, arguments);
286 }).call(CelProto, fnName);
292 Ext.CompositeElementLite.importElementMethods();
295 Ext.Element.selectorFunction = Ext.DomQuery.select;
299 * Selects elements based on the passed CSS selector to enable {@link Ext.Element Element} methods
300 * to be applied to many related elements in one statement through the returned {@link Ext.CompositeElement CompositeElement} or
301 * {@link Ext.CompositeElementLite CompositeElementLite} object.
302 * @param {String/HTMLElement[]} selector The CSS selector or an array of elements
303 * @param {HTMLElement/String} root (optional) The root element of the query or id of the root
304 * @return {Ext.CompositeElementLite/Ext.CompositeElement}
305 * @member Ext.Element
308 Ext.Element.select = function(selector, root){
310 if(typeof selector == "string"){
311 els = Ext.Element.selectorFunction(selector, root);
312 }else if(selector.length !== undefined){
317 sourceClass: "Ext.Element",
318 sourceMethod: "select",
321 msg: "Invalid selector specified: " + selector
325 return new Ext.CompositeElementLite(els);
328 * Selects elements based on the passed CSS selector to enable {@link Ext.Element Element} methods
329 * to be applied to many related elements in one statement through the returned {@link Ext.CompositeElement CompositeElement} or
330 * {@link Ext.CompositeElementLite CompositeElementLite} object.
331 * @param {String/HTMLElement[]} selector The CSS selector or an array of elements
332 * @param {HTMLElement/String} root (optional) The root element of the query or id of the root
333 * @return {Ext.CompositeElementLite/Ext.CompositeElement}
337 Ext.select = Ext.Element.select;