Merge pull request #220 from rappasoft/develop

v1.1

Author: rappasoft

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `laravel-livewire-tables` will be documented in this file
 
 ## [Unreleased]
 
+## [1.1.0] - 2021-04-21
+
+### Added
+
+- Added callback to column's sortable() method to customize sorting functionality per column. (https://github.com/rappasoft/laravel-livewire-tables/pull/216)
+- Support for polling `keep-alive` and `visible`.
+- Start of a test suite (https://github.com/rappasoft/laravel-livewire-tables/pull/218)
+
+### Changed
+
+- Updated Tailwind search clear button (https://github.com/rappasoft/laravel-livewire-tables/pull/217).
+- Updated readme
+
 ## [1.0.4] - 2021-04-18
 
 ### Added
@@ -192,7 +205,8 @@ All notable changes to `laravel-livewire-tables` will be documented in this file
 
 - Initial release
 
-[Unreleased]: https://github.com/rappasoft/laravel-livewire-tables/compare/v1.0.4...development
+[Unreleased]: https://github.com/rappasoft/laravel-livewire-tables/compare/v1.1.0...development
+[1.1.0]: https://github.com/rappasoft/laravel-livewire-tables/compare/v1.0.4...v1.1.0
 [1.0.4]: https://github.com/rappasoft/laravel-livewire-tables/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/rappasoft/laravel-livewire-tables/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/rappasoft/laravel-livewire-tables/compare/v1.0.1...v1.0.2

README.md

@@ -192,9 +192,9 @@ public function columns(): array
     {
         return [
             Column::make('Type') // Column text and optional column name, column name will be snake case of text if not defined
-                ->sortable() // Whether or not the heading can be clicked to sort
+                ->sortable(), // Whether or not the heading can be clicked to sort
             Column::make('Name')
-                ->sortable()
+                ->sortable(),
             Column::make('Permissions'),
             Column::make('Other', 'my_other_column')
                 ->sortable() // Allows the column to interact with the sorting methods
@@ -204,6 +204,17 @@ public function columns(): array
     }
 ```
 
+#### Customizing Sort Behavior
+
+If you need more control over the sort behavior of a column, you can pass a callback to the sortable() method:
+
+```php
+Column::make(__('Address'))
+    ->sortable(function(Builder $query, $direction) {
+        return $query->orderBy(UserAttribute::select('address')->whereColumn('user_attributes.user_id', 'users.id'), $direction);
+    })
+```
+
 #### Configuring Sort Names
 
 When clicking sortable column headers, the component will use the column name to define the sorting pill in the UI, if you don't like the way the name is rendered, you can overwrite it:
@@ -392,7 +403,7 @@ There are some class level properties you can set:
 | $searchFilterDebounce | null | null/int | Adds a debounce of `$searchFilterDebounce` ms to the search input |
 | $searchFilterDefer | null | null/bool | Adds `.defer` to the search input |
 | $searchFilterLazy | null | null/bool | Adds `.lazy` to the search input |
-| $refresh | false | false/int/string | Whether or not to refresh the table at a certain interval. false = off, int = ms, string = functionCall |
+| $refresh | false | false/int/string | Whether or not to refresh the table at a certain interval. false = off, int = ms, string = functionCall (if the string is `keep-alive` it will use `wire:poll.keep-alive`, if the string is `visible` it will use `wire:poll.visible`) |
 | $offlineIndicator | true | bool | Shows a red banner when there is no internet connection. |
 
 #### Using more than one table on a page
@@ -427,13 +438,6 @@ use Rappasoft\LaravelLivewireTables\Views\Filter;
 class UsersTable extends DataTableComponent
 {
 
-    public array $filters = [
-        'type' => null,
-        'active' => null,
-        'verified' => null,
-        '2fa' => null,
-    ];
-
     public array $sortNames = [
         'email_verified_at' => 'Verified',
         'two_factor_secret' => '2FA',
@@ -618,11 +622,18 @@ The final result would look like:
 
 - [x] Bootstrap 4 Template
 - [x] Bootstrap 5 Template
-- [ ] Sorting By Relationships
-- [ ] Test Suite
+- [x] Sorting By Relationships
+- [ ] Collection/Query Support  
+- [ ] Test Suite (WIP)
 - [ ] Column Search
 - [ ] Greater Configurability
 
+## Testing
+
+```bash
+composer test
+```
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

composer.json

@@ -24,6 +24,7 @@
         "illuminate/contracts": "^8.0"
     },
     "require-dev": {
+        "ext-sqlite3": "*",
         "orchestra/testbench": "^6.13",
         "phpunit/phpunit": "^9.3",
         "spatie/laravel-ray": "^1.9",

database/migrations/create_test_tables.php.stub

@@ -0,0 +1,39 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+class CreateTestTables extends Migration
+{
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up()
+    {
+        Schema::create('species', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+        });
+
+        Schema::create('breeds', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->integer('species_id')->unsigned();
+            $table->foreign('species_id')->references('id')->on('species');
+        });
+
+        Schema::create('pets', function (Blueprint $table) {
+            $table->id();
+            $table->string('name')->index();
+            $table->string('age')->nullable();
+            $table->date('last_visit')->nullable();
+            $table->integer('species_id')->unsigned()->nullable();
+            $table->integer('breed_id')->unsigned()->nullable();
+            $table->foreign('species_id')->references('id')->on('species');
+            $table->foreign('breed_id')->references('id')->on('breeds');
+        });
+    }
+}

resources/views/bootstrap-4/datatable.blade.php

@@ -1,5 +1,15 @@
 <div
-    @if (is_numeric($refresh)) wire:poll.{{ $refresh }}ms @elseif(is_string($refresh)) wire:poll="{{ $refresh }}" @endif
+    @if (is_numeric($refresh))
+        wire:poll.{{ $refresh }}ms
+    @elseif(is_string($refresh))
+        @if ($refresh === '.keep-alive' || $refresh === 'keep-alive')
+            wire:poll.keep-alive
+        @elseif($refresh === '.visible' || $refresh === 'visible')
+            wire:poll.visible
+        @else
+            wire:poll="{{ $refresh }}"
+        @endif
+    @endif
     class="container-fluid"
 >
     @include('livewire-tables::bootstrap-4.includes.offline')

resources/views/bootstrap-5/datatable.blade.php

@@ -1,5 +1,15 @@
 <div
-    @if (is_numeric($refresh)) wire:poll.{{ $refresh }}ms @elseif(is_string($refresh)) wire:poll="{{ $refresh }}" @endif
+    @if (is_numeric($refresh))
+        wire:poll.{{ $refresh }}ms
+    @elseif(is_string($refresh))
+        @if ($refresh === '.keep-alive' || $refresh === 'keep-alive')
+            wire:poll.keep-alive
+        @elseif($refresh === '.visible' || $refresh === 'visible')
+            wire:poll.visible
+        @else
+            wire:poll="{{ $refresh }}"
+        @endif
+    @endif
     class="container-fluid"
 >
     @include('livewire-tables::bootstrap-5.includes.offline')

resources/views/tailwind/datatable.blade.php

@@ -1,5 +1,15 @@
 <div
-    @if (is_numeric($refresh)) wire:poll.{{ $refresh }}ms @elseif(is_string($refresh)) wire:poll="{{ $refresh }}" @endif
+    @if (is_numeric($refresh))
+        wire:poll.{{ $refresh }}ms
+    @elseif(is_string($refresh))
+        @if ($refresh === '.keep-alive' || $refresh === 'keep-alive')
+            wire:poll.keep-alive
+        @elseif($refresh === '.visible' || $refresh === 'visible')
+            wire:poll.visible
+        @else
+            wire:poll="{{ $refresh }}"
+        @endif
+    @endif
 >
     @include('livewire-tables::tailwind.includes.offline')
 

resources/views/tailwind/includes/search.blade.php

@@ -8,8 +8,8 @@ class="flex-1 shadow-sm border-cool-gray-300 block w-full transition duration-15
         />
 
         @if (isset($filters['search']) && strlen($filters['search']))
-            <span class="inline-flex items-center px-3 rounded-r-md border border-l-0 border-gray-300 bg-gray-50 text-gray-500 sm:text-sm">
-                <svg wire:click="$set('filters.search', null)" xmlns="http://www.w3.org/2000/svg" class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <span wire:click="$set('filters.search', null)" class="inline-flex items-center px-3 rounded-r-md border border-l-0 border-gray-300 bg-gray-50 text-gray-500 cursor-pointer sm:text-sm">
+                <svg xmlns="http://www.w3.org/2000/svg" class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
                   <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
                 </svg>
             </span>

src/DataTableComponent.php

@@ -68,7 +68,7 @@ abstract class DataTableComponent extends Component
      * Whether or not to refresh the table at a certain interval
      * false is off
      * If it's an integer it will be treated as milliseconds (2000 = refresh every 2 seconds)
-     * If it's a string it will call that function every 5 seconds.
+     * If it's a string it will call that function every 5 seconds unless it is 'keep-alive' or 'visible'.
      *
      * @var bool|string
      */
@@ -190,4 +190,18 @@ public function render()
                 'rows' => $this->rows,
             ]);
     }
+
+    /**
+     * Get a column object by its field
+     *
+     * @param  string  $column
+     *
+     * @return mixed
+     */
+    protected function getColumn(string $column)
+    {
+        return collect($this->columns())
+            ->where('column', $column)
+            ->first();
+    }
 }

src/Traits/WithSorting.php

@@ -30,7 +30,11 @@ public function sortBy(string $field): ?string
     public function applySorting(Builder $query): Builder
     {
         foreach ($this->sorts as $field => $direction) {
-            $query->orderBy($field, $direction);
+            if (optional($this->getColumn($field))->hasSortCallback()) {
+                $query = app()->call($this->getColumn($field)->getSortCallback(), ['query' => $query, 'direction' => $direction]);
+            } else {
+                $query->orderBy($field, $direction);
+            }
         }
 
         return $query;