CalendarDrag
Feature

This feature provides drag-based event creation and modification for Calendars. When enabled (which is the default for calendars), the user can do the following via the mouse or touch screen:

Create events by touching (or pressing the mouse button in) an the empty space and dragging. As the drag progresses, a tentative event is rendered. On release, the EventEdit feature displays the event edit dialog to complete the process. This can be disabled via the creatable config.
Adjust the start or end times of an event in the day or week views by dragging the top or bottom of an event. This can be disabled via the resizable config or the resizable field on a per-event basis.
Adjust the start or end date of an all-day event in the month view by dragging the left-most or right-most end of an event. This can be disabled via the resizable config or the resizable field on a per-event basis.
Move an event from its current time (in day or week views) or date (in all views except agenda) by dragging the body of an event. This can be disabled via the draggable config or via the draggable field on a per-event basis.

 // change name for events created by drag to "Event":
 let calendar = new Calendar({
     features : {
         drag : {
             newName : 'Event'
         }
     }
 });

The events triggered by this feature are triggered through the client Calendar instance.

Asynchronous validation of resize, move and create operations

You can easily add a confirmation step after an operation to show a dialog to the end user. This is done using the beforeDragMoveEnd, beforeDragCreateEnd and beforeDragResizeEnd events.

 let calendar = new Calendar({
     listeners : {
         // Async event listeners allowing you to veto drag operations
         beforeDragMoveEnd : async({ eventRecord }) => {
              const result = await MessageDialog.confirm({
                  title   : 'Please confirm',
                  message : 'Is this the start time you wanted?'
              });

              // Return true to accept the drop or false to reject it
              return result === MessageDialog.yesButton;
          },
          beforeDragResizeEnd : async({ eventRecord }) => {
              const result = await MessageDialog.confirm({
                  title   : 'Please confirm',
                  message : 'Is this the duration you wanted?'
              });

              // Return true to accept the drop or false to reject it
              return result === MessageDialog.yesButton;
          },
          beforeDragCreateEnd : async({ eventRecord }) => {
              const result = await MessageDialog.confirm({
                  title   : 'Please confirm',
                  message : 'Want to create this event?'
              });

              // Return true to accept the drop or false to reject it
              return result === MessageDialog.yesButton;
          }
      }
 });

Converting "All day" events to intra day events

You may drag an "All day" event out of the top row of a DayView and into the body of the view.

The event's duration will be preserved if possible.

If the newly calculated end time (based on the dropped-at time and the duration of the event) will overflow the end of that date then the event is converted to the duration configured in the DayView's autoCreate.

This feature is enabled by default.

The example below demonstrates validation of drag gestures so that no event intersects with any TimeRange which have its disabled field set.

Useful configs

Config	Description
creatable	Allow drag-creating new events
draggable	Allow dragging events to new times
resizable	Allow drag-resizing event edges
tooltip	Tooltip shown during drag operations
validateCreateFn	Custom validation for drag-create

Configs

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

creatable : Boolean

Specify false to disallow creating events by drag gestures.
draggable : Boolean

Specify false to disallow dragging events to new times or days.
durationUnit : String

The durationUnit to use when drag-creating events.

If not specified, the dragUnit property of the active view's autoCreate is used.

For DayViews, this is normally 'hour', for views with a granularity level of one day, the default is 'day'.
footer : DomConfig{"className":"b-cal-event-footer"}

A DOM config object used to create an extra element during event drag to contain the end time of the tentative event. This element contains the CSS class 'b-cal-event-footer' which can be used for styling.

Set this to null to remove the end time rendering during drag operations.
gripper : HTMLElement/DomConfig

private

This is configured as a DomHelper specification and is promoted to an HTMLElement during initialization. This element is moved between calendar event elements on hover in order to show drag handles on the event under the mouse.
newName : String/Function
The name of new events or a function to call with the event record that will return the event name.

If a function is supplied, it is called in the scope of (the this reference is set to) the view being dragged within.

Cpnfigure as null to use the dragged-in view's autoCreatenewName property.
Parameters
- eventRecord : EventModel
  
  The record being drag-created.
Returns

String
:

Name of new event
recurrenceTip : String

The text to display as a hint for creating recurring events during drag. This tip is displayed in the tooltip in the same place as the recurrence summary (when there is no recurrence to display).
removeFromExternalStore : Booleantrue

By default, when an event is dragged from an external source, the event is removed from the source EventStore. Configure this as false to leave the event in place to allow for the dragging in of the same event repeatedly.

Has a corresponding runtime removeFromExternalStore property.
resizable : Boolean

Specify false to disallow dragging the edges of events to change their start or end.
tooltip : Boolean/EventTipConfig/EventTip

