DataGrids is a versatile package designed for Laravel applications, providing a straightforward and front-end agnostic solution for creating and managing data grids. It simplifies the process of displaying and filtering data, making it easier for developers to implement complex data management features without extensive coding. The package supports automatic discovery and registration of data grids, ensuring seamless integration into existing projects. With built-in support for various data normalizations and filtering options, DataGrids enhances the efficiency and functionality of data-driven applications.
You can install the package via composer:
composer require strucura/datagridsOptionally, you can publish the views using
php artisan vendor:publish --tag="datagrids-config"The discovery of grids in the application is configured in the config/datagrids.php file. This configuration allows
the package to automatically discover grid classes within specified paths and under certain conditions.
Here is how the discovery process is set up:
- Paths: The
pathsarray specifies the directories where the package will look for grid classes. By default, it includes theappdirectory. - Conditions: The
conditionsarray defines the criteria that a class must meet to be considered a grid. In this case, it uses theDiscoverConditionclass to find classes that implement theGridContractinterface.
<?php
return [
'discovery' => [
'paths' => [
app_path(''),
],
'conditions' => [
ConditionBuilder::create()
->classes()
->extending(AbstractDataGrid::class),
],
],
]This setup ensures that any class within the specified paths that implements the DataGridContract interface will be
automatically discovered and registered as a grid in the application.
Normalizers are used to perform data manipulations on the value of a filter before applying it to the query.
They ensure that the filter values are in the correct format and type required by the database query. Value
normalizers are registered in the config/datagrids.php file under the normalizers key. Each normalizer class must
implement the NormalizerContract interface.
<?php
return [
'normalizers' => [
BooleanNormalizer::class,
TimezoneNormalizer::class,
FloatNormalizer::class,
IntegerNormalizer::class,
NullNormalizer::class,
],
]This configuration ensures that the specified normalizers are applied to filter values in the order they are listed.
Filter operations are used to apply specific conditions to the data being queried. They help in narrowing down the
results based on various criteria. Filter operations are registered in the config/datagrids.php file under the
filter_operations key. Each filter operation class must extend the AbstractFilterOperation class and implement the FilterOperationContract
interface.
<?php
return [
'filter_operations' => [
// Equality
EqualsFilterOperation::class,
DoesNotEqualFilterOperation::class,
// Dates
DateAfterFilterOperation::class,
DateBeforeFilterOperation::class,
DateIsFilterOperation::class,
DateIsNotFilterOperation::class,
DateOnOrBeforeFilterOperation::class,
DateOnOrAfterFilterOperation::class,
// In
InFilterOperation::class,
NotInFilterOperation::class,
// Numeric
GreaterThanFilterOperation::class,
GreaterThanOrEqualToFilterOperation::class,
LessThanFilterOperation::class,
LessThanOrEqualToFilterOperation::class,
// String
ContainsFilterOperation::class,
DoesNotContainFilterOperation::class,
EndsWithFilterOperation::class,
StartsWithFilterOperation::class,
],
]This configuration ensures that the specified filters are available for use in the application. Each filter class defines the conditions it can handle and the logic to apply those conditions to the query.
To create a new grid, you need to define a class that extends the AbstractDataGrid class and implements the required
methods. Below is an example of how to create a ActiveUserDataGrid:
<?php
namespace Strucura\DataGrid\Tests\Fakes;
use Illuminate\Database\Query\Builder;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\DB;
use Strucura\DataGrid\Abstracts\AbstractDataGrid;
use Strucura\DataGrid\Columns\DateTimeColumn;
use Strucura\DataGrid\Columns\NumberColumn;
use Strucura\DataGrid\Columns\StringColumn;
use Strucura\DataGrid\Contracts\DataGridContract;
class ActiveUserDataGrid extends AbstractDataGrid implements DataGridContract
{
public function getColumns(): Collection
{
return collect([
NumberColumn::make('users.id', 'ID'),
StringColumn::make('users.name', 'Name'),
StringColumn::make('users.email', 'Email'),
DateTimeColumn::make('users.created_at', 'Created At'),
DateTimeColumn::make('users.created_at', 'Updated At'),
]);
}
public function getQuery(): Builder
{
return DB::table('users');
}
}In this example, the ActiveUserDataGrid class defines the columns and the query for the grid. The getColumns method
returns a collection of columns, and the getQuery method returns the query builder instance for the grid.
Once created, and picked up by the discovery process, new routes will be registered for the grid. These routes will
allow for fetching the data for the grid, and for fetching the column schema for the grid. Using the
ActiveUserDataGrid
as an
example, the following routes will be registered:
POST grids/active-users/data ............... grids.active-users.data
POST grids/active-users/schema ............. grids.active-users.schema
Should you desire to customize the routes, you can do so on the grid class by overriding any of the following methods:
- getRoutePrefix: Used to prefix the route path as well as the route name.
- getRouteName: Used to define the route name.
- getRoutePath: Used to define the route path .
composer testIf you discover any security-related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.