ui-sortable

UI.Sortable directive

This directive allows you to sort an array with drag & drop.

Requirements

• JQuery v3.1+ (for jQuery v1.x & v2.x use v0.14.x versions)
• JQueryUI v1.12+
• AngularJS v1.2+

Single minified cdn link ~245kB and example with JQuery v1.x, required parts of JQueryUI v1.10, AngularJS v1.2 & latest angular-ui-sortable.

Notes:

• JQuery must be included before AngularJS.
• JQueryUI dependecies include widget, data, scroll-parent, mouse & sortable. Creating a custom build will greatly reduce the required file size. (CDN links for comparison: full vs minimal)
• Users of AngularJS pre v1.2 can use v0.10.x or v0.12.x branches.
• Early adopters of Angular2 can use the ng2 branch.

Installation

• Install with Bower bower install -S angular-ui-sortable
• Install with npm npm install -S angular-ui-sortable
• Download one of the Releases or the latest Master branch

Usage

Load the script file: sortable.js in your application:

Add the sortable module as a dependency to your application module:

var myAppModule = angular.module('MyApp', ['ui.sortable'])

Apply the directive to your form elements:

  
{{ item }}

Developing Notes:

• ng-model is required, so that the directive knows which model to update.
• ui-sortable element should contain only one ng-repeat, but other non-repeater elements above or below may still exist. Otherwise the index matching of the ng-model's items and the DOM elements generated by the ng-repeat will break.
  In other words: The items of ng-model must match the indexes of the DOM elements generated by the ng-repeat.
• Filters that manipulate the model (like filter, orderBy, limitTo,...) should be applied in the controller instead of the ng-repeat (refer to the provided examples).
  This is the preferred way since it:
  • is performance wise better
  • reduces the chance of code duplication
  • is suggested by the angularJS team
  • it does not break the matching of the generated DOM elements and the ng-model's items
• ui-sortable lists containing many 'types' of items can be implemented by using dynamic template loading with ng-include or a loader directive, to determine how each model item should be rendered. Also take a look at the Tree with dynamic template example.

Options

All the jQueryUI Sortable options can be passed through the directive.
Additionally, the ui argument of the available callbacks gets enriched with some extra properties as specified to the API.md file. Any model changes that happen inside the available callbacks, are applied right after the stop event. We are not wrapping callbacks like start/change/... with $apply, in order to minimize the number of digest loops and avoid possible modifications of the model (eg: by watchers) before the drop takes place.

myAppModule.controller('MyController', function($scope) {
  $scope.items = ["One", "Two", "Three"];

  $scope.sortableOptions = {
    update: function(e, ui) { ... },
    axis: 'x'
  };
});

  
{{ item }}

When using event callbacks (start/update/stop...), avoid manipulating DOM elements (especially the one with the ng-repeat attached). The suggested pattern is to use callbacks for emmiting events and altering the scope (inside the 'Angular world').

ui-floating

ui-floating (default: undefined)
Description: Enables a workaround for smooth horizontal sorting.
Type: Boolean/String/undefined

• undefined: Relies on jquery.ui to detect the list's orientation.
• false: Forces jquery.ui.sortable to detect the list as vertical.
• true: Forces jquery.ui.sortable to detect the list as horizontal.
• "auto": Detects on each drag start if the element is floating or not.

To have a smooth horizontal-list reordering, jquery.ui.sortable needs to detect the orientation of the list. This detection takes place during the initialization of the plugin (and some of the checks include: whether the first item is floating left/right or if 'axis' parameter is 'x', etc). There is also a known issue about initially empty horizontal lists.

To provide a solution/workaround (till jquery.ui.sortable.refresh() also tests the orientation or a more appropriate method is provided), ui-sortable directive provides a ui-floating option as an extra to the jquery.ui.sortable options.

  
{{ item }}

OR

$scope.sortableOptions = {
  'ui-floating': true
};

  
{{ item }}

ui-model-items

ui-model-items (default: > [ng-repeat],> [data-ng-repeat],> [x-ng-repeat])
Description: Defines which elements should be considered as part of your model.
Type: CSS selector/String

This is the model related counterpart option of jQuery's items option.

ui-preserve-size

ui-preserve-size (default: undefined)
Description: Set's the size of the sorting helper to the size of the original element before the sorting.
Type: Boolean/undefined

This is useful for elements that their size is dependent to other page characteristics. A representative example of such cases are ` `s ands.

Attributes For Event Handling

To handle events with html bindings just define any expression to listed event attributes. If you defined an attribute for this events and defined callback function in sortableOptions at the same time, the attribute based callback will be called first.

• ui-sortable-start
• ui-sortable-activate
• ui-sortable-before-stop
• ui-sortable-update
• ui-sortable-remove
• ui-sortable-receive
• ui-sortable-deactivate
• ui-sortable-stop

Expression works on update event.

  
{{ item }}

On update event callBackFunction1 if called before callBackFunction2.

$scope.sortableOptions = {
  'update': callBackFunction2
};

  
{{ item }}

Canceling

Inside the update callback, you can check the item that is dragged and cancel the sorting.

$scope.sortableOptions = {
  update: function(e, ui) {
    if (ui.item.sortable.model == "can't be moved") {
      ui.item.sortable.cancel();
    }
  }
};

Notes:

• update is the appropriate place to cancel a sorting, since it occurs before any model/scope changes but after the DOM position has been updated. So ui.item.scope and the directive's ng-model, are equal to the scope before the drag start.
• To cancel a sorting between connected lists, cancel should be called inside the update callback of the originating list. A simple way to is to use the ui.item.sortable.received property:

update: function(event, ui) {
  if (// ensure we are in the first update() callback
      !ui.item.sortable.received &&
      // check that its an actual moving between the two lists
      ui.item.sortable.source[0] !== ui.item.sortable.droptarget[0] &&
      // check the size limitation
      ui.item.sortable.model == "can't be moved between lists") {
    ui.item.sortable.cancel();
  }
}

jQueryUI Sortable Event order

Single sortable demo

create

/* dragging starts */
helper
start
activate

/* multiple: sort/change/over/out */

beforeStop
update     .transclusionLvl1 > .transclusionLvl2 > .sortable-item'
  };
});

Examples

• Simple Demo
  • Simple Attribute Handlers Demo
  • Simple RequireJS Demo
  • Simple Touch-Enabled Demo using jQuery UI Touch Punch
  • Multiple items sorting (ctrl+click) using ui-sortable-multiselection
• Connected Lists
• Filtering (details)
• Ordering 1 & Ordering 2 (details)
• Cloning (details)
• Horizontal List
• Tree with dynamic template
• Canceling
  • Connected Lists With Max Size
  • Connected Lists Without Duplicates
  • Promised Reverting
• Locked Items
• Draggable Handle
• Drop Zone
• Draggable-Sortable like interaction
• Static HTML Sorting

Integrations

• firebase
• ui.bootstrap.accordion
• Angular Material (thanks yenoh2)
• Asynchronous loading jQuery+jQueryUI with crisbeto/angular-ui-sortable-loader

Reporting Issues

The above pen