The tooltip to display during a drag create process. Disabled by default, set to true, or provide a tooltip / config object, to enable it.

validateCreateFn : Function/String

An empty function by default that allows you to perform custom validation on an event being created by a drag gesture.

The drag context contains the following data items (see get):

eventDragMode : The CalendarDragMode object describing the drag operation.
eventCreate : The CalendarHit object that describes the target of the drag operation.

Return false to cancel the create operation.

Note that the Calendar also offers the beforeAutoCreate event which is triggered on drag start. Returning false from that event listener will also prevent the starting of the drag-create gesture.

This function can return a Promise (i.e., it can be async).

Example:

 let calendar = new Calendar({
     features : {
         drag : {
             async validateCreateFn({ eventRecord, drag }) {
                 // This method can be async so it can make ajax requests or interact
                 // with the user...

                 // if we return false, the event will be discarded

                 // The following is equivalent to returning false:
                 //
                 // return {
                 //     // Do not add the event to the store
                 //     add  : false,
                 //     // Do not display the edit dialog (in the eventEdit feature):
                 //     edit : false
                 // };
                 //
                 // This simply adds the event and does not display the editor:
                 //
                 return {
                     edit : false
                 };

                 // To do delay adding the event until the editor is done (and
                 // not via Cancel):
                 // return {
                 //     add : false
                 // };
             }
         }
     }
 });

or:

 let calendar = new Calendar({
     features : {
         drag : {
             // Will resolve on the Calendar
             validateCreateFn : 'up.validateCreate'
         }
     },
     validateCreate{ eventRecord, drag } {
         ...
     }
 });

Return true if the event should be added to the event store and to inform the eventEdit feature to display the edit dialog.

If this function returns an object, the add property can be set to false to prevent adding to the event store, and the edit property can be set to false to inform the eventEdit feature not to display the edit dialog.

Parameters

info : Object
Info
drag : DragContext

The drag create context.
event : Event

The browser event object.
view : CalendarView

The Calendar widget in which the drag is taking place.
eventRecord : EventModel

The Event record.

Returns

Boolean/ValidateCreateResult

Return false if this event should be rejected.

validateMoveFn : Function/String
An empty function by default that allows you to perform custom validation on the event being moved to a new date or time via a drag gesture.

The drag context contains the following data items (see get):
- eventDragMode : The CalendarDragMode object describing the drag operation.
- eventRecord : The event record being moved.
- eventSourceHit : The CalendarHit object that describes the source of the drag operation.
Return false to cancel the operation.

This function can return a Promise (i.e., it can be async).

Example:
```
 let calendar = new Calendar({
     features : {
         drag : {
             async validateMoveFn({ eventRecord, drag }) {
                 // This method can be async so it can make ajax requests or interact
                 // with the user...

                 // if we return false, the event move will be discarded
             }
         }
     }
 });
```
or:
```
 let calendar = new Calendar({
     features : {
         drag : {
             // Will resolve on the Calendar
             validateMoveFn : 'up.validateMove'
         }
     },
     validateMove{ eventRecord, drag } {
         ...
     }
 });
```
Parameters
- info : Object
  Info
- drag : DragContext
  
  The drag create context.
- event : Event
  
  The browser event object.
- view : CalendarView
  
  The Calendar widget in which the drag is taking place.
- eventRecord : EventModel
  
  A proxy event record which is updated during the drag operation to create the UI. This record is not the original event record. The original event record is unchanged until the drag operation is complete.
Returns

Boolean
:

Return false if this event change should be rejected.
validateResizeFn : Function/String

ASYNC
An empty function by default that allows you to perform custom validation on the event whose startDate or endDate is being modified via drag gesture.

The drag context contains the following data items (see get):
- eventDragMode : The CalendarDragMode object describing the drag operation.
- eventSourceHit : The CalendarHit object that describes the source of the drag operation.
Return false to cancel the operation.

This function can return a Promise (i.e., it can be async).

Example:
```
 let calendar = new Calendar({
     features : {
         drag : {
             async validateResizeFn({ eventRecord, drag }) {
                 // This method can be async so it can make ajax requests or interact
                 // with the user...

                 // if we return false, the event change will be discarded
             }
         }
     }
 });
```
or:
```
 let calendar = new Calendar({
     features : {
         drag : {
             // Will resolve on the Calendar
             validateResizeFn : 'up.validateResize'
         }
     },
     validateResize{ eventRecord, drag } {
         ...
     }
 });
```
Parameters
- info : Object
  Info
- drag : DragContext
  
  The drag create context.
- event : Event
  
  The browser event object.
- view : CalendarView
  
  The Calendar widget in which the drag is taking place.
