Coral.DragAction

Current Version: 2.1.7
Note:Any Coral CSS classes and attributes not explicitly mentioned in the public documentation are private and subject to change. Their direct use is not recommended and at high risk of breaking after subsequent updates of CoralUI library. For technical details of how to use Coral safely, please refer to the CoralUI Architecture.
Github: @coralui/coralui-component-dragaction

is a partial component, which may be used to built drag-and-drop interfaces. It cannot be used on its own but serves as a building

DragAction attributes

|

Usage

DragAction attributes are activated on DOMContentLoaded event. JS initialization can be used as alternative to handle dynamic HTML elements.

coral-dragaction

The coral-dragaction attribute adds draggable functionalities to the corresponding HTML element.
You can drag me around
Show Markup 
<span coral-dragaction>
  You can drag me around
</span>

coral-dragaction-handle

The coral-dragaction-handle attribute allows dragging only by dragging the specified handle.
You can only drag me using the handle
Show Markup 
<span coral-dragaction coral-dragaction-handle="#handle">
  You can only drag me using the <span id="handle"><b>handle</b></span>
</span>

coral-dragaction-dropzone

The coral-dragaction-dropzone attribute is used to indicate possible dropzones making it possible to build drag-and-drop enabled interfaces in conjunction with DragAction events.
You can drop me on #dropzone
I'm #dropzone
Show Markup 
<span id="dragaction" coral-dragaction coral-dragaction-dropzone="#dropzone">
  You can drop me on #dropzone
</span>
<div id="dropzone" style="height:200px;width:200px;background: #eee;">
  I'm #dropzone
</div>

coral-dragaction-axis

By supplying coral-dragaction-axis and setting it to either horizontal or vertical, it is possible to restrict the drag'n'drop to a single axis.
You can drag me on the horizontal axis only
Show Markup 
<span coral-dragaction coral-dragaction-axis='horizontal'>
  You can drag me on the horizontal axis only
</span>

coral-dragaction-scroll

coral-dragaction-scroll attribute will scroll the container when the draggable is moved beyond the viewport
You can drag me to the document's body edges and beyond !
Show Markup 
<span coral-dragaction coral-dragaction-scroll>
  You can drag me to the document's body edges and beyond !
</span>

coral-dragaction-containment

By setting coral-dragaction-containment, the draggable element will be constrained to its container.
You can not drag me out
Show Markup 
<div style="height:200px;width:200px;background: #eee;overflow:scroll;">
  <div coral-dragaction coral-dragaction-containment style="width:50px;border:1px solid #999;">
    You can not drag me out
  </div>
</div>

JavaScript Examples

JS Initialization

The following examples demonstrate how to initialize coral-dragaction using pure JavaScript.

I can not be dragged out
Show Markup 
<div style="height:200px;width:200px;background: #eee; overflow:scroll;">
  <span id="dragactionJS">I can not be dragged out</span>
</div>

Finally we can initialize Coral.DragAction using only JavaScript. 

document.addEventListener('DOMContentLoaded', function() {
  var dragAction = new Coral.DragAction('#dragactionJS');
  dragAction.containment = true;
});

Observing Events

DragActions create many additional events, which allow for more fine grained interactions and customizations. Those events are triggered on the source of the drag'n'drop. See the detailed documentation below for more information.

The following code logs some of the supported events.

document.addEventListener('DOMContentLoaded', function() {
  var console = $("#dragaction-log");
  // Events generated on drag start
  $('#dragaction')[0].addEventListener('coral-dragaction:dragstart', function (e) {
    console.log('Start on position: [' + e.detail.pageX + ',' + e.detail.pageY + ']');
  });
  // Events generated on drag
  $('#dragaction')[0].addEventListener('coral-dragaction:drag', function (e) {
    console.log('Drag on position: [' + e.detail.pageX + ',' + e.detail.pageY + ']');
  });
  // Events generated on drag end
  $('#dragaction')[0].addEventListener('coral-dragaction:dragend', function (e) {
    console.log('End on position: [' + e.detail.pageX + ',' + e.detail.pageY + ']');
  });
  // Events generated on dragenter
  $('#dragaction')[0].addEventListener('coral-dragaction:dragenter', function (e) {
    console.log('Entered element with id: ' + e.detail.dropElement.id);
  });
  // Events generated on dragover
  $('#dragaction')[0].addEventListener('coral-dragaction:dragover', function (e) {
    console.log('Over element with id: ' + e.detail.dropElement.id);
  });
  // Events generated on dragleave
  $('#dragaction')[0].addEventListener('coral-dragaction:dragleave', function (e) {
    console.log('Left element with id: ' + e.detail.dropElement.id);
  });
  // Events generated on drop
  $('#dragaction')[0].addEventListener('coral-dragaction:drop', function (e) {
    console.log('Drop on element with id: ' + e.detail.dropElement.id);
    e.detail.dropElement.style.background = 'beige';
  });
  });

