A drag and drop list item sorting and level changing library.
The jQuery-ui's sortable plugin allows us to sort items vertically or horizontally. But sometimes we need some items to make a child of another item and also need to sort a parent with all of the children items.
This is the reason why I've created this library for managing the parent-children relationship of list items and fully by drag and drop.
Download the required files from the Github. Use the treeSortable.js and treeSortable.css files to your project.
You also need to use jQuery and jQuery-ui libraries.
In the <head> tag use the css files.
<link href="https://code.jquery.com/ui/1.12.1/themes/smoothness/jquery-ui.css" rel="stylesheet" type="text/css" />
<link href="/path/to/treeSortable.css" rel="stylesheet" />Before the </body> tag
<script src="https://code.jquery.com/jquery-3.1.0.js"></script>
<script src="https://code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
<script src="/path/to/treeSortable.js"></script>Create a ul element with some ID attribute.
<ul id="tree"></ul>Then generate an array of object with the exact structure defined below. In the data structure the ordering is important, the tree will be rendered according to this order.
const data = [
{
id: 1,
level: 1,
parent_id: 0,
title: 'Branch 1'
},
{
id: 2,
level: 2,
parent_id: 1,
title: 'Branch 2'
},
.
.
.
]Now we are gonna create an instance of the tree sortable. And we can pass an options object as the constructor of the TreeSortable.
const sortable = new TreeSortable({
treeSelector: '#tree'
});Now create the HTML content of the tree from the data we've declared earlier, and append the $content to the <ul> element.
const $content = data.map(sortable.createBranch);
$('#tree').html($content);Finally, run the sortable for making it interactive.
sortable.run();You can pass customized options to the sortable while instantiating the function. All the options has the default values.
| Option | Default | Description |
|---|---|---|
| treeSortable | #tree | The tree root ID selector. If you change the root selector then you have to update the CSS as per requirements. |
| branchSelector | .tree-branch | The tree branch class selector. This need to be applied at the li element of the tree. |
| branchPathSelector | .branch-path | The left side path indication element's class selector. |
| dragHandlerSelector | .branch-drag-handler | The drag element. This element is responsible for enabling the dragging features of the branch. |
| placeholderName | sortable-placeholder | The placeholder name. This is for jquery-ui sortable. Note that there is no dot(.) or hash(#). See the jquery-ui sortable library. |
| childrenBusSelector | .children-bus | The children bus selector. This element is responsible for carrying the children on sorting a parent element. |
| levelPrefix | branch-level | This prefix is added to the li element and create a level class. For example, for the level 1 branch the class would be .branch-level-1 |
| maxLevel | 10 | The maximum level the tree could go. For example, if you set the maxLevel to 2 then the branch could have maximum .branch-level-2. |
| depth | 30 | The Depth of a child branch. If you change the depth then you have to update the CSS of the .branch-level-X classes. See the treeSortable.css for more references. |
For updating the options you could do-
const sortable = new TreeSortable({
treeSelector: '#someUlId',
branchSelector: '.some-branch-class-name',
depth: 20,
...
})Note: If you change the class selectors like
branchSelector,branchPathSelectoretc then you have to take care of the CSS design accordingly.
After each reorder or level change an event is fired for further operations.
sortable.onSortCompleted(function(event, ui) {
// here the `event` is the sortable event.
// The `ui` is the jquery-ui's ui object.
// You can use the `ui.item`, `ui.helper` and so on.
// See https://api.jqueryui.com/sortable/
});You can perform async operations here as well. make the callback function asynchronous in that case.
sortable.onSortCompleted(async function(event, ui) {
await updateDatabaseAsync();
});There are some functions provided to the library for adding child branch, sibling branch or delete branches recursively.
The sortable instance provides you an event listener that gives you the ability to attach any event listener for a specific instance.
This is basically a wrapper function of the original jQuery's event listener but this is more TreeSortable instance specific.
sortable.addListener('click', '.add-child', function (event, instance) {
event.preventDefault();
instance.addChildBranch($(event.target));
});For adding sibling-
sortable.addListener('click', '.add-child', function (event, instance) {
event.preventDefault();
instance.addSiblingBranch($(event.target));
});For deleting branch-
sortable.addListener('click', '.remove-branch', function (event, instance) {
event.preventDefault();
const confirm = window.confirm('Are you sure you want to delete this branch?');
if (!confirm) {
return;
}
instance.removeBranch($(this));
});If you find any issues please raise issue on github. Also if you want to contribute the plugin then create a PR.
This library is fully functional if your data structure satisfied the described situation. But this may not be perfect for some other situation.
If you need any customization then ping me on [email protected].
