EventDrag
Feature

Allows user to drag and drop events within the scheduler, to change startDate or resource assignment.

This feature is enabled by default

Customizing the drag drop tooltip

To show custom HTML in the tooltip, please see the tooltipTemplate config. Example:

features: {
    eventDrag : {
        // A minimal start date tooltip
        tooltipTemplate : ({ eventRecord, startDate }) => {
            return DateHelper.format(startDate, 'HH:mm');
        }
    }
}

Constraining the drag drop area

You can constrain how the dragged event is allowed to move by using the following configs

constrainDragToResource Resource fixed, only allowed to change start date
constrainDragToTimeSlot Start date is fixed, only move between resources
getDateConstraints A method on the Scheduler instance which lets you define the date range for the dragged event programmatically

// Enable dragging + constrain drag to current resource
const scheduler = new Scheduler({
    features : {
        eventDrag : {
            constrainDragToResource : true
        }
    }
});

Drag drop events from outside

Dragging unplanned events from an external grid is a very popular use case. There are several demos showing you how to do this. Please see the Drag from grid demo and study the Drag from grid guide to learn more.

Drag drop events to outside target

You can also drag events outside the schedule area by setting constrainDragToTimeline to false. You should also either:

provide a validatorFn to programmatically define if a drop location is valid or not
configure a externalDropTargetSelector CSS selector to define where drops are allowed

See this demo to see this in action.

Validating drag drop

It is easy to programmatically decide what is a valid drag drop operation. Use the validatorFn and return either true / false (optionally a message to show to the user).

features : {
    eventDrag : {
       validatorFn({ eventRecords, newResource }) {
           const task  = eventRecords[0],
                 valid = newResource.role === task.resource.role;

           return {
               valid   : newResource.role === task.resource.role,
               message : valid ? '' : 'Resource role does not match required role for this task'
           };
       }
    }
}

See this demo to see validation in action.

If you instead want to do a single validation upon drop, you can listen to beforeEventDropFinalize and set the valid flag on the context object provided.

  const scheduler = new Scheduler({
     listeners : {
         beforeEventDropFinalize({ context }) {
             const { eventRecords } = context;
             // Don't allow dropping events in the past
             context.valid = Date.now() <= eventRecords[0].startDate;
         }
     }
 });

Preventing drag of certain events

To prevent certain events from being dragged, you have two options. You can set draggable to false in your data, or you can listen for the beforeEventDrag event and return false to block the drag.

new Scheduler({
   listeners : {
       beforeEventDrag({ eventRecord }) {
           // Don't allow dragging events that have already started
           return Date.now() <= eventRecord.startDate;
       }
   }
})

Events that are selected, but not visually accessible, are not included in drag operations. This means that events in collapsed groups or filtered out resources are not dragged, even if they were selected prior to being collapsed or filtered out of visibility.

Useful configs and functions

Member	Description
beforeEventDrag	Fires before drag starts, return `false` to prevent
eventDragStart	Fires when event drag begins
eventDrag	Fires continuously during drag
eventDrop	Fires when event is dropped at new position
beforeEventDropFinalize	Async finalizer before drop is applied
tooltipTemplate	Template for the drag tooltip

Configs

Configs are options you supply in a configuration object when creating an instance of this class

alwaysCopy : Booleanfalse

Set this to true to always copy the event on drag drop operation.

Has a corresponding runtime alwaysCopy property.
constrainDragToResource : Booleanfalse

Set to true to only allow dragging events within the same resource.

Has a corresponding runtime constrainDragToResource property.
constrainDragToTimeSlot : Booleanfalse

Set to true to only allow dragging events to different resources, and disallow rescheduling by dragging.

Has a corresponding runtime constrainDragToTimeSlot property.
copyKey : 'CTRL'/'ALT'/'SHIFT'/'META'/''CTRL

A modifier key (CTRL, SHIFT, ALT, META) that when pressed will copy an event instead of moving it. Set to empty string to disable copying. Defaults to "CTRL" which is the Ctrl-key for Windows, and Meta-key for MacOS.

Has a corresponding runtime copyKey property.
copyMode : 'auto'/'assignment'/'event'auto

Event can be copied two ways: either by adding new assignment to an existing event ('assignment'), or by copying the event itself ('event'). 'auto' mode will pick 'event' for a single-assignment mode (when event has resourceId field) and 'assignment' mode otherwise.

Has a corresponding runtime copyMode property.
externalDropTargetSelector : String

A CSS selector specifying elements outside the scheduler element which are valid drop targets.
singleDirection : Booleanfalse

Set to true to only allow dragging in one direction (based on initial movement)

