add docs entry for custom step layout

Signed-off-by: Paul Cowan <paul.cowan@cutting.scot>
2022-09-21 13:21:48 +01:00
parent b27abf25f5
commit 0c8d3347b4
2 changed files with 88 additions and 0 deletions
@@ -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 }) => (
+  <>
+    <h1>{title}</h1>
+    <Grid container justifyContent="flex-end">
+      {properties.slice(0, mid).map(prop => (
+        <Grid item xs={6} key={prop.content.key}>
+          {prop.content}
+        </Grid>
+      ))}
+      {properties.slice(mid).map(prop => (
+        <Grid item xs={6} key={prop.content.key}>
+          {prop.content}
+        </Grid>
+      ))}
+    </Grid>
+    {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 = (
+  <FlatRoutes>
+    ...
+    <Route path="/create" element={<ScaffolderPage />}>
+      <ScaffolderLayouts>
+        <TwoColumnLayout />
+      </ScaffolderLayouts>
+    </Route>
+    ...
+  </FlatRoutes>
+);
+```
+
+## 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
+```
@@ -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