Drag and drop directives

Drag and drop directives are special attributes that can be used on template nodes to perform drag and drop operations.

Main directives

The following directives are the main directives to set up drag and drop.

`draggable`

Sets whether the node can be dragged.

Directive name : dragdrop:draggable

The value must be a boolean indicating whether the node can be dragged. The value can be a constrant or bound to a boolean field.

Example :

<repeat values="@Fields.List">
  <vertical-layout style:background="primary-100" layout:height="50" dragdrop:draggable="true">
    <text size="extralarge">
      $Item.Text
    </text>
  </vertical-layout>
</repeat>

For each element of the list, a vertical-layout node is created. On each node, we indicate it can be dragged.

`data`

Sets the data associated with the draggable node.

Directive name : dragdrop:data

The value must be a string or an object.

Example :

<repeat values="@Fields.List">
  <vertical-layout style:background="primary-100" layout:height="50" dragdrop:draggable="true" dragdrop:data="$Item">
    <text size="extralarge">
      $Item.Text
    </text>
  </vertical-layout>
</repeat>

In this example, the iterated element of the list is associated with its respective draggable node.

`dragover`

Sets the UI method that indicates whether a dragged node can be dropped on the node where the directive is.

Directive name : dragdrop:dragover

The value must be the name of a method that returns a boolean.

The method takes as first parameter a IDragEventArgs object. If the node bearing the directive is in a repeat node, the method must take a second parameter corresponding to the iterated element.

Example :

Template:

<repeat values="@Fields.List">
  <vertical-layout style:background="primary-100" layout:height="50" dragdrop:draggable="true" dragdrop:data="$Item">
    <text size="extralarge">
      $Item.Text
    </text>
  </vertical-layout>
</repeat>

<vertical-layout dragdrop:dragover="HandleDragOverOnDropzone">
  <text size="extralarge">
    Drop zone
  </text>
</vertical-layout>

HandleDragOverOnDropzone method:
- args : IDragEventArgs

return args.GetInternalDataObject() is CustomDataObject;

In this example, only nodes having an instance of CustomDataObject as data can be dropped.

`drop`

Sets the UI method that will be executed when a node is dropped on the node where the directive is.

Directive name : dragdrop:drop

The value must be the name of a method that returns nothing.

The method takes as first parameter a IDropEventArgs object. If the node bearing the directive is in a repeat node, the method must take a second parameter corresponding to the iterated element on which the dragged element is dropped.

Example :

Template:

<repeat values="@Fields.List">
  <vertical-layout style:background="primary-100" layout:height="50" dragdrop:draggable="true" dragdrop:data="$Item">
    <text size="extralarge">
      $Item.Text
    </text>
  </vertical-layout>
</repeat>

<vertical-layout dragdrop:dragover="HandleDragOverOnDropzone" dragdrop:drop="HandleDropOnDropzone">
  <text size="extralarge">
    Drop zone
  </text>
</vertical-layout>

HandleDropOnDropzone method:
- args : IDropEventArgs
- item: CustomDataObject

// UIResources.Core.DroppedElementTitle (Scope=Frontend) => "Dropped element"
await ShowMessageAsync(MessageType.Positive, UIResources.Core.DroppedElementTitle, ((CustomDataObject)args.GetInternalDataObject()).Text);
// UIResources.Core.DraggedElementTitle (Scope=Frontend) => "Dragged element"
await ShowMessageAsync(MessageType.Positive, UIResources.Core.DraggedElementTitle, item.Text);

In this example, when a node is dropped, a message will be displayed.

Additional directives

The following directives can be used to update the visual during the drag and drop operation such as highlighting the drop zone.

`dragstart`

Sets the method that will be executed when the node starts to be dragged.

Directive name : dragdrop:dragstart

The value must be the name of a method that returns nothing.

The method takes as first parameter an IDragStartEventArgs object. If the node bearing the directive is in a repeat node, the method must take a second parameter corresponding to the iterated element.

Instead of using the dragdrop:data directive, it is also possible to assign the data to the dragged node in the dragdrop:dragstart directive method via the IDragStartEventArgs.SetStringData() and IDragStartEventArgs.SetInternalDataObject() methods. This is useful in case you want to calculate the data assigned to the node when it starts to be dragged.

Example :

<repeat values="@Fields.List">
  <vertical-layout style:background="primary-100" layout:height="50" dragdrop:draggable="true" dragdrop:dragstart="HandleDragStart">
    <text size="extralarge">
      $Item.Text
    </text>
  </vertical-layout>
</repeat>

<vertical-layout dragdrop:dragover="HandleDragOverOnDropzone" dragdrop:drop="HandleDropOnDropzone">
  <text size="extralarge">
    Drop zone
  </text>
</vertical-layout>

args.SetInternalDataObject(item);
// UIResources.Core.DragStartedTitle (Scope=Frontend) => "Drag and dropd"
// UIResources.Core.DragStartedMessage (Scope=Frontend) => "Element starts to be dragged"
ShowToast(MessageType.Positive, UIResources.Core.DragStartedTitle, UIResources.Core.DragStartedMessage);