Has a corresponding runtime singleDirection property.
snapToPosition : Function
A hook that allows manipulating the position the drag proxy snaps to. Manipulate the snapTo property to alter snap position.
```
const scheduler = new Scheduler({
    features : {
        eventDrag : {
            snapToPosition({ eventRecord, snapTo }) {
                if (eventRecord.late) {
                    snapTo.x = 400;
                }
            }
        }
    }
});
```
Parameters
- context : Object
  Context
- assignmentRecord : AssignmentModel
  
  Dragged assignment
- eventRecord : EventModel
  
  Dragged event
- resourceRecord : ResourceModel
  
  Currently over this resource
- startDate : Date
  
  Start date for current position
- endDate : Date
  
  End date for current position
- snapTo : Object
  Snap to
- x : Number
  
  X to snap to
- y : Number
  
  Y to snap to
Returns

void
snapToResource : Boolean/Objecttrue
Defaults to true, which snaps events to resources while dragging, i.e. vertical row snap in horizontal mode and vice versa. Requires Scheduler to be configured to snap to have any effect:
```
const scheduler = new Scheduler({
    ...
    // Snap to time & resource
    snap : true
});
```
If you want to customize the number of pixels from the dragged event that will trigger the snapping behavior to the new resource, you can set the threshold property:
```
const scheduler = new Scheduler({
    ...
    snap     : true,
    features : {
        eventDrag : {
            // Customized snap threshold
            snapToResource : {
                threshold : 30
            }
        }
    },
    ...
});
```
- threshold : Number
  
  Amount of pixels from dragged event to the edge of new resource that will trigger the snapping behaviour to the new resource.
Has a corresponding runtime snapToResource property.
tooltipTemplate : Function
Template used to generate drag tooltip contents.
```
const scheduler = new Scheduler({
    features : {
        eventDrag : {
            tooltipTemplate({eventRecord, startText}) {
                return `${eventRecord.name}: ${startText}`
            }
        }
    }
});
```
Parameters
- data : Object
  
  Tooltip data
- eventRecord : EventModel
  Event record
- newResource : ResourceModel
  
  The new resource record
- valid : Boolean
  
  Currently over a valid drop target or not
- startDate : Date
  
  New start date
- endDate : Date
  
  New end date
Returns

String
unifiedDrag : Booleanfalse

When the host Scheduler is multiEventSelect: true then, there are two modes of dragging within the same Scheduler.

Non unified means that all selected events are dragged by the same number of resource rows.

Unified means that all selected events are collected together and dragged as one, and are all dropped on the same targeted resource row at the same targeted time.

Has a corresponding runtime unifiedDrag property.
validatorFn : Function
An empty function by default, but provided so that you can perform custom validation on the item being dragged. This function is called during the drag and drop process and also after the drop is made. Return true if the new position is valid, false to prevent the drag.
```
features : {
    eventDrag : {
        validatorFn({ eventRecords, newResource }) {
            const
                task  = eventRecords[0],
                valid = newResource.role === task.resource.role;

            return {
                valid   : newResource.role === task.resource.role,
                message : valid ? '' : 'Resource role does not match required role for this task'
            };
        }
    }
}
```
Parameters
- context : Object
  
  A drag drop context object
- startDate : Date
  
  New start date
- endDate : Date
  
  New end date
- assignmentRecords : AssignmentModel[]
  
  Assignment records which were dragged
- eventRecords : EventModel[]
  
  Event records which were dragged
- newResource : ResourceModel
  
  New resource record
- targetEventRecord : EventModel
  
  Currently hovering this event record
- event : Event
  
  The event object
Returns

Boolean/Object
:

true if this validation passes, false if it does not.

Or an object with 2 properties: valid - Boolean true/false depending on validity, and message - String with a custom error message to display when invalid.
validatorFnThisObj : Object

The this reference for the validatorFn

Properties

Properties are getters/setters or publicly accessible variables on this class

isEventDrag : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of EventDrag class, or subclass thereof.

alwaysCopy : Booleanfalse

Set this to true to always copy the event on drag drop operation.

Has a corresponding alwaysCopy config.
constrainDragToResource : Booleanfalse

Set to true to only allow dragging events within the same resource.

Has a corresponding constrainDragToResource config.
constrainDragToTimeSlot : Booleanfalse

Set to true to only allow dragging events to different resources, and disallow rescheduling by dragging.

Has a corresponding constrainDragToTimeSlot config.
copyKey : 'CTRL'/'ALT'/'SHIFT'/'META'/''CTRL

