polish custom filters docs

Author: tabacitu

7.x-dev/crud-filters.md

@@ -555,17 +555,87 @@ Inside this file, you'll have:
 
 <hr>
 
+<a name="examples"></a>
+## 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();
+    });
+```
+
+<a name="tips-and-tricks"></a>
+## Tips and Tricks
+
 <a name="using-filters-on-admin-page"></a>
-## 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')
 +<script>
 +    document.addEventListener('backpack:filters:cleared', function (event) {       
-+       console.log('filters cleared', event);
++       console.log('all filters cleared', event);
++    });
++
++    document.addEventListener('backpack:filter:cleared', function (event) {       
++       console.log('one filter cleared', event);
 +    });
 +
 +   document.addEventListener('backpack:filter:changed', function (event) {
 +        let filterName = event.detail.filterName;
 +        let filterValue = event.detail.filterValue;
 +        let shouldUpdateUrl = event.detail.shouldUpdateUrl;
-+        console.log('filter changed', filterName, filterValue, shouldUpdateUrl);
++        console.log('one filter changed', filterName, filterValue, shouldUpdateUrl);
 +    });
 +</script>
 +@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 -->
-
-<hr>
-
-<a name="examples"></a>
-## 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();
-    });
-```
-
-<a name="tips-and-tricks"></a>
-## 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;
 
 <a name="debouncing-filters"></a>
 ### 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.
 
 <a name="adding-a-filter-using-array-syntax"></a>
-### 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.
 

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