hamburgscleanest/data-tables

Data tables whose behavior and appearance can be extended by components. For example sorting, paginating or filtering the table. No JavaScript is required.

v0.9.3 2017-06-19 23:02 UTC

README

Latest Version on Packagist Software License Build Status Coverage Status Quality Score Total Downloads

Data tables whose behavior and appearance can be extended by components. For example sorting, paginating or filtering the table. No JavaScript is required.

Install

Via Composer

$ composer require hamburgscleanest/data-tables

Laravel < 5.5.x

Add the service provider to your providers array

    'providers' => [
                
                ...
           
            DataTablesServiceProvider::class,
        ],

Laravel >= 5.5.x

Automatic Package Discovery Everything is automatically registered for you when using Laravel 5.5.x or later.

Usage

Creating a simple table

    /** @var \hamburgscleanest\DataTables\Models\DataTable $dataTable */
    $dataTable = DataTable::model(User::class, ['created_at', 'name']);

Alternative way to specify the columns

    /** @var \hamburgscleanest\DataTables\Models\DataTable $dataTable */
    $dataTable = DataTable::model(User::class)->columns(['created_at', 'name']);

Rendering the table in your view

    ...
    
    {!! $dataTable->render() !!}
    
    ...

Extending behaviour

You can extend the behaviour of the table via data components. Just create a new component and add it to the table.

All added components can be accessed directly on the DataTable class via their classnames. Optionally you can pass a name for better identification or using multiple components of the same class.

Example 1 - Adding a component without a name:

$dataTable->addComponent(new Component())

Render it in the view: $dataTable->component->render()

Example 2 - Adding a component with a name:

$dataTable->addComponent(new Component(), 'my shiny component')

Render it in the view: $dataTable->myshinycomponent->render()

Adding pagination


    /** @var Paginator $paginator */
    $paginator = new Paginator();
    
    $dataTable->addComponent($paginator);

Rendering the pagination in your view (page links)

Render via DataTable property

Passing all of your components to your blade view via variables can be pretty wiry. To keep your code clean use the DataTables properties.

    ...
    
    {!! $dataTable->paginator->render() !!}
    
    ...

Render via passed variable

Of course you can pass your components to your view like always via view('my_view', ['paginator' => $paginator]); and render it in your blade file.

    ...
    
    {!! $paginator->render() !!}
    
    ...

Altering appearance

Modifying table headers, e.g. translating headers

    ...
    
     $dataTable->formatHeaders(new TranslateHeader(trans('my.translations')));
    
    ...

Formatting columns

Format columns via column formatters. For example you could format a column containing a date with the "DateColumn" formatter.

    ...
    
     $dataTable->formatColumn('created_at', new DateColumn('d.m.Y'));
    
    ...

It is also possible to define the formatters in the data table constructor.

    ...
    
     DataTable::model(User::class, ['created_at' => new DateColumn('d.m.Y')]);
    
    ...

Or even the "columns" function.

    ...
    
     DataTable::model(User::class)->columns(['created_at' => new DateColumn('d.m.Y')]);
    
    ...

Combine components and formatters

You can combine any number of components and formatters to get your desired results. Mix all the data components, header formatters and column formatters you need.

For example: Add sorting to the table with the "Sorter" data component and make your table headers sortable with the "SortableHeader" header formatter.

    ...
    
     $dataTable
        ->addComponent(new Sorter)
        ->formatHeaders(new SortableHeader(['name']));
    
    ...

Query relations

Access column values from "hasOne" and "belongsTo" relationships.

     DataTable::model(TestModel::class)->columns(['relation.name'])->with(['relation']);

Or access column values from "hasMany" and "belongsToMany" relationships by using an aggregate function. If you omit the aggregate function, the value of the first related record is returned.

     DataTable::model(TestModel::class)->columns(['COUNT(relation.id)'])->with(['relation']);

Changes

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email chroma91@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.