pan

Pan

Touch enabled implementation of WHATWG drag and drop (aka HTML drag and drop) mechanism.

• Pan
  • How Does It Work?
    • Visual Feedback
    • Benefits
  • Quick Start
    • Examples
  • Events
    • Event Object
  • Download

How Does It Work?

new Pan(targetElement);

This will give targetElement a draggable property and set an event listener for dragstart, drag and dragend; it will also set an event listener for touchstart, touchmove and touchend. These events are re-emitted through the eventEmitter and allow you to animate handle in response to drag/touch events.

Visual Feedback

HTML drag and drop spec does not define a method for styling or animating the handle in response to the drag event, e.g. there is no way to control element opacity while dragging.

The following mechanism is used to get the full control of the visual feedback:

In the event of dragstart and touchstart:

• Make a clone (handle) of the target element.
• Take the target element out of the flow (i.e., hide).
• Insert the handle element in place of the target element.

In the event of drag and touchmove:

• Make a reference to the handle element available to the event object.

In the event of dragend and touchend:

• Remove the handle element.
• Restore the target element.

As a result, you have full control over the visual feedback.

There is a reference to the handle element in the Event Object.

Benefits

• Access to all of the DOM events for drag and touch.
• Lightweight and performs good.

Quick Start

To make element draggable:

var targetElement,
    pan;

targetElement = document.querySelector('#target-element');
pan new Pan(targetElement);

pan.eventEmitter.on('start', function (e) {
    console.log(e);
});

pan.eventEmitter.on('move', function (e) {
    e.handle.style.transform = 'translate(' + e.offsetX + 'px,' + e.offsetY + 'px)';
});

pan.eventEmitter.on('end', function (e) {
    console.log(e);
});

This will make the #target-element element draggable using CSS3 transformations.

The result of Pan() is an object with a single property (eventEmitter) used to emit events.

Examples

• Basic element dragging using CSS transformations.
• Events logged in the console.log.

The code for all of the examples is in the examples folder.

Raise an issue if you are missing an example.

Events

You can listen for individual drag and touch DOM events:

targetElement.addEventListener('dragstart', dragStart);
targetElement.addEventListener('drag', dragMove);
targetElement.addEventListener('dragend', dragEnd);

targetElement.addEventListener('touchstart', dragStart);
targetElement.addEventListener('touchmove', dragMove);
targetElement.addEventListener('touchend', dragEnd);

You can use the eventEmitter object that will normalize drag and touch events to:

pan.eventEmitter.on('start', dragStart);
pan.eventEmitter.on('move', dragMove);
pan.eventEmitter.on('end', dragEnd);

Event Object

The listener of the eventEmitter is passed a single eventObject object.

pan.eventEmitter.on('move', function (eventObject) {
    
});

Name	Value
offsetX	Distance from the starting point on X axis.
offsetY	Distance from the starting point on Y axis.
target	Target that received the event.
handle	Element used to represent the target element when dragging.
type	Event name.

Download

Using Bower:

bower install pan

Using NPM:

npm install pan-drag

The old-fashioned way, download either of the following files:

• https://raw.githubusercontent.com/gajus/pan/master/dist/pan.js
• https://raw.githubusercontent.com/gajus/pan/master/dist/pan.min.js