3.4.2 Release (rappasoft#1824)

## [v3.4.2] - 2024-08-04
### New Features
- Additional Events & Customisable Behaviour by @lrljoe in rappasoft#1820

### Bug Fixes
- Typehinting to allow events to be used to update Multi-Value Filters by @lrljoe in rappasoft#1822

### Tweaks
- Add missing ReturnTypes by @lrljoe in rappasoft#1823
- Removing old $listeners approach, now using the Livewire v3 On attribute by @lrljoe in rappasoft#1821


---------

Co-authored-by: lrljoe <[email protected]>

Author: lrljoe

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `laravel-livewire-tables` will be documented in this file
 
+## [v3.4.2] - 2024-08-04
+### New Features
+- Additional Events & Customisable Behaviour by @lrljoe in https://github.com/rappasoft/laravel-livewire-tables/pull/1820
+
+### Bug Fixes
+- Typehinting to allow events to be used to update Multi-Value Filters by @lrljoe in https://github.com/rappasoft/laravel-livewire-tables/pull/1822
+
+### Tweaks
+- Add missing ReturnTypes by @lrljoe in https://github.com/rappasoft/laravel-livewire-tables/pull/1823
+- Removing old $listeners approach, now using the Livewire v3 On attribute by @lrljoe in https://github.com/rappasoft/laravel-livewire-tables/pull/1821
+
 ## [v3.4.1] - 2024-08-04
 ### Bug Fixes
 - Fix ViewComponentColumn issue with not accepting parameters cleanly by @lrljoe in https://github.com/rappasoft/laravel-livewire-tables/pull/1818

docs/datatable/events.md

@@ -3,44 +3,144 @@ title: Events
 weight: 2
 ---
 
-These are the available events on the datatable component that you can fire from your application:
+### Listened For
+These are the available events on the datatable component that you can fire from your application, or client-side
 
-### refreshDatatable
+#### refreshDatatable
 
 ```php
 $this->dispatch('refreshDatatable');
 ```
 
 Calls `$refresh` on the component. Good for updating from external sources or as an alternative to polling.
 
-### setSort
+#### setSort
 
 You can have the table sort a specific column:
 
 ```php
 $this->dispatch('setSort', 'name', 'asc');
 ```
 
-### clearSorts
+#### clearSorts
 
 You can clear all the applied sorts:
 
 ```php
 $this->dispatch('clearSorts');
 ```
 
-### setFilter
+#### setFilter
 
 You can have the table run a specific filter:
 
 ```php
 $this->dispatch('setFilter', 'status', '1');
 ```
 
-### clearFilters
+#### clearFilters
 
 You can have the table clear all filters:
 
 ```php
 $this->dispatch('clearFilters');
 ```
+
+### Dispatched
+
+There are several events, all in the Rappasoft\LaravelLivewireTables\Events namespace
+| Event Name | Event Purpose | Data Passed |
+| --- | --- | --- |
+| ColumnsSelected | Applied whenever a Column is selected/deselected from view | The Table Name ($tableName), Selected Columns ($value), Logged In User ($user) |
+| FilterApplied | Applied when a Filter is applied (not when removed) |  The Table Name ($tableName), Filter Key ($key), Filter Value ($value), Logged In User ($user) |
+| SearchApplied | Applied when a Search is applied (not when removed) | The Table Name ($tableName), Search Term ($value), Logged In User ($user) |
+
+By default, the Tables will dispatch an event when the Selected Columns is changed, you may customise this behaviour:
+
+#### enableAllEvents
+
+This enables all Dispatched Events.  This should be used with caution, as more events will be introduced in the future.
+
+```php
+public function configure(): void
+{
+  $this->enableAllEvents();
+}
+```
+
+#### disableAllEvents
+
+This disables all Dispatched Events.
+
+```php
+public function configure(): void
+{
+  $this->disableAllEvents();
+}
+```
+
+#### enableColumnSelectEvent
+
+Enables the Column Select Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+  $this->enableColumnSelectEvent();
+}
+```
+
+#### disableColumnSelectEvent
+
+Disables the Column Select Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+  $this->disableColumnSelectEvent();
+}
+```
+
+#### enableSearchAppliedEvent
+
+Enables the Search Applied Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+  $this->enableSearchAppliedEvent();
+}
+```
+
+#### disableSearchAppliedEvent
+
+Disables the Search Applied Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+  $this->disableSearchAppliedEvent();
+}
+```
+
+#### enableFilterAppliedEvent
+
+Enables the Filter Applied Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+  $this->enableFilterAppliedEvent();
+}
+```
+
+#### disableFilterAppliedEvent
+
+Disables the Filter Applied Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+  $this->disableFilterAppliedEvent();
+}
+```

