v3.3.4 - Development to Master (#1799)

* Add SetFilterDefaultValue to DateRange Filter (#1796)

---------

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

* Add Localised Pills for DateRangeFilter

---------

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

* Tidying Filters - Migrating Carbon usage into Trait, Adding Lifecycle Hooks (#1798)

* Tweaks to handle dates centrally

* Add localisation for DateFilter, DateTimeFilter, migrate DateRangeFilter to use Core Trait

* Add Filter Lifecycle Hooks

* Add Search Lifecycle Hook

* Update DateFilter, DateTimeFilter validate returns

* Update DateRangeFilterTest

* Add Pills Locale Tests to DateTests

* Remove superfluous method

---------

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

* Update ChangeLog

* Update docs for setPillsLocale (#1800)

---------

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

Author: lrljoe

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `laravel-livewire-tables` will be documented in this file
 
+## [v3.3.4] - 2024-07-27
+### New Features
+- Added capability to setFilterDefaultValue for a DateRangeFilter by @lrljoe in https://github.com/rappasoft/laravel-livewire-tables/pull/1796
+- Add localised pill values for DateFilter, DateTimeFilter, DateRangeFilter by @lrljoe in https://github.com/rappasoft/laravel-livewire-tables/pull/1797
+
+### Tweaks
+- Migrating Carbon usage into Trait, Adding Filter/Search Lifecycle Hooks by @lrljoe in https://github.com/rappasoft/laravel-livewire-tables/pull/1798
+
 ## [v3.3.3] - 2024-07-23
 ### New Features
 - Add additional DateRangeFilter options by @lrljoe in https://github.com/rappasoft/laravel-livewire-tables/pull/1793

docs/filter-types/filters-date.md

@@ -33,6 +33,7 @@ public function filters(): array
 }
 ```
 
+## setFilterDefaultValue
 Date filters also support the setFilterDefaultValue() method, which must be a valid date in the "Y-m-d" format.  This will apply as a default until removed.
 ```php
 public function filters(): array
@@ -47,5 +48,22 @@ public function filters(): array
     ];
 }
 ```
-                    
+
+## setPillsLocale        
+Date Filters also support the setPillsLocale method, which allows you to set a locale for use in generating the Filter Pills values
+```php
+public function filters(): array
+{
+    return [
+        DateFilter::make('Verified From')
+            ->setPillsLocale('fr ') // Use French localisation for the Filter Pills values
+            ->config([
+                'min' => '2020-01-01',  // Earliest Acceptable Date
+                'max' => '2021-12-31', // Latest Acceptable Date
+                'pillFormat' => 'd M Y', // Format for use in Filter Pills
+                'placeholder' => 'Enter Date', // A placeholder value
+            ])
+    ];
+}
+```
 

docs/filter-types/filters-daterange.md

@@ -66,6 +66,52 @@ A full list of options is below, please see the Flatpickr documentation for refe
 | time_24hr | Boolean | false | Displays time picker in 24 hour mode without AM/PM selection when enabled. | 
 | weekNumbers | Boolean | false | Enables display of week numbers in calendar. | 
 
+## setFilterDefaultValue
+
+You may use this to set a default value for the filter that will be applied on first load (but may be cleared by the user).  This should be an array:
+
+```
+    DateRangeFilter::make('EMail Verified Range')
+        ->setFilterDefaultValue(['minDate' => '2024-05-05', 'maxDate' => '2024-06-06'])
+```
+or
+```
+    DateRangeFilter::make('EMail Verified Range')
+        ->setFilterDefaultValue(['min' => '2024-05-05', 'max' => '2024-06-06'])
+```
+or
+```
+    DateRangeFilter::make('EMail Verified Range')
+        ->setFilterDefaultValue(['2024-05-05', '2024-06-06'])
+```
+
+## setPillsLocale
+DateRange Filters also support the setPillsLocale method, which allows you to set a locale for use in generating the Filter Pills values
+```php
+public function filters(): array
+{
+    return [
+        DateRangeFilter::make('EMail Verified Range')
+        ->setPillsLocale('fr ') // Use French localisation for the Filter Pills values
+        ->config([
+            'allowInput' => true,   // Allow manual input of dates
+            'altFormat' => 'F j, Y', // Date format that will be displayed once selected
+            'ariaDateFormat' => 'F j, Y', // An aria-friendly date format
+            'dateFormat' => 'Y-m-d', // Date format that will be received by the filter
+            'earliestDate' => '2020-01-01', // The earliest acceptable date
+            'latestDate' => '2023-08-01', // The latest acceptable date
+            'placeholder' => 'Enter Date Range', // A placeholder value
+            'locale' => 'en',
+        ])
+        ->setFilterPillValues([0 => 'minDate', 1 => 'maxDate']) // The values that will be displayed for the Min/Max Date Values
+        ->filter(function (Builder $builder, array $dateRange) { // Expects an array.
+            $builder
+                ->whereDate('users.email_verified_at', '>=', $dateRange['minDate']) // minDate is the start date selected
+                ->whereDate('users.email_verified_at', '<=', $dateRange['maxDate']); // maxDate is the end date selected
+        }),
+    ];
+}
+```
 
 ## Configuration
 By default, this filter will inject the Flatpickr JS Library and CSS. However, you can customise this behaviour using the configuration file.

docs/filter-types/filters-datetime.md

@@ -33,6 +33,7 @@ public function filters(): array
 }
 ```
 
+## setFilterDefaultValue
 DateTime filters also support the setFilterDefaultValue() method, which must be a valid datetime in the "Y-m-dTH:i" format.  This will apply as a default until removed.
 ```php
 public function filters(): array
@@ -47,6 +48,23 @@ public function filters(): array
             ->setFilterDefaultValue('2023-07-07T06:27')
     ];
 }
+```        
+
+## setPillsLocale        
+DateTime Filters also support the setPillsLocale method, which allows you to set a locale for use in generating the Filter Pills values
+```php
+public function filters(): array
+{
+    return [
+        DateTimeFilter::make('Verified From')
+            ->setPillsLocale('fr ') // Use French localisation for the Filter Pills values
+            ->config([
+                'min' => '2020-01-01',  // Earliest Acceptable Date
+                'max' => '2021-12-31', // Latest Acceptable Date
+                'pillFormat' => 'd M Y - H:i', // Format for use in Filter Pills
+                'placeholder' => 'Enter Date', // A placeholder value
+            ])
+    ];
+}
 ```
-                    
 

docs/misc/lifecycle-hooks.md

@@ -22,6 +22,24 @@ This is called immediately after the Columns are set up
 ## rowsRetrieved
 This is called immediately after the query is executed, and is passed the result from the executed query.
 
+## searchUpdated
+This is called whenever the search is updated, and is passed the value that has been searched for
+
+## filterApplying
+This is called whenever a Filter is applying
+
+## filterReset
+This is called whenever a Filter is reset
+
+## filterSet
+This is called whenever a Filter is set
+
+## filterUpdated
+This is called whenever a Filter is updated/used
+
+## filterRemoved
+This is called whenever a Filter is removed from the table
+
 ## Use in Traits
 To use these in a trait, allowing you to easily set defaults across multiple tables, you should ensure that you append the Lifecycle Hook with your trait name, e.g.
 

src/Commands/MakeCommand.php

@@ -63,7 +63,7 @@ public function handle(): void
             $this->argument('name')
         );
 
