From 8f42d1d704e229bb8971a69e39ef4cf45172e9fd Mon Sep 17 00:00:00 2001 From: pxpm Date: Fri, 7 Feb 2025 16:07:40 +0000 Subject: [PATCH 1/3] docs for agnostic filters --- 7.x-dev/crud-filters.md | 81 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/7.x-dev/crud-filters.md b/7.x-dev/crud-filters.md index 205e3154..70486a89 100644 --- a/7.x-dev/crud-filters.md +++ b/7.x-dev/crud-filters.md @@ -555,6 +555,87 @@ Inside this file, you'll have:
+ +## How to use Filters on any admin panel page + +Filters can be added to any admin panel page, not just the main CRUD table. Imagine that you want to have a dashboard page, with a few widgets that show some data. You can add filters to that page, and use them to filter the data shown in the widgets. +You start by creating a new page, eg: a reports page. +```bash +php artisan backpack:page Reports +``` +**NOTE:** You can read more about creating your custom pages in the [creating a custom page docs.](/docs/{{version}}/base-about#custom-pages-1) + +After the page is created, you should edit the `resources/views/admin/reports.blade.php` file and add the filters navbar and the event listeners: +```diff +@extends(backpack_view('blank')) + +@section('content') +
+

Reports

+

Page for Reports

