Plugin jQuery untuk Nested Sortable List dengan Force Bind

DragSort adalah plugin jQuery ringan yang memungkinkan Anda membuat nested sortable list (daftar bersarang yang dapat diurutkan) secara interaktif dengan fitur drag and drop.

Plugin ini dirancang dengan fitur unggulan Force Bind Mode, yang memungkinkan Anda menyeret item parent beserta seluruh child-nya secara otomatis. Cocok untuk membangun menu navigasi dinamis, struktur kategori, atau manajemen hierarki data lainnya.

📖 Daftar Isi

• Fitur Utama
• Instalasi
• Penggunaan Dasar
• API Reference
• Konfigurasi
• Callbacks
• CSS & Styling
• Struktur File
• License

✨ Fitur Utama

• ✅ Drag & Drop — Dukungan penuh mouse dan touch events (mobile friendly).
• ✅ Nested Hierarchy - Struktur parent-child tak terbatas (recursive).
• ✅ Force Bind Mode — Seret parent + semua child ikut secara otomatis (toggleable per item).
• ✅ Dynamic Indentation — Kontrol lebar indentasi secara runtime via API.
• ✅ Collapse / Expand — Tutup dan buka subtree untuk navigasi yang bersih.
• ✅ Real-time Sync — DOM dan Data Array selalu tersinkronisasi.
• ✅ Lifecycle Callbacks — Hook lengkap (onGrab, onDrag, onDrop, dll).
• ✅ Delete Validation — Validasi penghapusan via callback onDelete (bisa dibatalkan).
• ✅ Standard API Response — Response object konsisten untuk operasi modifikasi data.

📥 Instalasi

1. Sertakan Dependencies

Pastikan Anda telah menyertakan jQuery 3.x sebelum plugin ini.

<!-- jQuery -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

2. Sertakan Plugin & Stylesheet

<!-- Core CSS (Wajib) -->
<link rel="stylesheet" href="src/css/dragsort.css">

<!-- Plugin JS -->
<script src="src/js/dragsort.js"></script>

💡 Penggunaan Dasar

1. Siapkan HTML Container

Buat element <ul> atau <ol> dengan ID unik.

<ul id="menu-list" class="ds-list"></ul>

2. Siapkan Data Source

Data menggunakan format flat array dengan relasi parent_id (struktur tree).

var appData = [
  { id: "1", parent_id: "0", order: 1, label: "Dashboard", link: "/dashboard", icon: "D", type: "url", bind: true },
  { id: "2", parent_id: "0", order: 2, label: "Settings",  link: "/settings",  icon: "S", type: "url", bind: true },
  { id: "3", parent_id: "2", order: 1, label: "Roles",     link: "/roles",     icon: "R", type: "url", bind: true }
];

3. Inisialisasi Plugin

Panggil plugin dan simpan API reference yang dikembalikan.

var ds = $('#menu-list').dragsort({
  data: appData,
  indent: 40,
  indentSensitivity: 0.5
});

🚀 API Reference

Mulai versi 1.0.15, inisialisasi plugin mengembalikan API Object secara langsung, memungkinkan pemanggilan method yang bersih tanpa selector jQuery berulang.

Mengambil API Instance

// Saat init
var ds = $('#menu-list').dragsort({ ... });

// Retrieve API yang sudah ada (tanpa argumen)
var ds = $('#menu-list').dragsort();

Data Query Methods

Method	Returns	Deskripsi
ds.getSubtreeSize(id)	number	Total item dalam subtree (1 item + descendants)
ds.getDescendantIds(id)	string[]	Array ID semua descendant (tanpa item itu sendiri)
ds.getData()	Array<Object>	Shallow copy internal data array
ds.get(key)	*	Ambil nilai konfigurasi ('indent', 'sensitivity', 'data')

Action Methods

