Skip to content

Commit 5b39c6f

Browse files
yajrayajra
authored
Merge pull request yajra#74 from Arne1303/search-panes-documentation
Added SearchPanes documentation
2 parents 079e2ae + cd867fb commit 5b39c6f

File tree

5 files changed

+168
-1
lines changed

5 files changed

+168
-1
lines changed

‎documentation.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,11 @@
6565
- [Order Columns](/docs/{{package}}/{{version}}/order-columns)
6666
- [Order By Nulls Last](/docs/{{package}}/{{version}}/order-by-nulls-last)
6767

68+
- ## SearchPanes
69+
- [Add SearchPanes](/docs/{{package}}/{{version}}/search-panes-starter.md)
70+
- [Hide Columns in SearchPanes](/docs/{{package}}/{{version}}/search-panes-hide-columns.md)
71+
- [Further options](/docs/{{package}}/{{version}}/search-panes-options.md)
72+
6873
- ## Utilities
6974
- [XSS filtering](/docs/{{package}}/{{version}}/xss)
7075
- [Blacklist Columns](/docs/{{package}}/{{version}}/blacklist)

‎quick-starter.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,22 +31,28 @@ php artisan ui bootstrap --auth
3131
## Install Datatables.net assets
3232

3333
```
34-
yarn add datatables.net-bs4 datatables.net-buttons-bs4
34+
yarn add datatables.net-bs4 datatables.net-buttons-bs4 datatables.net-select-bs4 datatables.net-searchpanes-bs4
3535
```
3636

