|
0
|
1 Nestable2 - new pickup of Nestable!
|
|
|
2 ========
|
|
|
3
|
|
|
4 ### Drag & drop hierarchical list with mouse and touch compatibility (jQuery / Zepto plugin)
|
|
|
5
|
|
|
6 [](https://ramonsmit.github.com/Nestable2/)
|
|
|
7 [](https://travis-ci.org/RamonSmit/Nestable2)
|
|
|
8 [](https://github.com/RamonSmit/Nestable2/blob/master/LICENSE)
|
|
|
9 [](https://www.npmjs.com/package/nestable2)
|
|
|
10
|
|
|
11 Nestable is an experimental example and IS under active development. If it suits your requirements feel free to expand upon it!
|
|
|
12
|
|
|
13 ## Install
|
|
|
14
|
|
|
15 You can install this package either with `npm` or with `bower`.
|
|
|
16
|
|
|
17 ### npm
|
|
|
18
|
|
|
19 ```shell
|
|
|
20 npm install --save nestable2
|
|
|
21 ```
|
|
|
22
|
|
|
23 Then add a `<script>` to your `index.html`:
|
|
|
24
|
|
|
25 ```html
|
|
|
26 <script src="/node_modules/nestable2/jquery.nestable.js"></script>
|
|
|
27 ```
|
|
|
28
|
|
|
29 Or `require('nestable2')` from your code.
|
|
|
30
|
|
|
31 ### bower
|
|
|
32
|
|
|
33 ```shell
|
|
|
34 bower install --save nestable2
|
|
|
35 ```
|
|
|
36
|
|
|
37 ### CDN
|
|
|
38
|
|
|
39 You can also find us on [CDNJS](https://cdnjs.com/libraries/nestable2):
|
|
|
40
|
|
|
41 ```
|
|
|
42 //cdnjs.cloudflare.com/ajax/libs/nestable2/1.6.0/jquery.nestable.min.css
|
|
|
43 //cdnjs.cloudflare.com/ajax/libs/nestable2/1.6.0/jquery.nestable.min.js
|
|
|
44 ```
|
|
|
45
|
|
|
46 ## Usage
|
|
|
47
|
|
|
48 Write your nested HTML lists like so:
|
|
|
49 ```html
|
|
|
50 <div class="dd">
|
|
|
51 <ol class="dd-list">
|
|
|
52 <li class="dd-item" data-id="1">
|
|
|
53 <div class="dd-handle">Item 1</div>
|
|
|
54 </li>
|
|
|
55 <li class="dd-item" data-id="2">
|
|
|
56 <div class="dd-handle">Item 2</div>
|
|
|
57 </li>
|
|
|
58 <li class="dd-item" data-id="3">
|
|
|
59 <div class="dd-handle">Item 3</div>
|
|
|
60 <ol class="dd-list">
|
|
|
61 <li class="dd-item" data-id="4">
|
|
|
62 <div class="dd-handle">Item 4</div>
|
|
|
63 </li>
|
|
|
64 <li class="dd-item" data-id="5" data-foo="bar">
|
|
|
65 <div class="dd-nodrag">Item 5</div>
|
|
|
66 </li>
|
|
|
67 </ol>
|
|
|
68 </li>
|
|
|
69 </ol>
|
|
|
70 </div>
|
|
|
71 ```
|
|
|
72 Then activate with jQuery like so:
|
|
|
73 ```js
|
|
|
74 $('.dd').nestable({ /* config options */ });
|
|
|
75 ```
|
|
|
76
|
|
|
77 ### Events
|
|
|
78 `change`: For using an .on handler in jquery
|
|
|
79
|
|
|
80 The `callback` provided as an option is fired when elements are reordered or nested.
|
|
|
81 ```js
|
|
|
82 $('.dd').nestable({
|
|
|
83 callback: function(l,e){
|
|
|
84 // l is the main container
|
|
|
85 // e is the element that was moved
|
|
|
86 }
|
|
|
87 });
|
|
|
88 ```
|
|
|
89
|
|
|
90 `onDragStart` callback provided as an option is fired when user starts to drag an element. Returning `false` from this callback will disable the dragging.
|
|
|
91 ```js
|
|
|
92 $('.dd').nestable({
|
|
|
93 onDragStart: function(l,e){
|
|
|
94 // l is the main container
|
|
|
95 // e is the element that was moved
|
|
|
96 }
|
|
|
97 });
|
|
|
98 ```
|
|
|
99
|
|
|
100 This callback can be used to manipulate element which is being dragged as well as whole list.
|
|
|
101 For example you can conditionally add `.dd-nochildren` to forbid dropping current element to
|
|
|
102 some other elements for instance based on `data-type` of current element and other elements:
|
|
|
103
|
|
|
104 ```js
|
|
|
105 $('.dd').nestable({
|
|
|
106 onDragStart: function (l, e) {
|
|
|
107 // get type of dragged element
|
|
|
108 var type = $(e).data('type');
|
|
|
109
|
|
|
110 // based on type of dragged element add or remove no children class
|
|
|
111 switch (type) {
|
|
|
112 case 'type1':
|
|
|
113 // element of type1 can be child of type2 and type3
|
|
|
114 l.find("[data-type=type2]").removeClass('dd-nochildren');
|
|
|
115 l.find("[data-type=type3]").removeClass('dd-nochildren');
|
|
|
116 break;
|
|
|
117 case 'type2':
|
|
|
118 // element of type2 cannot be child of type2 or type3
|
|
|
119 l.find("[data-type=type2]").addClass('dd-nochildren');
|
|
|
120 l.find("[data-type=type3]").addClass('dd-nochildren');
|
|
|
121 break;
|
|
|
122 case 'type3':
|
|
|
123 // element of type3 cannot be child of type2 but can be child of type3
|
|
|
124 l.find("[data-type=type2]").addClass('dd-nochildren');
|
|
|
125 l.find("[data-type=type3]").removeClass('dd-nochildren');
|
|
|
126 break;
|
|
|
127 default:
|
|
|
128 console.error("Invalid type");
|
|
|
129 }
|
|
|
130 }
|
|
|
131 });
|
|
|
132 ```
|
|
|
133 `beforeDragStop` callback provided as an option is fired when user drop an element and before 'callback' method fired. Returning false from this callback will disable the dropping and restore element at start position.
|
|
|
134
|
|
|
135 ```js
|
|
|
136 $('.dd').nestable({
|
|
|
137 beforeDragStop: function(l,e, p){
|
|
|
138 // l is the main container
|
|
|
139 // e is the element that was moved
|
|
|
140 // p is the place where element was moved.
|
|
|
141 }
|
|
|
142 });
|
|
|
143 ```
|
|
|
144
|
|
|
145 ### Methods
|
|
|
146
|
|
|
147 `serialize`:
|
|
|
148 You can get a serialised object with all `data-*` attributes for each item.
|
|
|
149 ```js
|
|
|
150 $('.dd').nestable('serialize');
|
|
|
151 ```
|
|
|
152 The serialised JSON for the example above would be:
|
|
|
153 ```json
|
|
|
154 [{"id":1},{"id":2},{"id":3,"children":[{"id":4},{"id":5,"foo":"bar"}]}]
|
|
|
155 ```
|
|
|
156
|
|
|
157 `toArray`:
|
|
|
158 ```js
|
|
|
159 $('.dd').nestable('toArray');
|
|
|
160 ```
|
|
|
161 Builds an array where each element looks like:
|
|
|
162 ```js
|
|
|
163 {
|
|
|
164 'depth': depth,
|
|
|
165 'id': id,
|
|
|
166 'left': left,
|
|
|
167 'parent_id': parentId || null,
|
|
|
168 'right': right
|
|
|
169 }
|
|
|
170 ```
|
|
|
171
|
|
|
172 You can get a hierarchical nested set model like below.
|
|
|
173 ```js
|
|
|
174 $('.dd').nestable('asNestedSet');
|
|
|
175 ```
|
|
|
176 The output will be like below:
|
|
|
177 ```js
|
|
|
178 [{"id":1,"parent_id":"","depth":0,"lft":1,"rgt":2},{"id":2,"parent_id":"","depth":0,"lft":3,"rgt":4},{"id":3,"parent_id":"","depth":0,"lft":5,"rgt":10},{"id":4,"parent_id":3,"depth":1,"lft":6,"rgt":7},{"id":5,"parent_id":3,"depth":1,"lft":8,"rgt":9}]
|
|
|
179 ```
|
|
|
180
|
|
|
181 `add`:
|
|
|
182 You can add any item by passing an object. New item will be appended to the root tree.
|
|
|
183 ```js
|
|
|
184 $('.dd').nestable('add', {"id":1,"children":[{"id":4}]});
|
|
|
185 ```
|
|
|
186 Optionally you can set 'parent_id' property on your object and control in which place in tree your item will be added.
|
|
|
187 ```js
|
|
|
188 $('.dd').nestable('add', {"id":1,"parent_id":2,"children":[{"id":4}]});
|
|
|
189 ```
|
|
|
190
|
|
|
191 `replace`:
|
|
|
192 You can replace existing item in tree by passing an object with 'id' property.
|
|
|
193 ```js
|
|
|
194 $('.dd').nestable('replace', {"id":1,"foo":"bar"});
|
|
|
195 ```
|
|
|
196 You need to remember that if you're replacing item with children's you need to pass this children's in object as well.
|
|
|
197 ```js
|
|
|
198 $('.dd').nestable('replace', {"id":1,"children":[{"id":4}]});
|
|
|
199 ```
|
|
|
200
|
|
|
201 `remove`:
|
|
|
202 You can remove existing item by passing 'id' of this element. To animate item removing check `effect` config option. This will delete the item with all his children.
|
|
|
203 ```js
|
|
|
204 $('.dd').nestable('remove', 1);
|
|
|
205 ```
|
|
|
206 This will invoke callback function after deleting the item with data-id '1'.
|
|
|
207 ```js
|
|
|
208 $('.dd').nestable('remove', 1, function(){
|
|
|
209 console.log('Item deleted');
|
|
|
210 });
|
|
|
211 ```
|
|
|
212
|
|
|
213 `removeAll`:
|
|
|
214 Removes all items from the list. To animate items removing check `effect` config option. You can also use callback function to do something after removing all items.
|
|
|
215 ```js
|
|
|
216 $('.dd').nestable('removeAll', function(){
|
|
|
217 console.log('All items deleted');
|
|
|
218 });
|
|
|
219 ```
|
|
|
220
|
|
|
221 `destroy`:
|
|
|
222 You can deactivate the plugin by running
|
|
|
223 ```js
|
|
|
224 $('.dd').nestable('destroy');
|
|
|
225 ```
|
|
|
226 ### Autoscroll while dragging
|
|
|
227 Autoscrolls the container element while dragging if you drag the element over the offsets defined in `scrollTriggers` config option.
|
|
|
228
|
|
|
229 ```js
|
|
|
230 $('.dd').nestable({ scroll: true });
|
|
|
231 ```
|
|
|
232
|
|
|
233 To use this feature you need to have `jQuery >= 1.9` and `scrollParent()` method.
|
|
|
234 You can be find this method in `jQuery UI` or if you don't want to have `jQuery UI` as a dependency you can use [this repository](https://github.com/slindberg/jquery-scrollparent).
|
|
|
235
|
|
|
236
|
|
|
237 You can also control the scroll sensitivity and speed, check `scrollSensitivity` and `scrollSpeed` options.
|
|
|
238
|
|
|
239 ### On the fly nestable generation
|
|
|
240
|
|
|
241 You can passed serialized JSON as an option if you like to dynamically generate a Nestable list:
|
|
|
242 ```html
|
|
|
243 <div class="dd" id="nestable-json"></div>
|
|
|
244
|
|
|
245 <script>
|
|
|
246 var json = '[{"id":1},{"id":2},{"id":3,"children":[{"id":4},{"id":5,"foo":"bar"}]}]';
|
|
|
247 var options = {'json': json}
|
|
|
248 $('#nestable-json').nestable(options);
|
|
|
249 </script>
|
|
|
250 ```
|
|
|
251 NOTE: serialized JSON has been expanded so that an optional "content" property can be passed which allows for arbitrary custom content (including HTML) to be placed in the Nestable item
|
|
|
252
|
|
|
253 Or do it yourself the old-fashioned way:
|
|
|
254 ```html
|
|
|
255 <div class="dd" id="nestable3">
|
|
|
256 <ol class='dd-list dd3-list'>
|
|
|
257 <div id="dd-empty-placeholder"></div>
|
|
|
258 </ol>
|
|
|
259 </div>
|
|
|
260
|
|
|
261 <script>
|
|
|
262 $(document).ready(function(){
|
|
|
263 var obj = '[{"id":1},{"id":2},{"id":3,"children":[{"id":4},{"id":5}]}]';
|
|
|
264 var output = '';
|
|
|
265 function buildItem(item) {
|
|
|
266
|
|
|
267 var html = "<li class='dd-item' data-id='" + item.id + "'>";
|
|
|
268 html += "<div class='dd-handle'>" + item.id + "</div>";
|
|
|
269
|
|
|
270 if (item.children) {
|
|
|
271
|
|
|
272 html += "<ol class='dd-list'>";
|
|
|
273 $.each(item.children, function (index, sub) {
|
|
|
274 html += buildItem(sub);
|
|
|
275 });
|
|
|
276 html += "</ol>";
|
|
|
277
|
|
|
278 }
|
|
|
279
|
|
|
280 html += "</li>";
|
|
|
281
|
|
|
282 return html;
|
|
|
283 }
|
|
|
284
|
|
|
285 $.each(JSON.parse(obj), function (index, item) {
|
|
|
286
|
|
|
287 output += buildItem(item);
|
|
|
288
|
|
|
289 });
|
|
|
290
|
|
|
291 $('#dd-empty-placeholder').html(output);
|
|
|
292 $('#nestable3').nestable();
|
|
|
293 });
|
|
|
294 </script>
|
|
|
295 ```
|
|
|
296
|
|
|
297 ### Configuration
|
|
|
298
|
|
|
299 You can change the follow options:
|
|
|
300
|
|
|
301 * `maxDepth` number of levels an item can be nested (default `5`)
|
|
|
302 * `group` group ID to allow dragging between lists (default `0`)
|
|
|
303 * `callback` callback function when an element has been changed (default `null`)
|
|
|
304 * `scroll` enable or disable the scrolling behaviour (default: `false`)
|
|
|
305 * `scrollSensitivity` mouse movement needed to trigger the scroll (default: `1`)
|
|
|
306 * `scrollSpeed` speed of the scroll (default: `5`)
|
|
|
307 * `scrollTriggers` distance from the border where scrolling become active (default: `{ top: 40, left: 40, right: -40, bottom: -40 }`)
|
|
|
308 * `effect` removing items animation effect (default: `{ animation: 'none', time: 'slow'}`). To fadeout elements set 'animation' value to 'fade', during initialization the plugin.
|
|
|
309
|
|
|
310 These advanced config options are also available:
|
|
|
311
|
|
|
312 * `contentCallback` The callback for customizing content (default `function(item) {return item.content || '' ? item.content : item.id;}`)
|
|
|
313 * `listNodeName` The HTML element to create for lists (default `'ol'`)
|
|
|
314 * `itemNodeName` The HTML element to create for list items (default `'li'`)
|
|
|
315 * `rootClass` The class of the root element `.nestable()` was used on (default `'dd'`)
|
|
|
316 * `listClass` The class of all list elements (default `'dd-list'`)
|
|
|
317 * `itemClass` The class of all list item elements (default `'dd-item'`)
|
|
|
318 * `dragClass` The class applied to the list element that is being dragged (default `'dd-dragel'`)
|
|
|
319 * `noDragClass` The class applied to an element to prevent dragging (default `'dd-nodrag'`)
|
|
|
320 * `handleClass` The class of the content element inside each list item (default `'dd-handle'`)
|
|
|
321 * `collapsedClass` The class applied to lists that have been collapsed (default `'dd-collapsed'`)
|
|
|
322 * `noChildrenClass` The class applied to items that cannot have children (default `'dd-nochildren'`)
|
|
|
323 * `placeClass` The class of the placeholder element (default `'dd-placeholder'`)
|
|
|
324 * `emptyClass` The class used for empty list placeholder elements (default `'dd-empty'`)
|
|
|
325 * `expandBtnHTML` The HTML text used to generate a list item expand button (default `'<button data-action="expand">Expand></button>'`)
|
|
|
326 * `collapseBtnHTML` The HTML text used to generate a list item collapse button (default `'<button data-action="collapse">Collapse</button>'`)
|
|
|
327 * `includeContent` Enable or disable the content in output (default `false`)
|
|
|
328 * `listRenderer` The callback for customizing final list output (default `function(children, options) { ... }` - see defaults in code)
|
|
|
329 * `itemRenderer` The callback for customizing final item output (default `function(item_attrs, content, children, options) { ... }` - see defaults in code)
|
|
|
330 * `json` JSON string used to dynamically generate a Nestable list. This is the same format as the `serialize()` output
|
|
|
331
|
|
|
332 **Inspect the [Nestable2 Demo](https://ramonsmit.github.io/Nestable2/) for guidance.**
|
|
|
333
|
|
|
334 ## Change Log
|
|
|
335
|
|
|
336 ### 21th October 2017
|
|
|
337 * [klgd] Fixed conflict when project using also jQuery 2.*
|
|
|
338 * [RomanBurunkov] Moved effect and time parameter in `remove` method to config option. This changes break backward compatibility with version 1.5
|
|
|
339 * [RomanBurunkov] Added callback in methods `remove` and `removeAll` as a parameter
|
|
|
340 * [RomanKhomyshynets] Fixed `add` function with non-leaf parent_id, fixed [#84](https://github.com/RamonSmit/Nestable2/issues/84)
|
|
|
341
|
|
|
342 ### 9th August 2017
|
|
|
343 * [pjona] Added support for string (GUID) as a data id
|
|
|
344
|
|
|
345 ### 21th July 2017
|
|
|
346 * [spathon] Append the .dd-empty div if the list don't have any items on init, fixed [#52](https://github.com/RamonSmit/Nestable2/issues/52)
|
|
|
347 * [pjona] Fixed problem on Chrome with touch screen and mouse, fixed [#28](https://github.com/RamonSmit/Nestable2/issues/28) and[#73](https://github.com/RamonSmit/Nestable2/issues/73)
|
|
|
348
|
|
|
349 ### 15th July 2017
|
|
|
350 * [RomanBurunkov] Added fadeOut support to `remove` method
|
|
|
351 * [pjona] Fixed `replace` method (added collapse/expand buttons when item has children), see [#69](https://github.com/RamonSmit/Nestable2/issues/69)
|
|
|
352 * [uniring] Added autoscroll while dragging, see [#71](https://github.com/RamonSmit/Nestable2/issues/71)
|
|
|
353
|
|
|
354 ### 2nd July 2017
|
|
|
355 * [pjona] Added CDN support
|
|
|
356 * [pjona] Removed unneeded directories in `dist/`
|
|
|
357
|
|
|
358 ### 25th June 2017
|
|
|
359 * [pjona] Fixed `add` method when using parent_id, see [#66](https://github.com/RamonSmit/Nestable2/issues/66)
|
|
|
360
|
|
|
361 ### 22th June 2017
|
|
|
362 * [pjona] Added Travis CI builds after each commit and pull request
|
|
|
363 * [pjona] Added `test` task in gulp with eslint validation
|
|
|
364 * [pjona] Added minified version of JS and CSS
|
|
|
365 * [pjona] Changed project name to `nestable2`
|
|
|
366 * [pjona] Fixed `remove` method when removing last item from the list
|
|
|
367
|
|
|
368 ### 16th June 2017
|
|
|
369
|
|
|
370 * [imliam] Added support to return `false` from the `onDragStart` event to disable the drag event
|
|
|
371
|
|
|
372 ### 28th May 2017
|
|
|
373
|
|
|
374 * [pjona] Function `add` support `parent_id` property
|
|
|
375 * [pjona] Added `replace` function
|
|
|
376 * [pjona] Added `remove` function
|
|
|
377
|
|
|
378 ### 22th May 2017
|
|
|
379
|
|
|
380 * [pjona] Added npm installation
|
|
|
381 * [pjona] Added `add` function
|
|
|
382
|
|
|
383 ### 10th April 2017
|
|
|
384
|
|
|
385 * [timalennon] Added functions: `toHierarchy` and `toArray`
|
|
|
386
|
|
|
387 ### 17th November 2015
|
|
|
388
|
|
|
389 * [oimken] Added `destroy` function
|
|
|
390
|
|
|
391 ### 2nd November 2015
|
|
|
392
|
|
|
393 * [ivanbarlog] Added `onDragStart` event fired when user starts to drag an element
|
|
|
394
|
|
|
395 ### 21th April 2015
|
|
|
396
|
|
|
397 * [ozdemirburak] Added `asNestedSet` function
|
|
|
398 * [ozdemirburak] Added bower installation
|
|
|
399
|
|
|
400 ### 6th October 2014
|
|
|
401
|
|
|
402 * [zemistr] Created listRenderer and itemRenderer. Refactored build from JSON.
|
|
|
403 * [zemistr] Added support for adding classes via input data. (```[{"id": 1, "content": "First item", "classes": ["dd-nochildren", "dd-nodrag", ...] }, ... ]```)
|
|
|
404
|
|
|
405 ### 3rd October 2014
|
|
|
406
|
|
|
407 * [zemistr] Added support for additional data parameters.
|
|
|
408 * [zemistr] Added callback for customizing content.
|
|
|
409 * [zemistr] Added parameter "includeContent" for including / excluding content from the output data.
|
|
|
410 * [zemistr] Added fix for input data. (JSON string / Javascript object)
|
|
|
411
|
|
|
412 ### 7th April 2014
|
|
|
413
|
|
|
414 * New pickup of repo for developement.
|
|
|
415
|
|
|
416 ### 14th March 2013
|
|
|
417
|
|
|
418 * [tchapi] Merge Craig Sansam' branch [https://github.com/craigsansam/Nestable/](https://github.com/craigsansam/Nestable/) - Add the noChildrenClass option
|
|
|
419
|
|
|
420 ### 13th March 2013
|
|
|
421
|
|
|
422 * [tchapi] Replace previous `change` behaviour with a callback
|
|
|
423
|
|
|
424 ### 12th February 2013
|
|
|
425
|
|
|
426 * Merge fix from [jails] : Fix change event triggered twice.
|
|
|
427
|
|
|
428 ### 3rd December 2012
|
|
|
429
|
|
|
430 * [dbushell] add no-drag class for handle contents
|
|
|
431 * [dbushell] use `el.closest` instead of `el.parents`
|
|
|
432 * [dbushell] fix scroll offset on document.elementFromPoint()
|
|
|
433
|
|
|
434 ### 15th October 2012
|
|
|
435
|
|
|
436 * Merge for Zepto.js support
|
|
|
437 * Merge fix for remove/detach items
|
|
|
438
|
|
|
439 ### 27th June 2012
|
|
|
440
|
|
|
441 * Added `maxDepth` option (default to 5)
|
|
|
442 * Added empty placeholder
|
|
|
443 * Updated CSS class structure with options for `listClass` and `itemClass`.
|
|
|
444 * Fixed to allow drag and drop between multiple Nestable instances (off by default).
|
|
|
445 * Added `group` option to enabled the above.
|
|
|
446
|
|
|
447 * * *
|
|
|
448
|
|
|
449 Original Author: David Bushell [http://dbushell.com](http://dbushell.com/) [@dbushell](http://twitter.com/dbushell/)
|
|
|
450
|
|
|
451 New Author : Ramon Smit [http://ramonsmit.nl](http://ramonsmit.nl) [@ramonsmit94](https://twitter.com/Ram0nSm1t/)
|
|
|
452
|
|
|
453 Contributors :
|
|
|
454
|
|
|
455 * Cyril [http://tchap.me](http://tchap.me), Craig Sansam
|
|
|
456 * Zemistr [http://zemistr.eu](http://zemistr.eu), Martin Zeman
|
|
|
457 * And alot more.
|
|
|
458
|
|
|
459 Copyright © 2012 David Bushell / © Ramon Smit 2014/2017 | BSD & MIT license
|
