introduce ability to pin specific records

Author: Herbert Maschke

README.md

@@ -314,6 +314,30 @@ public function getExportStylesProperty()
     }
 ```
 
+### Pin Records
+
+If you want to give your users the ability to pin specific records to be able to, for example, compare
+them with each other, you can use the CanPinRecords trait. Ensure to have at least one Checkbox Column
+so the user can select records:
+
+```php
+use Mediconesystems\LivewireDatatables\Traits\CanPinRecords;
+
+class RecordTable extends LivewireDatatable
+{
+    use CanPinRecords;
+
+    public $model = Record::class;
+
+    public function columns()
+    {
+        return [
+            Column::checkbox(),
+
+            // ...
+
+```
+
 ### Custom column names
 It is still possible to take full control over your table, you can define a ```builder``` method using whatever query you like, using your own joins, groups whatever, and then name your columns using your normal SQL syntax:
 
@@ -343,7 +367,6 @@ public function columns()
 
 ```
 
-
 ### Callbacks
 Callbacks give you the freedom to perform any mutations you like on the data before displaying in the table.
 - The callbacks are performed on the paginated results of the database query, so shouldn't use a ton of memory

resources/views/livewire/datatables/checkbox.blade.php

@@ -1,3 +1,9 @@
 <div class="flex justify-center">
-    <input type="checkbox" wire:model="selected" value="{{ $value }}" class="form-checkbox mt-1 h-4 w-4 text-blue-600 transition duration-150 ease-in-out" />
+    <input
+        type="checkbox"
+        wire:model="selected"
+        value="{{ $value }}"
+        @if (in_array($value, $this->pinnedRecords)) checked @endif
+        class="w-4 h-4 mt-1 text-blue-600 form-checkbox transition duration-150 ease-in-out"
+    />
 </div>

resources/views/livewire/datatables/datatable.blade.php

@@ -121,22 +121,7 @@ class="px-3 py-2 text-xs font-medium tracking-wider text-green-500 uppercase bg-
                                 @endif
                             @endforeach
                         </div>
-
-                        <div class="table-row bg-blue-100 divide-x divide-blue-200">
-                            @foreach($this->columns as $index => $column)
-                                @if($column['hidden'])
-                                    @if($hideable === 'inline')
-                                        <div class="table-cell w-5 overflow-hidden align-top bg-blue-100"></div>
-                                    @endif
-                                @elseif($column['type'] === 'checkbox')
-                                    @include('datatables::filters.checkbox')
-                                @endunless
-                            @else
-                                @include('datatables::header-no-hide', ['column' => $column, 'sort' => $sort])
-                            @endif
-                        @endforeach
-                    </div>
-
+                    @endunless
                     <div class="table-row bg-blue-100 divide-x divide-blue-200">
                         @foreach($this->columns as $index => $column)
                             @if($column['hidden'])
@@ -166,7 +151,6 @@ class="px-3 py-2 text-xs font-medium tracking-wider text-green-500 uppercase bg-
                                 @endif
                             @endforeach
                         </div>
-                    @endif
                     @forelse($this->results as $row)
                         <div class="table-row p-1 {{ $this->rowClasses($row, $loop) }}">
                             @foreach($this->columns as $column)

src/Http/Livewire/LivewireDatatable.php

@@ -151,6 +151,7 @@ public function applyToTable($options)
             'activeNumberFilters',
             'hide',
             'selected',
+            'pinnedRecords',
         ] as $property) {
             if (isset($options[$property])) {
                 $this->$property = $options[$property];
@@ -178,6 +179,9 @@ public function resetTable()
         $this->hide = null;
         $this->resetHiddenColumns();
         $this->selected = [];
+        if (isset($this->pinnedRecords)) {
+            $this->pinnedRecords = [];
+        }
     }
 
     /**
@@ -245,6 +249,10 @@ public function mount(
         $this->initialisePerPage();
         $this->initialiseColumnGroups();
         $this->model = $this->model ?: get_class($this->builder()->getModel());
+
+        if (isset($this->pinnedRecords)) {
+            $this->initialisePinnedRecords();
+        }
     }
 
     // save settings
@@ -1502,6 +1510,9 @@ public function addTimeRangeFilter()
     public function addSort()
     {
         if (isset($this->sort) && isset($this->freshColumns[$this->sort]) && $this->freshColumns[$this->sort]['name']) {
+            if (isset($this->pinnedRecords) && $this->pinnedRecords) {
+                $this->query->orderBy(DB::raw('FIELD(id,' . implode(',', $this->pinnedRecords) . ')'), 'DESC');
+            }
             $this->query->orderBy(DB::raw($this->getSortString()), $this->direction ? 'asc' : 'desc');
         }
 
@@ -1793,6 +1804,5 @@ public function massActionOptionHandler()
         }
 
         $this->massActionOption = null;
-        $this->selected = [];
     }
 }

src/Traits/CanPinRecords.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace Mediconesystems\LivewireDatatables\Traits;
+
+use Mediconesystems\LivewireDatatables\Action;
+
+/**
+ * Use this trait to enable the functionality to pin specific records to the
+ * top of the table.
+ *
+ * Ensure to;
+ *
+ * 1) have at least one Checkbox Column in your table
+ * 2) have session storage activated (it is by default)
+ * 3) to enable the mass bulk action dropdown as described in:
+ *
+ * @link https://github.com/MedicOneSystems/livewire-datatables#mass-bulk-action
+ */
+trait CanPinRecords
+{
+    public array $pinnedRecords = [];
+
+    public string $sessionKeyPrefix = '_pinned_records';
+
+    public function buildActions()
+    {
+        return array_merge(parent::buildActions() ?? [], [
+            Action::value('pin')
+                ->label(__('Pin selected Records'))
+                ->callback(function ($mode, $items) {
+                    $this->pinnedRecords = array_merge($this->pinnedRecords, $items);
+                    $this->selected = $this->pinnedRecords;
+
+                    session()->put($this->sessionKey(), $this->pinnedRecords);
+                }),
+
+            Action::value('unpin')
+                ->label(__('Unpin selected Records'))
+                ->callback(function ($mode, $items) {
+                    $this->pinnedRecords = array_diff($this->pinnedRecords, $items);
+                    $this->selected = $this->pinnedRecords;
+
+                    session()->put($this->sessionKey(), $this->pinnedRecords);
+                }),
+        ]);
+    }
+
+    protected function initialisePinnedRecords()
+    {
+        if (session()->has($this->sessionKey())) {
+            $this->pinnedRecords = session()->get($this->sessionKey());
+        }
+
+        $this->selected = $this->pinnedRecords;
+    }
+
+    private function sessionKey(): string
+    {
+        return $this->sessionStorageKey() . $this->sessionKeyPrefix;
+    }
+}