README

An opinionated extension package for Laravel Orchid to extend its table handling capabilities, and some further useful helper methods.

Installation

Via Composer

$ composer require lmkhang10/orchid-tables

Usage

This package adds the following new shiny things:

Checklist td - Checklist for tables
TD/Field/Layout::can, canAll - permission-based visibility for fields, columns, layouts
Layout::html() - raw html for layouts
TD extensions:
- date
- num
- limit
- bool
- keyValues
- link
- renderable
- rowClass
- rowLink
TableAdvanced - Formattable, clickable table rows
QuickExport - Export datatables within seconds

Screen\TdChecklist

Checklist with select-all support. Can select range by pressing shift.

Usage:

use Lintaba\OrchidTables\Screen\TDChecklist;

class UserTable extends Table {
//...
    public function columns(): array
    {
        return [
            TDChecklist::make(),
            //...
            TD::make('id'),
        ];
    }
}

TDChecklist::make($name = 'checkbox')

->checkboxSet(key,value)

and almost everything available thats available on TD.

Without further configuration it sends the following:

checkbox[] = 1

The provided collection's items must have a getKey():int|string method, which provides the value for the checkbox.

By default the checklist belongs to the main form, which is linked to most of the action buttons, therefore having a Button within Screen@commandBar() will send the selection list too. However the modals are having their own forms, so it will not be included there. Currently only one form is supported. (Feel free to open a ticket if you need support for multiple forms/modals.)

Changing the form of the list to a modal:

class UserTable extends Table {
//...
    public function commandBar(): array {
        return [
            ModalToggle::make("my modal")->modal('myModal'),
        ];
    }
    public function columns(): array {
        return [
            TD::Checklist::make()->checkboxSet('form','screen-modal-form-myModal'),
        ];
    }

Redirecting back with error/success can keep the current selection:

class UserScreen extends Screen {
//...
    public function activateUsers(Request $request){
        Alert::message('Selected item count is still ' . count($request->get('checkbox', []) ) );
        $request->flash();
    }

Can mixins:

These are mixed into most of the orchid's makeable and visible things.

TD
Field
LayoutFactory

can(string[] $permissions...)

Hides the field if the current user has none of the listed permissions.

Shows only if a previous canSee didn't hide it, and if any of the listed permissions are given to the user.

canAll(string[] $permissions...)

Hides the field if the current user has none of the listed permissions.

Shows only if a previous canSee didn't hide it, and if all of the listed permissions are given to the user.

Both can and canAll internally usese canSee, so chaining another canSee after a can will invalidate the permission check.

Using a non-existing permission throws an easily fixable exception during development mode, to help avoid bugs.

Layout mixins:

html

html(string|callable $content): self

Makes a Layout component, that renders the provided html string (or the value of it, when its a closure.)

Cell mixins:

date

date(bool $withHumanReadable = true, string $format = null): self

Formats a date string or carbon date to human readable. Format defaults to config('orchid-tables.date_format'), config('app.date_format'), or Y?-m-d H:i. (omits year if its the current year.)

num

num(int $decimals = 0,
        string $suffix = null,
        string $decimalSeparator = ',',
        string $thousandsSeparator = DataHelpers::NBSP): self

Formats a numeric value to a more readable / convinient format.

Sets the decimals
May add a suffix, delimitered with a non-breakable space (nbsp), which guaranteed not to be broken to multiple lines.

example:

TD::make('size')->num(2,'m²')

limit

limit(int $max = 100, string $end = '...')

Keeps the text under the given maximum character count. If its longer, replaces the end with ... (or anything specified in end).

bool()

Shows a green tick, or a red cross, depending on if the column's value has a truthy or falsy value.

keyValues()

keyValues(int $maxDepth = 3)

Shows a key-value structure (using dl/dt/dd) of a complex object / array / json entry.

Limits max depth, by default to 3.

link($href, $segments = null)

Makes a link/button to the target location. Both $href and $segments can be a closure, or a value.

Example:

// article: { user: { id: 42, first: "John", last: "Doe", __toString:"John Doe" } }
TD::make('user')->link(function(User $user){return route('user.show',$user->id)}),
//<a href="/users/show/42">John Doe</a>

TD::make('user')->link('user.create',['last','first'])
//<a href="/users/show/42">Doe<br> John</a>

renderable()

Tries to render a model, using one of the following:

its value, when its a scalar or null
as a Personable Persona
->presenter() to get a Personable Persona
value from ->display()
its name, slug, or class@id as last resort.

Formatted exportable cells

These helper methods are useful with formatted excel exports. By default its not activated, as it adds an extra overhead, which is usually not being used. To activate, you can either set it up in the configuration:

# config/orchid-tables.php
        'cell'   => Mixins\CellExportFormattableMixin::class,

or call the following:

\Lintaba\OrchidTables\Facades\OrchidTables::mixinTdExportFormattables();

Augmented methods:

date
- Formatted as date
num
- Formatted as the provided number format, but stored as a number.
keyValues
- Stored as json in the output

Furthermore the following helper methods are available:

####notExportable($notExportable = true): self Sets a column to be non-exported.

Its advised to set it on ie. action buttons.

####setStyle($style): self

A callback that formats the given row, or the actual formatting. Can be called multiple times, and the result will be merged. Callback can either return with a phpexcel formatted array, or one (or multiple merged together) from the followings:

ExportStyles::FORMAT_NONE
ExportStyles::FORMAT_TEXT
ExportStyles::FORMAT_HUF
ExportStyles::FORMAT_USD
ExportStyles::FORMAT_EUR
ExportStyles::FORMAT_PCS
ExportStyles::FORMAT_DATE
ExportStyles::FORMAT_DATETIME
ExportStyles::FORMAT_TIME
ExportStyles::FORMAT_BOLD
ExportStyles::FORMAT_ITALIC
ExportStyles::FORMAT_UNDERLINED
ExportStyles::FORMAT_LEFT
ExportStyles::FORMAT_RIGHT
ExportStyles::FORMAT_CENTER
ExportStyles::FORMAT_TOP
ExportStyles::FORMAT_MIDDLE
ExportStyles::FORMAT_BOTTOM
ExportStyles::FORMAT_RED
ExportStyles::FORMAT_GREEN
ExportStyles::FORMAT_YELLOW
ExportStyles::FORMAT_BLUE
ExportStyles::FORMAT_BLACK

####exportRender(callable $callback): self

Sets the renderer method for excel. Input is the field's value. Must return with a string or stringable.

Example:

TD::make('name')->exportRender(function(string $value, User $entry, int $rowNum){
    return Str::upper($value).' #'.$entry->id.' (row-'.$rowNum.')';
})

QuickExport

Using Lintaba\OrchidTables\Exports\QuickExport its possible to set up data exports quickly, without creating extra classes, just by building on an already existing table.

Quick export example:

use Lintaba\OrchidTables\Exports\QuickExport;
use Orchid\Screen\Actions\Button;
use Orchid\Screen\Screen;

class UsersTableScreen extends Screen
{