Log

Typical event order

In the simplest successful use case - dragging an element, moving it to the target area and dropping it - the following events will occur:

  1. coral-dragaction:dragstart
  2. coral-dragaction:drag
  3. coral-dragaction:dragenter
  4. coral-dragaction:dragover (multiple times)
  5. coral-dragaction:drop
  6. coral-dragaction:dragleave
  7. coral-dragaction:dragend

Coral.DragAction API

Constructor

JavaScript:

new Coral.DragAction()
Parameters:
Name Type Description
dragElement String|HTMLElement The draggable element.

Static Properties

Coral.DragAction.axis {String}

Enum for DragAction axis restriction values.

Properties:

Name Type Value Description
FREE String free Allows vertically and horizontally dragging.
VERTICAL String vertical Allows vertically dragging only.
HORIZONTAL String horizontal Allows horizontally dragging only.

Instance Properties

instance.axis {Coral.DragAction.axis}

The axis to constrain drag movement.
Default Value:
  • Coral.DragAction.axis.FREE
HTML Attribute:
  • coral-dragaction-axis

instance.containment {Boolean}

Whether to constrain the draggable element to its container viewport.
Default Value:
  • false
HTML Attribute:
  • coral-dragaction-containment

instance.dragElement {String | HTMLElement}

Readonly
The draggable element.
HTML Attribute:
  • coral-dragaction

instance.dropZone {String | HTMLElement}

The dropZone to drop the dragged element.
HTML Attribute:
  • coral-dragaction-dropzone

instance.handle {String | HTMLElement}

The handle allowing to drag the element.
HTML Attribute:
  • coral-dragaction-handle

instance.scroll {Boolean}

Whether to scroll the container when the draggable element is moved beyond the viewport.
Default Value:
  • false
HTML Attribute:
  • coral-dragaction-scroll

Methods

Coral.DragAction.destroy

Remove draggable actions
Parameters:
Name Type Description
restorePosition Boolean Whether to restore the draggable element to its initial position

Events

coral-dragaction:drag

Triggered when the drag element is being dragged.
Callback Parameters:
Name Type Description
dragElement HTMLElement The dragged element
pageX Number The mouse position relative to the left edge of the document.
pageY Number The mouse position relative to the top edge of the document.

coral-dragaction:dragend

Triggered when the drag element stops to be dragged.
Callback Parameters:
Name Type Description
dragElement HTMLElement The dragged element
pageX Number The mouse position relative to the left edge of the document.
pageY Number The mouse position relative to the top edge of the document.

coral-dragaction:dragenter

Triggered when the drag element enters a drop element.
Callback Parameters:
Name Type Description
dragElement HTMLElement The dragged element
dropElement HTMLElement The drop element
pageX Number The mouse position relative to the left edge of the document.
pageY Number The mouse position relative to the top edge of the document.

coral-dragaction:dragleave

Triggered when the drag element leaves a drop element.
Callback Parameters:
Name Type Description
dragElement HTMLElement The dragged element
dropElement HTMLElement The drop element
pageX Number The mouse position relative to the left edge of the document.
pageY Number The mouse position relative to the top edge of the document.

coral-dragaction:dragover

Triggered when the drag element is over a drop element.
Callback Parameters:
Name Type Description
dragElement HTMLElement The dragged element
dropElement HTMLElement The drop element
pageX Number The mouse position relative to the left edge of the document.
pageY Number The mouse position relative to the top edge of the document.

coral-dragaction:dragstart

Triggered when the drag element starts to be dragged.
Callback Parameters:
Name Type Description
dragElement HTMLElement The dragged element
pageX Number The mouse position relative to the left edge of the document.
pageY Number The mouse position relative to the top edge of the document.

coral-dragaction:drop

Triggered when the drag element is dropped on a drop element.
Callback Parameters:
Name Type Description
dragElement HTMLElement The dragged element
dropElement HTMLElement The drop element
pageX Number The mouse position relative to the left edge of the document.
pageY Number The mouse position relative to the top edge of the document.