-        $livewireMakeCommand = new LivewireMakeCommand();
+        $livewireMakeCommand = new LivewireMakeCommand;
 
         if ($livewireMakeCommand->isReservedClassName($name = $this->parser->className())) {
             $this->line("<fg=red;options=bold>Class is reserved:</> {$name}");
@@ -184,7 +184,7 @@ private function getClassesList(string $file): array
      */
     private function generateColumns(string $modelName): string
     {
-        $model = new $modelName();
+        $model = new $modelName;
 
         if ($model instanceof Model === false) {
             throw new \Exception('Invalid model given.');

src/Traits/Helpers/FilterHelpers.php

@@ -135,6 +135,10 @@ public function getFilterByKey(string $key)
     public function setFilter(string $filterKey, mixed $value): void
     {
         $this->appliedFilters[$filterKey] = $this->filterComponents[$filterKey] = $value;
+
+        $this->callHook('filterSet', ['filter' => $filterKey, 'value' => $value]);
+        $this->callTraitHook('filterSet', ['filter' => $filterKey, 'value' => $value]);
+
     }
 
     public function selectAllFilterOptions(string $filterKey): void
@@ -238,6 +242,8 @@ public function resetFilter($filter): void
         if (! $filter instanceof Filter) {
             $filter = $this->getFilterByKey($filter);
         }
+        $this->callHook('filterReset', ['filter' => $filter->getKey()]);
+        $this->callTraitHook('filterReset', ['filter' => $filter->getKey()]);
 
         $this->setFilter($filter->getKey(), $filter->getDefaultValue());
     }

src/Traits/WithFilters.php

@@ -61,6 +61,9 @@ public function applyFilters(): Builder
                             continue;
                         }
 
+                        $this->callHook('filterApplying', ['filter' => $filter->getKey(), 'value' => $value]);
+                        $this->callTraitHook('filterApplying', ['filter' => $filter->getKey(), 'value' => $value]);
+
                         ($filter->getFilterCallback())($this->getBuilder(), $value);
                     }
                 }