In this example, when a node starts to be dragged, a toast will be displayed.

`dragenter`

Sets the UI method that will be executed when a dragged node "enters" the node where the directive is.

Directive name : dragdrop:dragenter

The value must be the name of a method that returns nothing.

The method takes as first parameter an IDragEventArgs object.

If the node bearing the directive is is in a repeat node, the method must take a second parameter corresponding to the iterated element.

Example :

<repeat values="@Fields.List">
  <vertical-layout style:background="primary-100" layout:height="50" dragdrop:draggable="true" dragdrop:data="$Item">
    <text size="extralarge">
      $Item.Text
    </text>
  </vertical-layout>
</repeat>

<vertical-layout dragdrop:dragover="HandleDragOverOnDropzone" dragdrop:drop="HandleDropOnDropzone" dragdrop:dragenter="HandleDragEnterOnDropzone">
  <text size="extralarge" style:color="@Fields.DropZoneTextColor">
    Drop zone
  </text>
</vertical-layout>

Fields.DropZoneTextColor = "primary-500";

In this example, the color of the drop zone text will change when a dragged node goes over the vertical-layout element.

`dragleave`

Sets the UI method that will be executed when a dragged node "leaves" the node where the directive is.

Directive name : dragdrop:dragleave

The value must be the name of a method that returns nothing.

The method takes as first parameter an IDragEventArgs object.

If the node bearing the directive is in a repeat node, the method must take a second parameter corresponding to the iterated element.

Example :

<repeat values="@Fields.List">
  <vertical-layout style:background="primary-100" layout:height="50" dragdrop:draggable="true" dragdrop:data="$Item">
    <text size="extralarge">
      $Item.Text
    </text>
  </vertical-layout>
</repeat>

<vertical-layout dragdrop:dragover="HandleDragOverOnDropzone" dragdrop:drop="HandleDropOnDropzone" dragdrop:dragenter="HandleDragEnterOnDropzone" dragdrop:dragleave="HandleDragLeaveOnDropzone">
  <text size="extralarge" style:color="@Fields.DropZoneTextColor">
    Drop zone
  </text>
</vertical-layout>

Fields.DropZoneTextColor = "foreground";

In this example, the color of the drop zone text will be reset when a dragged node leaves the vertical-layout element.

`dragend`

Sets the UI method that will be executed when a drag operation is finished by releasing the mouse button or pressing the escape key.

Directive name : dragdrop:dragend

The value must be the name of a method that returns nothing.

The method takes as first parameter an IDragEventArgs object.

If the node bearing the directive is in a repeat node, the method must take a second parameter corresponding to the iterated element.

Example :

<repeat values="@Fields.List">
  <vertical-layout style:background="primary-100" layout:height="50" dragdrop:draggable="true" dragdrop:data="$Item">
    <text size="extralarge">
      $Item.Text
    </text>
  </vertical-layout>
</repeat>

<vertical-layout dragdrop:dragover="HandleDragOverOnDropzone" dragdrop:drop="HandleDropOnDropzone" dragdrop:dragenter="HandleDragEnterOnDropzone" dragdrop:dragleave="HandleDragLeaveOnDropzone" dragdrop:dragend="HandleDragEndOnDropzone">
  <text size="extralarge" style:color="@Fields.DropZoneTextColor">
    Drop zone
  </text>
</vertical-layout>

Fields.DropZoneTextColor = "foreground";

In this example, the color of the drop zone text will be reset when the user has pressed the escape key while having the dragged node over the vertical-layout node.

Arguments

The expected UI method of the dragdrop:dragover, dragdrop:dragenter, dragdrop:dragleave and dragdrop:dragend directives take as first parameter an IDragEventArgs object that provides the following methods:

string GetStringData() : Gets the string data related to the drag operation. This method must be used when the associated data is a string.
object GetInternalDataObject() : Gets the data of any type related to the drag operation. This method must be used when the associated data is not a string.
bool HasFiles(): Gets a boolean indicating whether files from the computer are being dragged. When only files are allowed to be dropped, you can use it in the UI method bound to the dragover directive: return args.HasFiles()

The expected UI method of the dragdrop:drop directive takes as first parameter an IDropEventArgs object that provides the same methods as the IDragEventArgs object as well as an additional method:

DeferredFileReference[] GetFiles() : Gets the references to the files related to the drag operation.

The expected method of the dragdrop:dragstart directive takes as first parameter an IDragStartEventArgs object which provides the following methods:

void SetStringData(string data) : Assigns the data which is a string linked to the drag operation.
object SetInternalDataObject() : Assigns the data of any type related to the drag operation.

Limitations

When the data of a draggable node is a string, the node can either be dropped in any browser tab or even external applications that handle dragging and dropping text. However, if the data is an object, the node can only be dropped in the current web browser tab.

Table of Contents

Drag and drop directives

Main directives

draggable

data

dragover

drop

Additional directives

dragstart

dragenter

dragleave

dragend

Arguments

Limitations

`draggable`

`data`

`dragover`

`drop`

`dragstart`

`dragenter`

`dragleave`

`dragend`