README

A datatables Livewire component for the Netflex SDK.

This plugin assumes you already have Laravel Livewire installed and configured in your project.

Installation

You can install the package via composer:

composer require netflex/livewire-tables

Publishing Assets

Publishing assets are optional unless you want to customize this package.

php artisan vendor:publish --provider="Netflex\Livewire\Tables\LivewireTablesServiceProvider" --tag=views

php artisan vendor:publish --provider="Netflex\Livewire\Tables\LivewireTablesServiceProvider" --tag=lang

Usage

Creating Tables

To create a table component you draw inspiration from the below stub:

<?php

namespace App\Http\Livewire;

use App\Article;
use Netflex\Query\Builder;

use Netflex\Livewire\Tables\TableComponent;
use Netflex\Livewire\Tables\Traits\HtmlComponents;
use Netflex\Livewire\Tables\Views\Column;

class ArticleTable extends TableComponent
{
    use HtmlComponents;

    public function query() : Builder
    {
        return Article::query()->ignorePublishingStatus();
    }

    public function columns() : array
    {
        return [
            Column::make('ID')
                ->searchable()
                ->sortable(),
            Column::make('Image')
                ->format(function(Article $article) {
                    return $this->image($article->image, 'tableArticlePreset', $article->name, ['class' => 'img-fluid']);
                }),
            Column::make('Name')
                ->searchable()
                ->sortable(),
            Column::make('E-mail', 'email')
                ->searchable()
                ->sortable()
                ->format(function(Article $article) {
                    return $this->mailto($article->email, null, ['target' => '_blank']);
                }),
            Column::make('Actions')
                ->format(function(Article $article) {
                    return view('backend.auth.user.includes.actions', ['article' => $article]);
                })
                ->hideIf(!auth()->user()),
        ];
    }
}

Your component must implement two methods:

/**
 * This defines the start of the query, usually Model::query() but can add additonal constraints to the query.
 */
public function query() : Builder;

/**
 * This defines the columns of the table, they don't necessarily have to map to fields in the model structure.
 */
public function columns() : array;

Rendering the Table

Place the following where you want the table to appear.

Netflex SDK 3.x

<livewire:article-table />

Defining Columns

You can define the columns of your table with the column class.

The following methods are available to chain to a column:

/**
 * The first argument is the column header text
 * The attribute can be omitted if the text is equal to the lower case snake_cased version of the column
 * The attribute can also be used to reference a relationship (i.e. role.name)
 */
public function make($text, ?$attribute) : Column;

/**
 * Used to format the column data in different ways, see the HTML Components section.
 * You will be passed the current model and column (if you need it for some reason) which can be omitted as an argument if you don't need it.
 */
public function format(callable $callable = null) : self;

/**
 * This column is searchable, with no callback it will search the column by name or by the supplied relationship, using a callback overrides the default searching functionality.
 */
public function searchable(callable $callable = null) : self;

/**
 * This column is sortable, with no callback it will sort the column by name and sort order defined on the components $sortDirection variable
 */
public function sortable(callable $callable = null) : self;

/**
 * The columns output will be put through {!! !!} instead of {{ }}.
 */
public function raw() : self;

/**
 * Hide this column permanently
 */
public function hide() : self;

/**
 * Hide this column based on a condition. i.e.: user has or doesn't have a role or permission. Must return a boolean, not a closure.
 */
public function hideIf($condition) : self;

/**
 * This column is only included in exports and is not available to the UI
 */
public function exportOnly() : self;

/**
 * This column is excluded from the export but visible to the UI unless defined otherwise with hide() or hideIf()
 */
public function excludeFromExport() : self;

/**
 * If supplied, and the column is exportable, this will be the format when rendering the CSV/XLS/PDF instead of the format() function. You may have both, format() for the UI, and exportFormat() for the export only. If this method is not supplied, format() will be used and passed through strip_tags() to try to clean the output.
 */
public function exportFormat(callable $callable = null) : self;

Properties

You can override any of these in your table component:

Table

Searching

Sorting

Pagination

Loading

Offline

Exports

Other

Columns/Data

Use the following methods to alter the column/row metadata.

public function setTableHeadClass($attribute): ?string
public function setTableHeadId($attribute): ?string
public function setTableHeadAttributes($attribute): array
public function setTableRowClass($article): ?string
public function setTableRowId($article): ?string
public function setTableRowAttributes($article): array
public function getTableRowUrl($article): ?string
public function setTableDataClass($attribute, $value): ?string
public function setTableDataId($attribute, $value): ?string
public function setTableDataAttributes($attribute, $value): array

Pagination

Override these methods if you want to perform extra tasks when the search or per page attributes change.

public function updatingSearch(): void
public function updatingPerPage(): void

Search

Override this method if you want to perform extra steps when the search has been cleared.

public function clearSearch(): void

Sorting

Override this method if you want to change the default sorting behavior.

public function sort($attribute): void

HTML Components

This package includes some of the functionality from the laravelcollective/html package modified to fit the needs of this package.

To use these you must import the Netflex\Livewire\Tables\Traits\HtmlComponents trait.

You may return any of these functions from the format() method of a column:

