src/tree/plugin/TreeViewDragDrop.js

   1 /**
   2  * @class Ext.tree.ViewDDPlugin
   3  * @extends Ext.AbstractPlugin
   4  * <p>This plugin provides drag and/or drop functionality for a TreeView.</p>
   5  * <p>It creates a specialized instance of {@link Ext.dd.DragZone DragZone} which knows how to drag out of a {@link Ext.tree.View TreeView}
   6  * and loads the data object which is passed to a cooperating {@link Ext.dd.DragZone DragZone}'s methods with the following properties:<ul>
   7  * <li>copy : Boolean
   8  *  <div class="sub-desc">The value of the TreeView's <code>copy</code> property, or <code>true</code> if the TreeView was configured
   9  *  with <code>allowCopy: true</code> <u>and</u> the control key was pressed when the drag operation was begun.</div></li>
  10  * <li>view : TreeView
  11  *  <div class="sub-desc">The source TreeView from which the drag originated.</div></li>
  12  * <li>ddel : HtmlElement
  13  *  <div class="sub-desc">The drag proxy element which moves with the mouse</div></li>
  14  * <li>item : HtmlElement
  15  *  <div class="sub-desc">The TreeView node upon which the mousedown event was registered.</div></li>
  16  * <li>records : Array
  17  *  <div class="sub-desc">An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source TreeView.</div></li>
  18  * </ul></p>
  19  * <p>It also creates a specialized instance of {@link Ext.dd.DropZone} which cooperates with other DropZones which are members of the same
  20  * ddGroup which processes such data objects.</p>
  21  * <p>Adding this plugin to a view means that two new events may be fired from the client TreeView, <code>{@link #event-beforedrop beforedrop}</code> and
  22  * <code>{@link #event-drop drop}</code></p>
  23  */
  24 Ext.define('Ext.tree.plugin.TreeViewDragDrop', {
  25     extend: 'Ext.AbstractPlugin',
  26     alias: 'plugin.treeviewdragdrop',
  27
  28     uses: [
  29         'Ext.tree.ViewDragZone',
  30         'Ext.tree.ViewDropZone'
  31     ],
  32
  33     /**
  34      * @event beforedrop
  35      * <p><b>This event is fired through the TreeView. Add listeners to the TreeView object</b></p>
  36      * <p>Fired when a drop gesture has been triggered by a mouseup event in a valid drop position in the TreeView.
  37      * @param {HtmlElement} node The TreeView node <b>if any</b> over which the mouse was positioned.</p>
  38      * <p>Returning <code>false</code> to this event signals that the drop gesture was invalid, and if the drag proxy
  39      * will animate back to the point from which the drag began.</p>
  40      * <p>Returning <code>0</code> To this event signals that the data transfer operation should not take place, but
  41      * that the gesture was valid, and that the repair operation should not take place.</p>
  42      * <p>Any other return value continues with the data transfer operation.</p>
  43      * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone DragZone}'s
  44      * {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:<ul>
  45      * <li>copy : Boolean
  46      *  <div class="sub-desc">The value of the TreeView's <code>copy</code> property, or <code>true</code> if the TreeView was configured
  47      *  with <code>allowCopy: true</code> and the control key was pressed when the drag operation was begun</div></li>
  48      * <li>view : TreeView
  49      *  <div class="sub-desc">The source TreeView from which the drag originated.</div></li>
  50      * <li>ddel : HtmlElement
  51      *  <div class="sub-desc">The drag proxy element which moves with the mouse</div></li>
  52      * <li>item : HtmlElement
  53      *  <div class="sub-desc">The TreeView node upon which the mousedown event was registered.</div></li>
  54      * <li>records : Array
  55      *  <div class="sub-desc">An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source TreeView.</div></li>
  56      * </ul>
  57      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
  58      * @param {String} dropPosition <code>"before"</code>, <code>"after"</code> or <code>"append"</code> depending on whether the mouse is above or below the midline of the node,
  59      * or the node is a branch node which accepts new child nodes.
  60      * @param {Function} dropFunction <p>A function to call to complete the data transfer operation and either move or copy Model instances from the source
  61      * View's Store to the destination View's Store.</p>
  62      * <p>This is useful when you want to perform some kind of asynchronous processing before confirming
  63      * the drop, such as an {@link Ext.window.MessageBox#confirm confirm} call, or an Ajax request.</p>
  64      * <p>Return <code>0</code> from this event handler, and call the <code>dropFunction</code> at any time to perform the data transfer.</p>
  65      */
  66
  67     /**
  68      * @event drop
  69      * <b>This event is fired through the TreeView. Add listeners to the TreeView object</b>
  70      * Fired when a drop operation has been completed and the data has been moved or copied.
  71      * @param {HtmlElement} node The TreeView node <b>if any</b> over which the mouse was positioned.
  72      * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone DragZone}'s
  73      * {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:<ul>
  74      * <li>copy : Boolean
  75      *  <div class="sub-desc">The value of the TreeView's <code>copy</code> property, or <code>true</code> if the TreeView was configured
  76      *  with <code>allowCopy: true</code> and the control key was pressed when the drag operation was begun</div></li>
  77      * <li>view : TreeView
  78      *  <div class="sub-desc">The source TreeView from which the drag originated.</div></li>
  79      * <li>ddel : HtmlElement
  80      *  <div class="sub-desc">The drag proxy element which moves with the mouse</div></li>
  81      * <li>item : HtmlElement
  82      *  <div class="sub-desc">The TreeView node upon which the mousedown event was registered.</div></li>
  83      * <li>records : Array
  84      *  <div class="sub-desc">An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source TreeView.</div></li>
  85      * </ul>
  86      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
  87      * @param {String} dropPosition <code>"before"</code>, <code>"after"</code> or <code>"append"</code> depending on whether the mouse is above or below the midline of the node,
  88      * or the node is a branch node which accepts new child nodes.
  89      */
  90
  91     dragText : '{0} selected node{1}',
  92
  93     /**
  94      * @cfg {Boolean} allowParentInsert
  95      * Allow inserting a dragged node between an expanded parent node and its first child that will become a
  96      * sibling of the parent when dropped (defaults to false)
  97      */
  98     allowParentInserts: false,
  99
 100     /**
 101      * @cfg {String} allowContainerDrop
 102      * True if drops on the tree container (outside of a specific tree node) are allowed (defaults to false)
 103      */
 104     allowContainerDrops: false,
 105
 106     /**
 107      * @cfg {String} appendOnly
 108      * True if the tree should only allow append drops (use for trees which are sorted, defaults to false)
 109      */
 110     appendOnly: false,
 111
 112     /**
 113      * @cfg {String} ddGroup
 114      * A named drag drop group to which this object belongs.  If a group is specified, then both the DragZones and DropZone
 115      * used by this plugin will only interact with other drag drop objects in the same group (defaults to 'TreeDD').
 116      */
 117     ddGroup : "TreeDD",
 118
 119     /**
 120      * @cfg {String} dragGroup
 121      * <p>The ddGroup to which the DragZone will belong.</p>
 122      * <p>This defines which other DropZones the DragZone will interact with. Drag/DropZones only interact with other Drag/DropZones
 123      * which are members of the same ddGroup.</p>
 124      */
 125
 126     /**
 127      * @cfg {String} dropGroup
 128      * <p>The ddGroup to which the DropZone will belong.</p>
 129      * <p>This defines which other DragZones the DropZone will interact with. Drag/DropZones only interact with other Drag/DropZones
 130      * which are members of the same ddGroup.</p>
 131      */
 132
 133     /**
 134      * @cfg {String} expandDelay
 135      * The delay in milliseconds to wait before expanding a target tree node while dragging a droppable node
 136      * over the target (defaults to 1000)
 137      */
 138     expandDelay : 1000,
 139
 140     /**
 141      * @cfg {Boolean} enableDrop
 142      * <p>Defaults to <code>true</code></p>
 143      * <p>Set to <code>false</code> to disallow the View from accepting drop gestures</p>
 144      */
 145     enableDrop: true,
 146
 147     /**
 148      * @cfg {Boolean} enableDrag
 149      * <p>Defaults to <code>true</code></p>
 150      * <p>Set to <code>false</code> to disallow dragging items from the View </p>
 151      */
 152     enableDrag: true,
 153
 154     /**
 155      * @cfg {String} nodeHighlightColor The color to use when visually highlighting the dragged
 156      * or dropped node (defaults to 'c3daf9' - light blue). The color must be a 6 digit hex value, without
 157      * a preceding '#'. See also {@link #nodeHighlightOnDrop} and {@link #nodeHighlightOnRepair}.
 158      */
 159     nodeHighlightColor: 'c3daf9',
 160
 161     /**
 162      * @cfg {Boolean} nodeHighlightOnDrop Whether or not to highlight any nodes after they are
 163      * successfully dropped on their target. Defaults to the value of `Ext.enableFx`.
 164      * See also {@link #nodeHighlightColor} and {@link #nodeHighlightOnRepair}.
 165      * @markdown
 166      */
 167     nodeHighlightOnDrop: Ext.enableFx,
 168
 169     /**
 170      * @cfg {Boolean} nodeHighlightOnRepair Whether or not to highlight any nodes after they are
 171      * repaired from an unsuccessful drag/drop. Defaults to the value of `Ext.enableFx`.
 172      * See also {@link #nodeHighlightColor} and {@link #nodeHighlightOnDrop}.
 173      * @markdown
 174      */
 175     nodeHighlightOnRepair: Ext.enableFx,
 176
 177     init : function(view) {
 178         view.on('render', this.onViewRender, this, {single: true});
 179     },
 180
 181     /**
 182      * @private
 183      * AbstractComponent calls destroy on all its plugins at destroy time.
 184      */
 185     destroy: function() {
 186         Ext.destroy(this.dragZone, this.dropZone);
 187     },
 188
 189     onViewRender : function(view) {
 190         var me = this;
 191
 192         if (me.enableDrag) {
 193             me.dragZone = Ext.create('Ext.tree.ViewDragZone', {
 194                 view: view,
 195                 ddGroup: me.dragGroup || me.ddGroup,
 196                 dragText: me.dragText,
 197                 repairHighlightColor: me.nodeHighlightColor,
 198                 repairHighlight: me.nodeHighlightOnRepair
 199             });
 200         }
 201
 202         if (me.enableDrop) {
 203             me.dropZone = Ext.create('Ext.tree.ViewDropZone', {
 204                 view: view,
 205                 ddGroup: me.dropGroup || me.ddGroup,
 206                 allowContainerDrops: me.allowContainerDrops,
 207                 appendOnly: me.appendOnly,
 208                 allowParentInserts: me.allowParentInserts,
 209                 expandDelay: me.expandDelay,
 210                 dropHighlightColor: me.nodeHighlightColor,
 211                 dropHighlight: me.nodeHighlightOnDrop
 212             });
 213         }
 214     }
 215 });