From 308348ffc2343ff4e7dc44529c61cf73b71664ec Mon Sep 17 00:00:00 2001 From: Daniel Werner Date: Wed, 6 Mar 2024 19:39:54 +0100 Subject: [PATCH] Update docs --- README.md | 153 ++++++++++++++++++++++++++++++++++---- src/DataGrid/DataGrid.php | 4 +- 2 files changed, 139 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 4f1cee0..cf13bfd 100755 --- a/README.md +++ b/README.md @@ -1,17 +1,21 @@ -# Laravel integration for the Grid.js +# LaravelDatagrid [![Latest Version on Packagist](https://img.shields.io/packagist/v/wdev-rs/laravel-datagrid.svg?style=flat-square)](https://packagist.org/packages/wdev-rs/laravel-datagrid) [![Build Status](https://github.com/wdev-rs/laravel-datagrid/actions/workflows/test.yml/badge.svg)](https://github.com/wdev-rs/laravel-datagrid/actions/workflows/test.yml) [![Quality Score](https://img.shields.io/scrutinizer/g/wdev-rs/laravel-datagrid.svg?style=flat-square)](https://scrutinizer-ci.com/g/wdev-rs/laravel-datagrid) [![Total Downloads](https://img.shields.io/packagist/dt/wdev-rs/laravel-datagrid.svg?style=flat-square)](https://packagist.org/packages/wdev-rs/laravel-datagrid) -This package is a Laravel integration for the [Grid.js](https://gridjs.io/). The packages makes it easy to create data-grid for your Laravel application, for example admin panel lists. -It covers the basic server side functionalities for Grid.js like search, sorting and pagination. +This packages makes it easy to create data-grid for your Laravel application, for example admin panels, or any other +searchable and sortable list. This package comes with 2 frontend options: +- [Grid.js](https://gridjs.io/) +- DataGrid's own Vue 3 frontend. + +Both frontends offer server side functionalities like searching, sorting and pagination. ![Laravel DataGrid](https://raw.githubusercontent.com/wdev-rs/laravel-datagrid/master/resources/img/laravel-datagrid.png) ## Demo -Please find the demo of the application [here](https://laravel-datagrid.wdev.rs) and the source code of the demo application +Please find a demo application [here](https://laravel-datagrid.wdev.rs) and the source code of the demo application [here](https://github.com/wdev-rs/laravel-datagrid-demo); ## Installation @@ -22,29 +26,65 @@ You can install the package via composer: composer require wdev-rs/laravel-datagrid ``` -Install the Vue.js integration -(install the 4.0 version, the 5.0 doesn't work with the laravel-datagrid due to a [bug](https://github.com/grid-js/gridjs-vue/issues/427) in gridjs-vue): +Optional - if you use Grid.js install the package with npm + +```bash +npm install gridjs@^6.0.0 +``` + +Publish the vendor files by running the following command: + +**Using Grid.js frontend** ```bash -npm install gridjs-vue@^4.0.0 +php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="gridjs" ``` -Publish the vendor files by running +**Using Vue 3 frontend** ```bash -php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" +php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="datagrid" ``` Register the DataGrid fronted Vue.js component by adding the following line to your `app.js`: +**Using Grid.js frontend** + ```javascript -import './vendor/laravel-datagrid/laravel-datagrid'; +import DataGrid from "./vendor/laravel-datagrid/gridjs/Components/DataGrid.vue"; + +app.component('data-grid', DataGrid); +``` + +Use the component in your view file (or in another component): +```html + +``` + +**Using Datagrid frontend** + +```javascript +import DataGrid from "./vendor/laravel-datagrid/datagrid/Components/DataGrid.vue"; + +app.component('data-grid', DataGrid); +``` + +Use the component in your view file (or in another component): +```html + ``` ## Usage The base of this package is the `\WdevRs\LaravelDatagrid\DataGrid\DataGrid` class. This class is used to define the -columns and the behavior of the datagrid. While you can use this class directly from the controller, I'll +columns and the behavior of the datagrid. While you can use this class directly from the controller, I suggest extending it and create separate classes for each datagrid. ``` php @@ -61,6 +101,7 @@ class CategoriesDataGrid extends DataGrid ->column('name', 'Name', function ($category) { return view('admin.categories.actions.edit_link', ['category' => $category])->render(); }) + ->key('id') } } ``` @@ -72,6 +113,11 @@ The `column` method is used to define the columns of the DataGrid, the argument - `formatter` - optional, callable allows you to format the display of the column. As you can see from the above example probably the most elegant way to do this is to include a blade view and render it. - `width` - optional, the with of the column +- `sortable` - optional, boolean if the column should be sortable, default true +- `searchable` - optional, boolean if the column should be searchable, default true + +The `key` method defines the unique identifier for the rows, usually id. Specifying the +key is necessary for the mass actions to work when using datagrid frontend. ### Data sources You can create data grid from different data sources: @@ -89,7 +135,7 @@ When the DataGrid definition is ready, you can add it to the controller: ``` If the `render` method is called without arguments it will use the default view `resources/views/vendor/laravel-datagrid/datagrid.blade.php`, -or you can pass your own view and include the DataGrid blade file there: +or you can pass your own view and use the DataGrid there: ```php public function index(CategoriesDataGrid $dataGrid, Request $request) @@ -97,6 +143,23 @@ or you can pass your own view and include the DataGrid blade file there: return $dataGrid->render('admin.common.index'); } ``` + +If you use Inertia for frontend, you can configire laravel-datagrid to use +inertia for rendering instead of blade. First publish the config file: + +```shell +php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="config" +``` + +Change the rendering method in the published `config/laravel-datagrid.php`: + +```php +'render_with' => \WdevRs\LaravelDatagrid\LaravelDatagrid::RENDER_INERTIA +``` + +Now you can pass the name of the vue component to the `render` method, it +is going to be rendered with Inertia. + ## Available commands ###### Code related @@ -135,9 +198,11 @@ Generated class ## Frontend customisations -The frontend component of the DataGrid can be found in the `resources/js/vendor/laravel-datagrid/components/DataGrid.vue` +### Using Grid.js + +The frontend component of the DataGrid can be found in the `resources/js/vendor/laravel-datagrid/gridjs/Components/DataGrid.vue` By default DataGrid comes with one row action, which is the delete action. This action can be found in the following file: -`resources/js/vendor/laravel-datagrid/actions/delete.js` +`resources/js/vendor/laravel-datagrid/gridjs/actions/delete.js` You can extend it with more custom actions by creating them based on the existing one. To add the to the datagrid, extend the `cols` definition in the `DataGrid.vue`: @@ -157,14 +222,70 @@ extend the `cols` definition in the `DataGrid.vue`: ) ``` -## Upgrade from Laravel DataGrid 0.3 +### Using Datagrid Vue3 + +Datagrid's own vue 3 frontend offers extended functionality compared to +grid.js, for example mass actions, filters and row action customisations. + +#### Mass actions +Mass actions is a method to run specific action on multiple records. For example delete +multiple records at once. + +When using mass actions I suggest using datagrid in a wrapper component +Mass actions can be defined using the `mass-actions` prop in an array +`[{'action' : 'massDelete', 'label': 'Delete'}]` + +Datagrid will fire an event when the user selects rows and runs an action on them. +The event name is what you define as `action`, in this case massDelete. +Handle the event on usual way, the handler gets the array of selectedIds as an argument: + +```vue +@massDelete="(selectedIds) => alert('Simulating mass delete on id(s): ' + selectedIds.join(','))" +``` + +Please find the code of the complete component below. + +```vue + + + + +``` + +## Upgrade from Laravel DataGrid 0.x Update the vendor assets using --force option: +**Using Grid.js** ```php -php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --force +php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="gridjs" --force ``` +**Using datagrid frontend** +```php +php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="datagrid" --force +``` + +Update the import paths in the app.js to use correct DataGrid compoent (grid.js or datagrid), see the example above. + Update the usage of the data-grid component to pass the rows property: ```html diff --git a/src/DataGrid/DataGrid.php b/src/DataGrid/DataGrid.php index 2758f60..2c7e375 100644 --- a/src/DataGrid/DataGrid.php +++ b/src/DataGrid/DataGrid.php @@ -3,8 +3,8 @@ namespace WdevRs\LaravelDatagrid\DataGrid; use Illuminate\Database\Eloquent\Builder; +use Illuminate\Foundation\Auth\User; use Illuminate\Support\Collection; -use Inertia\Inertia; use WdevRs\LaravelDatagrid\DataGrid\DataSources\ArrayDataSource; use WdevRs\LaravelDatagrid\DataGrid\DataSources\CollectionDataSource; use WdevRs\LaravelDatagrid\DataGrid\DataSources\DataSourceContract; @@ -72,7 +72,7 @@ public function render(string $view = 'laravel-datagrid::datagrid') switch (config('laravel-datagrid.render_with')) { case LaravelDatagrid::RENDER_INERTIA: - return Inertia::render($view, [ + return \Inertia\Inertia::render($view, [ 'baseUrl' => $request->url(), 'columns' => $this->columns, 'rows' => $this->getData($request)