diff --git a/docs/core-components.md b/docs/core-components.md deleted file mode 100644 index 507b8f8..0000000 --- a/docs/core-components.md +++ /dev/null @@ -1,136 +0,0 @@ -# Core Components - -## Table Classes - -All table structures should be defined in the `/app/Tables` directory and should inherit the -`MtrDesign\Krait\Tables\BaseTable` class. - -By running `php artisan krait:table MyAwesomeTable`, Krait will generate the directory and the MyAwesomeTable -class automatically for you. - -```php -column( - name: 'my_first_column', - label: 'My First Column', - process: fn(mixed $resource) => 'This is the processed content!' - ); - } - - function additionalData(mixed $resource): array - { - return [ - 'additional_prop' => 'Krait is awesome!', - ]; - } -} -``` - -## Table Columns - -All columns are internally represented by the [`TableColumnDTO`](https://github.com/mtrdesign/krait/blob/main/krait/src/DTO/TableColumnDTO.php) class. We define the columns -inside our Table Definition Classes using the `column` method. Here is the list of all parameters that can be assigned to specific column. - - -```php - 'foo']]; - return MyAwesomeTable::from($records); - } -} -``` - -## Table Vue Components - -```js - - - - - -``` - -## Table Auto-generated Routes -Krait automatically associates routes to all table classes located in the `App/Tables` namespace. diff --git a/docs/core-components/dynamic-table-component.md b/docs/core-components/dynamic-table-component.md new file mode 100644 index 0000000..4a14039 --- /dev/null +++ b/docs/core-components/dynamic-table-component.md @@ -0,0 +1,54 @@ +## Description +The `krait-ui` DynamicTable component represents the table data on front-end. + +## Example + +```html + + + + + +``` + +## Highlights + +### Slots Usage +The `DynamicTable` component uses slots to provide an easy way to manipulate the front-end data. + +```html + +``` + +- The `record` object contains the record values for all columns +- The `column` object contains all column properties (`name`, `fixed`, `label`, etc.) diff --git a/docs/core-components/table-columns.md b/docs/core-components/table-columns.md new file mode 100644 index 0000000..2485fbc --- /dev/null +++ b/docs/core-components/table-columns.md @@ -0,0 +1,127 @@ +## Description + +All columns are internally represented by the [`TableColumnDTO`](https://github.com/mtrdesign/krait/blob/main/krait/src/DTO/TableColumnDTO.php) class. We define the columns +inside our Table Definition Classes using the `column` method. Here is the list of all parameters that can be assigned to specific column. + + + +```php + 'foo']]; + + /** + * Here you might fetch/manipulate the data. + */ + + return MyAwesomeTable::from($records); + } +} +``` + +## Methods + +*** + +### __invoke + +Processes the incoming front-end request. + +```php +public invoke(): MtrDesign\Krait\Http\Resources\TableCollection +``` diff --git a/docs/core-components/table-definition-classes.md b/docs/core-components/table-definition-classes.md new file mode 100644 index 0000000..d82cf25 --- /dev/null +++ b/docs/core-components/table-definition-classes.md @@ -0,0 +1,265 @@ +## Description + +All table structures should be defined in the `/app/Tables` directory and should inherit the +`MtrDesign\Krait\Tables\BaseTable` class. + +By running `php artisan krait:table MyAwesomeTable`, Krait will generate the directory and the MyAwesomeTable +class automatically for you. + +## Example + +```php +column( + name: 'my_first_column', + label: 'My First Column', + process: fn(mixed $resource) => 'This is the processed content!' + ); + + $this->column( + name: 'some_field', + label: 'Resource Field', + ); + } + + function additionalData(mixed $resource): array + { + return [ + 'additional_prop' => 'Krait is awesome!', + ]; + } +} +``` + +*** + +## Methods + +### name + +Returns the table name. + +```php +public name(): string +``` + +*** + +### initColumns + +Initializes the table columns. + +```php +public initColumns(): void +``` + +*** + +### shouldCache + +Flags if the columns should be cached. + +```php +protected shouldCache(): bool +``` + +Usable for dynamic columns serving (from a third-party services). + +*** + +### shouldRefresh + +Flags if the columns should be refreshed on every request. + +```php +protected shouldRefresh(): bool +``` + +Usable for dynamic columns serving (from a third-party services). + +*** + +### column + +Adds a column to the table + +```php +protected column( + string $name, + string $label, + bool $hideLabel = false, + bool $datetime = false, + bool $sortable = true, + bool $fixed = false, + string|null $classes = null, + callable|null $process = null, + callable|null $sort = null +): void +``` + +**Parameters:** + +| Parameter | Type | Description | +|--------------|------------------------|-------------------------------------------------------| +| `$name` | **string** | - The columns name | +| `$label` | **string** | - The columns label | +| `$hideLabel` | **bool** | - Flags if the label should be visible in the header. | +| `$datetime` | **bool** | - Flags if the column contains datetime object. | +| `$sortable` | **bool** | - Flags if the column is sortable. | +| `$fixed` | **bool** | - Flags if the column is resizable. | +| `$classes` | **string|null** | - Additional classes that will be added on FE. | +| `$process` | **callable|null** | - The column result generation callback. | +| `$sort` | **callable|null** | - The column sorting callback. | + +*** + +### getColumns + +Returns all columns + +```php +public getColumns(): \MtrDesign\Krait\DTO\TableColumnDTO[] +``` + +*** + +### getColumn + +Returns specific column + +```php +public getColumn(string $columnName): \MtrDesign\Krait\DTO\TableColumnDTO +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------------|--------------|-------------| +| `$columnName` | **string** | | + + +**Throws:** + +- [`Exception`](../../../Exception.md) + +*** + +### getCachedColumns + +Returns the columns from the cache (if there are any) + +```php +protected getCachedColumns(): ?array +``` +*** + +### getFacade + +Returns a Laravel Facade of the Table class. + +```php +protected static getFacade(): \MtrDesign\Krait\Tables\BaseTable +``` + +*** + +### processRecord + +Processes one record. + +```php +public processRecord(\Illuminate\Database\Eloquent\Model|array $resource, mixed|null $placeholder = null): array|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|----------------|------------------------------------------------------|-------------------------------------| +| `$resource` | **\Illuminate\Database\Eloquent\Model|array** | - The record. | +| `$placeholder` | **mixed|null** | - The placeholder for empty values. | + + +*** + +### process + +Processes a record. + +```php +public static process(mixed $resource, mixed|null $placeholder = null): mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|----------------|-----------------------|-------------------------------------| +| `$resource` | **mixed** | - The target record. | +| `$placeholder` | **mixed|null** | - The placeholder for empty values. | + +*** + +### from + +Generates an API Resource Collection for the table. + +```php +public static from(mixed $records): \MtrDesign\Krait\Http\Resources\TableCollection +``` + +**Parameters:** + +| Parameter | Type | Description | +|--------------|-------------|-------------------------| +| `$records` | **mixed** | - The target records. | + +*** + +### getName + +Returns the table name. + +```php +public static getName(): string +``` + +*** + +### additionalData + +Returns the table additional data passed to the FE. + +```php +public additionalData(mixed $resource): array +``` + + +**Parameters:** + +| Parameter | Type | Description | +|---------------|-------------|-------------| +| `$resource` | **mixed** | | + + +*** + +### getKeyName + +Returns the record ID key. + +```php +public getKeyName(): string +``` diff --git a/mkdocs.yml b/mkdocs.yml index 8c443e7..576b2df 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,7 +53,6 @@ markdown_extensions: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg - extra: social: - icon: fontawesome/brands/github-alt @@ -66,5 +65,9 @@ nav: - Installation & Usage Guide: - Installation: installation-guide.md - Usage: usage.md - - Core Components: core-components.md + - Core Components: + - Table Definition Classes: core-components/table-definition-classes.md + - Table Columns: core-components/table-columns.md + - Table Controller: core-components/table-controller.md + - Dynamic Table Component: core-components/dynamic-table-component.md - Contribution: contribution.md