TreeView Drag and Drop Events

When you drag one or multiple items or nodes within the IntegralUI TreeView, a set of drag and drop events are fired, which you can handle in your code. An event can fire when dragged item enters or leaves the tree view space, when it is dragged over some other target item or when item drops. Although the default drag and drop functionality is sufficient in most cases, you have an option to alter it by handling these events. You can find below detailed information about each event.

Event log:

TreeView component is part of IntegralUI Web
a suite of UI Components for development of web apps

If you have any questions, don't hesitate to contact us at support@lidorsystems.com

In the demo, you are free to drag and drop items one by one within the TreeView. When item is dragged over a different item, you can drop it above, below or as a child of the target item. In this particular example, if you drag an item over the "Downloads" item, you can only drop it as a child, the above and below positions are disabled within the drag over event handler. To see how, read further below.

To see which event is fired and in what order, the list on right logs all drag and drop events that occur, where at top position shows the last event fired. The list shows event name, information about the source and target item, position and how many times the event fires.

Available Events for Drag and Drop in TreeView

Here is a list of available drag and drop events:

  • dragEnd - occurs when HTML5 drag and drop operation ends over TreeView space
  • dragEnter - occurs when item is dragged over TreeView space for the first time
  • dragDrop - occurs when item drops within the TreeView
  • dragLeave - occurs when dragged item leaves the TreeView space
  • dragOver - occurs when item is dragged over other items and TreeView space
  • dragStart - occurs when HTML5 drag and drop operation starts over TreeView space

By handling one or all of these events, you can place different conditions and change the overall drag drop behavior. A first, you need to check what data is included within each event.

What Data is Included in Drag and Drop Event

In general, the event data is the same for all events with some exceptions. For example, dragEnter and dragLeave events don't have an option for cancellation. Here is a list of all fields available within the event data:

  • action - specifies whether item is moved or copied
  • cancel - determines whether drag drop is cancelled
  • dragObj - specifies an item(s) that is dragged
  • dropPos - specifies position at which dragged item can drop
    • 0 - item will drop as a child of target item
    • 1 - item will drop above target item
    • 2 - item will drop below target item
    • -1 - item will drop at the end of item collection of target component
  • event - general HTML5 drag drop event data settings
  • isDropAllowed - determines whether item can drop
  • mousePos - position of mouse cursor in page coordinates
  • sourceCtrl - a reference to a component from which drag drop operation has started
  • targetCtrl - a reference to a component over which dragged item is dropped
  • targetObj - specifies the item over which dragged item is positioned or dropped

As you can see, there is enough data that you can use it in your code to create different conditions and change the drag drop in part or as a whole.

The event data is not limited to the Tree View only, sourceCtrl and targetCtrl can hold a references to other components like Grid, ListBox, ListView, and TreeGrid or it can be a custom web component. As long as the component uses IntegralUIDragDropService, you can share data from different components.

How to Handle Drag Enter and Drag Leave Events

The dragEnter and dragLeave events fire only once, the first one when dragged item enters the tree view space for the first time and the second event when it leaves.

You can use these events to add some conditions like:

  • validate whether the targetCtrl from the event data is a valid component or not in cases when you have multiple tree views
  • change the Tree View style so that its border appears in different color on enter
  • change the Tree View allowDrop property to false, and suspend any drops over its space

In case of changing the tree view appearance, when you start to drag an item, change the TreeView border color or add shadow effect, and when you leave its space while dragging an item, return it back to normal. For this purpose you can add a new CSS class in HTML settings, and activate this class on drag enter.

Currently ReactJS doesn't have full support for Web Components. Mainly because of the way data is passed to the component via attributes and their own synthetic event system. For this reason, you can use available wrappers located under /integralui/wrappers directory, which are ReactJS components that provide all public API from specific IntegralUI component.

These are only few examples on when you can use these events, but you can add any custom action that is more suitable for your application.

How to Change Action on Drag Over and Drop

We mentioned in beginning that you can drop and item above, below and as a child or target item. In this example, you can learn how to override the default behavior when dragging over the tree view, if the drop position is 1 (above) or 2 (below) the "Downloads" item, cancel the operation. This will hide the drop marker and show a NO DROP icon:

If you want to allow drop in position 1 and 2, but still the item to drop as a child, you can handle the drop event like this:

  1. Add a handler for dragDrop event
  2. Cancel the default behavior if the target is the "Downloads" item
  3. Remove the dragged item from the source component
  4. Add it as a child to the target item

Currently VueJS doesn't have full support for events fired from Web Components. Although events are fired, the event handler set in VueJS template using @eventName="methodName" will not work. For this reason, you can add event handlers using standard addEventListener method, like it is presented here.

In this case, you don't need to handle the dragOver event.

You can add other kinds of conditions, based on the event data. For example, you can use the drop position, whether action is drag move or drag copy, single or multiple items are dragged etc.

How to Cancel Drag and Drop Event

You can only cancel the dragOver and dragDrop events. To do this, add a handler function to these events and set the cancel field of the event data to true. However, this will prevent any other item(s) to drop. In real scenarios, you may need to set some condition and cancel the drag and drop when fulfilled, like in previous example.

In most cases, you may need to cancel the default behavior, when you want to change the item data prior it drops, or when you need to first validate whether the server data is updated prior committing the change in the client. For this purpose, the best is to use the built-in wait and resolve methods.

The wait method temporarily suspends the drag and drop process and after some conditions are met, the call to resolve method resumes it. This is useful for example, when item(s) drops:

  1. Handle the dragDrop event
  2. Suspend the process by calling wait
  3. Update your server data with new position of the item that drops
  4. Resume the process by calling resolve

Conclusion

Drag and Drop in the IntegralUI TreeView component is accompanied by few custom events that may occur when item dragging starts, enters, it is over, drops or leaves the tree view space. By handling these events in your code, you can add custom conditions and change the default functionality.

In some cases, when required you can cancel the event and prevent item from dropping. If you need to validate server data change prior item drops, you can override the default behavior by suspending the process and when you receive a confirmation from the server, resume it.

The TreeView is a native Web Component, part of IntegralUI Web that you can use in any JavaScript framework. All code samples for drag and drop events in TreeView component are presented in vanilla JavaScript, Angular, React and Vue.