- eventRecord : EventModel
  
  A proxy event record which is updated during the drag operation to create the UI. This record is not the original event record. The original event record is unchanged until the drag operation is complete.
Returns

Boolean/Promise
:

Return false if this event change should be rejected.

Properties

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

isCalendarDrag : Booleantrue

READONLY

static

ADVANCED

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

removeFromExternalStore : Booleantrue

By default, when an event is dragged from an external source, the event is removed from the source EventStore. Configure this as false to leave the event in place to allow for the dragging in of the same event repeatedly.

Has a corresponding removeFromExternalStore config.
isCalendarDrag : Booleantrue

READONLY

ADVANCED

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

Events

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

beforeDragCreate

PREVENTABLE

ON-OWNER

This event fires on the owning Calendar before a drag creation gesture is started. Return false to veto the operation.

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

ASYNC

PREVENTABLE

ON-OWNER

This event fires on the owning Calendar before a drag creation gesture is completed. Return false to immediately veto the operation or a Promise yielding true or false for async vetoing.

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

PREVENTABLE

ON-OWNER

This event fires on the owning Calendar before a drag move gesture is started. Return false to veto the operation.

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

ASYNC

PREVENTABLE

ON-OWNER

This event fires on the owning Calendar before a drag move gesture is completed. Return false to immediately veto the operation or a Promise yielding true or false for async vetoing.

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

PREVENTABLE

ON-OWNER

This event fires on the owning Calendar before a drag resize gesture is started. Return false to veto the operation.

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

ASYNC

PREVENTABLE

ON-OWNER

This event fires on the owning Calendar before a drag resize gesture is completed. Return false to immediately veto the operation or a Promise yielding true or false for async vetoing.

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

ON-OWNER

This event fires on the owning Calendar when a drag creation gesture is completed.

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

ON-OWNER

This event fires on the owning Calendar when a drag move gesture is completed. The eventRecord has already been added to the eventStore of the owning calendar.

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

ON-OWNER

This event fires on the owning Calendar when a drag resize gesture is completed.

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

onBeforeDragCreate

PREVENTABLE

ON-OWNER

This handler is called on the owning Calendar before a drag creation gesture is started. Return false to veto the operation.

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

ASYNC

PREVENTABLE

ON-OWNER

This handler is called on the owning Calendar before a drag creation gesture is completed. Return false to immediately veto the operation or a Promise yielding true or false for async vetoing.

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

PREVENTABLE

ON-OWNER

This handler is called on the owning Calendar before a drag move gesture is started. Return false to veto the operation.

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

ASYNC

PREVENTABLE

ON-OWNER

This handler is called on the owning Calendar before a drag move gesture is completed. Return false to immediately veto the operation or a Promise yielding true or false for async vetoing.

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

PREVENTABLE

ON-OWNER

This handler is called on the owning Calendar before a drag resize gesture is started. Return false to veto the operation.

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

ASYNC

PREVENTABLE

ON-OWNER

This handler is called on the owning Calendar before a drag resize gesture is completed. Return false to immediately veto the operation or a Promise yielding true or false for async vetoing.

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

ON-OWNER

This handler is called on the owning Calendar when a drag creation gesture is completed.

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

ON-OWNER

This handler is called on the owning Calendar when a drag move gesture is completed. The eventRecord has already been added to the eventStore of the owning calendar.

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

ON-OWNER

This handler is called on the owning Calendar when a drag resize gesture is completed.

Note that this handler is called on the owning widget:

Type definitions

CalendarDragMode
An immutable object that describes a calendar drag mode. These objects are used to simplify detecting the drag mode to apply appropriate actions.
Properties
- type : 'create'/'move'/'resize'
  
  The value 'create', 'move', or 'resize'.
- create : Boolean
  
  The value true if type === 'create', otherwise false.
- move : Boolean
  
  The value true if type === 'move', otherwise false.
- resize : Boolean
  
  The value true if type === 'resize', otherwise false.
ValidateCreateResult
Format expected to be returned in a validateCreateFn
Properties
- add : Boolean
  
  Allow adding to store
- edit : Boolean
  
  Allow editor to open

CalendarDrag
Feature

Asynchronous validation of resize, move and create operations

Converting "All day" events to intra day events

Useful configs

See also

Configs

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Properties

Events

Event handlers

Type definitions

Properties

Properties

Source path

Inheritance tree4

Mixins2

Contents

CalendarDrag Feature

Asynchronous validation of resize, move and create operations

Converting "All day" events to intra day events

Useful configs

See also

Configs

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Properties

Events

Event handlers

Type definitions

Properties

Properties

Source path

Inheritance tree4

Mixins2

Contents

CalendarDrag
Feature