Drag&Drop Directives Specification

IgxDrag/IgxDrop Directives Specification

Contents

1. Overview
2. User Stories
3. Functionality
   • 3.1. Drag
   • 3.2. Drop
4. API
   • 4.1. Directives
   • 4.2. Interfaces
5. Assumptions and Limitations
6. Test Scenarios
   • 6.1. Manual
   • 6.2. Automation

Revision History

Version	User	Date	Notes
0.1	Svetoslav Krastev	Jun 20, 2019	Initial draft
0.2	Svetoslav Krastev	Jun 27, 2019	Updated draft

• Stefan Ivanov | Date:
• Radoslav Karaivanov | Date:
• Martin Pavlov | Date:
• Konstantin Dinev | Date:

1. Overview

IgxDrag provides a way to move an element by click and dragging it around. In combination with igxDrop directive that specifies where element can be put it allows an element to be moved from one place to another.

2. User Stories

Elaborate more on the multi-faceted use cases

As a developer, I want to:

• easily define an element can be dragged by using a directive on any element.
• easily define a drop area where a dragged element can be dropped on any element.
• specify if element that can be dragged and moved freely.
• specify if a ghost element should be rendered after dragging begins representing the original element and the original element should keep its original position.
• easily use a custom ghost element that is created from the drag directive after dragging starts.
• provide a way to set where the default/custom ghost should be rendered (what it's parent element should be).
• ? dynamically update the custom ghost based on my provided template
• have elements inside dragged elements that should not trigger dragging and can be interacted with.
• be able to listen to events when the drag has started/ended, when clicked or when the preview element is being created.
• be able to listen to events when element has been dropped onto a drop area.
• provide specific data that the igxDrag carries so when a specific element is dropped it can be distinguished.
• set new position in the DOM for the igxDrag instanced element and have animation that transitions to that new location.
• have ability to customize the animations applied to the igxDrag element when interacting with it

As an end user, I want to:

• drag an element around freely and it keeping its position on release.
• drag an element around and it rendering a ghost element that is placed under the pointer when dragging around.
• drag an element from one area to another area by both possible ways of dragging.
• use either mouse or touch interaction to drag an element.
• have a clear indication when the dragging has started.
• be able to click the draggable elements.
• have some room of error when clicking on an element so it doesn't start dragging immediately.
• have smooth transition animations if dragged elements keep their original position or have specific new ones that don't align with the exact drop location

3. Functionality

3.1 Drag

The igxDrag directive can be instantiated on any type of element. It can be used on its own without depending on the igxDrop. It should provide enough functionality so the user could determine where it has been released and so implements a custom logic.

Specific data can be stored inside the igxDrag for various purposes like identifying it among other draggable elements and etc. It can be specified by assigning it on the initialization tag [igxDrag] or by using the data input where it is stored:

<div [igxDrag]="myData">Drag me!</div>

By default the dragging will not start immediately in order to provide some room for error as well as not interrupt if the user wants to click the element instead. The tolerance for it is 5px in any direction and if it is exceeded then the dragging would start. This can be configured using the dragTolerance input.

Dragging with ghost element

The renderGhost input is set to true by default which means that the base element the igxDrag directive is initialized will keep its position and a ghost will be rendered under the user pointer once the dragging starts. While still holding and moving the ghost created will move along the user pointer instead of the base element.

• Customizing the ghost

  The ghost element by default is a copy of the base element the igxDrag is used on. It can be customized by providing a template reference to the ghostTemplate input directly. The template itself can be position anyway, since the only thing provided is reference to it. It can be done the following way:

  <div [igxDrag]="'Dolphin'" [ghostTemplate]="customGhost">
      Drag me!
  </div>
  <ng-template #customGhost>
      <div>I can fly!</div>
  </ng-template>

• Customizing the base

  Since when using a ghost element leaves us with the base element being still rendered at its original location we can hide it by setting applying custom visibility style when dragging starts or by completely replacing its content using ngIf.

  Hiding the base element:

  <div [igxDrag]="'Dolphin'" [ngStyle]="{ 'visibility': dragged ? 'hidden' : 'visible' }">
      Drag me!
  </div>

  Customizing the base content:

  <div [igxDrag]="'Dolphin'" [ngStyle]="{ 'visibility': dragged ? 'hidden' : 'visible' }">
      <div *ngIf="dragged; else originTemplate">Drag me!</div>
      <ng-template #originTemplate>Origin!</ng-template>
  </div>

Dragging without ghost

If renderGhost input is set to false the dragging logic for the igxDrag provides dragging ability for the initialized element itself. This means that it can freely move an element around by click and hold and when released it will keep its position where it was dragged.

Dragging using a handle

The user can specify an element that is a child of the igxDrag by which to drag since by default the whole element is used to perform that action. It can be done using the igxDragHandle directive and can be applied to multiple elements inside the igxDrag.

When multiple channels are applied to an igxDrag and one of them matches one of applied channels to an igxDrop, then all events and applied behaviors would be executed when that element is dropped.

Example:

<div igxDrag>
    <div igxDragHandle>X</div>
    Drag me!
</div>

Linking Drag to Drop element

Using the dragChannel and dropChannel input on respectively igxDrag and igxDrop directives the user can link different elements to interact only between each other. For example if an igxDrag element needs to be constrained so it can be dropped on specific igxDrop element and not all available this can easily be achieved by assigning them same channel.

When assigning either single or multiple channels using an array, each channel is compared using the Strict Equality comparison.

Example:

<div igxDrag [dragChannel]="['Mammals', 'Land']"> Human </div>
<div igxDrag [dragChannel]="['Mammals', 'Water']"> Dolphin </div>
<div igxDrag [dragChannel]="['Insects', 'Air']"> Butterfly </div>
<div igxDrag [dragChannel]="['Insects', 'Land']"> Ant </div>

<div igxDrop [dropChannel]="['Mammals']"> Mammals </div>
<div igxDrop [dropChannel]="['Insects']"> Insects </div>
<div igxDrop [dropChannel]="['Land']"> Land </div>

As displayed above only Human and Dolphin can be dropped in the 'Mammals' class but not in the 'Insects' class, where only the Butterfly and Bee can be dropped. Same for the 'Land' drop area where only Ant and Human can be dropped.

Animations

By default when an element is being dragged there are no animations applied.

The user can apply transition animation to the igxDrag any time, but it is advised to use it when dragging ends or the element is not currently dragged. This can be achieved using the animateToOrigin and the animateTo methods.

The animateToOrigin method as the name suggest animates the currently dragged element or its ghost to the start position where the dragging began. The animateTo method animates the element to a specific location relative to the page (i.e. pageX and pageY) or to the position of a specified element. If the element is not being currently dragged it will animate anyway or create ghost and animate it to the desired position.

Both function have arguments that the user can set to customize the transition animation and set duration, timing function or delay. If specific start location is set it will animate the element starting from there.

When the transition animation ends if a ghost is created it will be removed and the igxDrag directive will return to its initial state or if no ghost is created it will keep its position. In both cases then the onAnimationEnd event will be triggered depending on how long the animation lasts. If no animation is applied it will triggered instantly.

If the user want to have other types of animations that involve element transformations he can do that like any other element either using the Angular Animations or straight CSS Animations to either the base igxDrag element or its ghost. If he wants to apply them to the ghost he would need to define a custom ghost and apply animations to that element.

3.2 Drop

For achieving a drop functionality with the igxDrag directive the igxDrop directive should be used. It can be applied on any kind of element and it specifies an area where the igxDrag can be dropped.

By default the igxDrop does not apply any logic to the dragged element when it is dropped onto it. The user could choose between a few different drop strategies if he would like the igxDrop to perform some action or he could implement his own drop logic using the provided onDragDrop events.

Drop Strategies

The igxDrop comes with 4 drop strategies which are defined in the enum IgxDropStrategy and has the following values - Default, Append, Prepend, Insert:

• The Default strategy does not perform any action when an element is dropped onto an IgxDrop element and is implemented as a class named IgxDefaultDropStrategy.

• As the names suggest the first Append strategy inserts the dropped element as a last child and is implemented as a class named IgxAppendDropStrategy.

• The Prepend strategy inserts the dropped element as first child and is implemented as a class named IgxPrependDropStrategy.

• The Insert strategy inserts the dragged element at the dropped position. If there is a child under the element when it was dropped, the igxDrag instanced element will be inserted at that child's index. It is implemented as a class named IgxInsertDropStrategy

The way a strategy can be applied is by setting the dropStrategy input to one of the listed classes above. The value provided has to be e type and not an instance, since the igxDrop has to create the instance itself.

Example:

TypeScript:

public insertStrategy = IgxInsertDropStrategy;

HTML:

<div igxDrop [dropStrategy]="insertStrategy"></div>

Canceling a Drop Strategy

When using a specific drop strategy, its behavior can be canceled in the onDrop or onDragDrop events by setting the cancel property to true. The onDrop event is specific to the igxDrag and the onDragDrop event to the igxDrop. If the user does not have drop strategy applied to the igxDrop canceling the event would have no side effects.

Example:

HTML

<div igxDrag (onDragDrop)="onDragDropped($event)"></div>
<!-- ... -->
<div igxDrop></div>

TypeScript

public onDragDropped(event) {
    event.cancel = true;
}

If the user would like to implement its own drop logic it can easily be done by binding either to onDrop or the onDragDrop event and executing their logic when the event is triggered. Both events should provide enough context so the user could implement it on their own.

Animations

If the user decides that he want to use transition animations when dropping an element he can do that by using transition animations that can be applied to the igxDrag by calling the animateToOrigin or animateTo methods whenever he wants. Preferably that should be done when dragging of an element ends or when it is dropped onto a igxDrop instanced element.

Example:

HTML

<div>Products:</div>
<div #productsContainer>
    <div *ngFor="let product of availableProducts; let i = index"
        [igxDrag]="{index: i}"
        (onDragEnd)="onDragReleased($event)"
        (onDragDrop)="onDragDropped($event)"
        (onAnimationEnd)="onDragAnimationEnd($event)">
        {{product}
    </div>
<div>

<div>Basket:</div>
<div igxDrop>
    <div *ngFor="let product of basketProducts">{{product}}</div>
</div>

TypeScript

public availableProducts = ["milk", "cheese", "banana"];
public basketProducts = [];

public onDragReleased(event) {
    event.owner.animateToOrigin();
}
public onDragDropped(event) {
    event.owner.animateTo(event.dropDirective.element);
}
public onDragAnimationEnd(event) {
    const removeIndex = event.owner.data.index;
    const removedElem = availableProducts.splice(removeIndex, 1);
    basketProducts.push(removedElem);
}

4. API

4.1. Directives

• IgxDrag

  Inputs

  Name	Description	Type	Default value
  data	Sets information to be stored in the directive.	any	undefined
  dragTolerance	The amount of pixes the user need to move before the dragging starts and the preview is rendered.	number	5
  dragChannel	Specifies channel or multiple channels to which the element is linked to and can interact with only those igxDrop elements in those channels	number | string | number[] | string[]	undefined
  renderGhost	Sets if the when the dragging of the element start a ghost should be rendered under the pointer and the original element kept where it is positioned or not.	boolean	true
  ghostTemplate	A custom template for the ghost element that completely replaces the default one.	TempalteRef	undefined
  ghostHost	Sets the element to which the drag ghost element will be appended to. By default it's set to null and the ghost element is appended to the body.	ElementRef	undefined
  ghostOffsetX	Sets the offset position of the ghost element relative to the mouse horizontally.	number	undefined
  ghostOffsetY	Sets the offset position of the ghost element relative to the mouse vertically.	number	undefined

  Outputs

  Name	Description	Cancelable	Parameters
  onDragStart	Event triggered when any movement starts.	true	IDragBaseEventArgs
  onDragMove	Event triggered for every frame where the igxDrag element has been dragged.	true	IDragMoveEventArgs
  onDragEnd	Event triggered when the user releases the element area that is not inside an igxDrop. This is triggered before any animation starts.	false	IDragBaseEventArgs
  onDragClick	Even triggered when the user performs a click and not dragging	false	IDragBaseEventArgs
  onDragEnter	Event triggered once the drag element enters an igxDrop element	false	IDragEnterLeaveEventArgs
  onDragLeave	Event triggered once the drag element leaves an igxDrop element	false	IDragEnterLeaveEventArgs
  onDragDrop	Event triggered once the drag element has been released over an igxDrop element.	true	IDragDropEventArgs
  onAnimationEnd	Event triggered after any movement of the drag element has ended. This is triggered after all animations have ended and before the ghost is removed.	false	IDragBaseEventArgs
  onGhostCreate	Event triggered right before the ghost element is created	false	IDragGhostBaseEventArgs
  onGhostDestroy	Event triggered right before the ghost element is destroyed	false	IDragGhostBaseEventArgs

  Properties

  Name	Description	Type
  location	Gets the current location of the element relative to the page. If ghost is enabled it will get the location of the ghost, if the user is not currently dragging it will return the location of the base element.	IDragLocation

  Methods

  Name	Description	Parameters	Return Type
  setLocation	Sets new location for the igxDrag directive. When ghost is enable and it is not rendered it will be ignored.	newLocation?: IDragLocation	void
  animateToOrigin	Animates the element from its current location to its initial position. If it was not moved or no start location is specified nothing would happen .	customAnimationArgs?: IDragCustomAnimationArgs, startLocation?: IDragLocation,	void
  animateTo	Animates the element from its current location to specific location or DOM element. If it was not moved or no start location is specified nothing would happen.	target: IDragLocation|ElementRef, customAnimationArgs?: IDragCustomAnimationArgs, startLocation?: IDragLocation	void

• IgxDrop

  Inputs

  Name	Description	Type	Default value
  data	Sets information to be stored in the directive.	any	undefined
  dropChannel	Specifies channel or multiple channels to which the element is linked to and can interact with only those igxDrag elements in those channels	number | string | number[] | string[]	undefined
  dropStrategy	Sets a drop strategy that should be applied once an element is dropped into the current igxDrop element.	class reference	IgxDefaultDropStrategy

  Outputs

  Name	Description	Cancelable	Type
  onEnter	Event triggered once an IgxDrag instanced element enters the boundaries of the drop area. Similar to MouseEnter.	false	IDropBaseEventArgs
  onOver	Event triggered when an IgxDrag instanced element moves inside the boundaries of the drop area similar to MouseOver.	false	IDropBaseEventArgs
  onLeave	Event triggered once an IgxDrag instanced element leaves the boundaries of the drop area. Similar to MouseLeave.	false	IDropBaseEventArgs
  onDrop	Event triggered once an IgxDrag instanced element inside the drop area is released.	true	IDropDragDropEventArgs

  Properties

  Name	Description	Type
  location	Gets the current location of the element relative to the page.	IDragLocation

4.2. Interfaces

• IDragLocation

  Name	Description	Type
  pageX	The far left location of the drag element relative to the page horizontally.	number
  pageY	The far top location of the drag element relative to the page vertically.	number

• IDragCustomAnimationArgs

  Name	Description	Type
  duration	Specifies how many seconds or milliseconds the animation takes to complete.	number
  timingFunction	Specifies the speed curve for the animation effect.	string
  delay	Specifies a delay (in seconds) for the animation to start.	number

• IDragBaseEventArgs

  Name	Description	Type
  originalEvent	The original event that starting this interaction.	PointerEvent/MouseEvent/TouchEvent
  owner	The owner that triggered this event. In this case the igxDrag.	IgxDragDirective
  startX	The start pageX position of pointer that initiated the drag.	number
  startY	The start pageY position of pointer that initiated the drag.	number
  pageX	The current pageX position of pointer that initiated the drag.	number
  pageY	The current pageY position of pointer that initiated the drag.	number

• IDragMoveEventArgs

  Extends IDragBaseEventArgs.

  Name	Description	Type
  cancel	Property specifying if the default logic which that event is related should be canceled	boolean
  newPageX	The new pageX position that the igxDrag will set next. It can be overridden.	number
  newPageY	The new pageX position that the igxDrag will set next. It can be overridden.	number

• IDragEnterLeaveEventArgs

  Name	Description	Type
  originalEvent	The original event that starting this interaction.	PointerEvent/MouseEvent/TouchEvent
  owner	The owner that triggered this event. In this case the igxDrag.	IgxDragDirective
  dropDirective	The start pageX position of pointer that initiated the drag.	IgxDropDirective
  startX	The start pageX position of pointer that initiated the drag.	number
  startY	The start pageY position of pointer that initiated the drag.	number
  pageX	The current pageX position of pointer that performs the dragging.	number
  pageY	The current pageY position of pointer that performs the dragging.	number
  offsetX	The current offset of the pointer relative to the pageX position of the igxDrop.	number
  offsetY	The current offset of the pointer relative to the pageY position of the igxDrop.	number

• IDragDropEventArgs

  Extends IDragEnterLeaveEventArgs

  Name	Description	Type
  originalEvent	The original event that caused the interaction.	PointerEvent/MouseEvent/TouchEvent

• IDragGhostBaseEventArgs

  Name	Description	Type
  owner	Null or the owner directive that was used to specify custom ghost.	IgxDragGhostDirective
  dragDirective	The owner igxDrag directive that created/destroyed the ghost.	IgxDragDirective

• IDropBaseEventArgs

  Name	Description	Type
  originalEvent	The original event that caused the interaction.	PointerEvent/MouseEvent/TouchEvent
  owner	The owner element that triggered this event. In this case the igxDrop.	IgxDropDirective
  dragDirective	The owner igxDrag directive of the element being dragged over the drop area.	IgxDragDirective
  startX	The start pageX position of pointer that initiated the drag.	number
  startY	The start pageY position of pointer that initiated the drag.	number
  pageX	The current pageX position of pointer that performs the dragging.	number
  pageY	The current pageY position of pointer that performs the dragging.	number
  offsetX	The current offset of the pointer relative to the pageX position of the igxDrop.	number
  offsetY	The current offset of the pointer relative to the pageY position of the igxDrop.	number

• IDropDragDropEventArgs

  Extends IDropBaseEventArgs

  Name	Description	Type
  cancel	Specifies if the default drop logic related to the event should be canceled.	boolean

5. Assumptions and Limitations

Assumptions	Limitation Notes
Drag/Drop on iOS 11.0 and earlier	Due to missing implementation of vital document functions that the IgxDrag uses in iOS 11.0 and the combination of IgxDrag with IgxDrop would not work. IgxDrag on its own should still work.

6. Test Scenarios

6.1. Manual

IdxDrag

IgxDrop (combined with igxDrag)

6.2. Automation

IdxDrag

• Should correctly initialize drag and drop directives
• Should create drag ghost element and trigger onGhostCreate/onGhostDestroy.
• Should not create drag ghost element when the dragged amount is less than dragTolerance.
• Should trigger dragStart/dragMove/dragEnd events in that order.
• Should trigger igxDrag onDragEnter/onDragLeave events when it enters and leaves igxDrop area.
• • Should trigger igxDrag onDrop event when it is dropped onto and igxDrop area.
• Should position ghost at the same position relative to the mouse when drag started.
• Should position ghost relative to the mouse using offsetX and offsetY correctly.
• Should position ghost at the same position relative to the mouse when drag started when host is defined.
• Should allow customizing of ghost element by passing template reference and position it correctly.
• Should position custom ghost relative to the mouse using offsetX and offsetY correctly.
• Should correctly move igxDrag element when ghost is disabled and trigger dragStart/dragMove/dragEnd events.
• Should prevent dragging if it does not exceed dragTolerance and ghost is disabled.
• Should correctly apply dragTolerance of 0 when it is set to 0 and ghost is disabled.
• Should correctly set location using setLocation() method when ghost is disabled.

IgxDrop

• Should trigger onEnter/onDrop/onLeave events when element is dropped inside igxDrop element
• • Should trigger onEnter/onDrop/onLeave events when element is dropped inside and is linked with it.
• • Should not trigger onEnter/onDrop/onLeave events when element is dropped inside and is not linked with it.
• • Should not perform any action by default when an element is dropped inside.
• • Should put dropped element as a first child when Prepend drop strategy is used.
• • Should put dropped element as a last child when Append drop strategy is used.
• • Should put dropped element as a second child when Insert drop strategy is used and element is dropped over the second child already in the igxDrop area.
• • Should cancel drop strategy when the onDrop event is canceled.