Ember-sortable

Sortable UI primitives for Ember.

Check out the demo

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.

Installation

$ ember install ember-sortable

Basic usage:

// app/routes/my-route.js

export default Ember.Route.extend({
  model() {
    return {
      items: [
        { name: 'Uno' },
        { name: 'Dos' },
        { name: 'Tres' },
        { name: 'Cuatro' },
        { name: 'Cinco' }
      ]
    };
  },

  actions: {
    reorderItems(newOrder) {
      this.set('currentModel.items', newOrder);
    }
  }
});

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

{{#sortable-group tagName="ul" onChange="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}}

When model is set on the sortable-group, the onChange action is sent with two arguments: groupModel and itemModels:

// app/routes/my-route.js
  actions: {
    reorderItems(groupModel, itemModels) {
      groupModel.set('items', itemModels);
    }
  }
});

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

{{#sortable-group tagName="ul" model=model onChange="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}}

Notes on Usage

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. While it would be technically possible to automatically discover the parent group, we feel establishing this relationship explicitly is clearer. Feedback welcome.

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.

CSS

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;
}

Developing

Setup

$ git clone [email protected]:jgwhite/ember-sortable
$ cd ember-sortable
$ ember install

Dev Server

$ ember serve

Running Tests

$ npm test

Publishing Demo

$ make demo