https://github.com/lintaba/orchid-tables
An opinionated extension package for Laravel Orchid to extend its table handling capabilities, and some further useful helper methods.
https://github.com/lintaba/orchid-tables
hacktoberfest laravel orchid-platform orchidtables
Last synced: about 1 month ago
JSON representation
An opinionated extension package for Laravel Orchid to extend its table handling capabilities, and some further useful helper methods.
- Host: GitHub
- URL: https://github.com/lintaba/orchid-tables
- Owner: lintaba
- License: mit
- Created: 2022-01-28T04:43:55.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-08-16T20:20:28.000Z (almost 2 years ago)
- Last Synced: 2025-04-23T16:02:10.221Z (about 1 month ago)
- Topics: hacktoberfest, laravel, orchid-platform, orchidtables
- Language: PHP
- Homepage:
- Size: 130 KB
- Stars: 38
- Watchers: 1
- Forks: 19
- Open Issues: 7
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Contributing: contributing.md
- License: license.md
Awesome Lists containing this project
README
# OrchidTables
[![Latest Version on Packagist][ico-version]][link-packagist]
[![Total Downloads][ico-downloads]][link-downloads]
[![Build Status][ico-travis]][link-travis]
[![StyleCI][ico-styleci]][link-styleci]
[](https://github.com/lintaba/orchid-tables/actions/workflows/php.yml)
An opinionated extension package for [Laravel Orchid](orchid) to extend its table handling capabilities, and some
further useful helper methods.
## Installation
Via Composer
``` bash
$ composer require lintaba/orchid-tables
```
## Usage
This package adds the following new shiny things:
- [Checklist td](#TdChecklist) - Checklist for tables
- [TD/Field/Layout::can, canAll](#can) - permission-based visibility for fields, columns, layouts
- [Layout::html()](#layoutHtml) - raw html for layouts
- TD extensions:
- [date](#td-date)
- [num](#td-num)
- [limit](#td-limit)
- [bool](#td-bool)
- [keyValues](#td-keyValues)
- [link](#td-link)
- [renderable](#td-renderable)
- [rowClass](#td-rowClass)
- [rowLink](#td-rowLink)
- [TableAdvanced](#tableAdvanced) - Formattable, clickable table rows
- [QuickExport](#QuickExport) - Export datatables within seconds
Checklist with select-all support. Can select range by pressing `shift`.
Usage:
```php
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:
```post
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:
```php
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:
```php
class UserScreen extends Screen {
//...
public function activateUsers(Request $request){
Alert::message('Selected item count is still ' . count($request->get('checkbox', []) ) );
$request->flash();
}
```
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
```php
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
```php
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.)
```php
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:*
```php
TD::make('size')->num(2,'m²')
```
#### limit
```php
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`).
Shows a green tick, or a red cross, depending on if the column's value has a truthy or falsy value.
| Truthy | Falsy |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| | |
#### keyValues()
```php
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:
```php
// article: { user: { id: 42, first: "John", last: "Doe", __toString:"John Doe" } }
TD::make('user')->link(function(User $user){return route('user.show',$user->id)}),
//John Doe
TD::make('user')->link('user.create',['last','first'])
//Doe
John
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:
```php
# config/orchid-tables.php
'cell' => Mixins\CellExportFormattableMixin::class,
```
or call the following:
```php
\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:**
```php
TD::make('name')->exportRender(function(string $value, User $entry, int $rowNum){
return Str::upper($value).' #'.$entry->id.' (row-'.$rowNum.')';
})
```
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:**
```php
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:**
```php
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:
```shell
php artisan vendor:publish --tag="orchid-tables.config"
```
```php
# /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](changelog.md) for more information on what has changed recently.
## Testing
``` bash
$ composer test
```
## Contributing
Please see [contributing.md](contributing.md) and open tickets for details and a todolist.
## Credits
- [Bálint Vass][link-author]
- [All Contributors][link-contributors]
## License
MIT. Please see the [license file](license.md) for more information.
[ico-version]: https://img.shields.io/packagist/v/lintaba/orchid-tables.svg?style=flat-square
[ico-downloads]: https://img.shields.io/packagist/dt/lintaba/orchid-tables.svg?style=flat-square
[ico-travis]: https://img.shields.io/travis/lintaba/orchid-tables/master.svg?style=flat-square
[ico-styleci]: https://styleci.io/repos/452941365/shield
[link-packagist]: https://packagist.org/packages/lintaba/orchid-tables
[link-downloads]: https://packagist.org/packages/lintaba/orchid-tables
[link-travis]: https://travis-ci.org/lintaba/orchid-tables
[link-styleci]: https://styleci.io/repos/452941365
[link-author]: https://github.com/lintaba
[link-contributors]: ../../contributors
[orchid]: https://orchid.software/