From 9ef4587014e9601fbc078f2ec63d602fe746fe31 Mon Sep 17 00:00:00 2001 From: Joe <104938042+lrljoe@users.noreply.github.com> Date: Sun, 8 Dec 2024 02:57:40 +0000 Subject: [PATCH] Add setFilterSlidedownWrapperAttributes and setFilterSlidedownRowAttributes (#2120) * Add setFilterSlidedownRowAttributes and setFilterSlidedownWrapperAttributes * Fix styling --------- Co-authored-by: lrljoe --- docs/filters/available-component-methods.md | 273 +++++++++ docs/filters/available-filter-methods.md | 289 ++++++++++ docs/filters/available-methods.md | 520 +----------------- docs/filters/creating-filters.md | 2 +- docs/filters/introduction.md | 2 +- .../toolbar/items/filter-slidedown.blade.php | 48 +- .../FilterMenuStylingConfiguration.php | 20 + src/Traits/Styling/HasFilterMenuStyling.php | 4 + .../Helpers/FilterMenuStylingHelpers.php | 28 + .../Styling/FilterSlidedownStylingTest.php | 92 ++++ 10 files changed, 740 insertions(+), 538 deletions(-) create mode 100644 docs/filters/available-component-methods.md create mode 100644 docs/filters/available-filter-methods.md create mode 100644 tests/Unit/Traits/Styling/FilterSlidedownStylingTest.php diff --git a/docs/filters/available-component-methods.md b/docs/filters/available-component-methods.md new file mode 100644 index 000000000..9a463edbf --- /dev/null +++ b/docs/filters/available-component-methods.md @@ -0,0 +1,273 @@ +--- +title: Available Component Methods +weight: 5 +--- + +These are the available filters configuration methods on the component. These are "table-wide" methods. + +--- + +Filters are **enabled by default** but will only show up if you have at least one defined. + +## setFiltersStatus + +Enable/disable filters for the whole component. + +```php +public function configure(): void +{ + $this->setFiltersStatus(true); + $this->setFiltersStatus(false); +} +``` + +## setFiltersEnabled + +Enable filters for the component. + +```php +public function configure(): void +{ + // Shorthand for $this->setFiltersStatus(true) + $this->setFiltersEnabled(); +} +``` + +## setFiltersDisabled + +Disable filters for the component. + +```php +public function configure(): void +{ + // Shorthand for $this->setFiltersStatus(false) + $this->setFiltersDisabled(); +} +``` + +--- + +## setFiltersVisibilityStatus + +**Enabled by default**, show/hide the filters dropdown. + +```php +public function configure(): void +{ + $this->setFiltersVisibilityStatus(true); + $this->setFiltersVisibilityStatus(false); +} +``` + +## setFiltersVisibilityEnabled + +Show the filters dropdown for the component. + +```php +public function configure(): void +{ + // Shorthand for $this->setFiltersVisibilityStatus(true) + $this->setFiltersVisibilityEnabled(); +} +``` + +## setFiltersVisibilityDisabled + +Hide the filters dropdown for the component. + +```php +public function configure(): void +{ + // Shorthand for $this->setFiltersVisibilityStatus(false) + $this->setFiltersVisibilityDisabled(); +} +``` + +--- + +## setFilterPillsStatus + +**Enabled by default**, show/hide the filter pills. + +```php +public function configure(): void +{ + $this->setFilterPillsStatus(true); + $this->setFilterPillsStatus(false); +} +``` + +## setFilterPillsEnabled + +Show the filter pills for the component. + +```php +public function configure(): void +{ + // Shorthand for $this->setFilterPillsStatus(true) + $this->setFilterPillsEnabled(); +} +``` + +## setFilterPillsDisabled + +Hide the filter pills for the component. + +```php +public function configure(): void +{ + // Shorthand for $this->setFilterPillsStatus(false) + $this->setFilterPillsDisabled(); +} +``` + +--- + +## setFilterLayout + +Set the filter layout for the component. + +```php +public function configure(): void +{ + $this->setFilterLayout('slide-down'); +} +``` + +## setFilterLayoutPopover + +Set the filter layout to popover. + +```php +public function configure(): void +{ + $this->setFilterLayoutPopover(); +} +``` + +Set the filter layout to slide down. + +## setFilterLayoutSlideDown + +```php +public function configure(): void +{ + $this->setFilterLayoutSlideDown(); +} +``` + +## setFilterSlideDownDefaultStatusEnabled + +Set the filter slide down to visible by default + +```php +public function configure(): void +{ + // Shorthand for $this->setFilterSlideDownDefaultStatus(true) + $this->setFilterSlideDownDefaultStatusEnabled(); +} +``` + +## setFilterSlideDownDefaultStatusDisabled + +Set the filter slide down to collapsed by default + +```php +public function configure(): void +{ + // Shorthand for $this->setFilterSlideDownDefaultStatus(false) + $this->setFilterSlideDownDefaultStatusDisabled(); +} +``` + +## storeFiltersInSessionEnabled + +Optional behaviour - stores filter values in the session (specific to table - based on the table name) + +### Exercise Caution +If re-using the same Livewire Table Component multiple times in your site, with the same table name, this may cause clashes in filter values + +```php +public function configure(): void +{ + $this->storeFiltersInSessionEnabled(); +} +``` +## storeFiltersInSessionDisabled + +Default behaviour - does not store filters in the session + +```php +public function configure(): void +{ + $this->storeFiltersInSessionDisabled(); +} +``` + +## setFilterPopoverAttributes + +Allows for the customisation of the appearance of the Filter Popover Menu. + +Note the addition of a "default-width" boolean, allowing you to customise the width more smoothly without impacting other applied classes. + +You may also replace default colors by setting "default-colors" to false, or default styling by setting "default-styling" to false, and specifying replacement classes in the "class" property. + +You can also replace the default transition behaviours (Tailwind) by specifying replacement attributes in the array. + +```php +public function configure(): void +{ + $this->setFilterPopoverAttributes( + [ + 'class' => 'w-96', + 'default-width' => false, + 'default-colors' => true, + 'default-styling' => true, + 'x-transition:enter' => 'transition ease-out duration-100', + ] + ); +} +``` + +## setFilterSlidedownWrapperAttributes + +Allows for the customisation of the appearance of the Filter Slidedown Wrapper. + +You may also replace default colors by setting "default-colors" to false, or default styling by setting "default-styling" to false, and specifying replacement classes in the "class" property. + +You can also replace the default transition behaviours (Tailwind) by specifying replacement attributes in the array, for example to extend the duration of the transition effect from the default duration-100 to duration-1000: + +```php +public function configure(): void +{ + $this->setFilterSlidedownWrapperAttributes([ + 'x-transition:enter' => 'transition ease-out duration-1000', + 'class' => 'text-black', + 'default-colors' => true, + 'default-styling' => true, + ]); +} +``` + +## setFilterSlidedownRowAttributes + +Allows for the customisation of the appearance of the Filter Slidedown Row. Note that this uses a callback, which receives the "rowIndex" of the Slidedown Row + +You may replace default colors by setting "default-colors" to false, or default styling by setting "default-styling" to false, and specifying replacement classes in the "class" property. + +```php +public function configure(): void +{ + $this->setFilterSlidedownRowAttributes(fn($rowIndex) => $rowIndex % 2 === 0 ? + [ + 'class' => 'bg-red-500', + 'default-colors' => true, + 'default-styling' => true, + ] : [ + 'class' => 'bg-blue-500', + 'default-colors' => true, + 'default-styling' => true, + ] + ); +} +``` diff --git a/docs/filters/available-filter-methods.md b/docs/filters/available-filter-methods.md new file mode 100644 index 000000000..6e17a63b4 --- /dev/null +++ b/docs/filters/available-filter-methods.md @@ -0,0 +1,289 @@ +--- +title: Available Filter Methods +weight: 6 +--- + +The following methods are available on the filter object. These are "filter-specific" methods. + +---- + +## setFilterPillTitle + +By default, the filter pill title is the filter name, but you can make it whatever you want: + +```php +SelectFilter::make('Active') + ->setFilterPillTitle('User Status') +``` + +## setFilterPillValues + +If you have numeric, or generated keys as your filter option values, they probably don't look too nice in the filter pill. You can set the values to be displayed in the filter pill: + +```php +SelectFilter::make('Active') + ->setFilterPillTitle('User Status') + ->setFilterPillValues([ + '1' => 'Active', + '0' => 'Inactive', + ]) + ->options([ + '' => 'All', + '1' => 'Yes', + '0' => 'No', + ]) +``` + +Now instead of `Active: Yes` it will say `User Status: Active` + +## hiddenFromMenus + +Hide the filter from both the filter popover and the filter slide down. + +```php +SelectFilter::make('Active') + ->hiddenFromMenus() +``` + +## hiddenFromPills + +Hide the filter from the filter pills when applied. + +```php +SelectFilter::make('Active') + ->hiddenFromPills() +``` + +## hiddenFromFilterCount + +Hide the filter from the filter count when applied. + +```php +SelectFilter::make('Active') + ->hiddenFromFilterCount() +``` + +## hiddenFromAll + +Hide the filter from the menus, pills, and count. + +```php +SelectFilter::make('Active') + ->hiddenFromAll() +``` + +## notResetByClearButton + +By default the `clear` button will reset all filters to their defaults. You can prevent this on a specific filter by using this method. + +```php +SelectFilter::make('Active') + ->notResetByClearButton() +``` + +## setFilterSlidedownRow + +This method applies only when using the Slide Down approach to filter display. +By default the filters will be displayed in the order that they are listed in the filters() method. This method allows you to specify the row that the filter will be listed. When multiple filters are placed on the same row, and a mobile device is used, then the first filter listed will "win" that row. +You may use either a string or an integer to pass to this method, and it can be used in conjunction with setFilterSlidedownColspan + +```php +SelectFilter::make('Active') + ->setFilterSlidedownRow(1) +``` + +## setFilterSlidedownColspan + +This method applies only when using the Slide Down approach to filter display. +By default each filter will take up one column, with the number of columns determined by the size of the screen, this ranges from 1 on a mobile device, to a maximum of 5 on a large display. This method allows you to specify the number of columns that the filter should span. It will span the number of columns specified, up to the number of columns available (depending on screen size). +You may use either a string or an integer to pass to this method, and it can be used in conjunction with setFilterSlidedownRow + +```php +DateFilter::make('Date') + ->config([ + 'min' => '2020-01-01', + 'max' => '2021-12-31', + ]) + ->setFilterSlidedownColspan('2') +``` + +## setFilterPillBlade + +Set a blade file for use in displaying the filter values in the pills area. You can use this in conjunction with setFilterPillValues() to prettify your applied filter values display. You will receive two properties ($filter) containing the filter instance, and ($value) containing the filter value. + +```php +SelectFilter::make('Active') + ->setFilterPillBlade('path.to.blade') +``` + +Example blade: +```php +@aware(['component']) +@props(['filter']) + + + {{ $filter->getFilterPillTitle() }} - ({{ $filter->getFilterPillValue($value) }}) + + + +``` + +## setCustomFilterLabel + +Set a custom blade file for the filter's label. This will be used in both the Pop-Over and SlideDown filter displays, you should therefore ensure that you cater for the different filter layouts. + +```php +SelectFilter::make('Active') + ->setCustomFilterLabel('path.to.blade') +``` + +You will receive several properties to your blade, explained here: +- $filter (the filter instance) +- $filterLayout ('slide-down' or 'popover') +- $tableName (the table name) +- $isTailwind (bool - is theme Tailwind) +- $isBootstrap (bool - is theme Bootstrap 4 or Bootstrap 5) +- $isBootstrap4 (bool - is theme Bootstrap 4) +- $isBootstrap5 (bool - is theme Bootstrap 5) +- $customLabelAttributes (array -> any customLabel attributes set using setFilterLabelAttributes()) + +Example label blade: +```php +@props(['filter', 'filterLayout' => 'popover', 'tableName' => 'table', 'isTailwind' => false, 'isBootstrap' => false, 'isBootstrap4' => false, 'isBootstrap5' => false, 'customLabelAttributes' => []]) + + + +``` + +## setFilterLabelAttributes + +### Old Method (Still Supported) +Set custom attributes for a Filter Label. At present it is recommended to only use this for "class" and "style" attributes to avoid conflicts. + +By default, this replaces the default classes on the Filter Label wrapper, if you would like to keep them, set the default flag to true. + +```php +TextFilter::make('Name') + ->setFilterLabelAttributes( + [ + 'class' => 'text-xl', + 'default' => true, + ] + ), +``` + +### New Method (Recommended) +Set custom attributes for a Filter Label. At present it is recommended to only use this for "class" and "style" attributes to avoid conflicts. + +By default, this replaces the default classes on the Filter Label wrapper, if you would like to keep them, set the default flag to true. + +```php +TextFilter::make('Name') + ->setLabelAttributes( + [ + 'class' => 'text-xl', + 'default' => true, + ] + ), +``` + +## setCustomView +Use a fully custom view for a filter. This will utilise solely your view when rendering this filter. Note that the following methods will no longer apply to a filter using this: +- setCustomFilterLabel +- setFilterLabelAttributes + +```php +TextFilter::make('Name') + ->setCustomView('text-custom-view'), +``` + +## Config + +If the filter takes any config options, you can set them with the `config` method: + +```php + DateFilter::make('Date') + ->config([ + 'min' => '2020-01-01', + 'max' => '2021-12-31', + ]) +``` + +## Customising Wireable Behaviour + +For the following Filters, you may customise how the input is wire:model into the Table Component: + +- DateFilter (Defaults to Live) +- DateTimeFilter (Defaults to Live) +- MultiSelectDropdownFilter (Defaults to live.debounce.250ms) +- MultiSelectFilter (Defaults to live.debounce.250ms) +- NumberFilter (Defaults to Blur) +- SelectFilter (Defaults to Live) +- TextFilter (Defaults to Blur) + +You may override this using the following methods, on any of the above Filter types: + +### setWireBlur() +Forces the filter to use a wire:model.blur approach +```php + TextFilter::make('Name') + ->config([ + 'placeholder' => 'Search Name', + 'maxlength' => '25', + ]) + ->setWireBlur() +``` + +### setWireDefer() +Forces the filter to use a wire:model approach +```php + TextFilter::make('Name') + ->config([ + 'placeholder' => 'Search Name', + 'maxlength' => '25', + ]) + ->setWireDefer() +``` + +### setWireLive() +Forces the fitler to use a wire:model.live approach +```php + TextFilter::make('Name') + ->config([ + 'placeholder' => 'Search Name', + 'maxlength' => '25', + ]) + ->setWireLive() +``` + +### setWireDebounce(int $debounceDelay) +Allows you to pass a string to use a wire:model.live.debounce.Xms approach +```php + TextFilter::make('Name') + ->config([ + 'placeholder' => 'Search Name', + 'maxlength' => '25', + ]) + ->setWireDebounce(50) +``` diff --git a/docs/filters/available-methods.md b/docs/filters/available-methods.md index 820916003..2fd27f523 100644 --- a/docs/filters/available-methods.md +++ b/docs/filters/available-methods.md @@ -3,521 +3,7 @@ title: Available Methods weight: 4 --- -## Component Methods +The documentation has now been split into two sections to enhance clarity. -These are the available filters configuration methods on the component. - ---- - -Filters are **enabled by default** but will only show up if you have at least one defined. - -### setFiltersStatus - -Enable/disable filters for the whole component. - -```php -public function configure(): void -{ - $this->setFiltersStatus(true); - $this->setFiltersStatus(false); -} -``` - -### setFiltersEnabled - -Enable filters for the component. - -```php -public function configure(): void -{ - // Shorthand for $this->setFiltersStatus(true) - $this->setFiltersEnabled(); -} -``` - -### setFiltersDisabled - -Disable filters for the component. - -```php -public function configure(): void -{ - // Shorthand for $this->setFiltersStatus(false) - $this->setFiltersDisabled(); -} -``` - ---- - -### setFiltersVisibilityStatus - -**Enabled by default**, show/hide the filters dropdown. - -```php -public function configure(): void -{ - $this->setFiltersVisibilityStatus(true); - $this->setFiltersVisibilityStatus(false); -} -``` - -### setFiltersVisibilityEnabled - -Show the filters dropdown for the component. - -```php -public function configure(): void -{ - // Shorthand for $this->setFiltersVisibilityStatus(true) - $this->setFiltersVisibilityEnabled(); -} -``` - -### setFiltersVisibilityDisabled - -Hide the filters dropdown for the component. - -```php -public function configure(): void -{ - // Shorthand for $this->setFiltersVisibilityStatus(false) - $this->setFiltersVisibilityDisabled(); -} -``` - ---- - -### setFilterPillsStatus - -**Enabled by default**, show/hide the filter pills. - -```php -public function configure(): void -{ - $this->setFilterPillsStatus(true); - $this->setFilterPillsStatus(false); -} -``` - -### setFilterPillsEnabled - -Show the filter pills for the component. - -```php -public function configure(): void -{ - // Shorthand for $this->setFilterPillsStatus(true) - $this->setFilterPillsEnabled(); -} -``` - -### setFilterPillsDisabled - -Hide the filter pills for the component. - -```php -public function configure(): void -{ - // Shorthand for $this->setFilterPillsStatus(false) - $this->setFilterPillsDisabled(); -} -``` - ---- - -### setFilterLayout - -Set the filter layout for the component. - -```php -public function configure(): void -{ - $this->setFilterLayout('slide-down'); -} -``` - -### setFilterLayoutPopover - -Set the filter layout to popover. - -```php -public function configure(): void -{ - $this->setFilterLayoutPopover(); -} -``` - -Set the filter layout to slide down. - -### setFilterLayoutSlideDown - -```php -public function configure(): void -{ - $this->setFilterLayoutSlideDown(); -} -``` - -### setFilterSlideDownDefaultStatusEnabled - -Set the filter slide down to visible by default - -```php -public function configure(): void -{ - // Shorthand for $this->setFilterSlideDownDefaultStatus(true) - $this->setFilterSlideDownDefaultStatusEnabled(); -} -``` - -### setFilterSlideDownDefaultStatusDisabled - -Set the filter slide down to collapsed by default - -```php -public function configure(): void -{ - // Shorthand for $this->setFilterSlideDownDefaultStatus(false) - $this->setFilterSlideDownDefaultStatusDisabled(); -} -``` - -### storeFiltersInSessionEnabled - -Optional behaviour - stores filter values in the session (specific to table - based on the table name) - -#### Exercise Caution -If re-using the same Livewire Table Component multiple times in your site, with the same table name, this may cause clashes in filter values - -```php -public function configure(): void -{ - $this->storeFiltersInSessionEnabled(); -} -``` -### storeFiltersInSessionDisabled - -Default behaviour - does not store filters in the session - -```php -public function configure(): void -{ - $this->storeFiltersInSessionDisabled(); -} -``` - -### setFilterPopoverAttributes - -Allows for the customisation of the appearance of the Filter Popover Menu. - -Note the addition of a "default-width" boolean, allowing you to customise the width more smoothly without impacting other applied classes. - -You may also replace default colors by setting "default-colors" to false, or default styling by setting "default-styling" to false, and specifying replacement classes in the "class" property. - -You can also replace the default transition behaviours (Tailwind) by specifying replacement attributes in the array. - -```php -public function configure(): void -{ - $this->setFilterPopoverAttributes( - [ - 'class' => 'w-96', - 'default-width' => false, - 'default-colors' => true, - 'default-styling' => true, - 'x-transition:enter' => 'transition ease-out duration-100', - ] - ); -} -``` - ----- - -## Filter Methods - -The following methods are available on the filter object. - ----- - -### setFilterPillTitle - -By default, the filter pill title is the filter name, but you can make it whatever you want: - -```php -SelectFilter::make('Active') - ->setFilterPillTitle('User Status') -``` - -### setFilterPillValues - -If you have numeric, or generated keys as your filter option values, they probably don't look too nice in the filter pill. You can set the values to be displayed in the filter pill: - -```php -SelectFilter::make('Active') - ->setFilterPillTitle('User Status') - ->setFilterPillValues([ - '1' => 'Active', - '0' => 'Inactive', - ]) - ->options([ - '' => 'All', - '1' => 'Yes', - '0' => 'No', - ]) -``` - -Now instead of `Active: Yes` it will say `User Status: Active` - -### hiddenFromMenus - -Hide the filter from both the filter popover and the filter slide down. - -```php -SelectFilter::make('Active') - ->hiddenFromMenus() -``` - -### hiddenFromPills - -Hide the filter from the filter pills when applied. - -```php -SelectFilter::make('Active') - ->hiddenFromPills() -``` - -### hiddenFromFilterCount - -Hide the filter from the filter count when applied. - -```php -SelectFilter::make('Active') - ->hiddenFromFilterCount() -``` - -### hiddenFromAll - -Hide the filter from the menus, pills, and count. - -```php -SelectFilter::make('Active') - ->hiddenFromAll() -``` - -### notResetByClearButton - -By default the `clear` button will reset all filters to their defaults. You can prevent this on a specific filter by using this method. - -```php -SelectFilter::make('Active') - ->notResetByClearButton() -``` - -### setFilterSlidedownRow - -This method applies only when using the Slide Down approach to filter display. -By default the filters will be displayed in the order that they are listed in the filters() method. This method allows you to specify the row that the filter will be listed. When multiple filters are placed on the same row, and a mobile device is used, then the first filter listed will "win" that row. -You may use either a string or an integer to pass to this method, and it can be used in conjunction with setFilterSlidedownColspan - -```php -SelectFilter::make('Active') - ->setFilterSlidedownRow(1) -``` - -### setFilterSlidedownColspan - -This method applies only when using the Slide Down approach to filter display. -By default each filter will take up one column, with the number of columns determined by the size of the screen, this ranges from 1 on a mobile device, to a maximum of 5 on a large display. This method allows you to specify the number of columns that the filter should span. It will span the number of columns specified, up to the number of columns available (depending on screen size). -You may use either a string or an integer to pass to this method, and it can be used in conjunction with setFilterSlidedownRow - -```php -DateFilter::make('Date') - ->config([ - 'min' => '2020-01-01', - 'max' => '2021-12-31', - ]) - ->setFilterSlidedownColspan('2') -``` - -### setFilterPillBlade - -Set a blade file for use in displaying the filter values in the pills area. You can use this in conjunction with setFilterPillValues() to prettify your applied filter values display. You will receive two properties ($filter) containing the filter instance, and ($value) containing the filter value. - -```php -SelectFilter::make('Active') - ->setFilterPillBlade('path.to.blade') -``` - -Example blade: -```php -@aware(['component']) -@props(['filter']) - - - {{ $filter->getFilterPillTitle() }} - ({{ $filter->getFilterPillValue($value) }}) - - - -``` - -### setCustomFilterLabel - -Set a custom blade file for the filter's label. This will be used in both the Pop-Over and SlideDown filter displays, you should therefore ensure that you cater for the different filter layouts. - -```php -SelectFilter::make('Active') - ->setCustomFilterLabel('path.to.blade') -``` - -You will receive several properties to your blade, explained here: -- $filter (the filter instance) -- $filterLayout ('slide-down' or 'popover') -- $tableName (the table name) -- $isTailwind (bool - is theme Tailwind) -- $isBootstrap (bool - is theme Bootstrap 4 or Bootstrap 5) -- $isBootstrap4 (bool - is theme Bootstrap 4) -- $isBootstrap5 (bool - is theme Bootstrap 5) -- $customLabelAttributes (array -> any customLabel attributes set using setFilterLabelAttributes()) - -Example label blade: -```php -@props(['filter', 'filterLayout' => 'popover', 'tableName' => 'table', 'isTailwind' => false, 'isBootstrap' => false, 'isBootstrap4' => false, 'isBootstrap5' => false, 'customLabelAttributes' => []) - - - -``` - -### setFilterLabelAttributes - -#### Old Method (Still Supported) -Set custom attributes for a Filter Label. At present it is recommended to only use this for "class" and "style" attributes to avoid conflicts. - -By default, this replaces the default classes on the Filter Label wrapper, if you would like to keep them, set the default flag to true. - -```php -TextFilter::make('Name') - ->setFilterLabelAttributes( - [ - 'class' => 'text-xl', - 'default' => true, - ] - ), -``` - -#### New Method (Recommended) -Set custom attributes for a Filter Label. At present it is recommended to only use this for "class" and "style" attributes to avoid conflicts. - -By default, this replaces the default classes on the Filter Label wrapper, if you would like to keep them, set the default flag to true. - -```php -TextFilter::make('Name') - ->setLabelAttributes( - [ - 'class' => 'text-xl', - 'default' => true, - ] - ), -``` - -### setCustomView -Use a fully custom view for a filter. This will utilise solely your view when rendering this filter. Note that the following methods will no longer apply to a filter using this: -- setCustomFilterLabel -- setFilterLabelAttributes - -```php -TextFilter::make('Name') - ->setCustomView('text-custom-view'), -``` - -### Config - -If the filter takes any config options, you can set them with the `config` method: - -```php - DateFilter::make('Date') - ->config([ - 'min' => '2020-01-01', - 'max' => '2021-12-31', - ]) -``` - -### Customising Wireable Behaviour - -For the following Filters, you may customise how the input is wire:model into the Table Component: - -- DateFilter (Defaults to Live) -- DateTimeFilter (Defaults to Live) -- MultiSelectDropdownFilter (Defaults to live.debounce.250ms) -- MultiSelectFilter (Defaults to live.debounce.250ms) -- NumberFilter (Defaults to Blur) -- SelectFilter (Defaults to Live) -- TextFilter (Defaults to Blur) - -You may override this using the following methods, on any of the above Filter types: - -#### setWireBlur() -Forces the filter to use a wire:model.blur approach -```php - TextFilter::make('Name') - ->config([ - 'placeholder' => 'Search Name', - 'maxlength' => '25', - ]) - ->setWireBlur() -``` - -#### setWireDefer() -Forces the filter to use a wire:model approach -```php - TextFilter::make('Name') - ->config([ - 'placeholder' => 'Search Name', - 'maxlength' => '25', - ]) - ->setWireDefer() -``` - -#### setWireLive() -Forces the fitler to use a wire:model.live approach -```php - TextFilter::make('Name') - ->config([ - 'placeholder' => 'Search Name', - 'maxlength' => '25', - ]) - ->setWireLive() -``` - -#### setWireDebounce(int $debounceDelay) -Allows you to pass a string to use a wire:model.live.debounce.Xms approach -```php - TextFilter::make('Name') - ->config([ - 'placeholder' => 'Search Name', - 'maxlength' => '25', - ]) - ->setWireDebounce(50) -``` +Documentation for Available Component Methods is now: [Here](./available-component-methods) +Documentation for Available Filter Methods is now: [Here](./available-filter-methods) diff --git a/docs/filters/creating-filters.md b/docs/filters/creating-filters.md index e940c5952..e13e98563 100644 --- a/docs/filters/creating-filters.md +++ b/docs/filters/creating-filters.md @@ -3,7 +3,7 @@ title: Creating Filters weight: 2 --- -To create filters, you must implement the `filters()` method on your component. +To create filters, you must implement the `filters()` method on your component, which must return an array. ```php public function filters(): array diff --git a/docs/filters/introduction.md b/docs/filters/introduction.md index 11f0d9e76..b0888514b 100644 --- a/docs/filters/introduction.md +++ b/docs/filters/introduction.md @@ -3,7 +3,7 @@ title: Introduction weight: 1 --- -Filters are a good way to narrow down your data. Version 2 has two ways to interact with filters, either by a popover menu or a slide down area. +Filters are a good way to narrow down your data. Version 2 has two ways to interact with filters, either by a popover menu or a slide down area, which are configurable on a per-table basis. ## Popover Menu diff --git a/resources/views/components/tools/toolbar/items/filter-slidedown.blade.php b/resources/views/components/tools/toolbar/items/filter-slidedown.blade.php index be507404b..123e587ec 100644 --- a/resources/views/components/tools/toolbar/items/filter-slidedown.blade.php +++ b/resources/views/components/tools/toolbar/items/filter-slidedown.blade.php @@ -1,28 +1,38 @@ @aware([ 'tableName']) @props([]) -
$this->isBootstrap, - ]) - @if($this->isTailwind) - x-transition:enter="transition ease-out duration-100" - x-transition:enter-start="transform opacity-0" - x-transition:enter-end="transform opacity-100" - x-transition:leave="transition ease-in duration-75" - x-transition:leave-start="transform opacity-100" - x-transition:leave-end="transform opacity-0" - @endif +
merge($this->getFilterSlidedownWrapperAttributes) + ->merge($this->isTailwind ? [ + 'x-transition:enter' => 'transition ease-out duration-100', + 'x-transition:enter-start' => 'transform opacity-0', + 'x-transition:enter-end' => 'transform opacity-100', + 'x-transition:leave' => 'transition ease-in duration-75', + 'x-transition:leave-start' => 'transform opacity-100', + 'x-transition:leave-end' => 'transform opacity-0', + ] : []) + ->class([ + 'container' => $this->isBootstrap && ($this->getFilterSlidedownWrapperAttributes['default'] ?? true), + ]) + ->except(['default','default-colors','default-styling']) + }} + > - @foreach ($this->getFiltersByRow() as $filterRowIndex => $filterRow) -
$this->isBootstrap, - 'grid grid-cols-12 gap-6 px-4 md:p-0 mb-6' => $this->isTailwind, + @foreach ($this->getFiltersByRow() as $filterRowIndex => $filtersInRow) + @php($defaultAttributes = $this->getFilterSlidedownRowAttributes($filterRowIndex)) +
merge($defaultAttributes) + ->merge([ + 'row' => $filterRowIndex, + ]) + ->class([ + 'row col-12' => $this->isBootstrap && ($defaultAttributes['default-styling'] ?? true), + 'grid grid-cols-12 gap-6 px-4 py-2 mb-2' => $this->isTailwind && ($defaultAttributes['default-styling'] ?? true), ]) - row="{{ $filterRowIndex }}" + ->except(['default','default-colors','default-styling']) + }} > - @foreach ($filterRow as $filter) + @foreach ($filtersInRow as $filter)
diff --git a/src/Traits/Styling/Configuration/FilterMenuStylingConfiguration.php b/src/Traits/Styling/Configuration/FilterMenuStylingConfiguration.php index 92d8ba467..4a68532d5 100644 --- a/src/Traits/Styling/Configuration/FilterMenuStylingConfiguration.php +++ b/src/Traits/Styling/Configuration/FilterMenuStylingConfiguration.php @@ -16,6 +16,26 @@ public function setFilterPopoverAttributes(array $filterPopoverAttributes): self return $this; } + /** + * Used to set attributes for the Filter Slidedown Wrapper + */ + public function setFilterSlidedownWrapperAttributes(array $filterSlidedownWrapperAttributes): self + { + $this->filterSlidedownWrapperAttributes = array_merge($this->filterSlidedownWrapperAttributes, $filterSlidedownWrapperAttributes); + + return $this; + } + + /** + * Set a list of attributes to override on the th sort button elements + */ + public function setFilterSlidedownRowAttributes(\Closure $callback): self + { + $this->filterSlidedownRowCallback = $callback; + + return $this; + } + public function setFilterLayout(string $type): self { if (! in_array($type, ['popover', 'slide-down'], true)) { diff --git a/src/Traits/Styling/HasFilterMenuStyling.php b/src/Traits/Styling/HasFilterMenuStyling.php index c534027e4..03a6737b4 100644 --- a/src/Traits/Styling/HasFilterMenuStyling.php +++ b/src/Traits/Styling/HasFilterMenuStyling.php @@ -18,4 +18,8 @@ trait HasFilterMenuStyling public bool $filterSlideDownDefaultVisible = false; protected array $filterPopoverAttributes = ['class' => '', 'default-width' => true, 'default-colors' => true, 'default-styling' => true]; + + protected array $filterSlidedownWrapperAttributes = ['class' => '', 'default-colors' => true, 'default-styling' => true]; + + protected ?\Closure $filterSlidedownRowCallback; } diff --git a/src/Traits/Styling/Helpers/FilterMenuStylingHelpers.php b/src/Traits/Styling/Helpers/FilterMenuStylingHelpers.php index d5ddf6d6c..9833809d6 100644 --- a/src/Traits/Styling/Helpers/FilterMenuStylingHelpers.php +++ b/src/Traits/Styling/Helpers/FilterMenuStylingHelpers.php @@ -20,6 +20,34 @@ public function getFilterPopoverAttributes(): array } + /** + * Used to get attributes for the Filter Slidedown Wrapper + * + * @return array + */ + #[Computed] + public function getFilterSlidedownWrapperAttributes(): array + { + return $this->filterSlidedownWrapperAttributes; + + } + + /** + * Used to get attributes for the Filter Slidedown Row + * + * @return array + */ + #[Computed] + public function getFilterSlidedownRowAttributes(string $rowIndex): array + { + + if (isset($this->filterSlidedownRowCallback)) { + return array_merge(['class' => '', 'default-colors' => true, 'default-styling' => true, 'row' => (int) $rowIndex], call_user_func($this->filterSlidedownRowCallback, (int) $rowIndex)); + } + + return ['class' => '', 'default-colors' => true, 'default-styling' => true, 'row' => (int) $rowIndex]; + } + public function getFilterSlideDownDefaultStatus(): bool { return $this->filterSlideDownDefaultVisible; diff --git a/tests/Unit/Traits/Styling/FilterSlidedownStylingTest.php b/tests/Unit/Traits/Styling/FilterSlidedownStylingTest.php new file mode 100644 index 000000000..5ba1ac182 --- /dev/null +++ b/tests/Unit/Traits/Styling/FilterSlidedownStylingTest.php @@ -0,0 +1,92 @@ +assertSame(['class' => '', 'default-colors' => true, 'default-styling' => true], $this->basicTable->getFilterSlidedownWrapperAttributes()); + } + + public function test_filter_slidedown_wrapper_attributes_can_be_changed(): void + { + $this->assertSame(['class' => '', 'default-colors' => true, 'default-styling' => true], $this->basicTable->getFilterSlidedownWrapperAttributes()); + $this->basicTable->setFilterSlidedownWrapperAttributes([ + 'class' => 'text-blue-500', + 'default-colors' => true, + 'default-styling' => true, + 'x-transition:enter' => 'transition ease-out duration-1000', + ]); + + $this->assertSame(['class' => 'text-blue-500', 'default-colors' => true, 'default-styling' => true, 'x-transition:enter' => 'transition ease-out duration-1000'], $this->basicTable->getFilterSlidedownWrapperAttributes()); + + $this->basicTable->setFilterSlidedownWrapperAttributes([ + 'x-transition:enter-start' => 'transform opacity-0', + ]); + + $this->assertSame(['class' => 'text-blue-500', 'default-colors' => true, 'default-styling' => true, 'x-transition:enter' => 'transition ease-out duration-1000', 'x-transition:enter-start' => 'transform opacity-0'], $this->basicTable->getFilterSlidedownWrapperAttributes()); + + } + + public function test_filter_slidedown_row_attributes_returns_default_if_not_set(): void + { + $this->assertSame(['class' => '', 'default-colors' => true, 'default-styling' => true, 'row' => 1], $this->basicTable->getFilterSlidedownRowAttributes(1)); + $this->assertSame(['class' => '', 'default-colors' => true, 'default-styling' => true, 'row' => 2], $this->basicTable->getFilterSlidedownRowAttributes(2)); + $this->assertSame(['class' => '', 'default-colors' => true, 'default-styling' => true, 'row' => 1], $this->basicTable->getFilterSlidedownRowAttributes('1')); + $this->assertSame(['class' => '', 'default-colors' => true, 'default-styling' => true, 'row' => 2], $this->basicTable->getFilterSlidedownRowAttributes('2')); + } + + public function test_filter_slidedown_row_attributes_can_be_changed(): void + { + $this->assertSame(['class' => '', 'default-colors' => true, 'default-styling' => true, 'row' => 1], $this->basicTable->getFilterSlidedownRowAttributes(1)); + + $this->basicTable->setFilterSlidedownRowAttributes(fn ($rowIndex) => $rowIndex % 2 === 0 ? + [ + 'class' => 'bg-red-500', + 'default-colors' => true, + 'default-styling' => true, + ] : [ + 'class' => 'bg-blue-500', + 'default-colors' => true, + 'default-styling' => true, + ] + ); + $this->assertSame(['class' => 'bg-red-500', 'default-colors' => true, 'default-styling' => true, 'row' => 0], $this->basicTable->getFilterSlidedownRowAttributes(0)); + $this->assertSame(['class' => 'bg-blue-500', 'default-colors' => true, 'default-styling' => true, 'row' => 1], $this->basicTable->getFilterSlidedownRowAttributes(1)); + $this->assertSame(['class' => 'bg-red-500', 'default-colors' => true, 'default-styling' => true, 'row' => 2], $this->basicTable->getFilterSlidedownRowAttributes(2)); + $this->assertSame(['class' => 'bg-blue-500', 'default-colors' => true, 'default-styling' => true, 'row' => 3], $this->basicTable->getFilterSlidedownRowAttributes(3)); + $this->assertSame(['class' => 'bg-red-500', 'default-colors' => true, 'default-styling' => true, 'row' => 0], $this->basicTable->getFilterSlidedownRowAttributes('0')); + $this->assertSame(['class' => 'bg-blue-500', 'default-colors' => true, 'default-styling' => true, 'row' => 1], $this->basicTable->getFilterSlidedownRowAttributes('1')); + $this->assertSame(['class' => 'bg-red-500', 'default-colors' => true, 'default-styling' => true, 'row' => 2], $this->basicTable->getFilterSlidedownRowAttributes('2')); + $this->assertSame(['class' => 'bg-blue-500', 'default-colors' => true, 'default-styling' => true, 'row' => 3], $this->basicTable->getFilterSlidedownRowAttributes('3')); + + } + + public function test_filter_slidedown_row_attributes_can_be_changed_and_sets_defaults(): void + { + $this->assertSame(['class' => '', 'default-colors' => true, 'default-styling' => true, 'row' => 0], $this->basicTable->getFilterSlidedownRowAttributes(0)); + $this->assertSame(['class' => '', 'default-colors' => true, 'default-styling' => true, 'row' => 1], $this->basicTable->getFilterSlidedownRowAttributes(1)); + + $this->basicTable->setFilterSlidedownRowAttributes(fn ($rowIndex) => $rowIndex % 2 === 0 ? + [ + 'class' => 'bg-red-500', + 'default-colors' => false, + ] : [ + 'class' => 'bg-blue-500', + 'default-styling' => false, + ] + ); + $this->assertSame(['class' => 'bg-red-500', 'default-colors' => false, 'default-styling' => true, 'row' => 0], $this->basicTable->getFilterSlidedownRowAttributes(0)); + $this->assertSame(['class' => 'bg-blue-500', 'default-colors' => true, 'default-styling' => false, 'row' => 1], $this->basicTable->getFilterSlidedownRowAttributes(1)); + $this->assertSame(['class' => 'bg-red-500', 'default-colors' => false, 'default-styling' => true, 'row' => 2], $this->basicTable->getFilterSlidedownRowAttributes(2)); + $this->assertSame(['class' => 'bg-blue-500', 'default-colors' => true, 'default-styling' => false, 'row' => 3], $this->basicTable->getFilterSlidedownRowAttributes(3)); + $this->assertSame(['class' => 'bg-red-500', 'default-colors' => false, 'default-styling' => true, 'row' => 0], $this->basicTable->getFilterSlidedownRowAttributes('0')); + $this->assertSame(['class' => 'bg-blue-500', 'default-colors' => true, 'default-styling' => false, 'row' => 1], $this->basicTable->getFilterSlidedownRowAttributes('1')); + $this->assertSame(['class' => 'bg-red-500', 'default-colors' => false, 'default-styling' => true, 'row' => 2], $this->basicTable->getFilterSlidedownRowAttributes('2')); + $this->assertSame(['class' => 'bg-blue-500', 'default-colors' => true, 'default-styling' => false, 'row' => 3], $this->basicTable->getFilterSlidedownRowAttributes('3')); + + } +}