Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ahamed/treesortable
This is a jquery ui sortable helper plugin for handy tree type structure sotable.
https://github.com/ahamed/treesortable
jquery jqueryui sortable
Last synced: about 3 hours ago
JSON representation
This is a jquery ui sortable helper plugin for handy tree type structure sotable.
- Host: GitHub
- URL: https://github.com/ahamed/treesortable
- Owner: ahamed
- Created: 2021-01-07T05:44:50.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2022-10-10T15:09:10.000Z (about 2 years ago)
- Last Synced: 2024-05-21T02:42:11.357Z (6 months ago)
- Topics: jquery, jqueryui, sortable
- Language: JavaScript
- Homepage: https://ahamed.github.io/treeSortable
- Size: 1.71 MB
- Stars: 19
- Watchers: 1
- Forks: 6
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Tree Sortable
A drag and drop list item sorting and level changing library.
## Motivation
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.
## Installation
Download the required files from the [Github](https://github.com/ahamed/treeSortable/archive/refs/heads/master.zip). Use the `treeSortable.js` and `treeSortable.css` files to your project.
You also need to use `jQuery` and `jQuery-ui` libraries.
In the `` tag use the css files.
```html
```
Before the `` tag
```html
```
---
## Usage
Create a `ul` element with some ID attribute.
```html
```
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.
```js
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`.
```js
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 `
- ` element.
```js
const $content = data.map(sortable.createBranch);
$('#tree').html($content);
```
Finally, run the sortable for making it interactive.
```js
sortable.run();
```
## Change sortable options
You can pass customized options to the sortable while instantiating the function. All the options has the default values.
## Options
| 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-
```js
const sortable = new TreeSortable({
treeSelector: '#someUlId',
branchSelector: '.some-branch-class-name',
depth: 20,
...
})
```
>Note: If you change the class selectors like `branchSelector`, `branchPathSelector` etc then you have to take care of the CSS design accordingly.
## Event
After each reorder or level change an event is fired for further operations.
```js
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.
```js
sortable.onSortCompleted(async function(event, ui) {
await updateDatabaseAsync();
});
```
## Add child, Add sibling, delete branch.
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.
```js
sortable.addListener('click', '.add-child', function (event, instance) {
event.preventDefault();
instance.addChildBranch($(event.target));
});
```
For adding sibling-
```js
sortable.addListener('click', '.add-child', function (event, instance) {
event.preventDefault();
instance.addSiblingBranch($(event.target));
});
```
For deleting branch-
```js
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));
});
```
## Contribution
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]`.