Method	Returns	Deskripsi
ds.deleteItem(id, [callback])	Object	Hapus item + subtree. Lihat Delete Lifecycle
ds.render()	void	Re-render list dari data array
ds.collapseAll()	void	Collapse semua parent nodes
ds.expandAll()	void	Expand semua collapsed nodes
ds.set(key, value)	void	Set konfigurasi runtime ('indent', 'sensitivity')
ds.destroy()	void	Hapus instance, cleanup events & DOM

⚙️ Konfigurasi

Opsi yang dapat diberikan saat inisialisasi:

Key	Type	Default	Deskripsi
data	Array<Object>	[]	Data source array
indent	number	40	Lebar indentasi per level (px)
indentSensitivity	number	0.5	Sensitivitas perubahan depth saat drag horizontal (0-1)

🪝 Callbacks

Drag Lifecycle

Callback	Parameters	Deskripsi
onGrab	itemId	Mousedown/touchstart pada item (sebelum drag)
onDragStart	itemId	Drag dimulai (setelah melewati threshold 5px)
onDrag	itemId, x, y	Kursor bergerak saat drag aktif
onDrop	itemId, newDepth, orderData, isBinded	Item di-drop

State Callbacks

Callback	Parameters	Deskripsi
onChange	orderData	Setiap ada perubahan data (drag, delete)
onToggle	itemId, isNowCollapsed	Collapse/expand di-toggle
onBind	itemId, isNowBinded	Bind/unbind di-toggle
onCollapseAll	-	Semua node di-collapse
onExpandAll	-	Semua node di-expand

Delete Lifecycle

Penghapusan item memiliki dua fase callback untuk validasi dan post-processing.

1. onDelete(itemId, itemsToDelete) — Validation Gate

Dipanggil SEBELUM penghapusan. Return false untuk membatalkan.

onDelete: function(itemId, itemsToDelete) {
  if (itemId === 'protected-id') {
    return false; // Batalkan penghapusan!
  }
}

2. onDeleteComplete(itemId, deletedIds) — Post-Processing

Dipanggil SETELAH penghapusan berhasil. Cocok untuk sinkronisasi ke server.

onDeleteComplete: function(itemId, deletedIds) {
  $.post('/api/delete', { ids: deletedIds });
}

Standard Response ds.deleteItem()

var response = ds.deleteItem('102');

console.log(response);
// {
//   success: true,
//   status: 'success' | 'cancelled' | 'error',
//   message: '3 item(s) deleted successfully',
//   data: {
//     deletedIds: ['102', '103', '104'],
//     deletedCount: 3
//   }
// }

🎨 CSS & Styling

Plugin ini memisahkan CSS inti dan CSS halaman demo untuk portabilitas maksimal.

File CSS

File	Keterangan
src/css/dragsort.css	Wajib. Style inti plugin, variabel desain, dan state animasi.
src/css/index.css	Opsional. Hanya untuk layout halaman demo.
src/css/toast.css	Opsional. Style untuk notifikasi toast.

Customization (Design Tokens)

Anda dapat mengoverride variabel CSS di project Anda tanpa memodifikasi file inti plugin:

:root {
  --bg: #F8FAFC;
  --accent: #2563EB;
  --border: #E2E8F0;
  --shadow-drag: 0 25px 50px -12px rgba(0,0,0,0.12);
  /* ... variabel lainnya ... */
}

📂 Struktur File

dragsort/
│
├── index.html                # Halaman demo / test page
├── README.md                 # Dokumentasi proyek (file ini)
│
└── src/
    ├── css/
    │   ├── dragsort.css      # Core plugin styles (Wajib)
    │   ├── index.css         # Demo page styles
    │   └── toast.css         # Toast notification styles
    │
    └── js/
        ├── dragsort.js       # Core plugin logic (Wajib)
        └── toast.js          # Toast notification logic

🛡️ License

Atribut :

• Repository: https://github.com/haritsnb/dragsort
• Email Kontak: business.haritsnb@gmail.com

Lisensi : MIT License