Sortable

Sortable is an AngularJS module for sorting an arbitrary set of UI elements by dragging them.

• License
• Demo
• Installation
• Usage
• Caveats
• API Documentation

License

This software is provided free of charge and without restriction under the MIT License

Demo

https://boulevard.github.io/sortable

Installation

Using Bower

This package is installable through the Bower package manager.

bower install blvd-sortable --save

In your index.html file, include the sortable module.

<script type="text/javascript" src="bower_components/sortable/dist/sortable.min.js"></script>

Include the sortable module as a dependency in your application.

angular.module('myApp', ['sortable']);

Using npm and a Module Bundler (webpack or Browserify or jspm)

In addition, this package may be installed using npm.

npm install blvd-sortable --save

You may use Browserify to inject this module into your application.

angular.module('myApp', [require('blvd-sortable')]);

Usage

Basic Usage

<div>Rank your favorite junk food.</div>

<ol sortable>
  <li>Reeses Peanut Butter Cup</li>
  <li>Hostess Twinkies</li>
  <li>Ben & Jerry's Ice Cream</li>
</ol>

Responding to drag events

class SortableController {
  canSort = true;

  onDragStart = (element) => {
    ...
  }
  
  onDragMove = (element) => {
    ...
  }

  onDragEnd = (element, newIndex, oldIndex, sequence) => {
    ...
  }
}

<div>Rank your favorite junk food.</div>

<ol sortable="$ctrl.canSort" drag-start="$ctrl.onDragStart" drag-move="$ctrl.onDragMove" drag-end="$ctrl.onDragEnd">
  <li>Reeses Peanut Butter Cup</li>
  <li>Hostess Twinkies</li>
  <li>Ben & Jerry's Ice Cream</li>
</ol>

Caveats

Fixed elements are normally positioned relative to the initial containing block established by the viewport; however, when an ancestor of the element has a transform, perspective, or filter property it becomes the containing element. This complicates computing the position of the element being dragged. One solution may be to move the element being dragged to the document body, but that could conflict with computed css styles. For now I would recommend adding the following dragStart callback to manually correct the element's position.

function onDragStart(element) {
  // obtain the culprit element
  var transformedElement = document.querySelector('[style="transform: ..."]');
  var bounds = transformedElement.getBoundingClientRect();

  // correct the element's position
  element.css('left', element.css('left').slice(0, -2) - bounds.left + 'px');
  element.css('top', element.css('top').slice(0, -2) - bounds.top + 'px');
}

API Documentation

Don't forget to kebab-case attributes in your template (e.g. dragEnd should be written drag-end in your template).

Attributes

| Attribute | Type | Details | | :------------------------------------- | :----------- | :------ | | dragEnd (optional) | Function | Callback function on drag end. (see below for arguments) | | dragMove (optional) | Function | Callback function on drag move. (see below for arguments) | | dragStart (optional) | Function | Callback function on drag start. (see below for arguments) | | ngModel (optional) | Array | The array will be reordered as elements are sorted in the UI. | | options (optional) | Object | Configurable options. (see below for details) | | sortable | expression | Will enable sorting if empty or evaluates to true. |

Callbacks

dragStart(element)

| Argument | Type | Details | | :--------- | :-------- | :------ | | element | jqLite | The element being dragged. |

dragMove(element)

| Argument | Type | Details | | :--------- | :-------- | :------ | | element | jqLite | The element being dragged. |

dragEnd(element, newIndex, oldIndex, [sequence])

| Argument | Type | Details | | :--------- | :-------- | :------ | | element | jqLite | The element being dragged. | | newIndex | Integer | The new index of the element. | | oldIndex | Integer | The old index of the element. | | sequence | Array | A reference to the sequence. Requires ngModel |

Options

| Property | Type | Details | | :---------- | :-------- | :------ | | dropzone | String | Provide a template for the drop zone. By default an empty element with the same tag name as the element being dragged will be created. | | sameSize | Boolean | Will make the dropzone the same size as the element being dragged. The default is true | | threshold | Number | The magnitude, in pixels, the user must drag before initiating a drag. The default is 2 |

Styling

The element being dragged will have the dragging class. The drop zone will have the drop-zone class.