From a7455ed9af44df90a3d10c39e8c10c36238db573 Mon Sep 17 00:00:00 2001 From: Gustav Hansen Date: Tue, 18 Apr 2023 15:21:20 +0200 Subject: [PATCH] Docs: Extend contributor documention with review workflows (frontend) --- .../core/content-manager/review-workflows.mdx | 95 +++++++++++++++++++ .../content-type-builder/review-workflows.mdx | 38 ++++++++ docs/docs/core/settings/intro.mdx | 17 ++++ docs/docs/core/settings/review-workflows.mdx | 77 +++++++++++++++ docs/sidebars.js | 28 +++++- 5 files changed, 254 insertions(+), 1 deletion(-) create mode 100644 docs/docs/core/content-manager/review-workflows.mdx create mode 100644 docs/docs/core/content-type-builder/review-workflows.mdx create mode 100644 docs/docs/core/settings/intro.mdx create mode 100644 docs/docs/core/settings/review-workflows.mdx diff --git a/docs/docs/core/content-manager/review-workflows.mdx b/docs/docs/core/content-manager/review-workflows.mdx new file mode 100644 index 0000000000..95a30c5cca --- /dev/null +++ b/docs/docs/core/content-manager/review-workflows.mdx @@ -0,0 +1,95 @@ +--- +title: Review Workflows +slug: /content-manager/review-workflows +description: Guide for review workflows in the content-manager. +tags: + - content-manager + - review-workflows +--- + +## Summary + +Review workflows are disabled for all content-types by default and have to be enabled for each of them. More about how to [enable review-workflows for a content-type](/content-type-builder/review-workflows). + +The feature is visible in two locations of the content-manager: + +### List view + +If the feature is enabled for a content-type a new column will show up, displaying the current stage. If no stage was assigned to an entity, +the column is displayed as empty. + +### Edit view + +If the feature is enabled for a content-type the currently selected stage will show up in the information sidebar next to the edit view. Users +can select any other stage of the current workflow. + +Stage assignments are decoupled from entities, meaning that updating an entity won't set the selected stage. Instead the stage select +component will trigger an atomic update using the admin API to assign/ update a stage to the current entity, when a new value is selected. +Because of this decoupling stages **can not be assigned on entity creation** and only after the have been created. + +If no stage was assigned to the current entity the select component displays and error and asks a user to select a stage. + +## Default stage + +By default every entity which is part of a content-type with review workflows enabled, will get the first stage of the attached workflow +assigned upon creation via the **admin API**, **content API** and the **entity Service**. + +### Stage assignments + +The default stage is assigned upon entity creation. In the bootstrap phase of Strapi all entities that do not have a stage assigned +(and are part of a content-type which has the feature enabled) will have the default stage assigned. Initially this was meant as the +migration when the feature is enabled for the first time to ensure all entities, but became also a safety-net for entities +that do not have a stage set. + +### Nullish stages + +Entities which are not created through the admin API, content API or entity service will not have a stage assigned by default (e.g. lifecycle methods). +If entities are created through more low-level ways, developers need to take care to assign a stage individually. + +This means at any place where the UI displays a stage, it has to be prepared to receive `null` and should not crash. + +## List view + +The information which stage is current assigned to an entity is send as part of the content-type response payload for each entity in the attribute `strapi_reviewWorkflows_stage`. +Please see [Data Shapes](/settings/review-workflows#data-shapes) for type definitions. + +```ts +{ + // ... entity attributes + strapi_reviewWorkflows_stage?: Stage | null +} +``` + +`http://localhost:1337/content-manager/content-types` returns whether the feature is enabled for the content-type. `options.reviewWorkflows` is either `true`, `false` or undefined. + +**Note**: Downgrading from EE to CE won't delte the associated review workflow data and `http://localhost:1337/content-manager/content-types` still returns true. The admin app had to +add an additional check if the feature toggle returned in `http://localhost:1337/admin/project-type` is enabled. + +## Edit View + +The information which stage is current assigned to an entity is send as part of the entity response payload in the attribute `strapi_reviewWorkflows_stage`. +Please see [Data Shapes](/settings/review-workflows#data-shapes) for type definitions. + +```ts +{ + // ... entity attributes + strapi_reviewWorkflows_stage?: Stage | null +} +``` + +- `undefined`: the feature is not enabled for this content-type +- `null`: no stage is assigned to the entity + +### Endpoints + +#### `PUT /admin/content-manager/[kind]/[content-type-uid]/[entity-id]/stage` + +Assignes a stage to an entity. + +##### Payload + +```ts +data: { + id: int // assigned stage id +} +``` diff --git a/docs/docs/core/content-type-builder/review-workflows.mdx b/docs/docs/core/content-type-builder/review-workflows.mdx new file mode 100644 index 0000000000..b8e076cbd1 --- /dev/null +++ b/docs/docs/core/content-type-builder/review-workflows.mdx @@ -0,0 +1,38 @@ +--- +title: Review Workflows +slug: /content-type-builder/review-workflows +description: Guide for review workflows in the content-type-builder. +tags: + - content-type-builder + - review-workflows +--- + +## Summary + +By **default review workflows are disabled on all content-types** and users have to enable one workflow +per content-type. This can be achieved in the "Advanced Settings" Tab of the edit content-type +modal. + +Similar to draft & publish review-workflows registers a new input compontent type called `toggle-review-workflows` +which is used to render the checkbox component. + +**Note**: *Ideally the code should have been placed in the `ee` folder to be +under the enterprise license, but neither the content-type-builder nor the babel-plugin to transpile the ee code had support for this.* + +## Endpoints + +### `PUT /content-type-builder/content-types/[content-type-uid]` + +Toggle review workflows for the content-type. + +#### Payload + +```ts +{ + components: [], + contentType: { + attributes: {}, + reviewWorkflows: boolean + } +} +``` diff --git a/docs/docs/core/settings/intro.mdx b/docs/docs/core/settings/intro.mdx new file mode 100644 index 0000000000..32806bb2d9 --- /dev/null +++ b/docs/docs/core/settings/intro.mdx @@ -0,0 +1,17 @@ +--- +title: Introduction +slug: /settings/intro +tags: + - settings +--- + +# Settings + +This section is an overview of all the features related to Settings: + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import { useCurrentSidebarCategory } from '@docusaurus/theme-common'; + + +``` diff --git a/docs/docs/core/settings/review-workflows.mdx b/docs/docs/core/settings/review-workflows.mdx new file mode 100644 index 0000000000..5c0b9acf6e --- /dev/null +++ b/docs/docs/core/settings/review-workflows.mdx @@ -0,0 +1,77 @@ +--- +title: Review Workflows +slug: /settings/review-workflows +description: Guide for review workflows in settings. +tags: + - settings + - review-workflows +--- + +## Summary + +The settings page for review workflows is where users can add and edit stages in any workflow. A stage is a step within +each workflow. It is only **accessible in enterprise mode** and if the read permission `admin::review-workflows.read` is set to `true`. + +Upon mount the settings page injects itself into the global redux store under the namespace `settings_review-workflows`. Redux is +then used for all state management updates on the settings page. `Formik` is used to render and validate the list of stages. It +is integrated with redux, so that all input components are controlled components. + +### Form submission + +The form the wraps workflow stages submits all stages at once, because we expect the number of stages per workflow to be +rather small. Because of this we can simply re-order stages by sending a different order. Every stage that sends a corresponding `id` +attribute will be re-ordered and not created. Stages without an `id` property will be created in the database on submission. + +### Stage deletion + +In case a stage is deleted, all **entities which are connected to that stage are moved to the previous stage**. Because a stage deletion +might have big effects on the database, a confirmation is shown when a stage is up for deletion. + +Changes are only applied if the user hits "Save". It is not possible to remove all stages from a workflow (neither in the UI nor the API). + +### Hooks + +#### `useReviewWorkflows(workflowId?: number)` + +This hook allows to fetch either one (if `workflowId` is passed) or all workflows at once. By default all stages are populated. The +hooks returns a react-query result. This hook is used to fetch a workflow on the settings page and the content-manager edit view. + +The API returns an `array` of workflows. In the first iteration only one workflow is supported, but this is subject to change soon. + +### Data shapes + +```ts +type Stage { + id: int + name: string // max-length: 255 characters + createdAt: Date + updatedAt: Date +} + +type Worklow { + id: int, + stages: Stage[] + createdAt: Date + updatedAt: Date +} +``` + +### Endpoints + +#### `GET /admin/review-workflows/workflows/` + +Returns a list of all workflows. Stages can be populated using `?populate=stages`. + +#### `PUT /admin/review-workflows/workflows/` + +Update workflow stages. + +##### Payload + +```ts +{ + data: Stage[] +} +``` + +**Note**: All stages need to be submitted. Stages without an `id` attribute will be created. The order of stages is persisted in the database. diff --git a/docs/sidebars.js b/docs/sidebars.js index 787b6fc5ff..abf1393e10 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -75,6 +75,11 @@ const sidebars = { label: 'Relations', id: 'core/content-manager/relations', }, + { + type: 'doc', + label: 'Review Workflows', + id: 'core/content-manager/review-workflows', + }, ], }, { @@ -84,7 +89,13 @@ const sidebars = { type: 'doc', id: 'core/content-type-builder/intro', }, - items: ['example'], + items: [ + { + type: 'doc', + label: 'Review Workflows', + id: 'core/content-type-builder/review-workflows', + }, + ], }, { type: 'category', @@ -161,6 +172,21 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Settings', + link: { + type: 'doc', + id: 'core/settings/intro', + }, + items: [ + { + type: 'doc', + label: 'Review Workflows', + id: 'core/settings/review-workflows', + }, + ], + }, { type: 'category', label: 'Utils',