docs: Update README and DEVELOP

eea · Sep 29, 2023 · bcb0ca8 · bcb0ca8
1 parent 608f4d9
commit bcb0ca8
Show file tree

Hide file tree

Showing 2 changed files with 148 additions and 10 deletions.
diff --git a/DEVELOP.md b/DEVELOP.md
@@ -16,12 +16,14 @@
 
 1. Go to http://localhost:3000
 
-1.  Happy hacking!
+1. Initialize git hooks
 
     ```Bash
-    cd src/addons/volto-object-widget/
+    yarn prepare
     ```
 
+1. Happy hacking!
+
 ### Or add @eeacms/volto-object-widget to your Volto project
 
 Before starting make sure your development environment is properly set. See [Volto Developer Documentation](https://docs.voltocms.com/getting-started/install/)
@@ -48,18 +50,15 @@ Before starting make sure your development environment is properly set. See [Vol
 
 1.  Install
 
-        yarn develop
+        make develop
         yarn
 
 1.  Start backend
 
-        docker pull plone
-        docker run -d --name plone -p 8080:8080 -e SITE=Plone -e PROFILES="profile-plone.restapi:blocks" plone
+        docker run --pull always -it --rm --name plone -p 8080:8080 -e SITE=Plone plone/plone-backend
 
     ...wait for backend to setup and start - `Ready to handle requests`:
 
-        docker logs -f plone
-
     ...you can also check http://localhost:8080/Plone
 
 1.  Start frontend

diff --git a/README.md b/README.md
@@ -14,12 +14,151 @@
 [![Bugs](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-object-widget-develop&metric=bugs)](https://sonarqube.eea.europa.eu/dashboard?id=volto-object-widget-develop)
 [![Duplicated Lines (%)](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-object-widget-develop&metric=duplicated_lines_density)](https://sonarqube.eea.europa.eu/dashboard?id=volto-object-widget-develop)
 
-
-[Volto](https://github.com/plone/volto) add-on
+[Volto](https://github.com/plone/volto) add-on: Various Volto schema-based widgets.
 
 ## Features
 
-Demo GIF
+This Volto addon provides several "abstract" widgets, to allow complex
+information to be editable by the schema-based forms. It centers around the
+concept: "we can create a form to edit a JSON object by using a schema" and so
+it provides, right now, widgets to edit "list of JSON objects", a "mapping of
+JSON objects" and a single "JSON object, but I choose the schema for it".
+
+### FlatListObject
+
+![Flat List object](./img/flat-list-widget.png)
+
+This widget allows you to edit a list of objects by creating, editing and
+deleting instances of objects editable with the provided `schema` parameter.
+The list is sortable with drag&drop. You can also provide a schema extender,
+a function with signature `(schema, data) => schema`, which will adjust, per
+instance of object, its schema. To use this widget, in the schema, set the
+`widget` field to `object_list_inline`.
+
+Example of how the data could look like for a block:
+
+```
+"a55c5053-ba81-4f73-ab29-7cdea74df20f": {
+	"@type": "dataTable",
+	"columns": [
+		{
+			"@id": "f899ca76-68be-4ded-aa0b-669c04c27309",
+			"column": " PERC_HA_07\n(in %)",
+			"renderer": "progress",
+			"title": "21"
+		},
+		{
+			"@id": "94315c5a-e031-4b7e-acb2-93887878a252",
+			"column": " PERC_HA_07\n(in %)",
+			"title": "12"
+		}
+	],
+}
+```
+
+The `columns` field, in this case, is data generated by the `FlatListObject`.
+The schema for this field could look like (`ColumnSchema()` just generates
+another instance of a schema, suitable for the `column` definition of our
+specific use case):
+
+```
+columns: {
+  title: 'Columns',
+  description: 'Leave empty to show all columns',
+  schema: ColumnSchema(),
+  widget: 'object_list_inline',
+},
+```
+
+### Mapping Widget
+
+![Mapping widget](./img/mapping-widget.png)
+
+This widget allows editing the properties of an object. For example, in the
+following block data, the `row_colors` value is generated by an instance of the
+`MappingWidget`.
+
+```
+"4430a32a-a266-497b-88e7-72fead5ab718": {
+  "@type": "dottedTableChart",
+  "column_data": "habitat_group",
+  "row_colors": {
+    "Bad": "#ed1834",
+    "F - Heathland, scrub and tundra": "#88c24f",
+    "Good": "#3c8000",
+    "Poor": "#f2a70e",
+    "Unknown": "#8d8d8d"
+  },
+  "row_data": "assessment",
+  "size_data": "quantity"
+},
+```
+
+You need to provide the `options`, which is a list of objects with `{id, title}` and the `field_props`, which are parameters for the actual field that
+will be used to edit the values. In our case the schema definition that was
+used to edit the above value is (note, the options are empty, we're populating
+them in the edit component, before passing the schema to the form):
+
+```
+row_colors: {
+  title: 'Colors',
+  widget: 'option_mapping',
+  field_props: {
+    widget: 'simple_color',
+    available_colors: settings.available_colors,
+  },
+  options: [],
+}
+```
+
+To use this widget, in the schema, set the `widget` field to `option_mapping`.
+
+### Object by type
+
+![Object by type](./img/object-by-type-widget.png)
+
+With this widget you can choose the type of value that will be used, from
+a predefined list of schemas. A schema that would use this type of widget could
+look like:
+
+```
+const LinkEditSchema = {
+  title: 'Link',
+  fieldsets: [
+    {
+      id: 'default',
+      title: 'Default',
+      fields: ['link'],
+    },
+  ],
+  properties: {
+    link: {
+      title: 'Link',
+      widget: 'object_by_type',
+      schemas: [
+        {
+          id: 'internal',
+          icon: internalSVG,
+          schema: InternalLinkSchema,
+        },
+        {
+          id: 'external',
+          icon: externalSVG,
+          schema: ExternalLinkSchema,
+        },
+        {
+          id: 'email',
+          icon: emailSVG,
+          schema: EmailLinkSchema,
+        },
+      ],
+    },
+  },
+  required: [],
+};
+```
+
+To use this widget, in the schema, set the `widget` field to `object_by_type`.
 
 ## Getting started