Additional Events & Customisable Behaviour (#1820)

* Initial Commit - Adding Customisable Events

* Utilise Core LaravelLivewireTablesEvent to simplify

* Ensure defaults can be overridden

* Add additional Events Tests

* Add tests to ensure that User is passed into the Events

---------

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

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();
+}
+```

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();
+
+    }
+}

src/Traits/Configuration/EventConfiguration.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace Rappasoft\LaravelLivewireTables\Traits\Configuration;
+
+trait EventConfiguration
+{
+    public function setEventStatus(string $event, bool $status): self
+    {
+        $this->eventStatuses[$event] = $status;
+
+        return $this;
+    }
+
+    public function enableEvent(string $event): self
+    {
+        $this->setEventStatus($event, true);
+
+        return $this;
+    }
+
+    public function disableEvent(string $event): self
+    {
+        $this->setEventStatus($event, false);
+
+        return $this;
+    }
+
+    public function enableColumnSelectEvent(): self
+    {
+        $this->enableEvent('columnSelected');
+
+        return $this;
+    }
+
+    public function disableColumnSelectEvent(): self
+    {
+        $this->disableEvent('columnSelected');
+
+        return $this;
+    }
+
+    public function enableSearchAppliedEvent(): self
+    {
+        $this->enableEvent('searchApplied');
+
+        return $this;
+    }
+
+    public function disableSearchAppliedEvent(): self
+    {
+        $this->disableEvent('searchApplied');
+
+        return $this;
+    }
+
+    public function enableFilterAppliedEvent(): self
+    {
+        $this->enableEvent('filterApplied');
+
+        return $this;
+    }
+
+    public function disableFilterAppliedEvent(): self
+    {
+        $this->disableEvent('filterApplied');
+
+        return $this;
+    }
+
+    public function enableAllEvents(): self
+    {
+        foreach ($this->getEventNames() as $eventName) {
+            $this->enableEvent($eventName);
+        }
+
+        return $this;
+    }
+
+    public function disableAllEvents(): self
+    {
+        foreach ($this->getEventNames() as $eventName) {
+            $this->disableEvent($eventName);
+        }
+
+        return $this;
+    }
+}

src/Traits/Helpers/ColumnSelectHelpers.php

@@ -159,14 +159,18 @@ public function selectAllColumns(): void
             $this->selectedColumns[] = $column->getSlug();
         }
         $this->forgetColumnSelectSession();
-        event(new ColumnsSelected($this->getColumnSelectSessionKey(), $this->selectedColumns));
+        if ($this->getEventStatusColumnSelect()) {
+            event(new ColumnsSelected($this->getTableName(), $this->getColumnSelectSessionKey(), $this->selectedColumns));
+        }
     }
 
     public function deselectAllColumns(): void
     {
         $this->selectedColumns = [];
         session([$this->getColumnSelectSessionKey() => []]);
-        event(new ColumnsSelected($this->getColumnSelectSessionKey(), $this->selectedColumns));
+        if ($this->getEventStatusColumnSelect()) {
+            event(new ColumnsSelected($this->getTableName(), $this->getColumnSelectSessionKey(), $this->selectedColumns));
+        }
     }
 
     public function allVisibleColumnsAreSelected(): bool