diff --git a/docs/column-types/array_column.md b/docs/column-types/array_column.md index 7802e78aa..3d612248d 100644 --- a/docs/column-types/array_column.md +++ b/docs/column-types/array_column.md @@ -5,7 +5,7 @@ weight: 2 Array columns provide an easy way to work with and display an array of data from a field. -``` +```php ArrayColumn::make('notes', 'name') ->data(fn($value, $row) => ($row->notes)) ->outputFormat(fn($index, $value) => "".$value->name."") @@ -16,7 +16,7 @@ ArrayColumn::make('notes', 'name') ### Empty Value You may define the default/empty value using the "emptyValue" method -``` +```php ArrayColumn::make('notes', 'name') ->emptyValue('Unknown'), ``` diff --git a/docs/column-types/avg_column.md b/docs/column-types/avg_column.md index d5e4b32fb..f0f7680ac 100644 --- a/docs/column-types/avg_column.md +++ b/docs/column-types/avg_column.md @@ -5,7 +5,7 @@ weight: 3 Avg columns provide an easy way to display the "Average" of a field on a relation. -``` +```php AvgColumn::make('Average Related User Age') ->setDataSource('users','age') ->sortable(), diff --git a/docs/column-types/count_column.md b/docs/column-types/count_column.md index 4b1fe6c3a..beb7d3437 100644 --- a/docs/column-types/count_column.md +++ b/docs/column-types/count_column.md @@ -5,7 +5,7 @@ weight: 8 Count columns provide an easy way to display the "Count" of a relation. -``` +```php CountColumn::make('Related Users') ->setDataSource('users') ->sortable(), diff --git a/docs/column-types/livewire_component_column.md b/docs/column-types/livewire_component_column.md index ebeb72724..f48859641 100644 --- a/docs/column-types/livewire_component_column.md +++ b/docs/column-types/livewire_component_column.md @@ -8,7 +8,7 @@ Livewire Component Columns allow for the use of a Livewire Component as a Column This is **not recommended** as due to the nature of Livewire, it becomes inefficient at scale. ## component -``` +```php LivewireComponentColumn::make('Action') ->component('PathToLivewireComponent'), diff --git a/docs/filter-types/filters-livewire-component-array.md b/docs/filter-types/filters-livewire-component-array.md new file mode 100644 index 000000000..86b2491dc --- /dev/null +++ b/docs/filter-types/filters-livewire-component-array.md @@ -0,0 +1,51 @@ +--- +title: Livewire Custom Array Filter (Beta) +weight: 13 +--- + +**IN BETA** +This feature is currently in beta, and use in production is not recommended. + +### Usage +This allows you to use a child/nested Livewire Component in place of the existing Filters, giving you more control over the look/feel/behaviour of a filter. This version supports use of returning an array of values for use in filtering. + +To use a LivewireComponentArrayFilter, you must include it in your namespace: +```php +use Rappasoft\LaravelLivewireTables\Views\Filters\LivewireComponentArrayFilter; +``` + +When creating a filter: +- Specify a unique name +- Set the path to a valid Livewire Component +- Define a filter() callback to define how the returned value will be used. + +```php + public function filters(): array + { + return [ + LivewireComponentArrayFilter::make('My External Filter') + ->setLivewireComponent('my-test-external-filter') + ->filter(function (Builder $builder, array $values) { + $builder->whereIn('foreign_id', $values); + }), + ]; + } +``` + +### setPillsSeparator +As this is an array, you can define the separator to use between pills values, by default this is set to ", " + +```php + public function filters(): array + { + return [ + LivewireComponentArrayFilter::make('My External Filter') + ->setLivewireComponent('my-test-external-filter') + ->setPillsSeparator(' OR ') + ->filter(function (Builder $builder, array $values) { + $builder->whereIn('foreign_id', $values); + }), + ]; + } +``` + diff --git a/docs/filters/available-component-methods.md b/docs/filters/available-component-methods.md index bf3c51c43..ffa02f29c 100644 --- a/docs/filters/available-component-methods.md +++ b/docs/filters/available-component-methods.md @@ -85,135 +85,9 @@ public function configure(): void --- -## setFilterPillsStatus +## Pills -**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(); -} -``` - -## setFilterPillsItemAttributes -Allows for customisation of the appearance of the "Filter Pills Item" - -Note that this utilises a refreshed approach for attributes, and allows for appending to, or replacing the styles and colors independently, via the below methods. - -#### default-colors -Setting to false will disable the default colors for the Filter Pills Item, the default colors are: - -Bootstrap: None - -Tailwind: `bg-indigo-100 text-indigo-800 dark:bg-indigo-200 dark:text-indigo-900` - -#### default-styling -Setting to false will disable the default styling for the Filter Pills Item, the default styling is: - -Bootstrap 4: `badge badge-pill badge-info d-inline-flex align-items-center` - -Bootstrap 5: `badge rounded-pill bg-info d-inline-flex align-items-center` - -Tailwind: `inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium leading-4 capitalize` - -```php -public function configure(): void -{ - $this->setFilterPillsItemAttributes([ - 'class' => 'bg-rose-300 text-rose-800 dark:bg-indigo-200 dark:text-indigo-900', // Add these classes to the filter pills item - 'default-colors' => false, // Do not output the default colors - 'default-styling' => true // Output the default styling - ]); -} -``` - -## setFilterPillsResetFilterButtonAttributes -Allows for customisation of the appearance of the "Filter Pills Reset Filter Button" - -Note that this utilises a refreshed approach for attributes, and allows for appending to, or replacing the styles and colors independently, via the below methods. - -#### default-colors -Setting to false will disable the default colors for the Filter Pills Reset Filter Button, the default colors are: - -Bootstrap: None - -Tailwind: `text-indigo-400 hover:bg-indigo-200 hover:text-indigo-500 focus:bg-indigo-500 focus:text-white` - -#### default-styling -Setting to false will disable the default styling for the Filter Pills Reset Filter Button, the default styling is: - -Bootstrap: `text-white ml-2` - -Tailwind: `flex-shrink-0 ml-0.5 h-4 w-4 rounded-full inline-flex items-center justify-center focus:outline-none` - -```php -public function configure(): void -{ - $this->setFilterPillsResetFilterButtonAttributes([ - 'class' => 'text-rose-400 hover:bg-rose-200 hover:text-rose-500 focus:bg-rose-500', // Add these classes to the filter pills reset filter button - 'default-colors' => false, // Do not output the default colors - 'default-styling' => true // Output the default styling - ]); -} -``` - -## setFilterPillsResetAllButtonAttributes -Allows for customisation of the appearance of the "Filter Pills Reset All Button" - -Note that this utilises a refreshed approach for attributes, and allows for appending to, or replacing the styles and colors independently, via the below methods. - -#### default-colors -Setting to false will disable the default colors for the Filter Pills Reset All Button, the default colors are: - -Bootstrap: None - -Tailwind: `bg-gray-100 text-gray-800 dark:bg-gray-200 dark:text-gray-900` - -#### default-styling -Setting to false will disable the default styling for the Filter Pills Reset All Button, the default styling is: - -Bootstrap 4: `badge badge-pill badge-light` - -Bootstrap 5: `badge rounded-pill bg-light text-dark text-decoration-none` - -Tailwind: `inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium` - -```php -public function configure(): void -{ - $this->setFilterPillsResetAllButtonAttributes([ - 'class' => 'bg-rose-100 text-rose-800 dark:bg-gray-200 dark:text-gray-900', // Add these classes to the filter pills reset all button - 'default-colors' => false, // Do not output the default colors - 'default-styling' => true // Output the default styling - ]); -} -``` +See the [Filter Pills](./filter-pills) documentation for help with configuring the pills --- diff --git a/docs/filters/available-filter-methods.md b/docs/filters/available-filter-methods.md index 9597372d4..249273109 100644 --- a/docs/filters/available-filter-methods.md +++ b/docs/filters/available-filter-methods.md @@ -5,36 +5,10 @@ weight: 6 The following methods are available on the filter object. These are "filter-specific" methods. ----- +Ensure you check out: +- [Available Component Methods](./available-component-methods) documentation for Table Wide configuration +- [Filter Pills](./filter-pills) documentation for help with configuring the pills for a filter -## 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 @@ -80,8 +54,96 @@ By default the `clear` button will reset all filters to their defaults. You can SelectFilter::make('Active') ->notResetByClearButton() ``` - -## setFilterSlidedownRow + +## 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) +``` + +--- + +## Styling + +These methods allow you to over-ride default styling for individual Filters + +--- + +### 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. @@ -92,7 +154,7 @@ SelectFilter::make('Active') ->setFilterSlidedownRow(1) ``` -## setFilterSlidedownColspan +### 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). @@ -107,37 +169,9 @@ DateFilter::make('Date') ->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 +### 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. @@ -158,27 +192,27 @@ You will receive several properties to your blade, explained here: Example label blade: ```php -@props(['filter', 'filterLayout' => 'popover', 'tableName' => 'table', 'isTailwind' => false, 'isBootstrap' => false, 'isBootstrap4' => false, 'isBootstrap5' => false, 'customLabelAttributes' => []]) - - -