Aurelia-Dragula

aurelia-dragula is an Aurelia plugin which provides a simple (but not simplistic) library to add drag and drop functionality.

Because of the way Aurelia works, I have decided to fork Dragula and make it a bit more friendly to the framework.

To develop for the library, run npm install, jspm install, gulp build, gulp test

If installing in an aurelia application, jspm install npm:aurelia-dragula and remember to aurelia.use.plugin('aurelia-dragula') in your initialisation code. Aurelia-dragula is also webpack compatible.

As Aurelia doesn't support IE < 9, Aurelia-Dragula won't, either. Aurelia-dragula has zero external dependencies. None. Nada. Keine. Not a one.

Aurelia Dragula differs from the upstream library, in that it also passes the view-models for the item (and sibling on the drop event) if the item being dragged corresponds to an Aurelia Custom Element.

Usage

The element itself is called dragula-and-drop and you can bind all the options available for the main library (with camel-case converted to hyphenated attribute names in the standard way) to it as well as a couple of extras. The functions are short-hand for binding to the equivalent events and should be bound with .call and if you want to receive arguments, they should be named the same as in the Type column below:

E.g: viewmodel.html:

<template>
  <dragula-and-drop drop-fn.call="itemDropped(item, target, source, sibling, itemVM, siblingVM)"></dragula-and-drop>
  <div class="drag-source drop-target">
    <compose repeat.for="thing of things" view-model.bind="thing"></compose>
  </div>
</template>

viewmodel.js:

export class ViewModel {

  constructor() {
    this.things = [];
  }

  itemDropped(item, target, source, sibling, itemVM, siblingVM) {
    //do things in here
  }
}

As an extra helping hand, I have also exposed a helper function for moving an item before the sibling in an array (for such bindings as the previous ones): function moveBefore(array, itemMatcherFn, siblingMatcherFn) Where array is the array in which to move the objects, itemMatcherFn is a function which takes one of the items in array as an argument and returns a boolean, to say whether the js Object matches the item HTMLElement being dragged or not. siblingMatcherFn is a function which takes one of the items in array as an argument and returns a boolean, to say whether the js Object matches the sibling HTMLElement.

A more complete example is available here.

Options

import {Options} from 'aurelia-dragula;

The options can either be passed in as a parameter to the Dragula constructor for individual instances, or can be set globally during plugin configuration:

let options = new Options();
options.revertOnSpill = false;
let dragula = new Dragula(options);

or

aurelia.use
  .plugin('aurelia-dragula', (options) => {
    options.revertOnSpill = false;
  });

They can be used in conjunction with one another, with the individually set settings taking precedence over the global settings.

Events

Events can be subscribed to by calling dragula.on with the event name and a callback. They can be registered for multiple times, with different callbacks.

dragula.on('drag', (el, source) => {
  //do a thing here
});

Events can be unsubscribed from by calling the dragula.off function. If only an event type is passed, then all subscribers for that event will be unsubscribed. If a function is also given, then only the subscriber with the matching callback will be unsubscribed:

let fn = (el, source) => {
  //do a thing here
};
dragula.on('drag', fn);

dragula.off('drag', fn);
dragula.off('dragend');

If you only want the event to fire exactly once, then instead of registering and de-registering manually, the dragula.once registration function may be used:

dragula.once('drag', (item, source, itemVM) => {
  //do a thing here
});

Bundling

Bundling with Aurelia-Dragula currently requires the following resources:

"aurelia-dragula",
"aurelia-dragula/dragula.css!text",
"aurelia-dragula/dragula-and-drop.html!text",
"aurelia-dragula/dragula-and-drop.js"