You are viewing documentation for Vaadin Framework 8 and related products View documentation for Vaadin Framework 7 ›
Drag and Drop · Vaadin
Vaadin Framework - Advanced Topics - Drag and Drop
 Edit This Page

Drag and Drop

This feature is currently being developed and only available in the Framework 8.1 prerelease versions, starting from 8.1.0.alpha1.

Dragging an object from one location to another by grabbing it with mouse, holding the mouse button pressed, and then releasing the button to "drop" it to the other location is a common way to move, copy, or associate objects. For example, most operating systems allow dragging and dropping files between folders or dragging a document on a program to open it. Framework version 8.1 adds support for HTML5 drag and drop features. This makes it possible to set components as drag sources that user can drag and drop, or to set them as drop targets to drop things on.

Drag Source

Any component can be made a drag source that has textual data that is transferred when it is dragged and dropped.

To make a component a drag source, you apply the DragSourceExtension to it. Then you can define the text to transfer, and the allowed drag effect.

Label draggableLabel = new Label("You can grab and drag me");
DragSourceExtension<Label> dragSource = new DragSourceExtension<>(draggableLabel);

// set the allowed effect
dragSource.setEffectAllowed(EffectAllowed.MOVE);
// set the text to transfer
dragSource.setDataTransferText("hello receiver");

The effect allowed specifies the allowed effects that must match the drop effect of the drop target. If these don’t match, the drop event is never fired on the target. If multiple effects are allowed, the user can use the modifier keys to switch between the desired effects. The default effect and the modifier keys are system and browser dependent.

The data transfer text is textual data, that the drop target will receive in the drop event.

The DragStartEvent is fired when the drag has started, and the DragEndEvent event when the drag has ended, either in a drop or a cancel.

dragSource.addDragStartListener(event ->
    event.getComponent().addStyleName("dragged")
);
dragSource.addDragEndListener(event ->
    event.getComponent().removeStyleName("dragged")
);

It is possible to transfer any Object as server side data to the drop target if both the drag source and drop target are placed in the same UI. This data is available in the drop event via the DropEvent.getDragData() method.

dragSource.addDragStartListener(event ->
    dragSource.setDragData(myObject);
);
dragSource.addDragEndListener(event ->
    dragSource.setDragData(null);
};

The browsers allow the user to select and drag and drop text, which may cause some issues when trying to drag a component that has text. You can fix this by setting the following style rule to the drag source component to prevent dragging of the text instead of the whole component.

user-select: none;

Drop Target

The drag operations end when the mouse button is released on a valid drop target. It is then up to the target to react to the drop event and the data associated with the drag, set by the drag source.

To make a component be a drop target, you apply the DropTargetExtension to it. The extension allows you to control when the drop is acceptable and then react to the drop event.

VerticalLayout dropTargetLayout = new VerticalLayout();
dropTargetLayout.setCaption("Drop things inside me");
dropTargetLayout.addStyleName(ValoTheme.LAYOUT_CARD);

// make the layout accept drops
DropTargetExtension<VerticalLayout> dropTarget = new DropTargetExtension<>(dropTargetLayout);

// the drop effect must match the allowed effect in the drag source for a successful drop
dropTarget.setDropEffect(DropEffect.MOVE);

// catch the drops
dropTarget.addDropListener(event -> {
    // if the drag source is in the same UI as the target
    Optional<AbstractComponent> dragSource = event.getDragSourceComponent();
    if (dragSource.isPresent() && dragSource.get() instanceof Label) {
        // move the label to the layout
        dropTargetLayout.addComponent(dragSource.get());

        // get possible transfer data
        String message = event.getDataTransferText();
        Notification.show("DropEvent with data transfer: "+ message);

        // handle possible server side drag data, if the drag source was in the same UI
        event.getDragData().ifPresent(data -> handleMyDragData((MyObject) data));
    }
});

When data is dragged over a drop target, the v-drag-over class name is applied to the root element of the drop target component automatically.

Controlling When The Drop is Acceptable

The drop effect allows you to specify the desired drop effect, and for a succesful drop it must match the allowed effect that has been set for the drag source. Note that you can allow multiple effects, and that you should not rely on the default effect since it may vary between browsers.

The drag over criteria allows you determine whether the current drag source is allowed as a drop target, when the source is moved on top of the target. It is a script that is executed always when the dragover event is fired for the first time for this source, and returning false will prevent showing any drop effect. The script gets the dragover event as a parameter named event.

The drop criteria is similar to drag over criteria, but it is executed when the user has dropped the data by releasing the mouse button. The script gets the drop event as a parameter named event. Returning false will prevent the drop and no drop event is fired on the server side.

===

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 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.

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 DataGenerator instances, such as the row’s content and its key.

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 GridDragStartEvent is fired when dragging a row has started, and the GridDragEndEvent when the drag has ended, either in a drop or a cancel.

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 GridDropTarget extension to the component. When creating the extension, you need to specify where the transferred data can be dropped on.

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 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.

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());
        }
    });
});