+
+
+
+
+
+
++ @include('crud::inc.filters_navbar') +
+
+
+
+@endsection + ++@push('after_scripts') ++ ++@endpush +``` + +After that, time to add your own filters in the `ReportsController.php` + +```php +class ReportsController extends Controller +{ + public function index() + { + $crud = app('crud'); + + $crud->addFilter([ + 'type' => 'simple', + 'name' => 'checkbox', + 'label' => 'Simple', + ], false); + + $crud->addFilter([ // dropdown filter + 'name' => 'select_from_array', + 'type' => 'dropdown', + 'label'=> 'Dropdown', + ], ['one' => 'One', 'two' => 'Two', 'three' => 'Three']); + + return view('admin.reports', [ + 'title' => 'Reports', + 'breadcrumbs' => [ + trans('backpack::crud.admin') => backpack_url('dashboard'), + 'Reports' => false, + ], + 'crud' => $crud, + ]); + } +} +``` +
+ ## Examples From 5b1771844242247b0d4ca6efdd61fd094a59fe0d Mon Sep 17 00:00:00 2001 From: pxpm Date: Fri, 7 Feb 2025 16:15:12 +0000 Subject: [PATCH 2/3] wip --- 7.x-dev/crud-filters.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/7.x-dev/crud-filters.md b/7.x-dev/crud-filters.md index 70486a89..11228123 100644 --- a/7.x-dev/crud-filters.md +++ b/7.x-dev/crud-filters.md @@ -634,6 +634,11 @@ class ReportsController extends Controller } } ``` + +That's it, you should now have the filters navbar on your reports page. You can use the event listeners to update the data shown on the page based on the filters selected by the user. + +<-- INSERT IMAGE --> +
From 3a69a8792fd482852dc4a6aa57898db4fc66527d Mon Sep 17 00:00:00 2001 From: Cristian Tabacitu Date: Mon, 17 Feb 2025 11:33:54 +0200 Subject: [PATCH 3/3] polish custom filters docs --- 7.x-dev/crud-filters.md | 166 ++++++++++++++++++++------------------- 7.x-dev/release-notes.md | 6 +- 2 files changed, 91 insertions(+), 81 deletions(-) diff --git a/7.x-dev/crud-filters.md b/7.x-dev/crud-filters.md index 11228123..29a2bcd0 100644 --- a/7.x-dev/crud-filters.md +++ b/7.x-dev/crud-filters.md @@ -555,17 +555,87 @@ Inside this file, you'll have:
+ +## Examples + +Use a dropdown to filter by the values of a MySQL ENUM column: + +```php +CRUD::filter('published') + ->type('select2') + ->values(function() { + return \App\Models\Test::getEnumValuesAsAssociativeArray('published'); + }) + ->whenActive(function($value) { + CRUD::addClause('where', 'published', $value); + }); +``` + +Use a select2 to filter by a 1-n relationship: +```php +CRUD::filter('category_id') + ->type('select2') + ->values(function() { + return \App\Models\Category::all()->pluck('name', 'id')->toArray(); + }) + ->whenActive(function($value) { + CRUD::addClause('where', 'category_id', $value); + }); +``` + +Use a select2_multiple to filter Products by an n-n relationship: +```php +CRUD::filter('tags') + ->type('select2_multiple') + ->values(function() { // the options that show up in the select2 + return Product::all()->pluck('name', 'id')->toArray(); + }) + ->whenActive(function($values) { + foreach (json_decode($values) as $key => $value) { + $this->crud->query = $this->crud->query->whereHas('tags', function ($query) use ($value) { + $query->where('tag_id', $value); + }); + } + }); +``` + +Use a simple filter to add a scope if the filter is active: +```php +// add a "simple" filter called Published +CRUD::filter('published') + ->type('simple') + ->whenActive(function() { // if the filter is active (the GET parameter "published" exits) + CRUD::addClause('published'); + }); +``` + +Use a simple filter to show the softDeleted items (trashed): +```php +CRUD::filter('trashed') + ->type('simple') + ->whenActive(function($values) { + $this->crud->query = $this->crud->query->onlyTrashed(); + }); +``` + + +## Tips and Tricks + -## How to use Filters on any admin panel page +### Use Filters on custom admin panel pages Filters can be added to any admin panel page, not just the main CRUD table. Imagine that you want to have a dashboard page, with a few widgets that show some data. You can add filters to that page, and use them to filter the data shown in the widgets. -You start by creating a new page, eg: a reports page. + + +![](https://backpackforlaravel.com/uploads/docs/filters/filters-in-custom-page.png) + +You start by [creating a new page](/docs/{{version}}/base-about#custom-pages-1) to hold your custom content, eg: a reports page. + ```bash php artisan backpack:page Reports ``` -**NOTE:** You can read more about creating your custom pages in the [creating a custom page docs.](/docs/{{version}}/base-about#custom-pages-1) -After the page is created, you should edit the `resources/views/admin/reports.blade.php` file and add the filters navbar and the event listeners: +To use filters on a custom admin panel page, you should edit the blade file (in this example the `resources/views/admin/reports.blade.php` file) to **add the filters navbar** and **the event listeners**: ```diff @extends(backpack_view('blank')) @@ -589,20 +659,24 @@ After the page is created, you should edit the `resources/views/admin/reports.bl +@push('after_scripts') + +@endpush ``` -After that, time to add your own filters in the `ReportsController.php` +After that, time to add your own filters in your controller (in this example, `ReportsController.php`): ```php class ReportsController extends Controller @@ -635,77 +709,11 @@ class ReportsController extends Controller } ``` -That's it, you should now have the filters navbar on your reports page. You can use the event listeners to update the data shown on the page based on the filters selected by the user. - -<-- INSERT IMAGE --> - -
- - -## Examples - -Use a dropdown to filter by the values of a MySQL ENUM column: - -```php -CRUD::filter('published') - ->type('select2') - ->values(function() { - return \App\Models\Test::getEnumValuesAsAssociativeArray('published'); - }) - ->whenActive(function($value) { - CRUD::addClause('where', 'published', $value); - }); -``` - -Use a select2 to filter by a 1-n relationship: -```php -CRUD::filter('category_id') - ->type('select2') - ->values(function() { - return \App\Models\Category::all()->pluck('name', 'id')->toArray(); - }) - ->whenActive(function($value) { - CRUD::addClause('where', 'category_id', $value); - }); -``` - -Use a select2_multiple to filter Products by an n-n relationship: -```php -CRUD::filter('tags') - ->type('select2_multiple') - ->values(function() { // the options that show up in the select2 - return Product::all()->pluck('name', 'id')->toArray(); - }) - ->whenActive(function($values) { - foreach (json_decode($values) as $key => $value) { - $this->crud->query = $this->crud->query->whereHas('tags', function ($query) use ($value) { - $query->where('tag_id', $value); - }); - } - }); -``` - -Use a simple filter to add a scope if the filter is active: -```php -// add a "simple" filter called Published -CRUD::filter('published') - ->type('simple') - ->whenActive(function() { // if the filter is active (the GET parameter "published" exits) - CRUD::addClause('published'); - }); -``` - -Use a simple filter to show the softDeleted items (trashed): -```php -CRUD::filter('trashed') - ->type('simple') - ->whenActive(function($values) { - $this->crud->query = $this->crud->query->onlyTrashed(); - }); -``` - - -## Tips and Tricks +That's it, you should now have the filters navbar on your reports page. You can use the event listeners to update the data shown on the page based on the filters selected by the user. +Here are the Javascript events you can listen to: +- `backpack:filter:changed` when a filter is changed; +- `backpack:filter:cleared` when a filter is cleared; +- `backpack:filters:cleared` when all filters are cleared; ### Add a debounce time to filters @@ -725,7 +733,7 @@ CRUD::filter('name') All filter types accept a `debounce`, like for example the simple filter, range filter etc. -### Adding a filter using array syntax +### Add a filter using array syntax In Backpack v4-v5 we used an "array syntax" to add and manipulate filters. That syntax is still supported for backwards-compatiblity. But it most cases it's easier to use the fluent syntax. diff --git a/7.x-dev/release-notes.md b/7.x-dev/release-notes.md index f5cc34f0..664e7749 100644 --- a/7.x-dev/release-notes.md +++ b/7.x-dev/release-notes.md @@ -30,8 +30,10 @@ Previously when working with Operations, developers found themselves needing to ### Re-Usable Filters -// just like your air purifier -// TODO + +![](https://backpackforlaravel.com/uploads/docs/filters/filters-in-custom-page.png) + +Starting with this Backpack version, you can use the [filters](/docs/{{version}}/crud-filters) in custom pages too. Instead of being tied to DataTables, filters now trigger generic Javascript events like `backpack:filter:changed`. You can catch those events using custom code in Javascript or Livewire... and do stuff. This it possible to use filters on completely custom pages - like custom dashboards, custom reports or custom operations. [Read more](/docs/{{version}}/crud-filters#use-filters-on-custom-admin-panel-pages). ### Filters inside CustomViews