Merge pull request #114 from sebastienheyd/feat/datatable-row-reorder

feat(datatables): add row reorder support with drag-and-drop

Author: sebastienheyd

docs/docs/8.x/datatables/options.md

@@ -42,6 +42,7 @@ class ExampleDatatable extends Datatable
 | [noSearching()](#nosearching) | visible | Disable searching |
 | [noInfo()](#noinfo) | visible | Disable table informations |
 | [locale()](#locale) | [] | Set different locale for generic buttons |
+| [rowReorder()](#rowreorder) | disabled | Enables drag-and-drop row reordering |
 
 ---
 
@@ -278,4 +279,67 @@ $this->locale([
 ])
 ```
 
-> Default locale can be found in the [`datatable.php`](https://github.com/sebastienheyd/boilerplate/blob/master/src/resources/lang/en/datatable.php) lang file.
+> Default locale can be found in the [`datatable.php`](https://github.com/sebastienheyd/boilerplate/blob/master/src/resources/lang/en/datatable.php) lang file.
+
+## rowReorder
+
+Enables drag-and-drop row reordering on the DataTable. When a row is dragged to a new position, an AJAX POST request is sent to persist the new order.
+
+```php
+$this->rowReorder('position')
+```
+
+Parameters:
+
+| parameter | default | description |
+| --- | --- | --- |
+| `$dataSrc` | `'order'` | The column data source used for ordering |
+| `$updateUrl` | `''` | Custom URL for the reorder AJAX call. If empty, uses the default route `boilerplate.datatables.reorder` |
+| `$fullRow` | `true` | If `true`, the whole row is draggable. If `false`, only the first cell is draggable |
+
+### Complete example
+
+```php
+use Sebastienheyd\Boilerplate\Datatables\Column;
+use Sebastienheyd\Boilerplate\Datatables\Datatable;
+use Illuminate\Http\JsonResponse;
+
+class TasksDatatable extends Datatable
+{
+    public $slug = 'tasks';
+
+    public function setUp()
+    {
+        $this->rowReorder('position')
+             ->order('position', 'asc');
+    }
+
+    public function columns(): array
+    {
+        return [
+            Column::add('Title')->data('title'),
+            Column::add('Position')->data('position')->hidden(),
+        ];
+    }
+
+    public function datasource()
+    {
+        return Task::query();
+    }
+
+    public function reorder(array $changes): JsonResponse
+    {
+        foreach ($changes as $change) {
+            Task::where('id', $change['id'])->update(['position' => $change['position']]);
+        }
+
+        return response()->json(['success' => true]);
+    }
+}
+```
+
+The `reorder()` method receives an array of changes, where each item contains:
+- `id`: the row identifier
+- `position`: the new value for the ordering column
+
+After a successful reorder, the DataTable automatically redraws to reflect the new order.

src/Controllers/DatatablesController.php

@@ -2,6 +2,7 @@
 
 namespace Sebastienheyd\Boilerplate\Controllers;
 
+use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use ReflectionException;
 
@@ -25,6 +26,32 @@ public function make(Request $request, string $slug)
         return $this->getDatatable($slug)->make();
     }
 
+    /**
+     * Handle row reorder request.
+     *
+     * @param  Request  $request
+     * @param  string  $slug
+     * @return JsonResponse
+     *
+     * @throws ReflectionException
+     */
+    public function reorder(Request $request, string $slug): JsonResponse
+    {
+        if (! $request->ajax()) {
+            abort(404);
+        }
+
+        $datatable = $this->getDatatable($slug);
+
+        if (! method_exists($datatable, 'reorder')) {
+            abort(404);
+        }
+
+        $datatable->setUp();
+
+        return $datatable->reorder($request->input('changes', []));
+    }
+
     /**
      * Get DataTable class for the given slug.
      *
@@ -33,7 +60,7 @@ public function make(Request $request, string $slug)
      *
      * @throws ReflectionException
      */
-    private function getDatatable(string $slug)
+    protected function getDatatable(string $slug)
     {
         $datatable = app('boilerplate.datatables')->load(app_path('Datatables'))->getDatatable($slug);
 

src/Datatables/Datatable.php

@@ -27,6 +27,8 @@ abstract class Datatable
     protected array $locale = [];
     protected array $permissions = ['backend_access'];
     protected array $orderAttr = [];
+    protected array $rowReorder = [];
+    protected string $rowReorderUrl = '';
     protected array $attributes = [
         'filters'        => true,
         'info'           => true,
@@ -383,6 +385,55 @@ public function stateSave(): Datatable
         return $this;
     }
 
+    /**
+     * Enables row reorder (drag-and-drop) on the DataTable.
+     *
+     * @param  string  $dataSrc  Column data source used for ordering
+     * @param  string  $updateUrl  URL for the reorder AJAX call
+     * @param  bool  $fullRow  If true, the whole row is draggable
+     * @return $this
+     */
+    public function rowReorder(string $dataSrc = 'order', string $updateUrl = '', bool $fullRow = true): Datatable
+    {
+        $this->rowReorder = [
+            'dataSrc'  => $dataSrc,
+            'selector' => $fullRow ? 'tr' : 'td:first-child',
+            'update'   => false,
+        ];
+
+        $this->rowReorderUrl = $updateUrl;
+
+        return $this;
+    }
+
+    /**
+     * Gets the rowReorder configuration as JSON string.
+     *
+     * @return string|null
+     */
+    public function getRowReorderConfig(): ?string
+    {
+        if (empty($this->rowReorder)) {
+            return null;
+        }
+
+        return json_encode($this->rowReorder);
+    }
+
+    /**
+     * Gets the rowReorder URL for AJAX updates.
+     *
+     * @return string
+     */
+    public function getRowReorderUrl(): string
+    {
+        if (! empty($this->rowReorderUrl)) {
+            return $this->rowReorderUrl;
+        }
+
+        return route('boilerplate.datatables.reorder', $this->slug, false);
+    }
+
     /**
      * Shows checkboxes as first column.
      *

src/resources/views/components/datatable.blade.php

@@ -55,7 +55,7 @@
         @endif
     </table>
 </div>
-@include('boilerplate::load.async.datatables', ['buttons' => true])
+@include('boilerplate::load.async.datatables', ['buttons' => true, 'rowReorder' => !empty($datatable->rowReorder)])
 @include('boilerplate::load.pusher')
 @component('boilerplate::minify')
 <script>
@@ -87,6 +87,9 @@
                 stateSaveParams: $.fn.dataTable.saveFiltersState,
                 stateLoadParams: $.fn.dataTable.loadFiltersState,
             @endif
+            @if($datatable->getRowReorderConfig())
+                rowReorder: {!! $datatable->getRowReorderConfig() !!},
+            @endif
             ajax: {
                 url: '{!! route('boilerplate.datatables', $datatable->slug, false) !!}',
                 type: 'post',
@@ -109,6 +112,32 @@
         });
 
         window.{{ \Str::camel($id) }}.locale = {!! $datatable->getLocale() !!}
+
+        @if($datatable->getRowReorderConfig())
+        window.{{ \Str::camel($id) }}.on('row-reorder', function(e, diff) {
+            if (!diff.length) return;
+            var changes = [];
+            for (var i = 0; i < diff.length; i++) {
+                var rowId = diff[i].node.id || window.{{ \Str::camel($id) }}.row(diff[i].node).data().id;
+                if (!rowId) continue;
+                changes.push({id: rowId, position: diff[i].newData});
+            }
+            $.ajax({
+                url: '{!! $datatable->getRowReorderUrl() !!}',
+                type: 'POST',
+                data: {_token: '{{ csrf_token() }}', changes: changes},
+                success: function() {
+                    window.{{ \Str::camel($id) }}.draw('full-hold');
+                },
+                error: function() {
+                    window.{{ \Str::camel($id) }}.draw('full-hold');
+                    if (typeof toastr !== 'undefined') {
+                        toastr.error(window.{{ \Str::camel($id) }}.locale.reorderError || 'An error occurred while reordering.');
+                    }
+                }
+            });
+        });
+        @endif
     });
 
     whenAssetIsLoaded('echo', () => {

src/routes/boilerplate.php

@@ -101,6 +101,7 @@
 
         // Datatables
         Route::post('datatables/{slug}', [DatatablesController::class, 'make'])->name('datatables');
+        Route::post('datatables/{slug}/reorder', [DatatablesController::class, 'reorder'])->name('datatables.reorder');
         Broadcast::channel('dt.{name}.{signature}', function ($user, $name, $signature) {
             return channel_hash_equals($signature, 'dt', $name);
         });