Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kirschbaum-development/livewire-filters
Livewire Filters is a series of Livewire components that provide you with the tools to do live filtering of your data from your own Livewire components.
https://github.com/kirschbaum-development/livewire-filters
filtering laravel livewire
Last synced: 3 months ago
JSON representation
Livewire Filters is a series of Livewire components that provide you with the tools to do live filtering of your data from your own Livewire components.
- Host: GitHub
- URL: https://github.com/kirschbaum-development/livewire-filters
- Owner: kirschbaum-development
- License: mit
- Created: 2022-02-23T14:23:00.000Z (almost 3 years ago)
- Default Branch: dev
- Last Pushed: 2023-10-09T10:15:02.000Z (over 1 year ago)
- Last Synced: 2024-10-07T23:10:37.192Z (3 months ago)
- Topics: filtering, laravel, livewire
- Language: PHP
- Homepage:
- Size: 74.2 KB
- Stars: 15
- Watchers: 15
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
[//]: # ()
[](https://packagist.org/packages/kirschbaum-development/livewire-filters)
[](https://packagist.org/packages/kirschbaum-development/livewire-filters)
[](https://github.com/kirschbaum-development/livewire-filters/actions)
Livewire Filters is a series of Livewire components that provide you with the tools to do live filtering of your data from your own Livewire components.
## Requirements
This package requires Laravel 9.0+ and Livewire 2.10+.
## Installation
To get started, require the package via Composer:
```bash
composer require kirschbaum-development/livewire-filters
```
### Publishing views
The included filters are made with [Tailwind CSS](https://tailwindcss.com) and the [Tailwind CSS Forms plugin](https://github.com/tailwindlabs/tailwindcss-forms). We recommend publishing the views and changing the markup to match whatever styling or CSS framework your project uses.
```bash
php artisan vendor:publish --tag=livewire-filters-views
```
### Publishing config
Publishing the config file is only necessary to enable query string usage.
```bash
php artisan vendor:publish --tag=livewire-filters-config
```
## Usage
### Define your filters
You can use filters in your Livewire component by including the `HasFilters` trait provided by the package.
With the trait included, define a `filters` method that returns an array of `Filter` objects you want to use in your component. The included `Filter` class has a series of fluent methods for building up the specifics of each of your filters.
```php
use HasFilters;
public function filters(): array
{
return [
Filter::make('title'),
Filter::make('type')->options(['text', 'link', 'audio', 'video'])->default(['audio']),
Filter::make('status')->options(['published', 'draft'])->default('published'),
];
}
```
### Use your filters
With your component setup, you can include filters in the view file of your Livewire component. In order to setup the filter, simply use one of the filter components and pass the specific filter by its key. The component will take care of setting itself up.
```blade
```
There is more information below about the included filters in the package.
### Determining filtered status/count
The `HasFilters` trait includes two computed properties you can use to determine if there are active filters and how many of your filters are currently active. You can access these directly in your Livewire component by using `$this->isFiltered` or `$this->activeFilterCount`. You can also pass one or both of these properties to your Livewire component through the `render` method if you so choose.
These computed properties are handy if you want to change the color of a button, show/hide a specific section of your UI, show a badge of active filters, or simply show a visual indicator that there are active filters being applied.
### Getting filtered values
Because the `$filters` array contains `Filter` objects, you will need to either access the `value` property, use the `value()` method, or use the included `getFilterValue($key)` helper method.
```php
// Helper included in the HasFilters trait
$this->getFilteredValue('type');
// Using the accessor
$this->filters['type']->value();
// Using the property directly
$this->filters['type']->value;
```
### Example parent component
```php
use App\Models\Post;
use Kirschbaum\LivewireFilters\Filter;
use Kirschbaum\LivewireFilters\HasFilters;
use Livewire\Component;
class PostsList extends Component
{
use HasFilters;
public function filters(): array
{
return [
Filter::make('type')->options(['text', 'link', 'audio', 'video'])->default(['text', 'link']),
];
}
public function getPostsProperty()
{
return Post::query()
->when($this->getFilterValue('type'), fn ($query, $values) => $query->whereIn('type', $values))
->paginate();
}
public function render()
{
return view('livewire.posts-list', [
'filterCount' => $this->filterCount,
'isFiltered' => $this->isFiltered,
'posts' => $this->posts,
]);
}
}
```
## Included filters
The package includes 4 basic filters that can be used in your Livewire components.
### Checkbox filter
The checkbox filter allows you to select any number of options. Every time a change is made, the filter will emit an event with an array of the currently checked values.
```blade
```
| Setting | Type | Example |
|---------|----------|-------------------|
| key | `string` | `'type'` |
| options | `array` | `['a', 'b', 'c']` |
| default | `array` | `['a', 'b']` |
| value | `array` | `['b', 'c']` |
### Radio button filter
The radio button filter allows you to select a single option from the list of options. Every time a change is made, the filter will emit an event with the currently checked value.
```blade
```
| Setting | Type | Example |
|---------|----------|-------------------|
| key | `string` | `'type'` |
| options | `array` | `['a', 'b', 'c']` |
| default | `string` | `'a'` |
| value | `string` | `'b'` |
### Select menu filter
Similar to the radio button filter, the select menu filter allows you to select a single option from the list of options from a select menu. Every time a change is made, the filter will emit an event with the currently selected value.
```blade
```
| Setting | Type | Example |
|---------|----------|-------------------|
| key | `string` | `'type'` |
| options | `array` | `['a', 'b', 'c']` |
| default | `string` | `'a'` |
| value | `string` | `'b'` |
### Text box filter
The text box filter allows you to type freeform text that you can use for filtering. Every time a change is made, the filter will emit an event with the value of the text field.
```blade
```
| Setting | Type | Example |
|---------|----------|----------|
| key | `string` | `'name'` |
| default | `string` | `'John'` |
| value | `string` | `'Jane'` |
## The `Filter` class
The `Filter` class provides a fluent interface for defining filters in your Livewire component as well as retrieving information about the filter.
### `make($key)`
The first method you must call is the `make` method and pass it a unique key. After this method has been called, you can call any of the other methods in whatever order you want.
### `options($values)`
If you're using a filter that requires options, you can pass an array of those values into the `options` method. Calling the `options` method without any arguments will return the defined options for the filter.
### `value($values)`
If you would like to set the value of a filter, you can pass the value or an array of values into the `value` method. Calling the `value` method without any arguments will return the current value of the filter.
### `default($values)`
When defining a filter, you should use the `default` method to set the initial value of the filter. This will store the initial value on the object as well to help with determining the status of active filters as well as resetting the filter to its original state. Calling the `default` method without any arguments will return the initial value that you specified when you defined the filter.
### `meta(array $values)`
If you would like to set additional information on the filter to be used in the view file, you can pass an array of values into the `meta` method. Calling the `meta` method without any arguments will return the current array of meta information.
## Events
### `livewire-filters-reset`
### `livewire-filters-updated`
When a filter is updated, it will emit this event with 2 arguments: `key` and `payload`. The key should be used in identifying which filter should be updated. The `payload` is the new value of the filter.
This event is automatically handled by the `HasFilters` trait. If you would like to customize how the updates are handled, you can listen for this event and use your own method or override the `handleUpdateEvent` method.
## Making your own filters
In addition to the included filters, you can also make additional filters to suit your needs.
```php
use Kirschbaum\LivewireFilters\FilterComponent;
class DateFilter extends FilterComponent
{
public function render()
{
return view('livewire.filters.date-filter');
}
}
```
```blade
@if ($value !== $initialValue)
Reset
@endif
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
### Security
If you discover any security related issues, please email [email protected] or [email protected] instead of using the issue tracker.
## Credits
- [David VanScott](https://github.com/davidvanscott)
## Sponsorship
Development of this package is sponsored by Kirschbaum, a developer driven company focused on problem solving, team building, and community. Learn more [about us](https://kirschbaumdevelopment.com) or [join us](https://careers.kirschbaumdevelopment.com)!
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.