Ember-sortable

Sortable UI primitives for Ember.

Requirements

Version 1.0 depends upon the availability of 2D CSS transforms. Check the matrix on caniuse.com to see if your target browsers are compatible.

As of version 1.12.2 ember-sortable depends on Element.closest, which is unsupported in all versions of Internet Explorer. A polyfill is available - both on MDN, and as a package.

Installation

$ ember install ember-sortable

Usage

{{! app/templates/my-route.hbs }}

{{#sortable-group tagName="ul" onChange=(action "reorderItems") as |group|}}
  {{#each model.items as |item|}}
    {{#sortable-item tagName="li" model=item group=group handle=".handle"}}
      {{item.name}}
      <span class="handle">&varr;</span>
    {{/sortable-item}}
  {{/each}}
{{/sortable-group}}

The onChange action is called with two arguments:

Your item models in their new order
The model you just dragged

// app/routes/my-route.js

export default Ember.Route.extend({
  actions: {
    reorderItems(itemModels, draggedModel) {
      this.set('currentModel.items', itemModels);
      this.set('currentModel.justDragged', draggedModel);
    }
  }
});

Declaring a “group model”

When model is set on the sortable-group, the onChange action is called with that group model as the first argument:

{{! app/templates/my-route.hbs }}

{{#sortable-group tagName="ul" model=model onChange=(action "reorderItems") as |group|}}
  {{#each model.items as |item|}}
    {{#sortable-item tagName="li" model=item group=group handle=".handle"}}
      {{item.name}}
      <span class="handle">&varr;</span>
    {{/sortable-item}}
  {{/each}}
{{/sortable-group}}

// app/routes/my-route.js

export default Ember.Route.extend({
  actions: {
    reorderItems(groupModel, itemModels, draggedModel) {
      groupModel.set('items', itemModels);
    }
  }
});

Changing sort direction

To change sort direction, define direction on sortable-group (default is y):

{{#sortable-group direction="x" onChange=(action "reorderItems") as |group|}}

Changing spacing between currently dragged element and the rest of the group

When user starts to drag element, other elements jump back. Works both for the x and y direction option.

In y case: elements above current one jump up, and elements below current one - jump down. In x case: elements before current one jump to the left, and elements after current one - jump to the right.

To change this property, define spacing on sortable-item (default is 0):

{{#sortable-item tagName="li" group=group spacing=15}}

Changing the drag tolerance

distance attribute changes the tolerance, in pixels, for when sorting should start. If specified, sorting will not start until after mouse is dragged beyond distance. Can be used to allow for clicks on elements within a handle.

{{#sortable-item group=group distance=30}}

CSS, Animation

Sortable items can be in one of three states: default, dragging, dropping. The classes look like this:

<!-- Default -->
<li class="sortable-item">...</li>
<!-- Dragging -->
<li class="sortable-item is-dragging">...</li>
<!-- Dropping -->
<li class="sortable-item is-dropping">...</li>

In our example app.css we apply a transition of .125s in the default case:

.sortable-item {
  transition: all .125s;
}

While an item is dragging we want it to move pixel-for-pixel with the user’s mouse so we bring the transition duration to 0. We also give it a highlight color and bring it to the top of the stack:

.sortable-item.is-dragging {
  transition-duration: 0s;
  background: red;
  z-index: 10;
}

While dropping, the is-dragging class is removed and the item returns to its default transition duration. If we wanted to apply a different duration we could do so with the is-dropping class. In our example we opt to simply maintain the z-index and apply a slightly different colour:

.sortable-item.is-dropping {
  background: #f66;
  z-index: 10;
}

Drag Actions

The onDragStart and onDragStop actions are available for the sortable-items. You can provide an action name to listen to these actions to be notified when an item is being dragged or not.

When the action is called, the item's model will be provided as the only argument.

// app/routes/my-route.js

export default Ember.Route.extend({
  actions: {
    dragStarted(item) {
      console.log(`Item started dragging: ${item.get('name')}`);
    },
    dragStopped(item) {
      console.log(`Item stopped dragging: ${item.get('name')}`);
    }
  }
});

  {{#sortable-item
    onDragStart=(action "dragStarted")
    onDragStop=(action "dragStopped")
    tagName="li"
    model=item
    group=group
    handle=".handle"
  }}
    {{item.name}}
    <span class="handle">&varr;</span>
  {{/sortable-item}}

Data down, actions up

No data is mutated by sortable-group or sortable-item. In the spirit of “data down, actions up”, a fresh array containing the models from each item in their new order is sent via the group’s onChange action.

sortable-group yields itself to the block so that it may be assigned explicitly to each item’s group property.

Each item takes a model property. This should be fairly self-explanatory but it’s important to note that it doesn’t do anything with this object besides keeping a reference for later use in onChange.

Accessibility

sortable-items can receive a tabindex which allows them to be focused. Use this to enable keyboard sorting for accessibility.

{{#each myItems as |item idx| }}
  {{#sortable-item tabindex=0 keyUp=(action 'keyUp' idx) tagName="li" model=item group=group handle=".handle"}}
    {{item.name}}
    <span class="handle">&varr;</span>
  {{/sortable-item}}
{{/each}}

actions: {
  keyUp(index, evt) {
    switch(evt.key) {
      case "ArrowDown":
        // move item at `index` back one
        break;
      case "ArrowUp":
        // move item at `index` forward one
        break;
      default:
        return;
    }
  }
}

Testing

ember-sortable exposes some acceptance test helpers:

drag: Drags elements by an offset specified in pixels.
reorder: Reorders elements to the specified state.

To include them in your application, import then in your start-app.js:

// tests/helpers/start-app.js

import './ember-sortable/test-helpers';

Developing

Setup

$ git clone git@github.com:heroku/ember-sortable
$ cd ember-sortable
$ ember install

Dev Server

$ ember serve

Running Tests

$ npm test

Publishing Demo

$ make demo

MR-H0200/ember-sortable