From bcb0ca8b9a3e23025f3f064e374c38e2acbfad03 Mon Sep 17 00:00:00 2001 From: Alin Voinea Date: Fri, 29 Sep 2023 11:44:17 +0300 Subject: [PATCH] docs: Update README and DEVELOP --- DEVELOP.md | 13 +++-- README.md | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 148 insertions(+), 10 deletions(-) diff --git a/DEVELOP.md b/DEVELOP.md index 3fb6ace..7f05ad4 100644 --- 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 index 2e3f378..b8c9d81 100644 --- 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