    public function commandBar(): array
    {
        return [
            Button::make('export')->method('export')->rawClick(),
        ];
    }

    public function export(){
        $query = User::filters()->defaultSort('id', 'desc');
        return (new QuickExport($query, UserTable::class))->download('userExport.xlsx');
    }
//...

TableAdvanced

The extended table layout, \Lintaba\OrchidTables\Screen\TableAdvanced adds the following functionality:

rowClass($row)

Calculates classlist based on a row. Useful for coloring a whole row.

rowLink($row)

Makes a row clickable.

Example:

use Lintaba\OrchidTables\Screen\TableAdvanced

class UserTable extends TableAdvanced
{

    public function rowClass(User $row)
    {
        return $row->active ? 'bg-success' : 'bg-danger';
    }

    public function rowLink(User $row)
    {
        return route('admin.users.show',$row);
    }
//...

Customization

Run the following command to publish the configuration:

php artisan vendor:publish --tag="orchid-tables.config"

# /config/orchid-tables.php
use Lintaba\OrchidTables\Mixins;

return [
    'mixins' => [
        'can'    => Mixins\CanMixin::class,
        'cell'   => Mixins\CellMixin::class,
        'layout' => Mixins\LayoutMixin::class,
    ],

    'date_format' => null,
];

Extend or create your overwrites, based on the existing mixins, like \Lintaba\OrchidTables\CellMixin. You can turn on or off any of these mixins by setting their key to null.

Change log

Please see the changelog for more information on what has changed recently.

Testing

$ composer test

lmkhang10 / orchid-tables

Maintainers

Details