netflex / livewire-tables
A dynamic Livewire table component for the Netflex SDK
Requires
- php: ^7.3|^7.4|^8.0
- illuminate/support: ^8.27
- livewire/livewire: ^2.0
- netflex/api: ^4.0
- netflex/query-builder: ^4.0
- netflex/structures: ^4.0
Requires (Dev)
- netflex/pages: ^4.0
- phpoffice/phpspreadsheet: ^1.0
Suggests
- phpoffice/phpspreadsheet: Required to use export functionality
This package is auto-updated.
Last update: 2024-10-24 05:25:34 UTC
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