From 0c8d3347b4477cd117b85d6f711cdc693362b2b1 Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Wed, 21 Sep 2022 13:21:48 +0100 Subject: [PATCH 1/4] add docs entry for custom step layout Signed-off-by: Paul Cowan --- .../writing-custom-step-layouts.md | 84 +++++++++++++++++++ .../software-templates/writing-templates.md | 4 + 2 files changed, 88 insertions(+) create mode 100644 docs/features/software-templates/writing-custom-step-layouts.md diff --git a/docs/features/software-templates/writing-custom-step-layouts.md b/docs/features/software-templates/writing-custom-step-layouts.md new file mode 100644 index 0000000000..53b1ca342d --- /dev/null +++ b/docs/features/software-templates/writing-custom-step-layouts.md @@ -0,0 +1,84 @@ +--- +id: writing-custom-step-layouts +title: Writing custom step layouts +description: How to override the default step form layout +--- + +Every form in each step rendered in the frontend uses the default form layout from [react-json-schema-form](https://react-jsonschema-form.readthedocs.io/). It is possible to override this behaviour by supplying a `ui:ObjectFieldTemplate` property for a particular step: + +```yaml +parameters: + - title: Fill in some steps + ui:ObjectFieldTemplate: TwoColumn +``` + +This is the same [field](https://react-jsonschema-form.readthedocs.io/en/latest/advanced-customization/custom-templates/#objectfieldtemplate) used by [react-json-schema-form](https://react-jsonschema-form.readthedocs.io/) but we need to add a couple of steps to ensure that the string value of `TwoColumn` above is resolved to a react component. + +## Registering a React component as a custom step layout + +The [createScaffolderLayout](https://backstage.io/docs/reference/plugin-scaffolder.createscaffolderlayout) function is used to mark a component as a custom step layout: + +```ts +import React from 'react'; +import { + createScaffolderLayout, + LayoutTemplate, + scaffolderPlugin, +} from '@backstage/plugin-scaffolder'; +import { Grid } from '@material-ui/core'; + +const TwoColumn: LayoutTemplate = ({ properties, description, title }) => ( + <> +

{title}

+ + {properties.slice(0, mid).map(prop => ( + + {prop.content} + + ))} + {properties.slice(mid).map(prop => ( + + {prop.content} + + ))} + + {description} + +); + +export const TwoColumnLayout = scaffolderPlugin.provide( + createScaffolderLayout({ + name: 'TwoColumn', + component: TwoColumn, + }), +); +``` + +After you have registered your component as a custom layout then you need to provide the `layouts` to the `ScaffolderPage`: + +```tsx +import { MyCustomFieldExtension } from './scaffolder/MyCustomExtension'; +import { TwoColumnLayout } from './components/scaffolder/customScaffolderLayouts'; + +const routes = ( + + ... + }> + + + + + ... + +); +``` + +## Using the custom step layout + +Any component that has been passed to the `ScaffolderPage` as children of the `ScaffolderLayouts` component can be used as a `ui:ObjectFieldTemplate` in your template file: + +```yaml +parameters: + - title: Fill in some steps + ui:ObjectFieldTemplate: TwoColumn +``` diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index a1cd50f271..3baf642f24 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -258,6 +258,10 @@ use `ui:widget: password` or set some properties of `ui:backstage`: show: false # won't print any info about 'hidden' property on Review Step ``` +### Custom step layouts + +If you find the default layout of the form in used in a particular step does not meet your needs then you can supply your own [custom step layout](./writing-custom-step-layouts.md). + ### Remove sections or fields based on feature flags Based on feature flags you can hide sections or even only fields of your From 2b908d00b797835ee1f536b1f5a09bd2a433b9c9 Mon Sep 17 00:00:00 2001 From: Paul Date: Wed, 21 Sep 2022 16:32:07 +0100 Subject: [PATCH 2/4] Update docs/features/software-templates/writing-templates.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Paul Signed-off-by: Paul Cowan --- docs/features/software-templates/writing-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index 3baf642f24..826121bd02 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -260,7 +260,7 @@ use `ui:widget: password` or set some properties of `ui:backstage`: ### Custom step layouts -If you find the default layout of the form in used in a particular step does not meet your needs then you can supply your own [custom step layout](./writing-custom-step-layouts.md). +If you find that the default layout of the form used in a particular step does not meet your needs then you can supply your own [custom step layout](./writing-custom-step-layouts.md). ### Remove sections or fields based on feature flags From ff4f8bb9e58b2e8e83087066a9dcfc7f4366792b Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Wed, 21 Sep 2022 18:03:09 +0100 Subject: [PATCH 3/4] add writing-custom-step-layouts to sidebars.json Signed-off-by: Paul Cowan --- .../writing-custom-step-layouts.md | 41 +++++++++++-------- microsite/sidebars.json | 1 + .../scaffolder/customScaffolderLayouts.tsx | 1 - 3 files changed, 24 insertions(+), 19 deletions(-) diff --git a/docs/features/software-templates/writing-custom-step-layouts.md b/docs/features/software-templates/writing-custom-step-layouts.md index 53b1ca342d..69d61b93dc 100644 --- a/docs/features/software-templates/writing-custom-step-layouts.md +++ b/docs/features/software-templates/writing-custom-step-layouts.md @@ -27,24 +27,29 @@ import { } from '@backstage/plugin-scaffolder'; import { Grid } from '@material-ui/core'; -const TwoColumn: LayoutTemplate = ({ properties, description, title }) => ( - <> -

