Grid drag and drop documentation (#9055)

1 files changed, 105 insertions, 0 deletions

diff --git a/documentation/advanced/advanced-dragndrop.asciidoc b/documentation/advanced/advanced-dragndrop.asciidoc
index 6e085633c1..963a7a034d 100644
--- a/documentation/advanced/advanced-dragndrop.asciidoc
+++ b/documentation/advanced/advanced-dragndrop.asciidoc
@@ -143,6 +143,111 @@ compatible browser, such as Mozilla Firefox 3.6 or newer.
 
 ////
 
+[[advanced.dragndrop.grid]]
+== Drag and Drop Rows in Grid
+
+It is possible to drag and drop the rows of a Grid component. This allows reordering of rows, dragging rows between different Grids, dragging rows outside of a Grid or dropping data onto rows.
+
+=== Grid as a Drag Source
+
+A Grid component's rows can be made draggable by applying [classname]#GridDragSource# extension to the component. The extended Grid's rows become draggable, meaning that each row can be grabbed and moved by the mouse individually.
+When the Grid's selection mode is `SelectionMode.MULTI` and multiple rows are selected, it is possible to drag all the visible selected rows by grabbing one of them. However, when the grabbed row is not selected, only that one row will be dragged.
+
+The following example shows how you can define the allowed drag effect and customize the drag data with the drag data generator.
+
+[source,java]
+----
+Grid<Person> grid = new Grid<>();
+// ...
+GridDragSource<Person> dragSource = new GridDragSource<>(grid);
+
+// set allowed effects
+dragSource.setEffectAllowed(EffectAllowed.MOVE);
+
+// set the drag data generator
+dragSource.setDragDataGenerator(person -> {
+    JsonObject data = Json.createObject();
+    data.put("name", person.getFirstName() + " " + person.getLastName());
+    data.put("city", person.getAddress().getCity());
+    return data;
+});
+----
+
+The _drag data generator_ defines what data should be transferred when a row is dragged and dropped. The generator is executed for every inserted item and returns a `JsonObject` containing the data to be transferred for that item. The generated data is transferred as a JSON array using the HTML5 DataTransfer's data parameter of type `"text"`.
+When no generator is set, the whole row data is transferred as JSON, containing all the data generated by the attached [classname]#DataGenerator# instances, such as the row's content and its key.
+
+[NOTE]
+====
+Note that calling the inherited `setDataTransferText(String data)` method is not supported, since the drag data is set for each row based on the data provided by the generator.
+====
+
+The [classname]#GridDragStartEvent# is fired when dragging a row has started, and the [classname]#GridDragEndEvent# when the drag has ended, either in a drop or a cancel.
+
+[source,java]
+----
+dragSource.addGridDragStartListener(event ->
+    // Keep reference to the dragged items
+    draggedItems = event.getDraggedItems()
+);
+
+// Add drag end listener
+dragSource.addGridDragEndListener(event -> {
+    // If drop was successful, remove dragged items from source Grid
+    if (event.getDropEffect() == DropEffect.MOVE) {
+        ((ListDataProvider<Person>) grid.getDataProvider()).getItems()
+                .removeAll(draggedItems);
+        grid.getDataProvider().refreshAll();
+
+        // Remove reference to dragged items
+        draggedItems = null;
+    }
+});
+----
+
+The dragged rows can be accessed from both events using the `getDraggedItems()` method.
+
+=== Grid as a Drop Target
+
+To make a Grid component's rows accept a drop event, apply the [classname]#GridDropTarget# extension to the component. When creating the extension, you need to specify where the transferred data can be dropped on.
+
+[source,java]
+----
+Grid<Person> grid = new Grid<>();
+// ...
+GridDropTarget<Person> dropTarget = new GridDropTarget<>(grid, DropMode.BETWEEN);
+dropTarget.setDropEffect(DropEffect.MOVE);
+----
+
+The _drop mode_ specifies the behaviour of the row when an element is dragged over or dropped onto it. Use `DropMode.ON_TOP` when you want to drop elements on top of a row and `DropMode.BETWEEN` when you want to drop elements between rows.
+
+The [classname]#GridDropEvent# is fired when data is dropped onto one of the Grid's rows. The following example shows how you can insert items into the Grid at the drop position. If the drag source is another Grid, you can access the generated drag data with the event's `getDataTransferText()` method.
+
+[source,java]
+----
+dropTarget.addGridDropListener(event -> {
+    // Accepting dragged items from another Grid in the same UI
+    event.getDragSourceExtension().ifPresent(source -> {
+        if (source instanceof GridDragSource) {
+            // Get the target Grid's items
+            ListDataProvider<Person> dataProvider = (ListDataProvider<Person>)
+                    event.getComponent().getDataProvider();
+            List<Person> items = (List<Person>) dataProvider.getItems();
+
+            // Calculate the target row's index
+            int index = items.indexOf(event.getDropTargetRow()) + (
+                    event.getDropLocation() == DropLocation.BELOW ? 1 : 0);
+
+            // Add dragged items to the target Grid
+            items.addAll(index, draggedItems);
+            dataProvider.refreshAll();
+
+            // Show the dropped data
+            Notification.show("Dropped row data: " + event.getDataTransferText());
+        }
+    });
+});
+----
+
 (((range="endofrange", startref="term.advanced.dragndrop")))