Grids

Data Grids Framework for Laravel

All Laravel versions starting from Laravel 4.X are supported.

Features

• Data providers (php array, Eloquent model, Doctrine DBAL query object)
• Themes support
• Individual views for UI components
• Twitter Bootstrap v3 used by default
• Caching
• Smart input handling allows to avoid conflicts with get parameters & easily place few interactive grids on same page
• Rich customization facilities
• Component architecture
• Declarative approach
• Constructing grids via strict object oriented API or configuration in php arrays
• Rich variety of components:
  • Excel and CSV export
  • Records per page dropdown
  • Show/hide columns UI control
  • Sorting
  • Filtering
  • Totals calculation (sum, average value, records count, etc)
  • Pagination
  • etc

Upcoming Features (moved to view-components/grids)

• Autodetecting columns based on Eloquent model (if not specified)
• Builtin output formatters for different column types
• Working with json data sources via ajax
• Check compatibility with Lumen microframework

Requirements

• Laravel 4.X+
• laravelcollective/html package if you use Laravel5.X
• php 5.5+

Installation

Step 1: Install package using Composer

Add nayjest/grids to "require" section of your composer.json

"require": {
    "nayjest/grids": "^2.0.0"
},

For Laravel 5 you also need to add "laravelcollective/html":

"require": {
    "nayjest/grids": "^2.0.0",
    "laravelcollective/html": "^5"
},

Then install dependencies using following command:

php composer.phar install

Instead of editing composer.json and executing composer install you can just run following command:

For Laravel 4

php composer.phar require nayjest/grids

For Laravel 5 / Laravel 6

php composer.phar require nayjest/grids laravelcollective/html

Step 2: Laravel Setup

Add following line to 'providers' section of app/config/app.php file:

'Nayjest\Grids\ServiceProvider',

For Laravel 5 / 6 you also need to add "illuminate/html" service provider:

'Nayjest\Grids\ServiceProvider',
'Collective\Html\HtmlServiceProvider',

You may also add facade aliases to your application configuration:

    'Form'  => 'Collective\Html\FormFacade',
    'HTML'  => 'Collective\Html\HtmlFacade',
    'Grids'     => 'Nayjest\Grids\Grids',

Demo

Demonstration available here

Code

Usage

Basic example

In example below grid is configured by php array using Nayjest/Builder package facilities.

$cfg = [
    'src' => 'App\User',
    'columns' => [
            'id',
            'name',
            'email',
            'country'
    ]
];
echo Grids::make($cfg);

Results available here. For more details see demo application repository

Advanced example

If you don't like plain arrays, you can construct grids using object oriented api:

Step 1. Instantiate & Configure Grid

See example below

# Let's take a Eloquent query as data provider
# Some params may be predefined, other can be controlled using grid components         
$query = (new User)
    ->newQuery()
    ->with('posts')
    ->where('role', '=', User::ROLE_AUTHOR);


			
# Instantiate & Configure Grid
$grid = new Grid(
    (new GridConfig)
        # Grids name used as html id, caching key, filtering GET params prefix, etc
        # If not specified, unique value based on file name & line of code will be generated
        ->setName('my_report')
        # See all supported data providers in sources
        ->setDataProvider(new EloquentDataProvider($query))
        # Setup caching, value in minutes, turned off in debug mode
        ->setCachingTime(5) 
        # Setup table columns
        ->setColumns([
            # simple results numbering, not related to table PK or any obtained data
            new IdFieldConfig,
            (new FieldConfig)
                ->setName('login')
                # will be displayed in table header
                ->setLabel('Login')
                # That's all what you need for filtering. 
                # It will create controls, process input 
                # and filter results (in case of EloquentDataProvider -- modify SQL query)
                ->addFilter(
                    (new FilterConfig)
                        ->setName('login')
                        ->setOperator(FilterConfig::OPERATOR_LIKE)
                )
                # optional, 
                # use to prettify output in table cell 
                # or print any data located not in results field matching column name
                ->setCallback(function ($val, ObjectDataRow $row) {
                    if ($val) {
                        $icon  = "<span class='glyphicon glyphicon-user'></span>&nbsp;";
                        $user = $row->getSrc();
                        return $icon . HTML::linkRoute('users.profile', $val, [$user->id]);
                    }
                })
                # sorting buttons will be added to header, DB query will be modified
                ->setSortable(true)
            ,
            (new FieldConfig)
                ->setName('status')
                ->setLabel('Status')
                ->addFilter(
                    (new SelectFilterConfig)
                        ->setOptions(User::getStatuses())
                )
            ,
            (new FieldConfig)
                ->setName('country')
                ->setLabel('Country')
                ->addFilter(
                    (new SelectFilterConfig)
                        ->setName('country')
                        ->setOptions(get_countries_list())
                )
            ,
            (new FieldConfig)
                ->setName('registration_date')
                ->setLabel('Registration date')
                ->setSortable(true)
            ,
            (new FieldConfig)
                ->setName('comments_count')
                ->setLabel('Comments')
                ->setSortable(true)
            ,
            (new FieldConfig)
                ->setName('posts_count')
                ->setLabel('Posts')
                ->setSortable(true)
            ,
        ])
        # Setup additional grid components
        ->setComponents([
            # Renders table header (table>thead)
            (new THead)
                # Setup inherited components
                ->setComponents([
                    # Add this if you have filters for automatic placing to this row
                    new FiltersRow,
                    # Row with additional controls
                    (new OneCellRow)
                        ->setComponents([
                            # Control for specifying quantity of records displayed on page
                            (new RecordsPerPage)
                                ->setVariants([
                                    50,
                                    100,
                                    1000
                                ])
                            ,
                            # Control to show/hide rows in table
                            (new ColumnsHider)
                                ->setHiddenByDefault([
                                    'activated_at',
                                    'updated_at',
                                    'registration_ip',
                                ])
                            ,
                            # Submit button for filters. 
                            # Place it anywhere in the grid (grid is rendered inside form by default).
                            (new HtmlTag)
                                ->setTagName('button')
                                ->setAttributes([
                                    'type' => 'submit',
                                    # Some bootstrap classes
                                    'class' => 'btn btn-primary'
                                ])
                                ->setContent('Filter')
                        ])
                        # Components may have some placeholders for rendering children there.
                        ->setRenderSection(THead::SECTION_BEGIN)
                ])
            ,
            # Renders table footer (table>tfoot)
            (new TFoot)
                ->addComponent(
                    # TotalsRow component calculates totals on current page
                    # (max, min, sum, average value, etc)
                    # and renders results as table row.
                    # By default there is a sum.
                    new TotalsRow([
                        'comments',
                        'posts',
                    ])
                )
                ->addComponent(
                    # Renders row containing one cell 
                    # with colspan attribute equal to the table columns count
                    (new OneCellRow)
                        # Pagination control
                        ->addComponent(new Pager)
                )