{title}

- - {properties.slice(0, mid).map(prop => ( - - {prop.content} - - ))} - {properties.slice(mid).map(prop => ( - - {prop.content} - - ))} - - {description} - -); +const TwoColumn: LayoutTemplate = ({ properties, description, title }) => { + const mid = Math.ceil(properties.length / 2); + + return ( + <> +

{title}

+

In two column layout!!

+ + {properties.slice(0, mid).map(prop => ( + + {prop.content} + + ))} + {properties.slice(mid).map(prop => ( + + {prop.content} + + ))} + + {description} + + ); +}; export const TwoColumnLayout = scaffolderPlugin.provide( createScaffolderLayout({ diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 44d8e12869..dd1ea30e2e 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -97,6 +97,7 @@ "features/software-templates/builtin-actions", "features/software-templates/writing-custom-actions", "features/software-templates/writing-custom-field-extensions", + "features/software-templates/writing-custom-step-layouts", "features/software-templates/migrating-from-v1beta2-to-v1beta3" ] }, diff --git a/packages/app/src/components/scaffolder/customScaffolderLayouts.tsx b/packages/app/src/components/scaffolder/customScaffolderLayouts.tsx index 8dc6e5340a..b23d6e4073 100644 --- a/packages/app/src/components/scaffolder/customScaffolderLayouts.tsx +++ b/packages/app/src/components/scaffolder/customScaffolderLayouts.tsx @@ -28,7 +28,6 @@ const TwoColumn: LayoutTemplate = ({ properties, description, title }) => { return ( <>

{title}

-

In two column layout!!

{left.map(prop => ( From 54ad27833fd0c67107f055d009bb7bcc61f647d7 Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Wed, 21 Sep 2022 18:11:04 +0100 Subject: [PATCH 4/4] add writing-custom-step-layouts to mkdocs.yml Signed-off-by: Paul Cowan --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index c0a8e3a182..8c86ae095d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,6 +64,7 @@ nav: - Writing Templates: 'features/software-templates/writing-templates.md' - Builtin Actions: 'features/software-templates/builtin-actions.md' - Writing Custom Actions: 'features/software-templates/writing-custom-actions.md' + - Writing Custom Step Layouts: 'features/software-templates/writing-custom-step-layouts.md' - Writing Templates (Legacy): 'features/software-templates/legacy.md' - Migrating from v1alpha1 to v1beta2 templates: 'features/software-templates/migrating-from-v1alpha1-to-v1beta2.md' - Backstage Search: