Sortable and Collapsible Tree View Plugin For jQuery - Sortable Lists

Sortable and Collapsible Tree View Plugin For jQuery - Sortable Lists
File Size: 30 KB
Views Total: 9393
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   

A jQuery plugin that enables items in a list to be sorted vertically through drag and drop or touch gestures.

Supports nested lists that allows to collapse / expand list items like a tree structure.

How to use it:

You can do this:

  • You can set placeholder css in init object through placeholderCss object - jQuery css object or placeholderClass.
  • You can set dragged element css through currElCss object or currElClass.
  • You can set hint css through hintCss object or hintClass.
  • You can set hintWrapper css throungh hintWrapperCss object or hintWrapperClass. Class will be removed after item will be inserted to the active area.
  • You can set base object css in init object through the baseCss object or baseClass.
  • You can set insert zone as a distance which determines if item wil be inserted inside or ouside of the active area by insertZone:50 property.
  • You can set speed of scrolling by scroll:10 property. Default is 20.
  • You can set isAllowed callback which determine if is possible to insert element in to the active area.

You should do this:

  • If you use css classes to formating ul/ols you should set the class used for ul/ol lists through listsClass:'className'. It is necessary for hintWrapper element which is created on the fly.

Do not do this:

  • Do not use list-style-type values different as none. It works also with type, but it is not recomended. You can use background image instead.
  • Do not format lists with # selector. Use classes or element selectors(ul{color:red}). It can cause problems with formating.
  • Do not use absolute positioning on the lists.
  • Do not experiment with body margin-top/left or padding-top/left. Script tries to solve it but i am not sure if it is 100% OK.
  • Do not use construction where ul with margin top is direct child of body - <body><ul style="margin-top:XYpx">. Margin-top breaks the position of dragged element.

Basic usage

1. Include the jQuery Sortable Lists plugin in your project.

<!-- jQuery Is Required -->
<script src="/path/to/cdn/jquery.min.js"></script>
<!-- For Desktop -->
<script src="/path/to/jquery-sortable-lists.min.js"></script>
<!-- For Mobile -->
<script src="/path/to/jquery-sortable-lists-mobile.min.js"></script>
$('#selector').sortableLists(options);

2. Create nested HTML lists for the hierarchical tree.

<ul class="sTree-example listsClass" id="sTree-example">
  <li id="item_a" data-module="a">
    <div>Item a</div>
  </li>
  <li class="s-l-open" id="item_b" data-module="b">
    <div>Item b</div>
    <ul class="">
      <li id="item_b1" data-module="b">
        <div>Item b1</div>
      </li>
      <li id="item_b2" data-module="b">
        <div><span class="clickable">Item b2 - clickable text</span></div>
      </li>
      <li id="item_b3" data-module="b">
        <div>Item b3</div>
      </li>
      <li id="item_b4" data-module="b">
        <div>Item b4</div>
      </li>
      <li id="item_b5" data-module="b">
        <div>Item b5</div>
      </li>
    </ul>
  </li>
  <li class="" id="item_c" data-module="c">
    <div>Item c - c block disallows inserting items from other blocks</div>
    <ul class="">
      <li id="item_c1" data-module="c">
        <div>Item c1</div>
      </li>
      <li id="item_c2" data-module="c">
        <div>Item c2</div>
      </li>
      <li id="item_c3" data-module="c">
        <div>Item c3</div>
      </li>
      <li id="item_c4" data-module="c">
        <div>Item c4</div>
      </li>
      <li id="item_c5" data-module="c">
        <div>Item c5</div>
      </li>
    </ul>
  </li>
  <li class="" id="item_d" data-module="d">
    <div>Item d</div>
    <ul class="">
      <li id="item_d1" data-module="d">
        <div>Item d1</div>
      </li>
      <li id="item_d2" data-module="d">
        <div>Item d2</div>
      </li>
      <li id="item_d3" data-module="d">
        <div>Item d3</div>
      </li>
      <li id="item_d4" data-module="d">
        <div>Item d4</div>
      </li>
      <li id="item_d5" data-module="d">
        <div>Item d5</div>
      </li>
    </ul>
  </li>
  <li class="" id="item_e" data-module="e">
    <div>Item e</div>
  </li>
  <li class="" id="item_f" data-module="f">
    <div>Item f</div>
  </li>
</ul>

3. Initialize the plugin with several options.

$('#sTree-example').sortableLists({
  placeholderCss: {'background-color': '#ff8'},
  hintCss: {'background-color':'#bbf'},
  opener: {
    active: true,
    as: 'html',  // if as is not set plugin uses background image
    close: '<i class="fa fa-minus c3"></i>',  // or 'fa-minus c3',  // or './imgs/Remove2.png',
    open: '<i class="fa fa-plus"></i>',  // or 'fa-plus',  // or'./imgs/Add2.png',
    openerCss: {
      'display': 'inline-block',
      'float': 'left',
      'margin-left': '-35px',
      'margin-right': '5px',
      'font-size': '1.1em'
    }
  },
  ignoreClass: 'clickable'
});

4. All default options and callback functions.

currElClass: '',
placeholderClass: '',
placeholderCss: {
  'position': 'relative',
  'padding': 0
},
hintClass: '',
hintCss: {
  'display': 'none',
  'position': 'relative',
  'padding': 0
},
hintWrapperClass: '',
hintWrapperCss: { /* Description is below the defaults in this var section */ },
baseClass: '',
baseCss: {
  'position': 'absolute',
  'top': 0 - parseInt( jQBody.css( 'margin-top' ) ),
  'left': 0 - parseInt( jQBody.css( 'margin-left' ) ),
  'margin': 0,
  'padding': 0,
  'z-index': 2500
},
opener: {
  active: false,
  open: '',
  close: '',
  openerCss: {
    'float': 'left',
    'display': 'inline-block',
    'background-position': 'center center',
    'background-repeat': 'no-repeat'
  },
  openerClass: ''
},
maxLevels: false,
listSelector: 'ul',
listsClass: '', // Used for hintWrapper and baseElement
listsCss: {},
insertZone: 50,
insertZonePlus: false,
scroll: 20,
ignoreClass: '',
isAllowed: function( cEl, hint, target ) { return true; },  // Params: current el., hint el.
onDragStart: function( e, cEl ) { return true; },  // Params: e jQ. event obj., current el.
onChange: function( cEl ) { return true; },  // Params: current el.
complete: function( cEl ) { return true; }  // Params: current el.

5. Export the current data as Array/String/Hierarchy.

$('#sTree-example').sortableListsToArray();
$('#sTree-example').sortableListsToHierarchy();
$('#sTree-example').sortableListsToString();

Changelog:

2020-06-10

  • 2.0.0: Max levels number has been implemented and opener background-image has been removed

2018-01-17

  • 1.4.0: Support for mobile devices in jquery-sortable-lists-mobile.js

2016-02-05

  • 1.3.0: Added insertZonePlus option, fixed little bug with ol lists.

2016-02-02

  • 1.2.0: Added opener.as option to opener. Now is possible to use opener.as html or class option.

2016-01-27

  • v1.1.1: bugfixed

2015-11-21

  • v1.1.0: Callback onChange has been implemented.

2015-11-03

  • v1.0.14

2015-09-28

  • Bug fix - empty ignoreClass causes an big issue.

2015-09-24

  • Little bug fix

2015-08-29

  • Little bug fix

2015-07-28

  • sortableListsToString rewritten

2015-06-11

  • Added features onStratDrag and ignoreClass. 
  • Fixed complete position in code.

2015-06-10

  • Fixed opener.css + removed some js in index.html, improved toArray, toHierarchy functions.
  • toArray now returns array of objects and order param starts at 0 instead of 1. Also some redundant var declarations was removed.
  • Added mobile version.

2015-05-31

  • Fixed bug in opener object

2015-05-27

  • Fixed bug in open/close function

2015-05-22

  • autoscroll completely rewriten, open/close functionality added to ul/ols.

This awesome jQuery plugin is developed by camohub. For more Advanced Usages, please check the demo page or visit the official website.