ray-draggabilly v1.0.0

ray-draggabilly

ray-draggabilly.desandro.com

Rad because it supports IE10+ and multi-touch.

Install

Usage

Initialize ray-draggabilly as a jQuery plugin

var $draggable = $('.draggable').ray-draggabilly({
  // options...
})

Initialize ray-draggabilly with vanilla JS

var elem = document.querySelector('.draggable');
var draggie = new RayDraggabilly( elem, {
  // options...
});

// or pass in selector string as first argument
var draggie = new RayDraggabilly( '.draggable', {
  // options...
});

// if you have multiple .draggable elements
// get all draggie elements
var draggableElems = document.querySelectorAll('.draggable');
// array of Draggabillies
var draggies = []
// init Draggabillies
for ( var i=0, len = draggableElems.length; i < len; i++ ) {
  var draggableElem = draggableElems[i];
  var draggie = new RayDraggabilly( draggableElem, {
    // options...
  });
  draggies.push( draggie );
}

Classes

• .is-pointer-down added when the user's pointer (mouse, touch, pointer) first presses down.
• .is-dragging added when elements starts to drag.

Options

axis

Type: String

Values: 'x' or 'y'

axis: 'x'

Constrains movement to horizontal or vertical axis.

containment

Type: Element, Selector String, or Boolean

containment: '.container'

Contains movement to the bounds of the element. If true, the container will be the parent element.

grid

Type: Array

Values: [ x, y ]

grid: [ 20, 20 ]

Snaps the element to a grid, every x and y pixels.

handle

Type: Selector String

handle: '.handle'

Specifies on what element the drag interaction starts.

handle is useful for when you do not want all inner elements to be used for dragging, like inputs and forms. See back handle example on CodePen.

Events

Bind events with jQuery with standard jQuery event methods .on(), .off(), and .one(). Inside jQuery event listeners this refers to the ray-draggabilly element.

// jQuery
function listener(/* parameters */) {
  // get ray-draggabilly instance
  var draggie = $(this).data('ray-draggabilly');
  console.log( 'eventName happened', draggie.position.x, draggie.position.y );
}
// bind event listener
$draggable.on( 'eventName', listener );
// unbind event listener
$draggable.off( 'eventName', listener );
// bind event listener to trigger once. note ONE not ON
$draggable.one( 'eventName', function() {
  console.log('eventName happened just once');
});

Bind events with vanilla JS with .on(), .off(), and .once() methods. Inside vanilla JS event listeners this refers to the ray-draggabilly instance.

// vanilla JS
function listener(/* parameters */) {
  console.log( 'eventName happened', this.position.x, this.position.y );
}
// bind event listener
draggie.on( 'eventName', listener );
// unbind event listener
draggie.off( 'eventName', listener );
// bind event listener to trigger once. note ONCE not ONE or ON
draggie.once( 'eventName', function() {
  console.log('eventName happened just once');
});

dragStart

Triggered when dragging starts and the element starts moving. Dragging starts after the user's pointer has moved a couple pixels to allow for clicks.

// jQuery
$draggable.on( 'dragStart', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'dragStart', function( event, pointer ) {...})

• event - Type: Event - the original mousedown or touchstart event
• pointer - Type: MouseEvent or Touch - the event object that has .pageX and .pageY

dragMove

Triggered when dragging moves.

// jQuery
$draggable.on( 'dragMove', function( event, pointer, moveVector ) {...})
// vanilla JS
draggie.on( 'dragMove', function( event, pointer, moveVector ) {...})

• event - Type: Event - the original mousemove or touchmove event
• pointer - Type: MouseEvent or Touch - the event object that has .pageX and .pageY
• moveVector Type: Object - How far the pointer has moved from its start position { x: 20, y: -30 }

dragEnd

Triggered when dragging ends.

// jQuery
$draggable.on( 'dragEnd', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'dragEnd', function( event, pointer ) {...})

• event - Type: Event - the original mouseup or touchend event
• pointer - Type: MouseEvent or Touch - the event object that has .pageX and .pageY

pointerDown

Triggered when the user's pointer (mouse, touch, pointer) presses down.

// jQuery
$draggable.on( 'pointerDown', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'pointerDown', function( event, pointer ) {...})

• event - Type: Event - the original mousedown or touchstart event
• pointer - Type: MouseEvent or Touch - the event object that has .pageX and .pageY

pointerMove

