search

RamonSmit / Nestable2

New pickup of Nestable!
Other
322 stars 147 forks source link

readme

Nestable2

At this moment I really don't have any spare time to maintain this package. 
If there is anyone that wants to help me out with this, please message me trough a issue of mail.

Drag & drop hierarchical list with mouse and touch compatibility (jQuery / Zepto plugin)

Status Demo Build Status License NPM version Bower version

Nestable is an experimental example and IS under active development. If it suits your requirements feel free to expand upon it!

Install

You can install this package either with npm or with bower.

npm

npm install --save nestable2

Then add a <script> to your index.html:

<script src="https://github.com/RamonSmit/Nestable2/raw/master/node_modules/nestable2/jquery.nestable.js"></script>

Or require('nestable2') from your code.

bower

bower install --save nestable2

CDN

You can also find us on CDNJS:

//cdnjs.cloudflare.com/ajax/libs/nestable2/1.6.0/jquery.nestable.min.css
//cdnjs.cloudflare.com/ajax/libs/nestable2/1.6.0/jquery.nestable.min.js

You can also find us on jsDelivr

//cdn.jsdelivr.net/npm/nestable2@1.6.0/jquery.nestable.min.js
//cdn.jsdelivr.net/npm/nestable2@1.6.0/jquery.nestable.min.css

Usage

Write your nested HTML lists like so:

<div class="dd">
    <ol class="dd-list">
        <li class="dd-item" data-id="1">
            <div class="dd-handle">Item 1</div>
        </li>
        <li class="dd-item" data-id="2">
            <div class="dd-handle">Item 2</div>
        </li>
        <li class="dd-item" data-id="3">
            <div class="dd-handle">Item 3</div>
            <ol class="dd-list">
                <li class="dd-item" data-id="4">
                    <div class="dd-handle">Item 4</div>
                </li>
                <li class="dd-item" data-id="5" data-foo="bar">
                    <div class="dd-nodrag">Item 5</div>
                </li>
            </ol>
        </li>
    </ol>
</div>

Then activate with jQuery like so:

$('.dd').nestable({ /* config options */ });

Events

change: For using an .on handler in jquery

The callback provided as an option is fired when elements are reordered or nested.

$('.dd').nestable({
    callback: function(l,e){
        // l is the main container
        // e is the element that was moved
    }
});

onDragStart callback provided as an option is fired when user starts to drag an element. Returning false from this callback will disable the dragging.

$('.dd').nestable({
    onDragStart: function(l,e){
        // l is the main container
        // e is the element that was moved
    }
});

This callback can be used to manipulate element which is being dragged as well as whole list. For example you can conditionally add .dd-nochildren to forbid dropping current element to some other elements for instance based on data-type of current element and other elements:

 $('.dd').nestable({
     onDragStart: function (l, e) {
         // get type of dragged element
         var type = $(e).data('type');

         // based on type of dragged element add or remove no children class
         switch (type) {
             case 'type1':
                 // element of type1 can be child of type2 and type3
                 l.find("[data-type=type2]").removeClass('dd-nochildren');
                 l.find("[data-type=type3]").removeClass('dd-nochildren');
                 break;
             case 'type2':
                 // element of type2 cannot be child of type2 or type3
                 l.find("[data-type=type2]").addClass('dd-nochildren');
                 l.find("[data-type=type3]").addClass('dd-nochildren');
                 break;
             case 'type3':
                 // element of type3 cannot be child of type2 but can be child of type3
                 l.find("[data-type=type2]").addClass('dd-nochildren');
                 l.find("[data-type=type3]").removeClass('dd-nochildren');
                 break;
             default:
                 console.error("Invalid type");
         }
     }
 });

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.

$('.dd').nestable({
    beforeDragStop: function(l,e, p){
        // l is the main container
        // e is the element that was moved
        // p is the place where element was moved.
    }
});

Methods

serialize: You can get a serialised object with all data-* attributes for each item.

$('.dd').nestable('serialize');

