src/core/core/CompositeElementLite.js

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