diff --git a/README.md b/README.md index 2bc1490..c102094 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,187 @@ # Ginkelsoft DataTables -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. +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. --- + +## Table of Contents + +1. [Requirements](#requirements) +2. [Installation](#installation) +3. [Usage (Without Livewire)](#usage-without-livewire) +4. [Usage (With Livewire)](#usage-with-livewire) +5. [Working with Actions](#working-with-actions) +6. [Additional Features](#additional-features) +7. [Contributing](#contributing) +8. [License](#license) + +--- + +## Requirements + +- **PHP 8.2+** +- **Laravel 10.0+** +- **Livewire** *(Optional, only if you need AJAX-driven data tables.)* + +--- + +## Installation + +1. **Require the package**: + + ```bash + composer require ginkelsoft/datatables:dev-main + ``` + +2. **Optionally register** the service provider if not using auto-discovery: + + ```php + // config/app.php + + 'providers' => [ + // ... + Ginkelsoft\DataTables\DataTableServiceProvider::class, + ]; + ``` + +3. **Publish the package views** (optional) for customization: + + ```bash + php artisan vendor:publish --provider="Ginkelsoft\\DataTables\\DataTableServiceProvider" --tag=views + ``` + +--- + +## Usage (Without Livewire) + +For a traditional server-rendered app: + +```php +use Ginkelsoft\DataTables\DataTable; +use Ginkelsoft\DataTables\Column; +use App\Models\User; + +public function index() +{ + $query = User::query(); + + $datatable = (new DataTable($query)) + ->setColumns([ + Column::make('id', 'ID'), + Column::make('name', 'Name'), + Column::make('email', 'Email'), + ]) + ->setPerPage(10); + + $rows = $datatable->getRows(); + + return view('users.index', compact('rows')); +} +``` + +And in `resources/views/users/index.blade.php`: + +```blade + + + + + + + + + + @foreach($rows as $row) + + + + + + @endforeach + +
IDNameEmail
{{ $row->id }}{{ $row->name }}{{ $row->email }}
+ +{{ $rows->links() }} +``` + +--- + +## Usage (With Livewire) + +If you prefer an **AJAX-driven** workflow with real-time sorting, searching, and pagination: + +```blade + +``` + +You can now: + +- **Search** by typing in the search field (if your component includes that feature). +- **Sort** by clicking column headers. +- **Paginate** without page reload. +- **Select rows** individually or choose to select all. + +--- + +## Working with Actions + +### Row Actions + +Specify row-level actions in your Blade: + +```blade +:actions="[ + ['label' => 'Edit', 'route' => 'users.edit'], + ['label' => 'Delete', 'route' => 'users.destroy'] +]" +``` + +### Bulk Actions + +For bulk actions (like deleting multiple rows) set `:bulkActions`: + +```blade +:bulkActions="[ + 'delete' => ['label' => 'Delete', 'route' => 'users.bulk.delete'], + 'export' => ['label' => 'Export', 'route' => 'users.bulk.export'] +]" +``` + +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. + +--- + +## Additional Features + +- **Search Class** for multi-column searching. +- **Filter Class** for custom filters (status, categories, etc.). +- **Sorting Class** for ascending/descending ordering. +- **Select All** (with confirmation modal) to choose between only visible rows or all rows. + +--- + +## Contributing + +1. **Fork** this repository. +2. **Create** a new branch for your feature or fix. +3. **Push** your changes and open a **pull request**. + +We welcome improvements to code quality, new features, or better documentation. + +--- + +## License + +Ginkelsoft DataTables is open-sourced software licensed under the [MIT license](LICENSE). + diff --git a/composer.json b/composer.json index ea86a91..70129af 100644 --- a/composer.json +++ b/composer.json @@ -9,8 +9,8 @@ } }, "require": { - "php": ">=8.0", - "illuminate/support": "^9.0|^10.0|^11.0|^12.0", + "php": ">=8.2", + "illuminate/support": "^10.0|^11.0|^12.0", "livewire/livewire": "^3.0" }, "extra": {