Triggered when the user's pointer moves.

// jQuery
$draggable.on( 'pointerMove', function( event, pointer, moveVector ) {...})
// vanilla JS
draggie.on( 'pointerMove', function( event, pointer, moveVector ) {...})

• event - Type: Event - the original mousemove or touchmove event
• pointer - Type: MouseEvent or Touch - the event object that has .pageX and .pageY
• moveVector Type: Object - How far the pointer has moved from its start position { x: 20, y: -30 }

pointerUp

Triggered when the user's pointer unpresses.

// jQuery
$draggable.on( 'pointerUp', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'pointerUp', function( event, pointer ) {...})

• event - Type: Event - the original mouseup or touchend event
• pointer - Type: MouseEvent or Touch - the event object that has .pageX and .pageY

staticClick

Triggered when the user's pointer is pressed and unpressed and has not moved enough to start dragging.

click events are hard to detect with draggable UI, as they are triggered whenever a user drags. ray-draggabilly's staticClick event resolves this, as it is triggered when the user has not dragged.

// jQuery
$draggable.on( 'staticClick', function( event, pointer ) {...})
// vanilla JS
draggie.on( 'staticClick', function( event, pointer ) {...})

• event - Type: Event - the original mouseup or touchend event
• pointer - Type: MouseEvent or Touch - the event object that has .pageX and .pageY

Methods

disable

// jQuery
$draggable.ray-draggabilly('disable')
// vanilla JS
draggie.disable()

enable

// jQuery
$draggable.ray-draggabilly('enable')
// vanilla JS
draggie.enable()

destroy

// jQuery
$draggable.ray-draggabilly('destroy')
// vanilla JS
draggie.destroy()

jQuery.fn.data('ray-draggabilly')

Get the ray-draggabilly instance from a jQuery object. ray-draggabilly instances are useful to access ray-draggabilly properties.

var draggie = $('.draggable').data('ray-draggabilly')
// access ray-draggabilly properties
console.log( 'draggie at ' + draggie.position.x + ', ' + draggie.position.y )

Properties

position

{ x: 20, y: -30 }

• x Integer
• y Integer

RequireJS

ray-draggabilly works with RequireJS.

You can require ray-draggabilly.pkgd.js..

requirejs( [
  'path/to/ray-draggabilly.pkgd.js',
], function( ray-draggabilly ) {
  new RayDraggabilly( ... );
});

To use ray-draggabilly as a jQuery plugin with RequireJS and ray-draggabilly.pkgd.js, you need to call jQuery Bridget.

// require the require function
requirejs( [ 'require', 'jquery', 'path/to/ray-draggabilly.pkgd.js' ],
  function( require, $, ray-draggabilly ) {
    // require jquery-bridget, it's included in ray-draggabilly.pkgd.js
    require( [ 'jquery-bridget/jquery-bridget' ],
    function() {
      // make ray-draggabilly a jQuery plugin
      $.bridget( 'ray-draggabilly', ray-draggabilly );
      // now you can use $().ray-draggabilly()
      $('.draggable').ray-draggabilly({...})
    }
  );
});

You can require Bower dependencies and use Isotope as a jQuery plugin with jQuery Bridget.

requirejs.config({
  baseUrl: '../plugins',
  paths: {
    jquery: 'jquery/jquery'
  }
});

requirejs( [
    'jquery',
    'ray-draggabilly/ray-draggabilly',
    'jquery-bridget/jquery.bridget'
  ],
  function( $, RayDraggabilly ) {
    // make RayDraggabilly a jQuery plugin
    $.bridget( 'ray-draggabilly', RayDraggabilly );
    // now you can use $().RayDraggabilly()
    $('.draggable').RayDraggabilly({...})
});

install

npm install ray-draggabilly

var ray-draggabilly = require('ray-draggabilly');

var draggie = new RayDraggabilly( '.draggable', {
  // options
});

To use ray-draggabilly as a jQuery plugin with Browserify, you need to call jQuery Bridget.

npm install jquery-bridget

var $ = require('jquery');
require('jquery-bridget');
var RayDraggabilly = require('ray-draggabilly');

// make RayDraggabilly a jQuery plugin
$.bridget( 'ray-draggabilly', RayDraggabilly );
// now you can use $().RayDraggabilly()
$('.draggable').RayDraggabilly({...})

Browser support

IE10+, Android 4+, iOS 6+, and all modern browsers

License

MIT