Skip to content

Commit 3367339

Browse files
ginkelsoft-developmentginkelsoft-development
authored
Feature/readme file (#2)
1 parent bd7e0ac commit 3367339

File tree

2 files changed

+185
-3
lines changed

2 files changed

+185
-3
lines changed

‎README.md‎

Lines changed: 183 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,187 @@
11
# Ginkelsoft DataTables
22

3-
Ginkelsoft DataTables is a flexible and easy-to-use package for managing tabular data in your **Laravel** projects. It offers both a **base DataTable** for standard server-rendered apps and **Livewire integration** for dynamic, AJAX-driven experiences. With built-in support for filtering, searching, sorting, and bulk actions, it provides a quick way to build powerful data tables.
3+
Ginkelsoft DataTables is a flexible and easy-to-use package for managing tabular data in your Laravel projects. It supports both a **base DataTable** class for traditional server-rendered apps and an **optional Livewire** component for dynamic, AJAX-driven experiences. You can easily add filtering, searching, sorting, and bulk actions with minimal setup.
44

55
---
6+
7+
## Table of Contents
8+
9+
1. [Requirements](#requirements)
10+
2. [Installation](#installation)
11+
3. [Usage (Without Livewire)](#usage-without-livewire)
12+
4. [Usage (With Livewire)](#usage-with-livewire)
13+
5. [Working with Actions](#working-with-actions)
14+
6. [Additional Features](#additional-features)
15+
7. [Contributing](#contributing)
16+
8. [License](#license)
17+
18+
---
19+
20+
## Requirements
21+
22+
- **PHP 8.2+**
23+
- **Laravel 10.0+** 
24+
- **Livewire** *(Optional, only if you need AJAX-driven data tables.)*
25+
26+
---
27+
28+
## Installation
29+
30+
1. **Require the package**:
31+
32+
```bash
33+
composer require ginkelsoft/datatables:dev-main
34+
```
35+
36+
2. **Optionally register** the service provider if not using auto-discovery:
37+
38+
```php
39+
// config/app.php
40+
41+
'providers' => [
42+
// ...
43+
Ginkelsoft\DataTables\DataTableServiceProvider::class,
44+
];
45+
```
46+
47+
3. **Publish the package views** (optional) for customization:
48+
49+
```bash
50+
php artisan vendor:publish --provider="Ginkelsoft\\DataTables\\DataTableServiceProvider" --tag=views
51+
```
52+
53+
---
54+
55+
## Usage (Without Livewire)
56+
57+
For a traditional server-rendered app:
58+
59+
```php
60+
use Ginkelsoft\DataTables\DataTable;
61+
use Ginkelsoft\DataTables\Column;
62+
use App\Models\User;
63+
64+
public function index()
65+
{
66+
$query = User::query();
67+
68+
$datatable = (new DataTable($query))
69+
->setColumns([
70+
Column::make('id', 'ID'),
71+
Column::make('name', 'Name'),
72+
Column::make('email', 'Email'),
73+
])
74+
->setPerPage(10);
75+
76+
$rows = $datatable->getRows();
77+
78+
return view('users.index', compact('rows'));
79+
}
80+
```
81+
82+
And in `resources/views/users/index.blade.php`:
83+
84+
```blade
85+
<table>
86+
<thead>
87+
<tr>
88+
<th>ID</th>
89+
<th>Name</th>
90+
<th>Email</th>
91+
</tr>
92+
</thead>
93+
<tbody>
94+
@foreach($rows as $row)
95+
<tr>
96+
<td>{{ $row->id }}</td>
97+
<td>{{ $row->name }}</td>
98+
<td>{{ $row->email }}</td>
99+
</tr>
100+
@endforeach
101+
</tbody>
102+
</table>
103+
104+
{{ $rows->links() }}
105+
```
106+
107+
---
108+
109+
## Usage (With Livewire)
110+
111+
If you prefer an **AJAX-driven** workflow with real-time sorting, searching, and pagination:
112+
113+
```blade
114+
<livewire:datatable
115+
model="App\\Models\\User"
116+
:columns="['id', 'name', 'email']"
117+
:actions="[
118+
['label' => 'Edit', 'route' => 'users.edit'],
119+
['label' => 'Delete', 'route' => 'users.destroy']
120+
]"
121+
:bulkActions="[
122+
'delete' => ['label' => 'Delete', 'route' => 'users.bulk.delete'],
123+
'export' => ['label' => 'Export', 'route' => 'users.bulk.export']
124+
]"
125+
/>
126+
```
127+
128+
You can now:
129+
130+
- **Search** by typing in the search field (if your component includes that feature).
131+
- **Sort** by clicking column headers.
132+
- **Paginate** without page reload.
133+
- **Select rows** individually or choose to select all.
134+
135+
---
136+
137+
## Working with Actions
138+
139+
### Row Actions
140+
141+
Specify row-level actions in your Blade:
142+
143+
```blade
144+
:actions="[
145+
['label' => 'Edit', 'route' => 'users.edit'],
146+
['label' => 'Delete', 'route' => 'users.destroy']
147+
]"
148+
```
149+
150+
### Bulk Actions
151+
152+
For bulk actions (like deleting multiple rows) set `:bulkActions`:
153+
154+
```blade
155+
:bulkActions="[
156+
'delete' => ['label' => 'Delete', 'route' => 'users.bulk.delete'],
157+
'export' => ['label' => 'Export', 'route' => 'users.bulk.export']
158+
]"
159+
```
160+
161+
When multiple rows are selected, the component redirects to the specified route with `ids` in the query/string, so you can handle them in your controller.
162+
163+
---
164+
165+
## Additional Features
166+
167+
- **Search Class** for multi-column searching.
168+
- **Filter Class** for custom filters (status, categories, etc.).
169+
- **Sorting Class** for ascending/descending ordering.
170+
- **Select All** (with confirmation modal) to choose between only visible rows or all rows.
171+
172+
---
173+
174+
## Contributing
175+
176+
1. **Fork** this repository.
177+
2. **Create** a new branch for your feature or fix.
178+
3. **Push** your changes and open a **pull request**.
179+
180+
We welcome improvements to code quality, new features, or better documentation.
181+
182+
---
183+
184+
## License
185+
186+
Ginkelsoft DataTables is open-sourced software licensed under the [MIT license](LICENSE).
187+

‎composer.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@
99
}
1010
},
1111
"require": {
12-
"php": ">=8.0",
13-
"illuminate/support": "^9.0|^10.0|^11.0|^12.0",
12+
"php": ">=8.2",
13+
"illuminate/support": "^10.0|^11.0|^12.0",
1414
"livewire/livewire": "^3.0"
1515
},
1616
"extra": {

0 commit comments

Comments
 (0)