src/src/dom/Element.insertion.js

   1 //@tag dom,core
   2 //@define Ext.Element-all
   3 //@define Ext.Element-insertion
   4 //@require Ext.Element-alignment
   5
   6 /**
   7  * @class Ext.dom.Element
   8  */
   9 Ext.dom.Element.addMembers({
  10
  11     /**
  12      * Appends the passed element(s) to this element.
  13      * @param {HTMLElement/Ext.dom.Element} element a DOM Node or an existing Element.
  14      * @return {Ext.dom.Element} This element.
  15      */
  16     appendChild: function(element) {
  17         this.dom.appendChild(Ext.getDom(element));
  18
  19         return this;
  20     },
  21
  22     removeChild: function(element) {
  23         this.dom.removeChild(Ext.getDom(element));
  24
  25         return this;
  26     },
  27
  28     append: function() {
  29         this.appendChild.apply(this, arguments);
  30     },
  31
  32     /**
  33      * Appends this element to the passed element.
  34      * @param {String/HTMLElement/Ext.dom.Element} el The new parent element.
  35      * The id of the node, a DOM Node or an existing Element.
  36      * @return {Ext.dom.Element} This element.
  37      */
  38     appendTo: function(el) {
  39         Ext.getDom(el).appendChild(this.dom);
  40         return this;
  41     },
  42
  43     /**
  44      * Inserts this element before the passed element in the DOM.
  45      * @param {String/HTMLElement/Ext.dom.Element} el The element before which this element will be inserted.
  46      * The id of the node, a DOM Node or an existing Element.
  47      * @return {Ext.dom.Element} This element.
  48      */
  49     insertBefore: function(el) {
  50         el = Ext.getDom(el);
  51         el.parentNode.insertBefore(this.dom, el);
  52         return this;
  53     },
  54
  55     /**
  56      * Inserts this element after the passed element in the DOM.
  57      * @param {String/HTMLElement/Ext.dom.Element} el The element to insert after.
  58      * The `id` of the node, a DOM Node or an existing Element.
  59      * @return {Ext.dom.Element} This element.
  60      */
  61     insertAfter: function(el) {
  62         el = Ext.getDom(el);
  63         el.parentNode.insertBefore(this.dom, el.nextSibling);
  64         return this;
  65     },
  66
  67
  68     /**
  69      * Inserts an element as the first child of this element.
  70      * @param {String/HTMLElement/Ext.dom.Element} element The `id` or element to insert.
  71      * @return {Ext.dom.Element} this
  72      */
  73     insertFirst: function(element) {
  74         var elementDom = Ext.getDom(element),
  75             dom = this.dom,
  76             firstChild = dom.firstChild;
  77
  78         if (!firstChild) {
  79             dom.appendChild(elementDom);
  80         }
  81         else {
  82             dom.insertBefore(elementDom, firstChild);
  83         }
  84
  85         return this;
  86     },
  87
  88     /**
  89      * Inserts (or creates) the passed element (or DomHelper config) as a sibling of this element
  90      * @param {String/HTMLElement/Ext.dom.Element/Object/Array} el The id, element to insert or a DomHelper config
  91      * to create and insert *or* an array of any of those.
  92      * @param {String} [where=before] (optional) 'before' or 'after'.
  93      * @param {Boolean} returnDom (optional) `true` to return the raw DOM element instead of Ext.dom.Element.
  94      * @return {Ext.dom.Element} The inserted Element. If an array is passed, the last inserted element is returned.
  95      */
  96     insertSibling: function(el, where, returnDom) {
  97         var me = this, rt,
  98             isAfter = (where || 'before').toLowerCase() == 'after',
  99             insertEl;
 100
 101         if (Ext.isArray(el)) {
 102             insertEl = me;
 103             Ext.each(el, function(e) {
 104                 rt = Ext.fly(insertEl, '_internal').insertSibling(e, where, returnDom);
 105                 if (isAfter) {
 106                     insertEl = rt;
 107                 }
 108             });
 109             return rt;
 110         }
 111
 112         el = el || {};
 113
 114         if (el.nodeType || el.dom) {
 115             rt = me.dom.parentNode.insertBefore(Ext.getDom(el), isAfter ? me.dom.nextSibling : me.dom);
 116             if (!returnDom) {
 117                 rt = Ext.get(rt);
 118             }
 119         } else {
 120             if (isAfter && !me.dom.nextSibling) {
 121                 rt = Ext.core.DomHelper.append(me.dom.parentNode, el, !returnDom);
 122             } else {
 123                 rt = Ext.core.DomHelper[isAfter ? 'insertAfter' : 'insertBefore'](me.dom, el, !returnDom);
 124             }
 125         }
 126         return rt;
 127     },
 128
 129     /**
 130      * Replaces the passed element with this element.
 131      * @param {String/HTMLElement/Ext.dom.Element} element The element to replace.
 132      * The id of the node, a DOM Node or an existing Element.
 133      * @return {Ext.dom.Element} This element.
 134      */
 135     replace: function(element) {
 136         element = Ext.getDom(element);
 137
 138         element.parentNode.replaceChild(this.dom, element);
 139
 140         return this;
 141     },
 142
 143     /**
 144      * Replaces this element with the passed element.
 145      * @param {String/HTMLElement/Ext.dom.Element/Object} el The new element (id of the node, a DOM Node
 146      * or an existing Element) or a DomHelper config of an element to create.
 147      * @return {Ext.dom.Element} This element.
 148      */
 149     replaceWith: function(el) {
 150         var me = this;
 151
 152         if (el.nodeType || el.dom || typeof el == 'string') {
 153             el = Ext.get(el);
 154             me.dom.parentNode.insertBefore(el.dom, me.dom);
 155         } else {
 156             el = Ext.core.DomHelper.insertBefore(me.dom, el);
 157         }
 158
 159         delete Ext.cache[me.id];
 160         Ext.removeNode(me.dom);
 161         me.id = Ext.id(me.dom = el);
 162         return me;
 163     },
 164
 165     doReplaceWith: function(element) {
 166         var dom = this.dom;
 167         dom.parentNode.replaceChild(Ext.getDom(element), dom);
 168     },
 169
 170     /**
 171      * Creates the passed DomHelper config and appends it to this element or optionally inserts it before the passed child element.
 172      * @param {Object} config DomHelper element config object.  If no tag is specified (e.g., `{tag:'input'}`) then a div will be
 173      * automatically generated with the specified attributes.
 174      * @param {HTMLElement} insertBefore (optional) a child element of this element.
 175      * @param {Boolean} returnDom (optional) `true` to return the dom node instead of creating an Element.
 176      * @return {Ext.dom.Element} The new child element.
 177      */
 178     createChild: function(config, insertBefore, returnDom) {
 179         config = config || {tag: 'div'};
 180         if (insertBefore) {
 181             return Ext.core.DomHelper.insertBefore(insertBefore, config, returnDom !== true);
 182         }
 183         else {
 184             return Ext.core.DomHelper[!this.dom.firstChild ? 'insertFirst' : 'append'](this.dom, config, returnDom !== true);
 185         }
 186     },
 187
 188     /**
 189      * Creates and wraps this element with another element.
 190      * @param {Object} [config] (optional) DomHelper element config object for the wrapper element or `null` for an empty div
 191      * @param {Boolean} [domNode] (optional) `true` to return the raw DOM element instead of Ext.dom.Element.
 192      * @return {HTMLElement/Ext.dom.Element} The newly created wrapper element.
 193      */
 194     wrap: function(config, domNode) {
 195         var dom = this.dom,
 196             wrapper = this.self.create(config, domNode),
 197             wrapperDom = (domNode) ? wrapper : wrapper.dom,
 198             parentNode = dom.parentNode;
 199
 200         if (parentNode) {
 201             parentNode.insertBefore(wrapperDom, dom);
 202         }
 203
 204         wrapperDom.appendChild(dom);
 205
 206         return wrapper;
 207     },
 208
 209     wrapAllChildren: function(config) {
 210         var dom = this.dom,
 211             children = dom.childNodes,
 212             wrapper = this.self.create(config),
 213             wrapperDom = wrapper.dom;
 214
 215         while (children.length > 0) {
 216             wrapperDom.appendChild(dom.firstChild);
 217         }
 218
 219         dom.appendChild(wrapperDom);
 220
 221         return wrapper;
 222     },
 223
 224     unwrapAllChildren: function() {
 225         var dom = this.dom,
 226             children = dom.childNodes,
 227             parentNode = dom.parentNode;
 228
 229         if (parentNode) {
 230             while (children.length > 0) {
 231                 parentNode.insertBefore(dom, dom.firstChild);
 232             }
 233
 234             this.destroy();
 235         }
 236     },
 237
 238     unwrap: function() {
 239         var dom = this.dom,
 240             parentNode = dom.parentNode,
 241             grandparentNode;
 242
 243         if (parentNode) {
 244             grandparentNode = parentNode.parentNode;
 245             grandparentNode.insertBefore(dom, parentNode);
 246             grandparentNode.removeChild(parentNode);
 247         }
 248         else {
 249             grandparentNode = document.createDocumentFragment();
 250             grandparentNode.appendChild(dom);
 251         }
 252
 253         return this;
 254     },
 255
 256     detach: function() {
 257         var dom = this.dom;
 258
 259         if (dom && dom.parentNode && dom.tagName !== 'BODY') {
 260             dom.parentNode.removeChild(dom);
 261         }
 262
 263         return this;
 264     },
 265
 266     /**
 267      * Inserts an HTML fragment into this element.
 268      * @param {String} where Where to insert the HTML in relation to this element - 'beforeBegin', 'afterBegin', 'beforeEnd', 'afterEnd'.
 269      * See {@link Ext.DomHelper#insertHtml} for details.
 270      * @param {String} html The HTML fragment
 271      * @param {Boolean} [returnEl=false] (optional) `true` to return an Ext.dom.Element.
 272      * @return {HTMLElement/Ext.dom.Element} The inserted node (or nearest related if more than 1 inserted).
 273      */
 274     insertHtml: function(where, html, returnEl) {
 275         var el = Ext.core.DomHelper.insertHtml(where, this.dom, html);
 276         return returnEl ? Ext.get(el) : el;
 277     }
 278 });