Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: table docs #1421

Merged
merged 2 commits into from
May 15, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 137 additions & 0 deletions packages/dm-core-plugins/blueprints/table/docs/Documentation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
Tables display information in a way that's easy to scan, so that users can look for patterns and insights. They allow you to showcase a variety amounts of structured data and for use in dm applications, a great way for user to navigate nested items and objects.

## Table of contents
- [Table variants](#variants)
- [Passing data](#passing-data)
- [Scope to list](#scope)
- [Selecting data](#selecting-data)
- [Column config](#column-config)
- [Functionality](#functionality)
- [Enabling/disabling functionality](#limiting-editing)
- [Sorting](#sorting)

## Variants \{#variants}
Table config expects a list of table variants. Available variants are `view` and `edit`. You can pass one or both variants in the list - if both variants are enabled/passed, user can switch modes in the UI. The initial table variant that shows in the UI is based on which variant is passed first in the variant list.

```json title="table-variant.recipe.json
"variant": [
{
"name": "view",
"type": "PLUGINS:dm-core-plugins/table/TableVariantConfig",
"functionality": {
"add": false,
"delete": false
},
"density": "comfortable",
},
{
"name": "edit",
"type": "PLUGINS:dm-core-plugins/table/TableVariantConfig",
}
]
```

## Passing data \{#passing-data}

### Scope to list \{#scope}
Table expects a list of objects. List is passed to the plugin by using the scope method in ViewConfig.
```json {4}
"viewConfig": {
"type": "CORE:ReferenceViewConfig",
"recipe": {…},
"scope": "list_attribute_name"
}
```

### Selecting data \{#selecting-data}

Select fields from objects in list passed to table by defining columns and passing field name in the `data` field.

```json {7}
"recipe": {
"config": {
"type": "PLUGINS:dm-core-plugins/table/TablePluginConfig",
"columns": [
{
"type": "./TableColumnConfig",
"data": "name",
"label": "Name"
}
]
}
}
```

You can also select data by using dot syntax to show and edit nested data in objects.

```json {7,12}
"recipe": {
"config": {
"type": "PLUGINS:dm-core-plugins/table/TablePluginConfig",
"columns": [
{
"type": "./TableColumnConfig",
"data": "person.firstName",
"label": "First Name"
},
{
"type": "./TableColumnConfig",
"data": "hobbies[0].name",
"label": "Favorite hobby"
}
]
}
}
```

### Column config \{#column-config}

#### dataType
`dataType` is used to format fields when you're editing and saving data. Available types are `'string' | 'boolean' | 'number' | 'datetime'`. The type should match the attribute type in blueprint.

#### presentAs
When dataType is boolean, by default the field is shown as a checkbox in the table. Value can also be shown as plain text by setting `presentAs` to `text`.

#### labels
Set column header label.

#### editable
Even if you're table is editable, it's possible to disable editing for individual columns by setting `editable` to `false`.

#### sortable
Sortable columns can be enabled by setting `sortable` to `true`. Sorting is only available in view/no-edit variant of table.

### Entry points to new tab and expandable content
There are two predefined fieldNames that allows you to add functionality to make the row expandable and open the table item in a new tab. These are prefixed by `^`.

#### Open in new tab
Opens item in new tab. Should be used in accordance with TabsPlugin/a view selector.
```json {7}
"recipe": {
"config": {
"type": "PLUGINS:dm-core-plugins/table/TablePluginConfig",
"columns": [
{
"type": "./TableColumnConfig",
"data": "^tab",
}
]
}
}
```

#### Expandable
```json {7}
"recipe": {
"config": {
"type": "PLUGINS:dm-core-plugins/table/TablePluginConfig",
"columns": [
{
"type": "./TableColumnConfig",
"data": "^expandable",
}
]
}
}
```
When using expandable for table items you can also pass a custom viewConfig for only this view by using the `expandableViewConfig` config field.
123 changes: 123 additions & 0 deletions packages/dm-core-plugins/blueprints/table/docs/Examples/Basic.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
{
"title": "Basic Table",
"description": "Minimal example for use of table plugin",
"note": "",
"showDemo": true,
"entityFilePrefix": "cars",
"blueprint": {
"name": "CarList",
"type": "dmss://system/SIMOS/Blueprint",
"attributes": [
{
"name": "type",
"type": "dmss://system/SIMOS/BlueprintAttribute",
"attributeType": "string"
},
{
"name": "name",
"type": "dmss://system/SIMOS/BlueprintAttribute",
"attributeType": "string"
},
{
"name": "cars",
"type": "dmss://system/SIMOS/BlueprintAttribute",
"attributeType": "./Car",
"dimensions": "*"
}
]
},
"entity": {
"type": "./CarList",
"cars": [
{
"_id": "volvo-in-car-list",
"name": "Volvo",
"type": "./Car",
"color": "White",
"model": "XC40"
},
{
"_id": "audi-in-car-list",
"name": "Audi",
"type": "./Car",
"color": "Black",
"model": "A2"
},
{
"_id": "bmw-in-car-list",
"name": "BMW",
"type": "./Car",
"color": "Blue",
"model": "X1"
}
]
},
"recipe": {
"name": "cars",
"type": "CORE:UiRecipe",
"description": "List of cars",
"plugin": "@development-framework/dm-core-plugins/table",
"config": {
"type": "PLUGINS:dm-core-plugins/table/TablePluginConfig",
"columns": [
{
"type": "PLUGINS:dm-core-plugins/table/TableColumnConfig",
"data": "name",
"label": "Name",
"sortable": true
},
{
"type": "PLUGINS:dm-core-plugins/table/TableColumnConfig",
"data": "model",
"label": "Model"
},
{
"type": "PLUGINS:dm-core-plugins/table/TableColumnConfig",
"data": "color",
"label": "Color"
}
],
"variant": [
{
"name": "view",
"type": "PLUGINS:dm-core-plugins/table/TableVariantConfig"
}
]
}
},
"scope": "cars",
"childBlueprints": [
{
"name": "Car",
"type": "CORE:Blueprint",
"description": "",
"attributes": [
{
"name": "type",
"type": "dmss://system/SIMOS/BlueprintAttribute",
"attributeType": "string",
"optional": false
},
{
"name": "name",
"type": "CORE:BlueprintAttribute",
"attributeType": "string",
"label": "Manufacturer"
},
{
"name": "model",
"type": "CORE:BlueprintAttribute",
"attributeType": "string",
"label": "Model"
},
{
"name": "color",
"type": "CORE:BlueprintAttribute",
"attributeType": "string",
"label": "Color",
"optional": true
}
]
}
]
}
122 changes: 122 additions & 0 deletions packages/dm-core-plugins/blueprints/table/docs/Examples/EditTable.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
{
"title": "Edit Table",
"description": "Modify, add and delete data in edit variant of table",
"note": "",
"showDemo": true,
"entityFilePrefix": "cars",
"blueprint": {
"name": "CarList",
"type": "dmss://system/SIMOS/Blueprint",
"attributes": [
{
"name": "type",
"type": "dmss://system/SIMOS/BlueprintAttribute",
"attributeType": "string"
},
{
"name": "name",
"type": "dmss://system/SIMOS/BlueprintAttribute",
"attributeType": "string"
},
{
"name": "cars",
"type": "dmss://system/SIMOS/BlueprintAttribute",
"attributeType": "./Car",
"dimensions": "*"
}
]
},
"entity": {
"type": "./CarList",
"cars": [
{
"_id": "volvo-in-car-list",
"name": "Volvo",
"type": "./Car",
"color": "White",
"model": "XC40"
},
{
"_id": "audi-in-car-list",
"name": "Audi",
"type": "./Car",
"color": "Black",
"model": "A2"
},
{
"_id": "bmw-in-car-list",
"name": "BMW",
"type": "./Car",
"color": "Blue",
"model": "X1"
}
]
},
"recipe": {
"name": "cars",
"type": "CORE:UiRecipe",
"description": "List of cars",
"plugin": "@development-framework/dm-core-plugins/table",
"config": {
"type": "PLUGINS:dm-core-plugins/table/TablePluginConfig",
"columns": [
{
"type": "PLUGINS:dm-core-plugins/table/TableColumnConfig",
"data": "name",
"label": "Name"
},
{
"type": "PLUGINS:dm-core-plugins/table/TableColumnConfig",
"data": "model",
"label": "Model"
},
{
"type": "PLUGINS:dm-core-plugins/table/TableColumnConfig",
"data": "color",
"label": "Color"
}
],
"variant": [
{
"name": "edit",
"type": "PLUGINS:dm-core-plugins/table/TableVariantConfig"
}
]
}
},
"scope": "cars",
"childBlueprints": [
{
"name": "Car",
"type": "CORE:Blueprint",
"description": "",
"attributes": [
{
"name": "type",
"type": "dmss://system/SIMOS/BlueprintAttribute",
"attributeType": "string",
"optional": false
},
{
"name": "name",
"type": "CORE:BlueprintAttribute",
"attributeType": "string",
"label": "Manufacturer"
},
{
"name": "model",
"type": "CORE:BlueprintAttribute",
"attributeType": "string",
"label": "Model"
},
{
"name": "color",
"type": "CORE:BlueprintAttribute",
"attributeType": "string",
"label": "Color",
"optional": true
}
]
}
]
}
Loading
Loading