src/core/src/dom/Element.insertion.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   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.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @class Ext.Element
  17  */
  18 Ext.Element.addMethods({
  19     /**
  20      * Appends the passed element(s) to this element
  21      * @param {String/HTMLElement/Ext.Element} el
  22      * The id of the node, a DOM Node or an existing Element.
  23      * @return {Ext.Element} this
  24      */
  25     appendChild : function(el) {
  26         return Ext.get(el).appendTo(this);
  27     },
  28
  29     /**
  30      * Appends this element to the passed element
  31      * @param {String/HTMLElement/Ext.Element} el The new parent element.
  32      * The id of the node, a DOM Node or an existing Element.
  33      * @return {Ext.Element} this
  34      */
  35     appendTo : function(el) {
  36         Ext.getDom(el).appendChild(this.dom);
  37         return this;
  38     },
  39
  40     /**
  41      * Inserts this element before the passed element in the DOM
  42      * @param {String/HTMLElement/Ext.Element} el The element before which this element will be inserted.
  43      * The id of the node, a DOM Node or an existing Element.
  44      * @return {Ext.Element} this
  45      */
  46     insertBefore : function(el) {
  47         el = Ext.getDom(el);
  48         el.parentNode.insertBefore(this.dom, el);
  49         return this;
  50     },
  51
  52     /**
  53      * Inserts this element after the passed element in the DOM
  54      * @param {String/HTMLElement/Ext.Element} el The element to insert after.
  55      * The id of the node, a DOM Node or an existing Element.
  56      * @return {Ext.Element} this
  57      */
  58     insertAfter : function(el) {
  59         el = Ext.getDom(el);
  60         el.parentNode.insertBefore(this.dom, el.nextSibling);
  61         return this;
  62     },
  63
  64     /**
  65      * Inserts (or creates) an element (or DomHelper config) as the first child of this element
  66      * @param {String/HTMLElement/Ext.Element/Object} el The id or element to insert or a DomHelper config
  67      * to create and insert
  68      * @return {Ext.Element} The new child
  69      */
  70     insertFirst : function(el, returnDom) {
  71         el = el || {};
  72         if (el.nodeType || el.dom || typeof el == 'string') { // element
  73             el = Ext.getDom(el);
  74             this.dom.insertBefore(el, this.dom.firstChild);
  75             return !returnDom ? Ext.get(el) : el;
  76         }
  77         else { // dh config
  78             return this.createChild(el, this.dom.firstChild, returnDom);
  79         }
  80     },
  81
  82     /**
  83      * Inserts (or creates) the passed element (or DomHelper config) as a sibling of this element
  84      * @param {String/HTMLElement/Ext.Element/Object/Array} el The id, element to insert or a DomHelper config
  85      * to create and insert *or* an array of any of those.
  86      * @param {String} where (optional) 'before' or 'after' defaults to before
  87      * @param {Boolean} returnDom (optional) True to return the .;ll;l,raw DOM element instead of Ext.Element
  88      * @return {Ext.Element} The inserted Element. If an array is passed, the last inserted element is returned.
  89      */
  90     insertSibling: function(el, where, returnDom){
  91         var me = this, rt,
  92         isAfter = (where || 'before').toLowerCase() == 'after',
  93         insertEl;
  94
  95         if(Ext.isArray(el)){
  96             insertEl = me;
  97             Ext.each(el, function(e) {
  98                 rt = Ext.fly(insertEl, '_internal').insertSibling(e, where, returnDom);
  99                 if(isAfter){
 100                     insertEl = rt;
 101                 }
 102             });
 103             return rt;
 104         }
 105
 106         el = el || {};
 107
 108         if(el.nodeType || el.dom){
 109             rt = me.dom.parentNode.insertBefore(Ext.getDom(el), isAfter ? me.dom.nextSibling : me.dom);
 110             if (!returnDom) {
 111                 rt = Ext.get(rt);
 112             }
 113         }else{
 114             if (isAfter && !me.dom.nextSibling) {
 115                 rt = Ext.DomHelper.append(me.dom.parentNode, el, !returnDom);
 116             } else {
 117                 rt = Ext.DomHelper[isAfter ? 'insertAfter' : 'insertBefore'](me.dom, el, !returnDom);
 118             }
 119         }
 120         return rt;
 121     },
 122
 123     /**
 124      * Replaces the passed element with this element
 125      * @param {String/HTMLElement/Ext.Element} el The element to replace.
 126      * The id of the node, a DOM Node or an existing Element.
 127      * @return {Ext.Element} this
 128      */
 129     replace : function(el) {
 130         el = Ext.get(el);
 131         this.insertBefore(el);
 132         el.remove();
 133         return this;
 134     },
 135
 136     /**
 137      * Replaces this element with the passed element
 138      * @param {String/HTMLElement/Ext.Element/Object} el The new element (id of the node, a DOM Node
 139      * or an existing Element) or a DomHelper config of an element to create
 140      * @return {Ext.Element} this
 141      */
 142     replaceWith: function(el){
 143         var me = this;
 144
 145         if(el.nodeType || el.dom || typeof el == 'string'){
 146             el = Ext.get(el);
 147             me.dom.parentNode.insertBefore(el, me.dom);
 148         }else{
 149             el = Ext.DomHelper.insertBefore(me.dom, el);
 150         }
 151
 152         delete Ext.cache[me.id];
 153         Ext.removeNode(me.dom);
 154         me.id = Ext.id(me.dom = el);
 155         Ext.Element.addToCache(me.isFlyweight ? new Ext.Element(me.dom) : me);
 156         return me;
 157     },
 158
 159     /**
 160      * Creates the passed DomHelper config and appends it to this element or optionally inserts it before the passed child element.
 161      * @param {Object} config DomHelper element config object.  If no tag is specified (e.g., {tag:'input'}) then a div will be
 162      * automatically generated with the specified attributes.
 163      * @param {HTMLElement} insertBefore (optional) a child element of this element
 164      * @param {Boolean} returnDom (optional) true to return the dom node instead of creating an Element
 165      * @return {Ext.Element} The new child element
 166      */
 167     createChild : function(config, insertBefore, returnDom) {
 168         config = config || {tag:'div'};
 169         if (insertBefore) {
 170             return Ext.DomHelper.insertBefore(insertBefore, config, returnDom !== true);
 171         }
 172         else {
 173             return Ext.DomHelper[!this.dom.firstChild ? 'insertFirst' : 'append'](this.dom, config,  returnDom !== true);
 174         }
 175     },
 176
 177     /**
 178      * Creates and wraps this element with another element
 179      * @param {Object} config (optional) DomHelper element config object for the wrapper element or null for an empty div
 180      * @param {Boolean} returnDom (optional) True to return the raw DOM element instead of Ext.Element
 181      * @return {HTMLElement/Ext.Element} The newly created wrapper element
 182      */
 183     wrap : function(config, returnDom) {
 184         var newEl = Ext.DomHelper.insertBefore(this.dom, config || {tag: "div"}, !returnDom),
 185             d = newEl.dom || newEl;
 186
 187         d.appendChild(this.dom);
 188         return newEl;
 189     },
 190
 191     /**
 192      * Inserts an html fragment into this element
 193      * @param {String} where Where to insert the html in relation to this element - beforeBegin, afterBegin, beforeEnd, afterEnd.
 194      * See {@link Ext.DomHelper#insertHtml} for details.
 195      * @param {String} html The HTML fragment
 196      * @param {Boolean} returnEl (optional) True to return an Ext.Element (defaults to false)
 197      * @return {HTMLElement/Ext.Element} The inserted node (or nearest related if more than 1 inserted)
 198      */
 199     insertHtml : function(where, html, returnEl) {
 200         var el = Ext.DomHelper.insertHtml(where, this.dom, html);
 201         return returnEl ? Ext.get(el) : el;
 202     }
 203 });
 204