diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 000000000..ffbb4f1a7 --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,33 @@ +version: 2.0 +jobs: + build: + docker: + - image: circleci/node:10.16-browsers + steps: + - checkout + + - restore_cache: + keys: + - v1-dependencies-{{ checksum "package.json" }} + - v1-dependencies- + + - run: npm install + + - save_cache: + paths: + - node_modules + key: v1-dependencies-{{ checksum "package.json" }} + + - run: npm run build:umd + + - run: + name: Compatibility Test + command: | + if [ -z "$CIRCLE_PR_NUMBER" ]; + then + npm run test:compat + fi + - run: npm run test + + - store_test_results: + path: /tmp/test-results diff --git a/.editorconfig b/.editorconfig index b0d7fd91b..09d275186 100644 --- a/.editorconfig +++ b/.editorconfig @@ -10,3 +10,6 @@ insert_final_newline = true [*.md] trim_trailing_whitespace = false + +[*.yml] +indent_style = space diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md new file mode 100644 index 000000000..53a033cfd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -0,0 +1,73 @@ +--- +name: Bug report +about: Create a report to help us improve +title: "[bug] " +labels: "" +assignees: "" +--- + + + +**Describe the bug** + + + +**To Reproduce** +Steps to reproduce the behavior: + +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** + + + +**Information** + + + +Versions - Look in your `package.json` for this information: +sortablejs = ^x.x.x +@types/sortablejs = ^x.x.x + +**Additional context** +Add any other context about the problem here. + +**Reproduction** +codesandbox: + + diff --git a/.github/ISSUE_TEMPLATE/custom-template.md b/.github/ISSUE_TEMPLATE/custom-template.md new file mode 100644 index 000000000..14e2a2239 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/custom-template.md @@ -0,0 +1,48 @@ +--- +name: Custom issue template +about: Not a feature request or a bug report. Usually questions, queries or concerns +title: "" +labels: "" +assignees: "" +--- + +**Custom** + + + +**Reproduction** +codesandbox: + + diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 000000000..a0bbb57d0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,41 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: "[feature] " +labels: "" +assignees: "" +--- + + + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.gitignore b/.gitignore index 115f20ffc..bb83eae77 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,5 @@ node_modules mock.png .*.sw* .build* +jquery.fn.* +.idea/ diff --git a/.jshintrc b/.jshintrc index e870dcc84..ffbcc18f9 100644 --- a/.jshintrc +++ b/.jshintrc @@ -1,10 +1,11 @@ { - "strict": true, - "newcap": false, // "Tolerate uncapitalized constructors" + "strict": false, + "newcap": false, "node": true, - "expr": true, // - true && call() "Expected an assignment or function call and instead saw an expression." - "supernew": true, // - "Missing '()' invoking a constructor." + "expr": true, + "supernew": true, "laxbreak": true, + "esversion": 9, "white": true, "globals": { "define": true, diff --git a/.testcaferc.json b/.testcaferc.json new file mode 100644 index 000000000..58a061e62 --- /dev/null +++ b/.testcaferc.json @@ -0,0 +1,7 @@ +{ + "speed": 0.4, + "reporter": { + "name": "xunit", + "output": "/tmp/test-results/res.xml" + } +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..25c149014 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,26 @@ +# Contribution Guidelines + +### Issue + + 1. Try [master](https://github.com/SortableJS/Sortable/tree/master/)-branch, perhaps the problem has been solved; + 2. [Use the search](https://github.com/SortableJS/Sortable/search?type=Issues&q=problem), maybe already have an answer; + 3. If not found, create example on [jsbin.com (draft)](https://jsbin.com/kamiwez/edit?html,js,output) and describe the problem. + +--- + +### Pull Request + + 1. Only request to merge with the [master](https://github.com/SortableJS/Sortable/tree/master/)-branch. + 2. Only modify source files, **do not commit the resulting build** + +### Setup + + 1. Fork the repo on [github](https://github.com) + 2. Clone locally + 3. Run `npm i` in the local repo + +### Building + + - For development, build the `./Sortable.js` file using the command `npm run build:umd:watch` + - To build everything and minify it, run `npm run build` + - Do not commit the resulting builds in any pull request – they will be generated at release diff --git a/Gruntfile.js b/Gruntfile.js deleted file mode 100644 index 64cfc702f..000000000 --- a/Gruntfile.js +++ /dev/null @@ -1,54 +0,0 @@ -module.exports = function (grunt) { - 'use strict'; - - grunt.initConfig({ - pkg: grunt.file.readJSON('package.json'), - - version: { - src: ['<%= pkg.exportName %>.js', '*.json'] - }, - - jshint: { - all: ['*.js', '!*.min.js'], - - options: { - jshintrc: true - } - }, - - uglify: { - options: { - banner: '/*! <%= pkg.exportName %> <%= pkg.version %> - <%= pkg.license %> | <%= pkg.repository.url %> */\n' - }, - dist: { - files: { - '<%= pkg.exportName %>.min.js': ['<%= pkg.exportName %>.js'] - } - } - }, - - exec: { - 'meteor-test': { - command: 'meteor/runtests.sh' - }, - 'meteor-publish': { - command: 'meteor/publish.sh' - } - } - - }); - - - grunt.loadNpmTasks('grunt-version'); - grunt.loadNpmTasks('grunt-contrib-jshint'); - grunt.loadNpmTasks('grunt-contrib-uglify'); - grunt.loadNpmTasks('grunt-exec'); - - // Meteor tasks - grunt.registerTask('meteor-test', 'exec:meteor-test'); - grunt.registerTask('meteor-publish', 'exec:meteor-publish'); - grunt.registerTask('meteor', ['meteor-test', 'meteor-publish']); - - grunt.registerTask('tests', ['jshint']); - grunt.registerTask('default', ['tests', 'version', 'uglify']); -}; diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..91bffc2c9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2019 All contributors to Sortable + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index b67881a47..c95740711 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,95 @@ -# Sortable -Sortable is a minimalist JavaScript library for reorderable drag-and-drop lists. +# Sortable   [![Financial Contributors on Open Collective](https://opencollective.com/Sortable/all/badge.svg?label=financial+contributors)](https://opencollective.com/Sortable) [![CircleCI](https://circleci.com/gh/SortableJS/Sortable.svg?style=svg)](https://circleci.com/gh/SortableJS/Sortable) [![DeepScan grade](https://deepscan.io/api/teams/3901/projects/5666/branches/43977/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=3901&pid=5666&bid=43977) [![](https://data.jsdelivr.com/v1/package/npm/sortablejs/badge)](https://www.jsdelivr.com/package/npm/sortablejs) [![npm](https://img.shields.io/npm/v/sortablejs.svg)](https://www.npmjs.com/package/sortablejs) -Demo: http://rubaxa.github.io/Sortable/ +Sortable is a JavaScript library for reorderable drag-and-drop lists. +Demo: http://sortablejs.github.io/Sortable/ + +[](https://saucelabs.com/) ## Features - * Supports touch devices and [modern](http://caniuse.com/#search=drag) browsers + * Supports touch devices and [modern](http://caniuse.com/#search=drag) browsers (including IE9) * Can drag from one list to another or within the same list * CSS animation when moving items * Supports drag handles *and selectable text* (better than voidberg's html5sortable) * Smart auto-scrolling + * Advanced swap detection + * Smooth animations + * [Multi-drag](https://github.com/SortableJS/Sortable/tree/master/plugins/MultiDrag) support + * Support for CSS transforms * Built using native HTML5 drag and drop API - * Supports [Meteor](meteor/README.md) and [AngularJS](#ng) + * Supports + * [Meteor](https://github.com/SortableJS/meteor-sortablejs) + * Angular + * [2.0+](https://github.com/SortableJS/angular-sortablejs) + * [1.*](https://github.com/SortableJS/angular-legacy-sortablejs) + * React + * [ES2015+](https://github.com/SortableJS/react-sortablejs) + * [Mixin](https://github.com/SortableJS/react-mixin-sortablejs) + * [Knockout](https://github.com/SortableJS/knockout-sortablejs) + * [Polymer](https://github.com/SortableJS/polymer-sortablejs) + * [Vue](https://github.com/SortableJS/Vue.Draggable) + * [Ember](https://github.com/SortableJS/ember-sortablejs) * Supports any CSS library, e.g. [Bootstrap](#bs) * Simple API - * No jQuery + * Support for [plugins](#plugins) + * [CDN](#cdn) + * No jQuery required (but there is [support](https://github.com/SortableJS/jquery-sortablejs)) + * Typescript definitions at `@types/sortablejs` + + +
+ + +### Articles + + * [Dragging Multiple Items in Sortable](https://github.com/SortableJS/Sortable/wiki/Dragging-Multiple-Items-in-Sortable) (April 26, 2019) + * [Swap Thresholds and Direction](https://github.com/SortableJS/Sortable/wiki/Swap-Thresholds-and-Direction) (December 2, 2018) + * [Sortable v1.0 — New capabilities](https://github.com/SortableJS/Sortable/wiki/Sortable-v1.0-—-New-capabilities/) (December 22, 2014) + * [Sorting with the help of HTML5 Drag'n'Drop API](https://github.com/SortableJS/Sortable/wiki/Sorting-with-the-help-of-HTML5-Drag'n'Drop-API/) (December 23, 2013) + +
+ +### Getting Started + +Install with NPM: +```bash +npm install sortablejs --save +``` + +Install with Bower: +```bash +bower install --save sortablejs +``` + +Import into your project: +```js +// Default SortableJS +import Sortable from 'sortablejs'; + +// Core SortableJS (without default plugins) +import Sortable from 'sortablejs/modular/sortable.core.esm.js'; + +// Complete SortableJS (with all plugins) +import Sortable from 'sortablejs/modular/sortable.complete.esm.js'; +``` + +Cherrypick plugins: +```js +// Cherrypick extra plugins +import Sortable, { MultiDrag, Swap } from 'sortablejs'; + +Sortable.mount(new MultiDrag(), new Swap()); + + +// Cherrypick default plugins +import Sortable, { AutoScroll } from 'sortablejs/modular/sortable.core.esm.js'; + +Sortable.mount(new AutoScroll()); +``` + + +--- ### Usage @@ -32,7 +106,7 @@ var el = document.getElementById('items'); var sortable = Sortable.create(el); ``` -You can use any element for the list and its elements, not just `ul`/`li`. Here is an [example with `div`s](http://jsbin.com/luxero/2/edit?html,js,output). +You can use any element for the list and its elements, not just `ul`/`li`. Here is an [example with `div`s](https://jsbin.com/visimub/edit?html,js,output). --- @@ -41,61 +115,125 @@ You can use any element for the list and its elements, not just `ul`/`li`. Here ### Options ```js var sortable = new Sortable(el, { - group: "name", // or { name: "...", pull: [true, false, clone], put: [true, false, array] } + group: "name", // or { name: "...", pull: [true, false, 'clone', array], put: [true, false, array] } sort: true, // sorting inside list + delay: 0, // time in milliseconds to define when the sorting should start + delayOnTouchOnly: false, // only delay if user is using touch + touchStartThreshold: 0, // px, how many pixels the point should move before cancelling a delayed drag event disabled: false, // Disables the sortable if set to true. store: null, // @see Store animation: 150, // ms, animation speed moving items when sorting, `0` — without animation + easing: "cubic-bezier(1, 0, 0, 1)", // Easing for animation. Defaults to null. See https://easings.net/ for examples. handle: ".my-handle", // Drag handle selector within list items filter: ".ignore-elements", // Selectors that do not lead to dragging (String or Function) - draggable: ".item", // Specifies which items inside the element should be sortable + preventOnFilter: true, // Call `event.preventDefault()` when triggered `filter` + draggable: ".item", // Specifies which items inside the element should be draggable + + dataIdAttr: 'data-id', // HTML attribute that is used by the `toArray()` method + ghostClass: "sortable-ghost", // Class name for the drop placeholder - - scroll: true, // or HTMLElement - scrollSensitivity: 30, // px, how near the mouse must be to an edge to start scrolling. - scrollSpeed: 10, // px - - setData: function (dataTransfer, dragEl) { - dataTransfer.setData('Text', dragEl.textContent); + chosenClass: "sortable-chosen", // Class name for the chosen item + dragClass: "sortable-drag", // Class name for the dragging item + + swapThreshold: 1, // Threshold of the swap zone + invertSwap: false, // Will always use inverted swap zone if set to true + invertedSwapThreshold: 1, // Threshold of the inverted swap zone (will be set to swapThreshold value by default) + direction: 'horizontal', // Direction of Sortable (will be detected automatically if not given) + + forceFallback: false, // ignore the HTML5 DnD behaviour and force the fallback to kick in + + fallbackClass: "sortable-fallback", // Class name for the cloned DOM Element when using forceFallback + fallbackOnBody: false, // Appends the cloned DOM Element into the Document's Body + fallbackTolerance: 0, // Specify in pixels how far the mouse should move before it's considered as a drag. + + dragoverBubble: false, + removeCloneOnHide: true, // Remove the clone element when it is not showing, rather than just hiding it + emptyInsertThreshold: 5, // px, distance mouse must be from empty sortable to insert drag element into it + + + setData: function (/** DataTransfer */dataTransfer, /** HTMLElement*/dragEl) { + dataTransfer.setData('Text', dragEl.textContent); // `dataTransfer` object of HTML5 DragEvent + }, + + // Element is chosen + onChoose: function (/**Event*/evt) { + evt.oldIndex; // element index within parent }, - // dragging started + // Element is unchosen + onUnchoose: function(/**Event*/evt) { + // same properties as onEnd + }, + + // Element dragging started onStart: function (/**Event*/evt) { evt.oldIndex; // element index within parent }, - - // dragging ended + + // Element dragging ended onEnd: function (/**Event*/evt) { - evt.oldIndex; // element's old index within parent - evt.newIndex; // element's new index within parent + var itemEl = evt.item; // dragged HTMLElement + evt.to; // target list + evt.from; // previous list + evt.oldIndex; // element's old index within old parent + evt.newIndex; // element's new index within new parent + evt.oldDraggableIndex; // element's old index within old parent, only counting draggable elements + evt.newDraggableIndex; // element's new index within new parent, only counting draggable elements + evt.clone // the clone element + evt.pullMode; // when item is in another sortable: `"clone"` if cloning, `true` if moving }, // Element is dropped into the list from another list onAdd: function (/**Event*/evt) { - var itemEl = evt.item; // dragged HTMLElement - evt.from; // previous list - // + indexes from onEnd + // same properties as onEnd }, // Changed sorting within list onUpdate: function (/**Event*/evt) { - var itemEl = evt.item; // dragged HTMLElement - // + indexes from onEnd + // same properties as onEnd }, // Called by any change to the list (add / update / remove) onSort: function (/**Event*/evt) { - // same properties as onUpdate + // same properties as onEnd }, // Element is removed from the list into another list onRemove: function (/**Event*/evt) { - // same properties as onUpdate + // same properties as onEnd }, // Attempt to drag a filtered element onFilter: function (/**Event*/evt) { var itemEl = evt.item; // HTMLElement receiving the `mousedown|tapstart` event. + }, + + // Event when you move an item in the list or between lists + onMove: function (/**Event*/evt, /**Event*/originalEvent) { + // Example: https://jsbin.com/nawahef/edit?js,output + evt.dragged; // dragged HTMLElement + evt.draggedRect; // DOMRect {left, top, right, bottom} + evt.related; // HTMLElement on which have guided + evt.relatedRect; // DOMRect + evt.willInsertAfter; // Boolean that is true if Sortable will insert drag element after target by default + originalEvent.clientY; // mouse position + // return false; — for cancel + // return -1; — insert before target + // return 1; — insert after target + // return true; — keep default insertion point based on the direction + // return void; — keep default insertion point based on the direction + }, + + // Called when creating a clone of element + onClone: function (/**Event*/evt) { + var origEl = evt.item; + var cloneEl = evt.clone; + }, + + // Called when dragging element changes position + onChange: function(/**Event*/evt) { + evt.newIndex // most likely why this event is used is to get the dragging element's current index + // same properties as onEnd } }); ``` @@ -109,17 +247,109 @@ To drag elements from one list into another, both lists must have the same `grou You can also define whether lists can give away, give and keep a copy (`clone`), and receive elements. * name: `String` — group name - * pull: `true|false|'clone'` — ability to move from the list. `clone` — copy the item, rather than move. - * put: `true|false|["foo", "bar"]` — whether elements can be added from other lists, or an array of group names from which elements can be taken. Demo: http://jsbin.com/naduvo/2/edit?html,js,output + * pull: `true|false|["foo", "bar"]|'clone'|function` — ability to move from the list. `clone` — copy the item, rather than move. Or an array of group names which the elements may be put in. Defaults to `true`. + * put: `true|false|["baz", "qux"]|function` — whether elements can be added from other lists, or an array of group names from which elements can be added. + * revertClone: `boolean` — revert cloned element to initial position after moving to a another list. + + +Demo: + - https://jsbin.com/hijetos/edit?js,output + - https://jsbin.com/nacoyah/edit?js,output — use of complex logic in the `pull` and` put` + - https://jsbin.com/bifuyab/edit?js,output — use `revertClone: true` --- #### `sort` option -Sorting inside list +Allow sorting inside list. + +Demo: https://jsbin.com/jayedig/edit?js,output + + +--- + + +#### `delay` option +Time in milliseconds to define when the sorting should start. +Unfortunately, due to browser restrictions, delaying is not possible on IE or Edge with native drag & drop. + +Demo: https://jsbin.com/zosiwah/edit?js,output + + +--- + + +#### `delayOnTouchOnly` option +Whether or not the delay should be applied only if the user is using touch (eg. on a mobile device). No delay will be applied in any other case. Defaults to `false`. + + +--- + + +#### `swapThreshold` option +Percentage of the target that the swap zone will take up, as a float between `0` and `1`. + +[Read more](https://github.com/SortableJS/Sortable/wiki/Swap-Thresholds-and-Direction#swap-threshold) + +Demo: http://sortablejs.github.io/Sortable#thresholds + -Demo: http://jsbin.com/xizeh/2/edit?html,js,output +--- + + +#### `invertSwap` option +Set to `true` to set the swap zone to the sides of the target, for the effect of sorting "in between" items. + +[Read more](https://github.com/SortableJS/Sortable/wiki/Swap-Thresholds-and-Direction#forcing-inverted-swap-zone) + +Demo: http://sortablejs.github.io/Sortable#thresholds + + +--- + + +#### `invertedSwapThreshold` option +Percentage of the target that the inverted swap zone will take up, as a float between `0` and `1`. If not given, will default to `swapThreshold`. + +[Read more](https://github.com/SortableJS/Sortable/wiki/Swap-Thresholds-and-Direction#dealing-with-swap-glitching) + + +--- + + +#### `direction` option +Direction that the Sortable should sort in. Can be set to `'vertical'`, `'horizontal'`, or a function, which will be called whenever a target is dragged over. Must return `'vertical'` or `'horizontal'`. + +[Read more](https://github.com/SortableJS/Sortable/wiki/Swap-Thresholds-and-Direction#direction) + + +Example of direction detection for vertical list that includes full column and half column elements: + +```js +Sortable.create(el, { + direction: function(evt, target, dragEl) { + if (target !== null && target.className.includes('half-column') && dragEl.className.includes('half-column')) { + return 'horizontal'; + } + return 'vertical'; + } +}); +``` + + +--- + + +#### `touchStartThreshold` option +This option is similar to `fallbackTolerance` option. + +When the `delay` option is set, some phones with very sensitive touch displays like the Samsung Galaxy S8 will fire +unwanted touchmove events even when your finger is not moving, resulting in the sort not triggering. + +This option sets the minimum pointer movement that must occur before the delayed sorting is cancelled. + +Values between 3 to 5 are good. --- @@ -128,7 +358,7 @@ Demo: http://jsbin.com/xizeh/2/edit?html,js,output #### `disabled` options Disables the sortable if set to `true`. -Demo: http://jsbin.com/xiloqu/1/edit?html,js,output +Demo: https://jsbin.com/sewokud/edit?js,output ```js var sortable = Sortable.create(list); @@ -149,7 +379,7 @@ To make list items draggable, Sortable disables text selection by the user. That's not always desirable. To allow text selection, define a drag handler, which is an area of every list element that allows it to be dragged around. -Demo: http://jsbin.com/newize/1/edit?html,js,output +Demo: https://jsbin.com/numakuh/edit?html,js,output ```js Sortable.create(el, { @@ -182,7 +412,7 @@ Sortable.create(el, { Sortable.create(list, { filter: ".js-remove, .js-edit", onFilter: function (evt) { - var item = el.item, + var item = evt.item, ctrl = evt.target; if (Sortable.utils.is(ctrl, ".js-remove")) { // Click on remove button @@ -200,9 +430,9 @@ Sortable.create(list, { #### `ghostClass` option -Class name for the drop placeholder. +Class name for the drop placeholder (default `sortable-ghost`). -Demo: http://jsbin.com/boqugumiqi/1/edit?css,js,output +Demo: https://jsbin.com/henuyiw/edit?css,js,output ```css .ghost { @@ -220,69 +450,119 @@ Sortable.create(list, { --- -#### `scroll` option -If set to `true`, the page (or sortable-area) scrolls when coming to an edge. +#### `chosenClass` option +Class name for the chosen item (default `sortable-chosen`). -Demo: - - `window`: http://jsbin.com/boqugumiqi/1/edit?html,js,output - - `overflow: hidden`: http://jsbin.com/kohamakiwi/1/edit?html,js,output +Demo: https://jsbin.com/hoqufox/edit?css,js,output + +```css +.chosen { + color: #fff; + background-color: #c00; +} +``` + +```js +Sortable.create(list, { + delay: 500, + chosenClass: "chosen" +}); +``` --- -#### `scrollSensitivity` option -Defines how near the mouse must be to an edge to start scrolling. +#### `forceFallback` option +If set to `true`, the Fallback for non HTML5 Browser will be used, even if we are using an HTML5 Browser. +This gives us the possibility to test the behaviour for older Browsers even in newer Browser, or make the Drag 'n Drop feel more consistent between Desktop , Mobile and old Browsers. + +On top of that, the Fallback always generates a copy of that DOM Element and appends the class `fallbackClass` defined in the options. This behaviour controls the look of this 'dragged' Element. + +Demo: https://jsbin.com/sibiput/edit?html,css,js,output --- -#### `scrollSpeed` option -The speed at which the window should scroll once the mouse pointer gets within the `scrollSensitivity` distance. +#### `fallbackTolerance` option +Emulates the native drag threshold. Specify in pixels how far the mouse should move before it's considered as a drag. +Useful if the items are also clickable like in a list of links. + +When the user clicks inside a sortable element, it's not uncommon for your hand to move a little between the time you press and the time you release. +Dragging only starts if you move the pointer past a certain tolerance, so that you don't accidentally start dragging every time you click. + +3 to 5 are probably good values. --- - -### Support AngularJS -Include [ng-sortable.js](ng-sortable.js) +#### `dragoverBubble` option +If set to `true`, the dragover event will bubble to parent sortables. Works on both fallback and native dragover event. +By default, it is false, but Sortable will only stop bubbling the event once the element has been inserted into a parent Sortable, or *can* be inserted into a parent Sortable, but isn't at that specific time (due to animation, etc). -Demo: http://jsbin.com/naduvo/1/edit?html,js,output +Since 1.8.0, you will probably want to leave this option as false. Before 1.8.0, it may need to be `true` for nested sortables to work. -```html -
-
    -
  • {{item}}
    • -
- -
    -
  • {{item}}
    • -
- -
    -
  • {{item}}
    • -
-
-``` +--- -```js -angular.module('myApp', ['ng-sortable']) - .controller('demo', ['$scope', function ($scope) { - $scope.items = ['item 1', 'item 2']; - $scope.foo = ['foo 1', '..']; - $scope.bar = ['bar 1', '..']; - $scope.barConfig = { group: 'foobar', animation: 150 }; - }]); + +#### `removeCloneOnHide` option +If set to `false`, the clone is hidden by having it's CSS `display` property set to `none`. +By default, this option is `true`, meaning Sortable will remove the cloned element from the DOM when it is supposed to be hidden. + + +--- + + +#### `emptyInsertThreshold` option +The distance (in pixels) the mouse must be from an empty sortable while dragging for the drag element to be inserted into that sortable. Defaults to `5`. Set to `0` to disable this feature. + +Demo: https://jsbin.com/becavoj/edit?js,output + +An alternative to this option would be to set a padding on your list when it is empty. + +For example: +```css +ul:empty { + padding-bottom: 20px; +} ``` +Warning: For `:empty` to work, it must have no node inside (even text one). + +Demo: +https://jsbin.com/yunakeg/edit?html,css,js,output + +--- +### Event object ([demo](https://jsbin.com/fogujiv/edit?js,output)) + + - to:`HTMLElement` — list, in which moved element + - from:`HTMLElement` — previous list + - item:`HTMLElement` — dragged element + - clone:`HTMLElement` + - oldIndex:`Number|undefined` — old index within parent + - newIndex:`Number|undefined` — new index within parent + - oldDraggableIndex: `Number|undefined` — old index within parent, only counting draggable elements + - newDraggableIndex: `Number|undefined` — new index within parent, only counting draggable elements + - pullMode:`String|Boolean|undefined` — Pull mode if dragging into another sortable (`"clone"`, `true`, or `false`), otherwise undefined + + +#### `move` event object + - to:`HTMLElement` + - from:`HTMLElement` + - dragged:`HTMLElement` + - draggedRect:`DOMRect` + - related:`HTMLElement` — element on which have guided + - relatedRect:`DOMRect` + - willInsertAfter:`Boolean` — `true` if will element be inserted after target (or `false` if before) + --- -### Method +### Methods ##### option(name:`String`[, value:`*`]):`*` @@ -290,20 +570,20 @@ Get or set the option. -##### closest(el:`String`[, selector:`HTMLElement`]):`HTMLElement|null` +##### closest(el:`HTMLElement`[, selector:`String`]):`HTMLElement|null` For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree. ##### toArray():`String[]` -Serializes the sortable's item `data-id`'s into an array of string. +Serializes the sortable's item `data-id`'s (`dataIdAttr` option) into an array of string. -##### sort(order:`String[]`) +##### sort(order:`String[]`, useAnimation:`Boolean`) Sorts the elements according to the array. ```js var order = sortable.toArray(); -sortable.sort(order.reverse()); // apply +sortable.sort(order.reverse(), true); // apply ``` @@ -340,7 +620,7 @@ Sortable.create(el, { * @returns {Array} */ get: function (sortable) { - var order = localStorage.getItem(sortable.options.group); + var order = localStorage.getItem(sortable.options.group.name); return order ? order.split('|') : []; }, @@ -350,7 +630,7 @@ Sortable.create(el, { */ set: function (sortable) { var order = sortable.toArray(); - localStorage.setItem(sortable.options.group, order.join('|')); + localStorage.setItem(sortable.options.group.name, order.join('|')); } } }) @@ -362,7 +642,7 @@ Sortable.create(el, { ### Bootstrap -Demo: http://jsbin.com/luxero/2/edit?html,js,output +Demo: https://jsbin.com/visimub/edit?html,js,output ```html @@ -370,12 +650,12 @@ Demo: http://jsbin.com/luxero/2/edit?html,js,output - +