@@ -84,7 +87,14 @@ public function updatedFilterComponents(string|array|null $value, string $filter
         $filter = $this->getFilterByKey($filterName);
 
         if ($filter && $filter->isEmpty($value)) {
+            $this->callHook('filterRemoved', ['filter' => $filter->getKey()]);
+            $this->callTraitHook('filterRemoved', ['filter' => $filter->getKey()]);
+
             $this->resetFilter($filterName);
+        } elseif ($filter) {
+            $this->callHook('filterUpdated', ['filter' => $filter->getKey(), 'value' => $value]);
+            $this->callTraitHook('filterUpdated', ['filter' => $filter->getKey(), 'value' => $value]);
+
         }
     }
 }

src/Traits/WithSearch.php

@@ -50,6 +50,9 @@ public function applySearch(): Builder
         if ($this->searchIsEnabled() && $this->hasSearch()) {
             $searchableColumns = $this->getSearchableColumns();
 
+            $this->callHook('searchUpdated', ['value' => $this->getSearch()]);
+            $this->callTraitHook('searchUpdated', ['value' => $this->getSearch()]);
+
             if ($searchableColumns->count()) {
                 $this->setBuilder($this->getBuilder()->where(function ($query) use ($searchableColumns) {
                     foreach ($searchableColumns as $index => $column) {

src/Views/Filters/DateFilter.php

@@ -2,14 +2,14 @@
 
 namespace Rappasoft\LaravelLivewireTables\Views\Filters;
 
-use DateTime;
 use Rappasoft\LaravelLivewireTables\Views\Filter;
 use Rappasoft\LaravelLivewireTables\Views\Traits\Core\HasWireables;
-use Rappasoft\LaravelLivewireTables\Views\Traits\Filters\{HasConfig, IsStringFilter};
+use Rappasoft\LaravelLivewireTables\Views\Traits\Filters\{HandlesDates, HasConfig, IsStringFilter};
 
 class DateFilter extends Filter
 {
-    use HasConfig,
+    use HandlesDates,
+        HasConfig,
         IsStringFilter;
     use HasWireables;
 
@@ -21,17 +21,16 @@ class DateFilter extends Filter
 
     public function validate(string $value): string|bool
     {
-        if (DateTime::createFromFormat('Y-m-d', $value) === false) {
-            return false;
-        }
+        $this->setInputDateFormat('Y-m-d')->setOutputDateFormat($this->getConfig('pillFormat') ?? 'Y-m-d');
+        $carbonDate = $this->createCarbonDate($value);
 
-        return $value;
+        return ($carbonDate === false) ? false : $carbonDate->format('Y-m-d');
     }
 
     public function getFilterPillValue($value): string|array|null
     {
         if ($this->validate($value)) {
-            return DateTime::createFromFormat('Y-m-d', $value)->format($this->getConfig('pillFormat'));
+            return $this->outputTranslatedDate($this->createCarbonDate($value));
         }
 
         return null;