phpstan.neon

@@ -6,7 +6,7 @@ parameters:
         - config
         - database
         - src
-    level: 5
+    level: 6
     tmpDir: build/phpstan
     checkOctaneCompatibility: true
     checkModelProperties: true

src/DataTableComponent.php

@@ -2,25 +2,18 @@
 
 namespace Rappasoft\LaravelLivewireTables;
 
+use Livewire\Attributes\On;
 use Livewire\Component;
 use Rappasoft\LaravelLivewireTables\Traits\HasAllTraits;
 
 abstract class DataTableComponent extends Component
 {
     use HasAllTraits;
 
-    /** @phpstan-ignore-next-line */
-    protected $listeners = [
-        'refreshDatatable' => '$refresh',
-        'setSort' => 'setSortEvent',
-        'clearSorts' => 'clearSortEvent',
-        'setFilter' => 'setFilterEvent',
-        'clearFilters' => 'clearFilterEvent',
-    ];
-
     /**
      * Runs on every request, immediately after the component is instantiated, but before any other lifecycle methods are called
      */
+    #[On('refreshDatatable')]
     public function boot(): void
     {
         //

src/Events/ColumnsSelected.php

@@ -5,17 +5,19 @@
 use Illuminate\Foundation\Events\Dispatchable;
 use Illuminate\Queue\SerializesModels;
 
-class ColumnsSelected
+class ColumnsSelected extends LaravelLivewireTablesEvent
 {
     use Dispatchable, SerializesModels;
 
     public array $columns;
 
-    public string $key;
-
-    public function __construct(string $key, array $columns)
+    public function __construct(string $tableName, string $key, array $columns = [])
     {
-        $this->key = $key;
+        $this->setTableForEvent($tableName)
+            ->setKeyForEvent($key)
+            ->setValueForEvent($columns)
+            ->setUserForEvent();
+
         $this->columns = $columns;
     }
 }

src/Events/FilterApplied.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Rappasoft\LaravelLivewireTables\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class FilterApplied extends LaravelLivewireTablesEvent
+{
+    use Dispatchable, SerializesModels;
+
+    public function __construct(string $tableName, string $key, string|array|null $value = null)
+    {
+        $this->setTableForEvent($tableName)
+            ->setKeyForEvent($key)
+            ->setValueForEvent($value)
+            ->setUserForEvent();
+
+    }
+}

src/Events/LaravelLivewireTablesEvent.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Rappasoft\LaravelLivewireTables\Events;
+
+use Illuminate\Foundation\Auth\User;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class LaravelLivewireTablesEvent
+{
+    use Dispatchable, SerializesModels;
+
+    public string $tableName;
+
+    public ?string $key;
+
+    public string|array|null $value;
+
+    public ?User $user;
+
+    public function setKeyForEvent(string $key): self
+    {
+        $this->key = $key;
+
+        return $this;
+    }
+
+    public function setValueForEvent(string|array $value): self
+    {
+        $this->value = $value;
+
+        return $this;
+
+    }
+
+    public function setTableForEvent(string $tableName): self
+    {
+        $this->tableName = $tableName;
+
+        return $this;
+    }
+
+    public function setUserForEvent(): self
+    {
+        if (auth()->user()) {
+            $this->user = auth()->user();
+        }
+
+        return $this;
+    }
+}

src/Events/SearchApplied.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Rappasoft\LaravelLivewireTables\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class SearchApplied extends LaravelLivewireTablesEvent
+{
+    use Dispatchable, SerializesModels;
+
+    public function __construct(string $tableName, string $value)
+    {
+        $this->setTableForEvent($tableName)
+            ->setValueForEvent($value)
+            ->setUserForEvent();
+
+    }
+}