From a2d26b259331389b9e2ec765165cf46641f6fbe1 Mon Sep 17 00:00:00 2001 From: Andrea Vesterhus Date: Fri, 10 May 2024 09:38:07 +0200 Subject: [PATCH] feat: table docs --- .../blueprints/table/docs/Documentation.md | 137 ++++++++++++++ .../blueprints/table/docs/Examples/Basic.json | 123 +++++++++++++ .../table/docs/Examples/EditTable.json | 122 ++++++++++++ .../table/docs/Examples/Nested.json | 173 ++++++++++++++++++ 4 files changed, 555 insertions(+) create mode 100644 packages/dm-core-plugins/blueprints/table/docs/Documentation.md create mode 100644 packages/dm-core-plugins/blueprints/table/docs/Examples/Basic.json create mode 100644 packages/dm-core-plugins/blueprints/table/docs/Examples/EditTable.json create mode 100644 packages/dm-core-plugins/blueprints/table/docs/Examples/Nested.json diff --git a/packages/dm-core-plugins/blueprints/table/docs/Documentation.md b/packages/dm-core-plugins/blueprints/table/docs/Documentation.md new file mode 100644 index 000000000..3f45c98dd --- /dev/null +++ b/packages/dm-core-plugins/blueprints/table/docs/Documentation.md @@ -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. \ No newline at end of file diff --git a/packages/dm-core-plugins/blueprints/table/docs/Examples/Basic.json b/packages/dm-core-plugins/blueprints/table/docs/Examples/Basic.json new file mode 100644 index 000000000..88cfc06f1 --- /dev/null +++ b/packages/dm-core-plugins/blueprints/table/docs/Examples/Basic.json @@ -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 + } + ] + } + ] +} diff --git a/packages/dm-core-plugins/blueprints/table/docs/Examples/EditTable.json b/packages/dm-core-plugins/blueprints/table/docs/Examples/EditTable.json new file mode 100644 index 000000000..9b59378e7 --- /dev/null +++ b/packages/dm-core-plugins/blueprints/table/docs/Examples/EditTable.json @@ -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 + } + ] + } + ] +} diff --git a/packages/dm-core-plugins/blueprints/table/docs/Examples/Nested.json b/packages/dm-core-plugins/blueprints/table/docs/Examples/Nested.json new file mode 100644 index 000000000..c1f3cdc00 --- /dev/null +++ b/packages/dm-core-plugins/blueprints/table/docs/Examples/Nested.json @@ -0,0 +1,173 @@ +{ + "title": "Nested Data", + "description": "Example for using and configuring nested data in 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", + "engine": { + "name": "V60", + "type": "./blueprints/Engine", + "hp": 1000 + } + }, + { + "_id": "audi-in-car-list", + "name": "Audi", + "type": "./Car", + "color": "Black", + "model": "A2", + "engine": { + "name": "TDI 1.6", + "type": "./blueprints/Engine", + "hp": 120 + } + }, + { + "_id": "bmw-in-car-list", + "name": "BMW", + "type": "./Car", + "color": "Blue", + "model": "X1", + "engine": { + "name": "TDI 1.8", + "type": "./blueprints/Engine", + "hp": 122 + } + } + ] + }, + "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" + }, + { + "type": "PLUGINS:dm-core-plugins/table/TableColumnConfig", + "data": "engine.name", + "label": "Engine" + } + ], + "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 + }, + { + "name": "engine", + "type": "CORE:BlueprintAttribute", + "attributeType": "./Engine", + "label": "Engine", + "optional": true + } + ] + }, + { + "name": "Engine", + "type": "CORE:Blueprint", + "description": "", + "attributes": [ + { + "name": "type", + "type": "CORE:BlueprintAttribute", + "attributeType": "string", + "optional": false + }, + { + "name": "name", + "type": "CORE:BlueprintAttribute", + "attributeType": "string", + "label": "Manufacturer" + }, + { + "name": "hp", + "type": "CORE:BlueprintAttribute", + "attributeType": "number" + } + ] + } + ] +}