public function image($pathOrMediaUrlResolvable, $presetOrSize, $alt = null, $attributes = []): HtmlString
public function link($url, $title = null, $attributes = [], $secure = null, $escape = true): HtmlString
public function secureLink($url, $title = null, $attributes = [], $escape = true): HtmlString
public function linkAsset($url, $title = null, $attributes = [], $secure = null, $escape = true): HtmlString
public function linkSecureAsset($url, $title = null, $attributes = [], $escape = true): HtmlString
public function linkRoute($name, $title = null, $parameters = [], $attributes = [], $secure = null, $escape = true): HtmlString
public function linkAction($action, $title = null, $parameters = [], $attributes = [], $secure = null, $escape = true): HtmlString
public function mailto($email, $title = null, $attributes = [], $escape = true): HtmlString
public function email($email): string
public function html($html): HtmlString

Exporting Data

The table component supports exporting to CSV, XLS, XLSX, and PDF.

In order to use this functionality you must install PhpSpreadsheet 1.0 or newer.

What exports your table supports

By default, exporting is off. You can add a list of available export types with the $exports class property.

public $exports = ['csv', 'xls', 'xlsx', 'pdf'];

Defining the file name.

By default, the filename will be data.type. I.e. data.pdf, data.csv.

You can change the filename with the $exportFileName class property.

public $exportFileName = 'users-table'; - Obviously omit the file type

Deciding what columns to export

You have a couple option on exporting information. By default, if not defined at all, all columns will be exported.

If you have a column that you want visible to the UI, but not to the export, you can chain on excludeFromExport()

If you have a column that you want visible to the export, but not to the UI, you can chain on exportOnly()

Formatting column data for export

By default, the export will attempt to render the information just as it is shown to the UI. For a normal column based attribute this is fine, but when exporting formatted columns that output a view or HTML, it will attempt to strip the HTML out.

Instead, you have available to you the exportFormat() method on your column, to define how you want this column to be formatted when outputted to the file.

So you can have a column that you want both available to the UI and the export, and format them differently based on where it is being outputted.

Exporting example

<?php

namespace App\Http\Livewire;

use App\Article;

use Netflex\Query\Builder;
use Netflex\Livewire\Tables\TableComponent;
use Netflex\Livewire\Tables\Traits\HtmlComponents;
use Netflex\Livewire\Tables\Views\Column;

class ArticleTable extends TableComponent
{
    use HtmlComponents;

    public function query() : Builder
    {
        return Article::query()->ignorePublishingStatus();
    }

    public function columns() : array
    {
        return [
            Column::make('ID')
                ->searchable()
                ->sortable()
                ->excludeFromExport(), // This column is visible to the UI, but not export.
            Column::make('ID')
                ->exportOnly(), // This column is only rendered on export
            Column::make('Image')
                ->format(function(User $article) {
                    return $this->image($article->image, 'presetName', $article->name, ['class' => 'img-fluid']);
                })
                ->excludeFromExport(), // This column is visible to the UI, but not export.
            Column::make('Name') // This columns is visible to both the UI and export, and is rendered the same
                ->searchable()
                ->sortable(),
            Column::make('E-mail', 'email')
                ->searchable()
                ->sortable()
                ->format(function(Article $article) {
                    return $this->mailto($article->email, null, ['target' => '_blank']);
                })
                ->exportFormat(function(User $article) { // This column is visible to both the UI and the export, but is formatted differently to the export via this method.
                    return $article->email;
                }),
            Column::make('Actions')
                ->format(function(User $article) {
                    return view('backend.auth.user.includes.actions', ['article' => $article]);
                })
                ->hideIf(!auth()->user())
                ->excludeFromExport(), // This column is visible to the UI, but not export.
        ];
    }
}

Customizing Exports

Currently, there are no customization options available. But there is a config item called exports where you can define the class to do the rendering. You can use the \Netflex\Livewire\Tables\Exports\Export class as a base.

More options will be added in the future, but the built in options should be good for most applications.

Setting Component Options

There are some frontend framework specific options that can be set.

These have to be set from the $options property of your component.

They are done this way instead of the config file that way you can have per-component control over these settings.

protected $options = [
    // The class set on the table
    'classes.table' => 'table table-striped table-bordered',

    // The class set on the table's thead
    'classes.thead' => null,

    // The class set on the table's export dropdown button
    'classes.buttons.export' => 'btn btn-secondary',
    
    // Whether or not the table is wrapped in a `.container-fluid` or not
    'container' => true,
    
    // Whether or not the table is wrapped in a `.table-responsive` or not
    'responsive' => true,
];

For this to work you have to pass an associative array of overrides to the $options property. The above are the defaults, if you're not changing them then you can leave them out or disregard the property all together.

Passing Properties

To pass properties from your blade view to your table, you can use the normal Livewire mount method:

<livewire:article-table status="{{ request('status') }}" />

protected $status = 'active';

public function mount($status) {
    $this->status = $status;
}

License

Copyright Apility AS © 2021

Licensed under the MIT License.

This software contains work based on the laravel-livewire-tables package: Copyright © Anthony Rappa and contributors