itstructure / laravel-grid-view
Grid view for laravel framework
Installs: 32 588
Dependents: 2
Suggesters: 0
Security: 0
Stars: 24
Watchers: 2
Forks: 10
Open Issues: 1
Requires
- php: >=7.1.0
- laravel/framework: ~5.5.0|~5.6.0|~5.7.0|~5.8.0|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
README
Introduction
This package is to displaying the model data in a Grid table.
Requirements
- laravel 5.5+ | 6+ | 7+ | 8+ | 9+ | 10+ | 11+
- Bootstrap 4 for styling
- JQuery
- php >= 7.1
- composer
Installation
General from remote repository
Run the composer command:
composer require itstructure/laravel-grid-view "^1.1.5"
If you are testing this package from a local server directory
In application composer.json
file set the repository, as in example:
"repositories": [ { "type": "path", "url": "../laravel-grid-view", "options": { "symlink": true } } ],
Here,
../laravel-grid-view - directory path, which has the same directory level as application and contains Grid View package.
Then run command:
composer require itstructure/laravel-grid-view:dev-master --prefer-source
Publish files (Not necessary)
-
To publish views run command:
php artisan grid_view:publish --only=views
It stores view files to
resources/views/vendor/grid_view
folder. -
To publish translations run command:
php artisan grid_view:publish --only=lang
It stores translation files to
resources/lang/vendor/grid_view
folder. -
To publish all parts run command without
only
argument:php artisan grid_view:publish
Else you can use
--force
argument to rewrite already published files.
Where this is already used (my packages)
You can see this packages above as examples.
Usage
Make sure you use a Bootstrap 4 for styling and JQuery in your application.
Controller part
Must use EloquentDataProvider
to insert data in to the view template.
For EloquentDataProvider
class constructor use a model query object.
Example:
namespace App\Http\Controllers; use Itstructure\GridView\DataProviders\EloquentDataProvider;
class ExampleController extends Controller { public function example() { $dataProvider = new EloquentDataProvider(ExampleModel::query()); return view('example-view', [ 'dataProvider' => $dataProvider ]); } }
View template part
Use @gridView()
directive with config array in a blade view template.
Simple quick usage
You can simply set columns to display as string format in columnFields
array.
Note:
There search filter fields are displayed automatically. By default text form field filters are used.
If you don't want to use search filters, set useFilters
= false.
@php $gridData = [ 'dataProvider' => $dataProvider, 'title' => 'Panel title', 'useFilters' => false, 'columnFields' => [ 'id', 'active', 'icon', 'created_at' ] ]; @endphp
@gridView($gridData)
Alternative variant without a blade directive:
{!! grid_view([ 'dataProvider' => $dataProvider, 'useFilters' => false, 'columnFields' => [ 'id', 'active', 'icon', 'created_at' ] ]) !!}
Setting custom options
Main columns
Simple example:
@gridView([ 'dataProvider' => $dataProvider, 'columnFields' => [ [ 'label' => 'First Name', // Column label. 'attribute' => 'first_name', // Attribute, by which the row column data will be taken from a model. ], [ 'label' => 'Last Name', 'value' => function ($row) { return $row->last_name; } 'sort' => 'last_name' // To sort rows. Have to set if an 'attribute' is not defined for column. ], ] ])
Special columns
Besides main columns, there can be the next special columns:
-
ActionColumn
- is for displaying Buttons to view, edit and delete rows.Set
'class' => Itstructure\GridView\Columns\ActionColumn::class
in column optionThere are the next required
actionTypes
:- view - makes a link for viewing. Default url scheme:
url()->current() . '/' . $row->id . '/delete'
. - edit - makes a link for edition. Default url scheme:
url()->current() . '/' . $row->id . '/edit'
. - delete - makes a link for deletion. Default url scheme:
url()->current() . '/' . $row->id . '/delete'
.
They can be simple strings, arrays or callbacks.
For array format it is necessary set
class
. And optional:url
,htmlAttributes
.By callback you can change urls to your routes.
Simple example for a column config:
@gridView([ 'dataProvider' => $dataProvider, 'columnFields' => [ [ 'label' => 'Actions', // Optional 'class' => Itstructure\GridView\Columns\ActionColumn::class, // Required 'actionTypes' => [ // Required 'view', 'edit' => function ($data) { return '/admin/pages/' . $data->id . '/edit'; }, [ 'class' => Itstructure\GridView\Actions\Delete::class, // Required 'url' => function ($data) { // Optional return '/admin/pages/' . $data->id . '/delete'; }, 'htmlAttributes' => [ // Optional 'target' => '_blank', 'style' => 'color: yellow; font-size: 16px;', 'onclick' => 'return window.confirm("Are you sure you want to delete?");' ] ] ] ] ] ])
- view - makes a link for viewing. Default url scheme:
-
CheckboxColumn
- is for displaying Checkboxes to multiple choose the rows.Set
'class' => Itstructure\GridView\Columns\CheckboxColumn::class
in column optionThere are the next required options:
- field - is for a
name
checkbox input attribute. It is rendered as an arrayname="{{ $field }}[]"
. - attribute - is for a
value
checkbox input attribute. It is rendered as:value="$row->{$this->attribute}"
.
Simple example for a column config:
@gridView([ 'dataProvider' => $dataProvider, 'columnFields' => [ [ 'class' => Itstructure\GridView\Columns\CheckboxColumn::class, 'field' => 'delete', 'attribute' => 'id' ] ] ])
- field - is for a
Filters
There are the next filter's variants:
-
Column option to switch off the filter:
'filter' => false
-
TextFilter
- is a default filter, which renders a text form field to search, using column attribute. -
DropdownFilter
- is a filter, which renders<select>
html tag.Set the next as column option:
@gridView([ 'dataProvider' => $dataProvider, 'columnFields' => [ [ 'attribute' => 'example_attribute', 'filter' => [ 'class' => Itstructure\GridView\Filters\DropdownFilter::class, 'data' => ['key' => 'value', 'key' => 'value'] // Array keys are for html <option> tag values, array values are for titles. ] ] ] ])
If
attribute
is not defined for column or you want to set a special filter field name:@gridView([ 'dataProvider' => $dataProvider, 'columnFields' => [ [ 'filter' => [ 'class' => Itstructure\GridView\Filters\DropdownFilter::class, 'name' => 'example_name', 'data' => ['key' => 'value', 'key' => 'value'] // Array keys are for html <option> tag values, array values are for titles. ] ] ] ])
Formatters
There are the next formatter keys:
- html - is for passing a row content with html tags.
- image - is for inserting a row data in to
src
attribute of<img>
tag. - text - applies
strip_tags()
for a row data. - url - is for inserting a row data in to
href
attribute of<a>
tag.
For that keys there are the next formatters:
HtmlFormatter
ImageFormatter
TextFormatter
UrlFormatter
Also you can set formatter with some addition options. See the next simple example:
@gridView([ 'dataProvider' => $dataProvider, 'columnFields' => [ [ 'attribute' => 'url', 'format' => [ 'class' => Itstructure\GridView\Formatters\UrlFormatter::class, 'title' => 'Source', 'htmlAttributes' => [ 'target' => '_blank' ] ] ], [ 'attribute' => 'content', 'format' => 'html' ] ] ])
Existing form areas and main buttons
There are two main form areas:
-
grid_view_filters_form
Two buttons affect search request submission:
- Search. You can change a button label by option:
searchButtonLabel
. - Reset. You can change a button label by option:
resetButtonLabel
.
If
useFilters
= false, these buttons will not be displayed. - Search. You can change a button label by option:
-
grid_view_rows_form
You can set a specific
action
attribute value by optionrowsFormAction
.One button affect a main submit request:
-
Send. You can change a button label by option:
sendButtonLabel
.Note! This button will be displayed under one of two conditions:
- There is a checkbox column.
- Option
useSendButtonAnyway
= true.
-
Complex extended example
@php $gridData = [ 'dataProvider' => $dataProvider, 'paginatorOptions' => [ // Here you can set some options of paginator Illuminate\Pagination\LengthAwarePaginator, used in a package. 'pageName' => 'p' ], 'rowsPerPage' => 5, // The number of rows in one page. By default 10. 'title' => 'Panel title', // It can be empty '' 'strictFilters' => true, // If true, then a searching by filters will be strict, using an equal '=' SQL operator instead of 'like'. 'rowsFormAction' => '/admin/pages/deletion', // Route url to send slected checkbox items for deleting rows, for example. 'useSendButtonAnyway' => true, // If true, even if there are no checkbox column, the main send button will be displayed. 'searchButtonLabel' => 'Find', 'columnFields' => [ [ 'attribute' => 'id', // REQUIRED if value is not defined. Attribute name to get row column data. 'label' => 'ID', // Column label. 'filter' => false, // If false, then column will be without a search filter form field., 'htmlAttributes' => [ 'width' => '5%' // Width of table column. ] ], [ 'label' => 'Active', // Column label. 'value' => function ($row) { // You can set 'value' as a callback function to get a row data value dynamically. return '<span class="icon fas '.($row->active == 1 ? 'fa-check' : 'fa-times').'"></span>'; }, 'filter' => [ // For dropdown it is necessary to set 'data' array. Array keys are for html <option> tag values, array values are for titles. 'class' => Itstructure\GridView\Filters\DropdownFilter::class, // REQUIRED. For this case it is necessary to set 'class'. 'name' => 'active', // REQUIRED if 'attribute' is not defined for column. 'data' => [ // REQUIRED. 0 => 'No active', 1 => 'Active', ] ], 'format' => 'html', // To render column content without lossless of html tags, set 'html' formatter. 'sort' => 'active' // To sort rows. Have to set if an attribute is not defined for column. ], [ 'label' => 'Icon', // Column label. 'value' => function ($row) { // You can set 'value' as a callback function to get a row data value dynamically. return $row->icon; }, 'filter' => false, // If false, then column will be without a search filter form field. 'format' => [ // Set special formatter. If $row->icon value is a url to image, it will be inserted in to 'src' attribute of <img> tag. 'class' => Itstructure\GridView\Formatters\ImageFormatter::class, // REQUIRED. For this case it is necessary to set 'class'. 'htmlAttributes' => [ // Html attributes for <img> tag. 'width' => '100' ] ] ], 'created_at', // Simple column setting by string. [ // Set Action Buttons. 'class' => Itstructure\GridView\Columns\ActionColumn::class, // REQUIRED. 'actionTypes' => [ // REQUIRED. 'view', 'edit' => function ($data) { return '/admin/pages/' . $data->id . '/edit'; }, [ 'class' => Itstructure\GridView\Actions\Delete::class, // REQUIRED 'url' => function ($data) { return '/admin/pages/' . $data->id . '/delete'; }, 'htmlAttributes' => [ 'target' => '_blank', 'style' => 'color: yellow; font-size: 16px;', 'onclick' => 'return window.confirm("Sure to delete?");' ] ] ] ], [ // For this case checkboxes will be rendered according with: <input type="checkbox" name="delete[]" value="{{ $row->id }}" /> 'class' => Itstructure\GridView\Columns\CheckboxColumn::class, // REQUIRED. 'field' => 'delete', // REQUIRED. 'attribute' => 'id' // REQUIRED. 'display' => function ($row) { return {...condition to return true for displaying...}; } ] ] ]; @endphp
@gridView($gridData)
License
Copyright © 2020-2024 Andrey Girnik girnikandrey@gmail.com.
Licensed under the MIT license. See LICENSE.txt for details.