37+
> {tip} datatables.net-select-bs4` and `datatables.net-searchpanes-bs4` are only required if you want to use SearchPanes
38+
3739
## Register datatables.net assets in bootstrap.js and app.scss
3840

3941
Edit `resources/js/bootstrap.js` and add the following:
4042

4143
require('bootstrap');
4244
require('datatables.net-bs4');
4345
require('datatables.net-buttons-bs4');
46+
require('datatables.net-select-bs4');
47+
require('datatables.net-searchpanes-bs4');
4448

4549
Edit `resources/scss/app.scss` and add the following:
4650

4751
// DataTables
4852
@import "~datatables.net-bs4/css/dataTables.bootstrap4.css";
4953
@import "~datatables.net-buttons-bs4/css/buttons.bootstrap4.css";
54+
@import '~datatables.net-select-bs4/css/select.dataTables.css';
55+
@import '~datatables.net-searchpanes-dt/css/searchPanes.dataTables.css';
5056

5157
## Compile assets
5258

‎search-panes-hide-columns.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Hide Columns in SearchPanes
2+
3+
Some columns you might not want in your SearchPanes, to hide them you can add `->searchPanes(false)` in your column
4+
definition:
5+
6+
```php
7+
protected function getColumns() : array
8+
{
9+
return [
10+
Column::make('id')
11+
->searchPanes(false);
12+
]
13+
}
14+
```

‎search-panes-options.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Further SearchPanes options
2+
3+
```php
4+
public function html() : \Yajra\DataTables\Html\Builder
5+
{
6+
return $this->builder()
7+
->searchPanes(
8+
SearchPane::make()
9+
->hideCount() // Hides the count next to the options, the amount of records with the filters
10+
->hideTotal() // Hides the total how many are available without the filters
11+
->clear(false) // Hides the clear button, used to clear the user selection
12+
->controls(false) // disable controls (search for filters)
13+
->layout('columns-2') // can be used to set the layout (amount of search panes in one row)
14+
->order(['user_id', 'age']) // Sets the order of the search panes, uses the name of the search pane
15+
->orderable(false) // If the order icons should be displayed in the interface
16+
->panes( // Can be used to add additional search panes which do not belong to any existing column
17+
[
18+
// SearchPane::make()...
19+
]
20+
)
21+
->dtOpts( // Sets the options for the datatables inside the searchpanes
22+
[
23+
'paging' => true,
24+
'pagingType' => 'numbers'
25+
]
26+
)
27+
28+
);
29+
}
30+
```

‎search-panes-starter.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Add SearchPane
2+
3+
[SearchPanes](https://datatables.net/extensions/searchpanes/) ([example](https://datatables.net/extensions/searchpanes/examples/initialisation/simple.html))
4+
allow the user to quickly filter the datatable after predefined filters.
5+
6+
> {note} To use datatables you need to make sure that the npm packages `datatables.net-select-bs4` and `datatables.net-searchpanes-bs4` are installed and added to your `app.js`/`app.css` files.
7+
8+
## Adding SearchPanes to the frontend
9+
10+
To be able to see SearchPanes you need to either add them fixed in the dom (displayed at all time) or add a button which
11+
opens them as popup.
12+
13+
### Adding SearchPanes fixed in the dom
14+
15+
SearchPanes can be added to a table via the dom string, in it, they are marked with a `P` if you for example
16+
are using `Bfrtip` as dom you can use `PBfrtip` to display the SearchPanes at the top of the datatable, or `BfrtipP`
17+
to display them at the very bottom.
18+
19+
Setting the dom String with the `\Yajra\DataTables\Html\Builder`:
20+
```php
21+
public function html() : \Yajra\DataTables\Html\Builder
22+
{
23+
// Setting the dom string directly
24+
return $this->builder()
25+
->searchPanes(SearchPane::make())
26+
->dom('PBfrtip');
27+
28+
// Alternatively set the dom with parameters
29+
return $this->builder()
30+
->searchPanes(SearchPane::make())
31+
->parameters([
32+
'dom' => 'PBfrtip'
33+
]);
34+
}
35+
```
36+
37+
### Adding SearchPanes with a button
38+
39+
To add a button which opens the SearchPanes you need to make one extending `searchPanes`:
40+
41+
```php
42+
public function html() : \Yajra\DataTables\Html\Builder
43+
{
44+
// Adding via class
45+
return $this->builder()
46+
->searchPanes(SearchPane::make())
47+
->buttons([
48+
\Yajra\DataTables\Html\Button::make('searchPanes')
49+
// other buttons...
50+
]);
51+
52+
// Alternatively set the buttons with options
53+
return $this->builder()
54+
->searchPanes(SearchPane::make())
55+
->parameters([
56+
'buttons' => ['searchPanes', /*other buttons...*/]
57+
]);
58+
}
59+
```
60+
61+
## Adding SearchPanes to the backend
62+
63+
The SearchPanes can be filled in the datatables declaration via the `searchPane()` method. The method takes the column
64+
for which the SearchPane is, as well as the options of the SearchPane. It also allows you to set custom processing for
65+
the options.
66+
67+
68+
```php
69+
public function dataTable($query) : Yajra\DataTables\DataTableAbstract
70+
{
71+
return datatables()
72+
->eloquent($query)
73+
// Adding the SearchPane
74+
->searchPane(
75+
/*
76+
* This is the column for which this SearchPane definition is for
77+
*/
78+
'user_id',
79+
80+
/*
81+
* Here we define the options for our SearchPane. This should be either a collection or an array with the
82+
* form:
83+
* [
84+
* [
85+
* 'value' => 1,
86+
* 'label' => 'display value',
87+
* 'total' => 5, // optional
88+
* 'count' => 3 // optional
89+
* ],
90+
* [
91+
* 'value' => 2,
92+
* 'label' => 'display value 2',
93+
* 'total' => 6, // optional
94+
* 'count' => 5 // optional
95+
* ],
96+
* ]
97+
*/
98+
fn() => User::query()->select('id as value', 'name as label')->get(),
99+
100+
/*
101+
* This is the filter that gets executed when the user selects one or more values on the SearchPane. The
102+
* values are always given in an array even if just one is selected
103+
*/
104+
function (\Illuminate\Database\Eloquent\Builder $query, array $values) {
105+
return $query
106+
->whereIn(
107+
'id',
108+
$values);
109+
}
110+
);
111+
}
112+
```

0 commit comments

Comments
 (0)