src/grid/plugin/DragDrop.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  * This plugin provides drag and/or drop functionality for a GridView.
  17  *
  18  * It creates a specialized instance of {@link Ext.dd.DragZone DragZone} which knows how to drag out of a {@link
  19  * Ext.grid.View GridView} and loads the data object which is passed to a cooperating {@link Ext.dd.DragZone DragZone}'s
  20  * methods with the following properties:
  21  *
  22  * - `copy` : Boolean
  23  *
  24  *   The value of the GridView's `copy` property, or `true` if the GridView was configured with `allowCopy: true` _and_
  25  *   the control key was pressed when the drag operation was begun.
  26  *
  27  * - `view` : GridView
  28  *
  29  *   The source GridView from which the drag originated.
  30  *
  31  * - `ddel` : HtmlElement
  32  *
  33  *   The drag proxy element which moves with the mouse
  34  *
  35  * - `item` : HtmlElement
  36  *
  37  *   The GridView node upon which the mousedown event was registered.
  38  *
  39  * - `records` : Array
  40  *
  41  *   An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.
  42  *
  43  * It also creates a specialized instance of {@link Ext.dd.DropZone} which cooperates with other DropZones which are
  44  * members of the same ddGroup which processes such data objects.
  45  *
  46  * Adding this plugin to a view means that two new events may be fired from the client GridView, `{@link #beforedrop
  47  * beforedrop}` and `{@link #drop drop}`
  48  *
  49  *     @example
  50  *     Ext.create('Ext.data.Store', {
  51  *         storeId:'simpsonsStore',
  52  *         fields:['name'],
  53  *         data: [["Lisa"], ["Bart"], ["Homer"], ["Marge"]],
  54  *         proxy: {
  55  *             type: 'memory',
  56  *             reader: 'array'
  57  *         }
  58  *     });
  59  *
  60  *     Ext.create('Ext.grid.Panel', {
  61  *         store: 'simpsonsStore',
  62  *         columns: [
  63  *             {header: 'Name',  dataIndex: 'name', flex: true}
  64  *         ],
  65  *         viewConfig: {
  66  *             plugins: {
  67  *                 ptype: 'gridviewdragdrop',
  68  *                 dragText: 'Drag and drop to reorganize'
  69  *             }
  70  *         },
  71  *         height: 200,
  72  *         width: 400,
  73  *         renderTo: Ext.getBody()
  74  *     });
  75  */
  76 Ext.define('Ext.grid.plugin.DragDrop', {
  77     extend: 'Ext.AbstractPlugin',
  78     alias: 'plugin.gridviewdragdrop',
  79
  80     uses: [
  81         'Ext.view.DragZone',
  82         'Ext.grid.ViewDropZone'
  83     ],
  84
  85     /**
  86      * @event beforedrop
  87      * **This event is fired through the GridView. Add listeners to the GridView object**
  88      *
  89      * Fired when a drop gesture has been triggered by a mouseup event in a valid drop position in the GridView.
  90      *
  91      * @param {HTMLElement} node The GridView node **if any** over which the mouse was positioned.
  92      *
  93      * Returning `false` to this event signals that the drop gesture was invalid, and if the drag proxy will animate
  94      * back to the point from which the drag began.
  95      *
  96      * Returning `0` To this event signals that the data transfer operation should not take place, but that the gesture
  97      * was valid, and that the repair operation should not take place.
  98      *
  99      * Any other return value continues with the data transfer operation.
 100      *
 101      * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone
 102      * DragZone}'s {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:
 103      *
 104      * - copy : Boolean
 105      *
 106      *   The value of the GridView's `copy` property, or `true` if the GridView was configured with `allowCopy: true` and
 107      *   the control key was pressed when the drag operation was begun
 108      *
 109      * - view : GridView
 110      *
 111      *   The source GridView from which the drag originated.
 112      *
 113      * - ddel : HtmlElement
 114      *
 115      *   The drag proxy element which moves with the mouse
 116      *
 117      * - item : HtmlElement
 118      *
 119      *   The GridView node upon which the mousedown event was registered.
 120      *
 121      * - records : Array
 122      *
 123      *   An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.
 124      *
 125      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
 126      *
 127      * @param {String} dropPosition `"before"` or `"after"` depending on whether the mouse is above or below the midline
 128      * of the node.
 129      *
 130      * @param {Function} dropFunction
 131      *
 132      * A function to call to complete the data transfer operation and either move or copy Model instances from the
 133      * source View's Store to the destination View's Store.
 134      *
 135      * This is useful when you want to perform some kind of asynchronous processing before confirming the drop, such as
 136      * an {@link Ext.window.MessageBox#confirm confirm} call, or an Ajax request.
 137      *
 138      * Return `0` from this event handler, and call the `dropFunction` at any time to perform the data transfer.
 139      */
 140
 141     /**
 142      * @event drop
 143      * **This event is fired through the GridView. Add listeners to the GridView object** Fired when a drop operation
 144      * has been completed and the data has been moved or copied.
 145      *
 146      * @param {HTMLElement} node The GridView node **if any** over which the mouse was positioned.
 147      *
 148      * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone
 149      * DragZone}'s {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:
 150      *
 151      * - copy : Boolean
 152      *
 153      *   The value of the GridView's `copy` property, or `true` if the GridView was configured with `allowCopy: true` and
 154      *   the control key was pressed when the drag operation was begun
 155      *
 156      * - view : GridView
 157      *
 158      *   The source GridView from which the drag originated.
 159      *
 160      * - ddel : HtmlElement
 161      *
 162      *   The drag proxy element which moves with the mouse
 163      *
 164      * - item : HtmlElement
 165      *
 166      *   The GridView node upon which the mousedown event was registered.
 167      *
 168      * - records : Array
 169      *
 170      *   An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.
 171      *
 172      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
 173      *
 174      * @param {String} dropPosition `"before"` or `"after"` depending on whether the mouse is above or below the midline
 175      * of the node.
 176      */
 177
 178     dragText : '{0} selected row{1}',
 179
 180     /**
 181      * @cfg {String} ddGroup
 182      * A named drag drop group to which this object belongs. If a group is specified, then both the DragZones and
 183      * DropZone used by this plugin will only interact with other drag drop objects in the same group.
 184      */
 185     ddGroup : "GridDD",
 186
 187     /**
 188      * @cfg {String} dragGroup
 189      * The ddGroup to which the DragZone will belong.
 190      *
 191      * This defines which other DropZones the DragZone will interact with. Drag/DropZones only interact with other
 192      * Drag/DropZones which are members of the same ddGroup.
 193      */
 194
 195     /**
 196      * @cfg {String} dropGroup
 197      * The ddGroup to which the DropZone will belong.
 198      *
 199      * This defines which other DragZones the DropZone will interact with. Drag/DropZones only interact with other
 200      * Drag/DropZones which are members of the same ddGroup.
 201      */
 202
 203     /**
 204      * @cfg {Boolean} enableDrop
 205      * False to disallow the View from accepting drop gestures.
 206      */
 207     enableDrop: true,
 208
 209     /**
 210      * @cfg {Boolean} enableDrag
 211      * False to disallow dragging items from the View.
 212      */
 213     enableDrag: true,
 214
 215     init : function(view) {
 216         view.on('render', this.onViewRender, this, {single: true});
 217     },
 218
 219     /**
 220      * @private
 221      * AbstractComponent calls destroy on all its plugins at destroy time.
 222      */
 223     destroy: function() {
 224         Ext.destroy(this.dragZone, this.dropZone);
 225     },
 226
 227     enable: function() {
 228         var me = this;
 229         if (me.dragZone) {
 230             me.dragZone.unlock();
 231         }
 232         if (me.dropZone) {
 233             me.dropZone.unlock();
 234         }
 235         me.callParent();
 236     },
 237
 238     disable: function() {
 239         var me = this;
 240         if (me.dragZone) {
 241             me.dragZone.lock();
 242         }
 243         if (me.dropZone) {
 244             me.dropZone.lock();
 245         }
 246         me.callParent();
 247     },
 248
 249     onViewRender : function(view) {
 250         var me = this;
 251
 252         if (me.enableDrag) {
 253             me.dragZone = Ext.create('Ext.view.DragZone', {
 254                 view: view,
 255                 ddGroup: me.dragGroup || me.ddGroup,
 256                 dragText: me.dragText
 257             });
 258         }
 259
 260         if (me.enableDrop) {
 261             me.dropZone = Ext.create('Ext.grid.ViewDropZone', {
 262                 view: view,
 263                 ddGroup: me.dropGroup || me.ddGroup
 264             });
 265         }
 266     }
 267 });