Skip to content

Custom drag sources and drop targets

Drag sources and drop targets must be created according to the HTML 5 specification. In HTML 5, the DataTransfer object is used to exchange data from source to target.

The source sets the data with dataTransfer.setData(format, data) and the target reads the data with dataTransfer.getData(format). HCL Digital Experience (DX) always uses format = "Text". The data is a stringified JSON object with the following structure:

{ "uri" : URI }

In the previous example, the URI is the URI of the object that is dragged. If more than one object is dragged, the structure looks like this example.

{ "uri" : [ URI\_1, URI\_2, ... ] }

Each URI can have a list of parameters. In this case, the JSON object has the following structure.

{ "uri" : [ { key_11 : value_11, key_12 : value_12, ... }, URI\_1, { key_21 : value_21, key_22 : value_22, ... }, URI\_2, ... ] }

In the previous example, key_1x:value_1x are the parameters of URI_1 and key_2x:value_2x are the parameters of URI_2.

The theme module i$.dnd provides two convenience functions that simplify the creation of HTML 5 drag sources and drop targets. To create a drag source, you can use the following code.

i$.dnd.addSource(parameter)

In the previous example, the parameter object needs to have the following elements:

  • {DOMNode} parameter.node

    The DOM node that acts as the drag source.

  • {String} parameter.type

    The type of data that is transferred, typically "Text".

  • {Object} parameter.data

    The data to transfer when dropped. When you exchang data with a standard HCL DX drop target, it must be a stringified JSON object with the structure described before.

  • {DOMNode} parameter.avatar

    The DOM node to use as the DnD avatar. (optional)

  • {Function} parameter.dragstart

    A function to start when dragstart is called. (optional) The following parameters are passed to this function:

    • {Event} e

      The event. For example, you can use the event to set e.dataTransfer.effectAllowed = "copy";.

    • {DOMNode} n

      The DomNode of the source area.

  • {Function} parameter.dragend

    A function to start when dragend is called. It has the same parameters as parameter.dragstart. (optional)

To create a drop target, you can use the following code.

i$.dnd.addTarget(parameter)

In the previous example, the parameter object must have the following elements:

  • {DOMNode} parameter.node

    The DOMnode acting as the drop target.

  • {String} parameter.type

    The type of data that is transferred, typically "Text".

  • {Function} parameter.drop

    Function to handle the drop event. The following parameters are passed to this function:

    • {Event} e

      The drop event.

    • {DOMNode} n

      The DOM node of the drop target.

    • {String} type

      The type of data that is transferred.

    • {Object} data

      The data that was transferred from the drag source. When receiving data from standard HCL DX drag sources, it is a stringified JSON object with the structure described before.

  • {Function} parameter.dragenter

    Function to start when dragenter is called. (optional) The following parameters are passed to this function:

    • {Event} e

      The event.

    • {DOMNode} n

      The DOM node of the drop target.

  • {Function} parameter.dragleave

    Function to start when dragend is called with the same parameters as dragenter. (optional)

  • {Function} parameter.dragover

    Function to start when dragover is called with the same parameters as dragenter. (optional)