The serialised JSON for the example above would be:

[{"id":1},{"id":2},{"id":3,"children":[{"id":4},{"id":5,"foo":"bar"}]}]

toArray:

$('.dd').nestable('toArray');

Builds an array where each element looks like:

{
    'depth': depth,
    'id': id,
    'left': left,
    'parent_id': parentId || null,
    'right': right
}

You can get a hierarchical nested set model like below.

$('.dd').nestable('asNestedSet');

The output will be like below:

[{"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}]

add: You can add any item by passing an object. New item will be appended to the root tree.

$('.dd').nestable('add', {"id":1,"children":[{"id":4}]});

Optionally you can set 'parent_id' property on your object and control in which place in tree your item will be added.

$('.dd').nestable('add', {"id":1,"parent_id":2,"children":[{"id":4}]});

replace: You can replace existing item in tree by passing an object with 'id' property.

$('.dd').nestable('replace', {"id":1,"foo":"bar"});

You need to remember that if you're replacing item with children's you need to pass this children's in object as well.

$('.dd').nestable('replace', {"id":1,"children":[{"id":4}]});

remove: 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.

$('.dd').nestable('remove', 1);

This will invoke callback function after deleting the item with data-id '1'.

$('.dd').nestable('remove', 1, function(){
    console.log('Item deleted');
});

removeAll: 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.

$('.dd').nestable('removeAll', function(){
    console.log('All items deleted');
});

destroy: You can deactivate the plugin by running

$('.dd').nestable('destroy');

Autoscroll while dragging

Autoscrolls the container element while dragging if you drag the element over the offsets defined in scrollTriggers config option.

$('.dd').nestable({ scroll: true });

To use this feature you need to have jQuery >= 1.9 and scrollParent() method. 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.

You can also control the scroll sensitivity and speed, check scrollSensitivity and scrollSpeed options.

On the fly nestable generation

You can passed serialized JSON as an option if you like to dynamically generate a Nestable list:

<div class="dd" id="nestable-json"></div>

<script>
var json = '[{"id":1},{"id":2},{"id":3,"children":[{"id":4},{"id":5,"foo":"bar"}]}]';
var options = {'json': json}
$('#nestable-json').nestable(options);
</script>

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

Or do it yourself the old-fashioned way:

<div class="dd" id="nestable3">
    <ol class='dd-list dd3-list'>
        <div id="dd-empty-placeholder"></div>
    </ol>
</div>

<script>
$(document).ready(function(){
    var obj = '[{"id":1},{"id":2},{"id":3,"children":[{"id":4},{"id":5}]}]';
    var output = '';
    function buildItem(item) {

        var html = "<li class='dd-item' data-id='" + item.id + "'>";
        html += "<div class='dd-handle'>" + item.id + "</div>";

        if (item.children) {

            html += "<ol class='dd-list'>";
            $.each(item.children, function (index, sub) {
                html += buildItem(sub);
            });
            html += "</ol>";

        }

        html += "</li>";

        return html;
    }

    $.each(JSON.parse(obj), function (index, item) {

        output += buildItem(item);

    });

    $('#dd-empty-placeholder').html(output);
    $('#nestable3').nestable();
});
</script>

Configuration

You can change the follow options:

These advanced config options are also available:

Inspect the Nestable2 Demo for guidance.

Change Log

21th October 2017

9th August 2017

21th July 2017

15th July 2017

2nd July 2017

25th June 2017

22th June 2017

16th June 2017

28th May 2017

22th May 2017

10th April 2017

17th November 2015

2nd November 2015

21th April 2015

6th October 2014

3rd October 2014

7th April 2014

14th March 2013

13th March 2013

12th February 2013

3rd December 2012

15th October 2012

27th June 2012

Original Author: David Bushell http://dbushell.com @dbushell

New Author : Ramon Smit http://ramonsmit.nl @ramonsmit94

Contributors :

Copyright © 2012 David Bushell / © Ramon Smit 2014/2017 | BSD & MIT license