source: classroom-assembly/trunk/fuentes/classroom-assembly/src/node_modules/sortablejs/README.md @ 6056

Last change on this file since 6056 was 6056, checked in by joamuran, 2 years ago

completed agenda

File size: 16.8 KB
Line 
1# Sortable
2Sortable is a <s>minimalist</s> JavaScript library for reorderable drag-and-drop lists.
3
4Demo: http://rubaxa.github.io/Sortable/
5
6
7## Features
8
9 * Supports touch devices and [modern](http://caniuse.com/#search=drag) browsers (including IE9)
10 * Can drag from one list to another or within the same list
11 * CSS animation when moving items
12 * Supports drag handles *and selectable text* (better than voidberg's html5sortable)
13 * Smart auto-scrolling
14 * Built using native HTML5 drag and drop API
15 * Supports
16  * [Meteor](https://github.com/SortableJS/meteor-sortablejs)
17  * AngularJS
18    * [2.0+](https://github.com/SortableJS/angular-sortablejs)
19    * [1.*](https://github.com/SortableJS/angular-legacy-sortablejs)
20  * React
21    * [ES2015+](https://github.com/SortableJS/react-sortablejs)
22    * [Mixin](https://github.com/SortableJS/react-mixin-sortablejs)
23  * [Knockout](https://github.com/SortableJS/knockout-sortablejs)
24  * [Polymer](https://github.com/SortableJS/polymer-sortablejs)
25  * [Vue](https://github.com/SortableJS/Vue.Draggable)
26 * Supports any CSS library, e.g. [Bootstrap](#bs)
27 * Simple API
28 * [CDN](#cdn)
29 * No jQuery (but there is [support](#jq))
30
31
32<br/>
33
34
35### Articles
36
37 * [Sortable v1.0 — New capabilities](https://github.com/RubaXa/Sortable/wiki/Sortable-v1.0-—-New-capabilities/) (December 22, 2014)
38 * [Sorting with the help of HTML5 Drag'n'Drop API](https://github.com/RubaXa/Sortable/wiki/Sorting-with-the-help-of-HTML5-Drag'n'Drop-API/) (December 23, 2013)
39
40
41<br/>
42
43### Install
44
45Via npm
46
47```bash
48$ npm install sortablejs --save
49```
50
51Via bower:
52
53```bash
54$ bower install --save sortablejs
55```
56
57<br/>
58
59### Usage
60```html
61<ul id="items">
62        <li>item 1</li>
63        <li>item 2</li>
64        <li>item 3</li>
65</ul>
66```
67
68```js
69var el = document.getElementById('items');
70var sortable = Sortable.create(el);
71```
72
73You can use any element for the list and its elements, not just `ul`/`li`. Here is an [example with `div`s](http://jsbin.com/qumuwe/edit?html,js,output).
74
75
76---
77
78
79### Options
80```js
81var sortable = new Sortable(el, {
82        group: "name",  // or { name: "...", pull: [true, false, clone], put: [true, false, array] }
83        sort: true,  // sorting inside list
84        delay: 0, // time in milliseconds to define when the sorting should start
85        disabled: false, // Disables the sortable if set to true.
86        store: null,  // @see Store
87        animation: 150,  // ms, animation speed moving items when sorting, `0` — without animation
88        handle: ".my-handle",  // Drag handle selector within list items
89        filter: ".ignore-elements",  // Selectors that do not lead to dragging (String or Function)
90        preventOnFilter: true, // Call `event.preventDefault()` when triggered `filter`
91        draggable: ".item",  // Specifies which items inside the element should be draggable
92        ghostClass: "sortable-ghost",  // Class name for the drop placeholder
93        chosenClass: "sortable-chosen",  // Class name for the chosen item
94        dragClass: "sortable-drag",  // Class name for the dragging item
95        dataIdAttr: 'data-id',
96
97        forceFallback: false,  // ignore the HTML5 DnD behaviour and force the fallback to kick in
98
99        fallbackClass: "sortable-fallback",  // Class name for the cloned DOM Element when using forceFallback
100        fallbackOnBody: false,  // Appends the cloned DOM Element into the Document's Body
101        fallbackTolerance: 0, // Specify in pixels how far the mouse should move before it's considered as a drag.       
102       
103        scroll: true, // or HTMLElement
104        scrollFn: function(offsetX, offsetY, originalEvent) { ... }, // if you have custom scrollbar scrollFn may be used for autoscrolling
105        scrollSensitivity: 30, // px, how near the mouse must be to an edge to start scrolling.
106        scrollSpeed: 10, // px
107
108        setData: function (/** DataTransfer */dataTransfer, /** HTMLElement*/dragEl) {
109                dataTransfer.setData('Text', dragEl.textContent); // `dataTransfer` object of HTML5 DragEvent
110        },
111
112        // Element is chosen
113        onChoose: function (/**Event*/evt) {
114                evt.oldIndex;  // element index within parent
115        },
116
117        // Element dragging started
118        onStart: function (/**Event*/evt) {
119                evt.oldIndex;  // element index within parent
120        },
121
122        // Element dragging ended
123        onEnd: function (/**Event*/evt) {
124                evt.oldIndex;  // element's old index within parent
125                evt.newIndex;  // element's new index within parent
126        },
127
128        // Element is dropped into the list from another list
129        onAdd: function (/**Event*/evt) {
130                var itemEl = evt.item;  // dragged HTMLElement
131                evt.from;  // previous list
132                // + indexes from onEnd
133        },
134
135        // Changed sorting within list
136        onUpdate: function (/**Event*/evt) {
137                var itemEl = evt.item;  // dragged HTMLElement
138                // + indexes from onEnd
139        },
140
141        // Called by any change to the list (add / update / remove)
142        onSort: function (/**Event*/evt) {
143                // same properties as onUpdate
144        },
145
146        // Element is removed from the list into another list
147        onRemove: function (/**Event*/evt) {
148                // same properties as onUpdate
149        },
150
151        // Attempt to drag a filtered element
152        onFilter: function (/**Event*/evt) {
153                var itemEl = evt.item;  // HTMLElement receiving the `mousedown|tapstart` event.
154        },
155
156        // Event when you move an item in the list or between lists
157        onMove: function (/**Event*/evt, /**Event*/originalEvent) {
158                // Example: http://jsbin.com/tuyafe/1/edit?js,output
159                evt.dragged; // dragged HTMLElement
160                evt.draggedRect; // TextRectangle {left, top, right и bottom}
161                evt.related; // HTMLElement on which have guided
162                evt.relatedRect; // TextRectangle
163                originalEvent.clientY; // mouse position
164                // return false; — for cancel
165        },
166       
167        // Called when creating a clone of element
168        onClone: function (/**Event*/evt) {
169                var origEl = evt.item;
170                var cloneEl = evt.clone;
171        }
172});
173```
174
175
176---
177
178
179#### `group` option
180To drag elements from one list into another, both lists must have the same `group` value.
181You can also define whether lists can give away, give and keep a copy (`clone`), and receive elements.
182
183 * name: `String` — group name
184 * pull: `true|false|'clone'|function` — ability to move from the list. `clone` — copy the item, rather than move.
185 * put: `true|false|["foo", "bar"]|function` — whether elements can be added from other lists, or an array of group names from which elements can be taken.
186 * revertClone: `boolean` — revert cloned element to initial position after moving to a another list.
187
188
189Demo:
190 - http://jsbin.com/naduvo/edit?js,output
191 - http://jsbin.com/rusuvot/edit?js,output — use of complex logic in the `pull` and` put`
192 - http://jsbin.com/magogub/edit?js,output — use `revertClone: true`
193
194
195---
196
197
198#### `sort` option
199Sorting inside list.
200
201Demo: http://jsbin.com/videzob/edit?html,js,output
202
203
204---
205
206
207#### `delay` option
208Time in milliseconds to define when the sorting should start.
209
210Demo: http://jsbin.com/xizeh/edit?html,js,output
211
212
213---
214
215
216#### `disabled` options
217Disables the sortable if set to `true`.
218
219Demo: http://jsbin.com/xiloqu/edit?html,js,output
220
221```js
222var sortable = Sortable.create(list);
223
224document.getElementById("switcher").onclick = function () {
225        var state = sortable.option("disabled"); // get
226
227        sortable.option("disabled", !state); // set
228};
229```
230
231
232---
233
234
235#### `handle` option
236To make list items draggable, Sortable disables text selection by the user.
237That's not always desirable. To allow text selection, define a drag handler,
238which is an area of every list element that allows it to be dragged around.
239
240Demo: http://jsbin.com/newize/edit?html,js,output
241
242```js
243Sortable.create(el, {
244        handle: ".my-handle"
245});
246```
247
248```html
249<ul>
250        <li><span class="my-handle">::</span> list item text one
251        <li><span class="my-handle">::</span> list item text two
252</ul>
253```
254
255```css
256.my-handle {
257        cursor: move;
258        cursor: -webkit-grabbing;
259}
260```
261
262
263---
264
265
266#### `filter` option
267
268
269```js
270Sortable.create(list, {
271        filter: ".js-remove, .js-edit",
272        onFilter: function (evt) {
273                var item = evt.item,
274                        ctrl = evt.target;
275
276                if (Sortable.utils.is(ctrl, ".js-remove")) {  // Click on remove button
277                        item.parentNode.removeChild(item); // remove sortable item
278                }
279                else if (Sortable.utils.is(ctrl, ".js-edit")) {  // Click on edit link
280                        // ...
281                }
282        }
283})
284```
285
286
287---
288
289
290#### `ghostClass` option
291Class name for the drop placeholder (default `sortable-ghost`).
292
293Demo: http://jsbin.com/hunifu/4/edit?css,js,output
294
295```css
296.ghost {
297  opacity: 0.4;
298}
299```
300
301```js
302Sortable.create(list, {
303  ghostClass: "ghost"
304});
305```
306
307
308---
309
310
311#### `chosenClass` option
312Class name for the chosen item  (default `sortable-chosen`).
313
314Demo: http://jsbin.com/hunifu/3/edit?html,css,js,output
315
316```css
317.chosen {
318  color: #fff;
319  background-color: #c00;
320}
321```
322
323```js
324Sortable.create(list, {
325  delay: 500,
326  chosenClass: "chosen"
327});
328```
329
330
331---
332
333
334#### `forceFallback` option
335If set to `true`, the Fallback for non HTML5 Browser will be used, even if we are using an HTML5 Browser.
336This 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.
337
338On 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.
339
340Demo: http://jsbin.com/yacuqib/edit?html,css,js,output
341
342
343---
344
345
346#### `fallbackTolerance` option
347Emulates the native drag threshold. Specify in pixels how far the mouse should move before it's considered as a drag.
348Useful if the items are also clickable like in a list of links.
349
350When 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. 
351Dragging only starts if you move the pointer past a certain tolerance, so that you don't accidentally start dragging every time you click.
352
3533 to 5 are probably good values.
354
355
356---
357
358
359#### `scroll` option
360If set to `true`, the page (or sortable-area) scrolls when coming to an edge.
361
362Demo:
363 - `window`: http://jsbin.com/tutuzeh/edit?html,js,output
364 - `overflow: hidden`: http://jsbin.com/kolisu/edit?html,js,output
365
366
367---
368
369
370#### `scrollFn` option
371Defines function that will be used for autoscrolling. el.scrollTop/el.scrollLeft is used by default.
372Useful when you have custom scrollbar with dedicated scroll function.
373
374
375---
376
377
378#### `scrollSensitivity` option
379Defines how near the mouse must be to an edge to start scrolling.
380
381
382---
383
384
385#### `scrollSpeed` option
386The speed at which the window should scroll once the mouse pointer gets within the `scrollSensitivity` distance.
387
388
389---
390
391
392### Event object ([demo](http://jsbin.com/xedusu/edit?js,output))
393
394 - to:`HTMLElement` — list, in which moved element.
395 - from:`HTMLElement` — previous list
396 - item:`HTMLElement` — dragged element
397 - clone:`HTMLElement`
398 - oldIndex:`Number|undefined` — old index within parent
399 - newIndex:`Number|undefined` — new index within parent
400
401
402#### `move` event object
403 - to:`HTMLElement`
404 - from:`HTMLElement`
405 - dragged:`HTMLElement`
406 - draggedRect:` TextRectangle`
407 - related:`HTMLElement` — element on which have guided
408 - relatedRect:` TextRectangle`
409
410
411---
412
413
414### Method
415
416
417##### option(name:`String`[, value:`*`]):`*`
418Get or set the option.
419
420
421
422##### closest(el:`String`[, selector:`HTMLElement`]):`HTMLElement|null`
423For 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.
424
425
426##### toArray():`String[]`
427Serializes the sortable's item `data-id`'s (`dataIdAttr` option) into an array of string.
428
429
430##### sort(order:`String[]`)
431Sorts the elements according to the array.
432
433```js
434var order = sortable.toArray();
435sortable.sort(order.reverse()); // apply
436```
437
438
439##### save()
440Save the current sorting (see [store](#store))
441
442
443##### destroy()
444Removes the sortable functionality completely.
445
446
447---
448
449
450<a name="store"></a>
451### Store
452Saving and restoring of the sort.
453
454```html
455<ul>
456        <li data-id="1">order</li>
457        <li data-id="2">save</li>
458        <li data-id="3">restore</li>
459</ul>
460```
461
462```js
463Sortable.create(el, {
464        group: "localStorage-example",
465        store: {
466                /**
467                 * Get the order of elements. Called once during initialization.
468                 * @param   {Sortable}  sortable
469                 * @returns {Array}
470                 */
471                get: function (sortable) {
472                        var order = localStorage.getItem(sortable.options.group.name);
473                        return order ? order.split('|') : [];
474                },
475
476                /**
477                 * Save the order of elements. Called onEnd (when the item is dropped).
478                 * @param {Sortable}  sortable
479                 */
480                set: function (sortable) {
481                        var order = sortable.toArray();
482                        localStorage.setItem(sortable.options.group.name, order.join('|'));
483                }
484        }
485})
486```
487
488
489---
490
491
492<a name="bs"></a>
493### Bootstrap
494Demo: http://jsbin.com/qumuwe/edit?html,js,output
495
496```html
497<!-- Latest compiled and minified CSS -->
498<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/css/bootstrap.min.css"/>
499
500
501<!-- Latest Sortable -->
502<script src="http://rubaxa.github.io/Sortable/Sortable.js"></script>
503
504
505<!-- Simple List -->
506<ul id="simpleList" class="list-group">
507        <li class="list-group-item">This is <a href="http://rubaxa.github.io/Sortable/">Sortable</a></li>
508        <li class="list-group-item">It works with Bootstrap...</li>
509        <li class="list-group-item">...out of the box.</li>
510        <li class="list-group-item">It has support for touch devices.</li>
511        <li class="list-group-item">Just drag some elements around.</li>
512</ul>
513
514<script>
515    // Simple list
516    Sortable.create(simpleList, { /* options */ });
517</script>
518```
519
520
521---
522
523
524### Static methods & properties
525
526
527
528##### Sortable.create(el:`HTMLElement`[, options:`Object`]):`Sortable`
529Create new instance.
530
531
532---
533
534
535##### Sortable.active:`Sortable`
536Link to the active instance.
537
538
539---
540
541
542##### Sortable.utils
543* on(el`:HTMLElement`, event`:String`, fn`:Function`) — attach an event handler function
544* off(el`:HTMLElement`, event`:String`, fn`:Function`) — remove an event handler
545* css(el`:HTMLElement`)`:Object` — get the values of all the CSS properties
546* css(el`:HTMLElement`, prop`:String`)`:Mixed` — get the value of style properties
547* css(el`:HTMLElement`, prop`:String`, value`:String`) — set one CSS properties
548* css(el`:HTMLElement`, props`:Object`) — set more CSS properties
549* find(ctx`:HTMLElement`, tagName`:String`[, iterator`:Function`])`:Array` — get elements by tag name
550* bind(ctx`:Mixed`, fn`:Function`)`:Function` — Takes a function and returns a new one that will always have a particular context
551* is(el`:HTMLElement`, selector`:String`)`:Boolean` — check the current matched set of elements against a selector
552* closest(el`:HTMLElement`, selector`:String`[, ctx`:HTMLElement`])`: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
553* clone(el`:HTMLElement`)`:HTMLElement` — create a deep copy of the set of matched elements
554* toggleClass(el`:HTMLElement`, name`:String`, state`:Boolean`) — add or remove one classes from each element
555
556
557---
558
559
560<a name="cdn"></a>
561### CDN
562
563```html
564<!-- CDNJS :: Sortable (https://cdnjs.com/) -->
565<script src="//cdnjs.cloudflare.com/ajax/libs/Sortable/1.6.1/Sortable.min.js"></script>
566
567
568<!-- jsDelivr :: Sortable (http://www.jsdelivr.com/) -->
569<script src="//cdn.jsdelivr.net/sortable/1.6.1/Sortable.min.js"></script>
570
571
572<!-- jsDelivr :: Sortable :: Latest (http://www.jsdelivr.com/) -->
573<script src="//cdn.jsdelivr.net/sortable/latest/Sortable.min.js"></script>
574```
575
576
577---
578
579
580<a name="jq"></a>
581### jQuery compatibility
582To assemble plugin for jQuery, perform the following steps:
583
584```bash
585  cd Sortable
586  npm install
587  grunt jquery
588```
589
590Now you can use `jquery.fn.sortable.js`:<br/>
591(or `jquery.fn.sortable.min.js` if you run `grunt jquery:min`)
592
593```js
594  $("#list").sortable({ /* options */ }); // init
595
596  $("#list").sortable("widget"); // get Sortable instance
597
598  $("#list").sortable("destroy"); // destroy Sortable instance
599
600  $("#list").sortable("{method-name}"); // call an instance method
601
602  $("#list").sortable("{method-name}", "foo", "bar"); // call an instance method with parameters
603```
604
605And `grunt jquery:mySortableFunc` → `jquery.fn.mySortableFunc.js`
606
607---
608
609
610### Contributing (Issue/PR)
611
612Please, [read this](CONTRIBUTING.md).
613
614
615---
616
617
618## MIT LICENSE
619Copyright 2013-2017 Lebedev Konstantin <ibnRubaXa@gmail.com>
620http://rubaxa.github.io/Sortable/
621
622Permission is hereby granted, free of charge, to any person obtaining
623a copy of this software and associated documentation files (the
624"Software"), to deal in the Software without restriction, including
625without limitation the rights to use, copy, modify, merge, publish,
626distribute, sublicense, and/or sell copies of the Software, and to
627permit persons to whom the Software is furnished to do so, subject to
628the following conditions:
629
630The above copyright notice and this permission notice shall be
631included in all copies or substantial portions of the Software.
632
633THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
634EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
635MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
636NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
637LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
638OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
639WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
640
Note: See TracBrowser for help on using the repository browser.