A modifier key (CTRL, SHIFT, ALT, META) that when pressed will copy an event instead of moving it. Set to empty string to disable copying. Defaults to "CTRL" which is the Ctrl-key for Windows, and Meta-key for MacOS.

Has a corresponding copyKey config.
copyMode : 'auto'/'assignment'/'event'auto

Event can be copied two ways: either by adding new assignment to an existing event ('assignment'), or by copying the event itself ('event'). 'auto' mode will pick 'event' for a single-assignment mode (when event has resourceId field) and 'assignment' mode otherwise.

Has a corresponding copyMode config.
mode : 'move'/'copy'

READONLY

Mode of the current drag drop operation.
singleDirection : Booleanfalse

Set to true to only allow dragging in one direction (based on initial movement)

Has a corresponding singleDirection config.
snapToResource : Boolean/Objecttrue
Defaults to true, which snaps events to resources while dragging, i.e. vertical row snap in horizontal mode and vice versa. Requires Scheduler to be configured to snap to have any effect:
```
const scheduler = new Scheduler({
    ...
    // Snap to time & resource
    snap : true
});
```
If you want to customize the number of pixels from the dragged event that will trigger the snapping behavior to the new resource, you can set the threshold property:
```
const scheduler = new Scheduler({
    ...
    snap     : true,
    features : {
        eventDrag : {
            // Customized snap threshold
            snapToResource : {
                threshold : 30
            }
        }
    },
    ...
});
```
- threshold : Number
  
  Amount of pixels from dragged event to the edge of new resource that will trigger the snapping behaviour to the new resource.
Has a corresponding snapToResource config.
unifiedDrag : Booleanfalse

When the host Scheduler is multiEventSelect: true then, there are two modes of dragging within the same Scheduler.

Non unified means that all selected events are dragged by the same number of resource rows.

Unified means that all selected events are collected together and dragged as one, and are all dropped on the same targeted resource row at the same targeted time.

Has a corresponding unifiedDrag config.
isEventDrag : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of EventDrag class, or subclass thereof.

Functions

Functions are methods available for calling on the class

getCoordinate( eventRecord, element, coord )
: Number/Number[]

private

Get correct axis coordinate depending on schedulers mode (horizontal -> x, vertical -> y). Also takes milestone layout into account.
getDragData( info )
: *

private

Initializes drag data (dates, constraints, dragged events etc). Called when drag starts.
getRelatedRecords( assignmentRecord )
: AssignmentModel[]

Provide your custom implementation of this to allow additional selected records to be dragged together with the original one.
isValidDrop( )
: Boolean

private

Checks if an event can be dropped on the specified position.
resolveResource( )
: ResourceModel

private

Get resource record occluded by the drag proxy.
updateAssignments( )
: Promise

private

ASYNC

Update assignments being dragged
updateRecords( context )
: Promise

private

ASYNC

Update events being dragged.

Events

Events are triggered for certain actions in this class and can be listened for to react to those actions in your code

afterEventDrop

ON-OWNER

Fired on the owning Scheduler after event drop

Note that this event is triggered on the owning widget:
beforeEventDrag

PREVENTABLE

ON-OWNER

Fired on the owning Scheduler before event dragging starts. Return false to prevent the action.

Note that this event is triggered on the owning widget:
beforeEventDropFinalize

ON-OWNER
This event is fired on the owning Scheduler after the event drag operation completes, but before changing any data. It allows implementer to use asynchronous validation/finalization by setting context.async = true in the listener, for example, to show a confirmation popup, make async data request etc. In such case, implementer need to call the context.finalize() method manually:
```
 scheduler.on('beforeeventdropfinalize', ({ context }) => {
     context.async = true;
     setTimeout(() => {
         // `true` to perform the drop, `false` to ignore it
         context.finalize(true);
     }, 1000);
 })
```
For synchronous one-time validation, simply set context.valid to true or false.
```
 scheduler.on('beforeeventdropfinalize', ({ context }) => {
     context.valid = false;
 })
```
Note that this event is triggered on the owning widget:
eventDrag

ON-OWNER

Fired on the owning Scheduler when event is dragged

Note that this event is triggered on the owning widget:
eventDragAbort

ON-OWNER

Fired on the owning Scheduler after an event drag operation has been aborted

Note that this event is triggered on the owning widget:
eventDragModeChange

ON-OWNER

Triggered when drag mode is changed, for example when copy key is pressed or released while dragging.

Note that this event is triggered on the owning widget:
eventDragReset

ON-OWNER

Fired on the owning Scheduler after an event drag operation regardless of the operation being cancelled or not

Note that this event is triggered on the owning widget:
eventDragStart

