Add API for multiple drag data generators (#9321)

* Add ability to set multiple drag data generators for any drag data type
and change default to be accepted by spreadsheet applications such as Excel

1 files changed, 14 insertions, 14 deletions

diff --git a/documentation/advanced/advanced-dragndrop.asciidoc b/documentation/advanced/advanced-dragndrop.asciidoc
index d3d2913d70..4a4499b81f 100644
--- a/documentation/advanced/advanced-dragndrop.asciidoc
+++ b/documentation/advanced/advanced-dragndrop.asciidoc
@@ -234,7 +234,12 @@ When the Grid's selection mode is `SelectionMode.MULTI` and multiple rows are se
 It is important to note that when dragging multiple rows, only the visible selected rows will be set as dragged data.
 ====
 
-The following example shows how you can define the allowed drag effect and customize the drag data with the drag data generator.
+By default, the drag data of type `"text"` will contain the content of each column separated by a tabulator character (`"\t"`).
+When multiple rows are dragged, the generated data is combined into one String separated by new line characters (`"\n"`).
+You can override the default behaviour and provide a custom drag data for each item by setting a custom _drag data generator_ for the `"text"` type.
+The generator is executed for each item and returns a `String` containing the data to be transferred for that item.
+
+The following example shows how you can define the allowed drag effect and customize the drag data by setting a drag data generator.
 
 [source,java]
 ----
@@ -245,22 +250,16 @@ 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;
+// add a drag data generator
+dragSource.setDragDataGenerator("text", person -> {
+    return person.getFirstName() + " " + person.getLastName() +
+           "\t" +  // tabulator character
+           person.getAddress().getCity();
 });
 ----
 
-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.
-====
+It is possible to set multiple generators with the `setDragDataGenerator(type, generator)` method.
+The generated data will be set as data transfer data with the given type and can then be accessed during drop from the drop event's `getDataTransferData(type)` method.
 
 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.
 
@@ -306,6 +305,7 @@ 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.
+If the drag source Grid uses a custom generator for a different type than `"text"`, you can access it's generated data using the `getDataTransferData(type)` method.
 
 [source,java]
 ----