Skip to content

Commit 7252dbd

Browse files
hamidrezarjhamidrezarj
committed
updated README
1 parent b102261 commit 7252dbd

File tree

1 file changed

+155
-23
lines changed

1 file changed

+155
-23
lines changed

‎README.md‎

Lines changed: 155 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,66 @@ return [
5656

5757
## Usage
5858

59+
This section covers various use cases and features of Laravel Datatable. From basic querying to advanced filtering and relationship handling, you'll find examples to help you make the most of this package.
60+
61+
### Table of Contents
62+
- [Method Parameters](#method-parameters)
63+
- [Filter Array Structure](#filter-array-structure)
64+
- [Return Data Structure](#return-data-structure)
65+
- [Basic Usage](#basic-usage)
66+
- [Using Query Builder](#using-query-builder)
67+
- [Advanced Filtering and Sorting](#advanced-filtering-and-sorting)
68+
- [Using `between` Search Function](#using-between-search-function)
69+
- [Filtering Model's Relationship](#filtering-models-relationship)
70+
71+
### Method Parameters
72+
73+
The `run` method of `DatatableFacade` accepts the following parameters:
74+
75+
1. `$mixed`: Model instance or query builder instance to perform queries on.
76+
2. `$requestParameters`: Contains parameters like `filter`, `sorting`, `size`, and `start` of required data.
77+
3. `$allowedFilters`: (Optional) Specifies columns users are allowed to filter on.
78+
4. `$allowedSortings`: (Optional) Specifies columns users are allowed to sort on.
79+
5. `$allowedSelects`: (Optional) Specifies which columns users can actually see.
80+
6. `$allowedRelations`: (Optional) Specifies which model relations users are allowed to filter on.
81+
82+
### Filter Array Structure
83+
84+
Each filter in the `filters` array should have the following attributes:
85+
86+
- `id`: Name of the column to filter on. When filtering a relationship's attribute, use the format: `relationName.attribute`. (`relationName` must exist as a `HasOne` or `HasMany` relationship in the base Model, e.g., User model)
87+
- `value`: Value of the filter
88+
- For most filter types: a single value
89+
- For `fn = 'between'`: an array of two values, e.g., `[min, max]`
90+
- `fn`: Type of filter to apply. Available options include:
91+
- `contains`
92+
- `between`
93+
- `equals`
94+
- `notEquals`
95+
- `lessThan`
96+
- `lessThanOrEqual`
97+
- `greaterThan`
98+
- `greaterThanOrEqual`
99+
- `datatype`: Type of column. Options include:
100+
- `text`
101+
- `numeric`
102+
- `date`
103+
104+
### Return Data Structure
105+
106+
The `run` method returns an array with the following structure:
107+
108+
```php
109+
[
110+
"data" => [
111+
// Array of matching records
112+
],
113+
"meta" => [
114+
"totalRowCount" => 10 // Total count of matching records
115+
]
116+
]
117+
```
118+
59119
### Basic Usage
60120

61121
Here's a simple example of requesting a chunk of 10 users starting from the 11th record (i.e., page 2 of the datatable):
@@ -90,17 +150,19 @@ $data = DatatableFacade::run(
90150
```
91151

92152
### Advanced Filtering and Sorting
93-
Here's an example of filtering users whose usernames contain 'sth', sorted by creation date in descending order:
153+
Here's an example of filtering users whose ages are greater than 15, sorted by creation date in descending order:
94154
```php
155+
$query = User::query();
156+
95157
$requestParameters = [
96158
'start' => 10,
97159
'size' => 10,
98160
'filters' => [
99161
[
100-
'id' => 'username',
101-
'value' => 'sth',
102-
'fn' => 'contains',
103-
'datatype' => 'text'
162+
'id' => 'age',
163+
'value' => 15,
164+
'fn' => 'greaterThan',
165+
'datatype' => 'numeric'
104166
]
105167
],
106168
'sorting' => [
@@ -111,7 +173,7 @@ $requestParameters = [
111173
]
112174
];
113175

114-
$allowedFilters = ['username'];
176+
$allowedFilters = ['age'];
115177
$allowedSortings = ['created_at'];
116178

117179
$data = DatatableFacade::run(
@@ -123,29 +185,99 @@ $data = DatatableFacade::run(
123185
```
124186
**Note**: Ensure that columns used for filtering and sorting are included in the `$allowedFilters` and `$allowedSortings` arrays to avoid `InvalidFilterException` and `InvalidSortingException`.
125187

126-
### Method Parameters
127-
The `run` method of `DatatableFacade` accepts the following parameters:
188+
### Using `between` search function
189+
Here's an example of filtering users whose creation dates are between two dates:
190+
```php
191+
$query = User::query()
128192

129-
1. `$mixed`: Model instance or query builder instance to perform queries on.
130-
2. `$requestParameters`: Contains parameters like `filter`, `sorting`, `size`, and `start` of required data.
131-
3. `$allowedFilters`: (Optional) Specifies columns users are allowed to filter on.
132-
4. `$allowedSortings`: (Optional) Specifies columns users are allowed to sort on.
133-
5. `$allowedSelects`: (Optional) Specifies which columns users can actually see.
134-
6. `$allowedRelations`: (Optional) Specifies which model relations users are allowed to filter on.
193+
$requestParameters = [
194+
'start' => 0,
195+
'size' => 10,
196+
'filters' => [
197+
[
198+
'id' => 'created_at',
199+
'value' => ['2024-05-23 10:30:00', '2024-05-29 15:00:00'],
200+
'fn' => 'between',
201+
'datatype' => 'date'
202+
]
203+
],
204+
'sorting' => []
205+
];
206+
207+
$allowedFilters = array('created_at');
208+
$allowedSelects = array('username', 'age', 'created_at');
209+
210+
$data = (new Datatable())->run(
211+
$query,
212+
$requestParameters,
213+
$allowedFilters,
214+
allowedSelects: $allowedSelects
215+
);
216+
```
217+
**Note**: Using `$allowedSelects` will only return specified columns in the query result:
218+
```php
219+
[
220+
"data" => [
221+
[
222+
'username' => 'mwindler'
223+
'age' => 49
224+
'created_at' => '2024-05-23T12:00:00.000000Z'
225+
],
226+
// more matching records
227+
],
228+
"meta" => [
229+
"totalRowCount" => 10 // Total count of matching records
230+
]
231+
]
232+
```
135233

136-
### Filter Array Structure
137-
Each filter in the `filters` array should have the following attributes:
138-
- `id`: Name of the column to filter on
139-
- `value`: Value of the filter
140-
- `fn`: Type of filter to apply (e.g., contains, between, equals, less than)
141-
- `datatype`: Type of column (e.g., text, numeric, date)
234+
### Filtering Model's Relationship
235+
In this example, we filter only users who have posts that contain 'my post' in their titles:
142236

143-
### Return Data Structure
144-
The `run` method returns an array with the following structure:
237+
```php
238+
$query = User::query();
239+
240+
$requestParameters = [
241+
'start' => 0,
242+
'size' => 10,
243+
'filters' => [
244+
[
245+
'id' => 'posts.title',
246+
'value' => 'my post',
247+
'fn' => 'contains',
248+
'datatype' => 'text'
249+
]
250+
],
251+
'sorting' => []
252+
];
253+
254+
$allowedFilters = array('posts.title');
255+
$allowedRelations = array('posts');
256+
257+
$data = (new Datatable())->run(
258+
$query,
259+
$requestParameters,
260+
$allowedFilters,
261+
allowedRelations: $allowedRelations
262+
);
263+
```
264+
**Note**:
265+
- Use `posts.title` in `id` (the User model must have a `posts` relation defined in `Models/User` class)
266+
- Using `$allowedRelations` loads each user's posts in the query result:
145267
```php
146268
[
147269
"data" => [
148-
// Array of matching records
270+
[
271+
'id' => 1,
272+
'username' => 'sth',
273+
'posts' => [ // posts included in result
274+
[
275+
'title' => 'wow! my post got 1k impressions!'
276+
],
277+
// ...
278+
]
279+
],
280+
// more matching records
149281
],
150282
"meta" => [
151283
"totalRowCount" => 10 // Total count of matching records

0 commit comments

Comments
 (0)