ON-OWNER

Fired on the owning Scheduler when event dragging starts

Note that this event is triggered on the owning widget:
eventDrop

ON-OWNER

Fired on the owning Scheduler when an event is dropped

Note that this event is triggered on the owning widget:

Event handlers

Event handlers are callbacks called as a result of certain actions in this class

onAfterEventDrop

ON-OWNER

Called on the owning Scheduler after event drop

Note that this handler is called on the owning widget:
onBeforeEventDrag

PREVENTABLE

ON-OWNER

Called on the owning Scheduler before event dragging starts. Return false to prevent the action.

Note that this handler is called on the owning widget:
onBeforeEventDropFinalize

ON-OWNER
This event is called on the owning Scheduler after the event drag operation completes, but before changing any data. It allows implementer to use asynchronous validation/finalization by setting context.async = true in the listener, for example, to show a confirmation popup, make async data request etc. In such case, implementer need to call the context.finalize() method manually:
```
 scheduler.on('beforeeventdropfinalize', ({ context }) => {
     context.async = true;
     setTimeout(() => {
         // `true` to perform the drop, `false` to ignore it
         context.finalize(true);
     }, 1000);
 })
```
For synchronous one-time validation, simply set context.valid to true or false.
```
 scheduler.on('beforeeventdropfinalize', ({ context }) => {
     context.valid = false;
 })
```
Note that this handler is called on the owning widget:
onEventDrag

ON-OWNER

Called on the owning Scheduler when event is dragged

Note that this handler is called on the owning widget:
onEventDragAbort

ON-OWNER

Called on the owning Scheduler after an event drag operation has been aborted

Note that this handler is called on the owning widget:
onEventDragModeChange

ON-OWNER

Called when drag mode is changed, for example when copy key is pressed or released while dragging.

Note that this handler is called on the owning widget:
onEventDragReset

ON-OWNER

Called on the owning Scheduler after an event drag operation regardless of the operation being cancelled or not

Note that this handler is called on the owning widget:
onEventDragStart

ON-OWNER

Called on the owning Scheduler when event dragging starts

Note that this handler is called on the owning widget:
onEventDrop

ON-OWNER

Called on the owning Scheduler when an event is dropped

Note that this handler is called on the owning widget:

Type definitions

EventDropData
Object with information about the drop point for a single dragged event.
Properties
- eventRecord : EventModel
  
  The event about to be dropped. Note, that when "copying" mode is enabled, this will still be the originally dragged event, not the copy (which will be created only during drag'n'drop finalization).
- startDate : Date
  
  The estimated start date of the event after drop. Note, that actual start date might be different because of the other features, affecting the scheduling, like dependencies and constraints.
- endDate : Date
  
  The estimated end date of the event after drop. Note, that actual end date might be different because of the other features, affecting the scheduling, like dependencies and constraints.
AssignmentDropData
Object with information about the drop point for a dragged assignment.
Properties
- assignmentRecord : AssignmentModel
  
  The assignment about to be dropped. Note, that in case if "copying" mode is enabled, this will still be the originally dragged assignment, not the copy (which will be created only during drag'n'drop finalization).
- resourceRecord : ResourceModel
  
  The new resource for the assignment. Note, that resource might belong to another project (in case of drag and drop between different scheduler instances).
DropData
Object with information about the drop points for the dragged events. It is used in the Scheduler's beforeEventDropFinalize event.
Properties
- events : EventDropData[]
  
  The array of drop points for every dragged event.
- assignments : AssignmentDropData[]
  
  The array of drop points for every dragged assignment.

id: eventDrag

Source path

Scheduler/feature/EventDrag.js

Demo

examples/basic

EventDrag
Feature

Customizing the drag drop tooltip

Constraining the drag drop area

Drag drop events from outside

Drag drop events to outside target

Validating drag drop

Preventing drag of certain events

Useful configs and functions

See also

Configs

Parameters

Returns

Parameters

Returns

Parameters

Returns

Properties

Functions

Events

Event handlers

Type definitions

Properties

Properties

Properties

Source path

Demo

Inheritance tree4

Mixins2

Contents

EventDrag Feature

Customizing the drag drop tooltip

Constraining the drag drop area

Drag drop events from outside

Drag drop events to outside target

Validating drag drop

Preventing drag of certain events

Useful configs and functions

See also

Configs

Parameters

Returns

Parameters

Returns

Parameters

Returns

Properties

Functions

Events

Event handlers

Type definitions

Properties

Properties

Properties

Source path

Demo

Inheritance tree4

Mixins2

Contents

EventDrag
Feature