docs(scaffolder): add info about custom field explorer

Signed-off-by: Phil Kuang <pkuang@factset.com>
2022-11-10 13:11:03 -05:00
parent aa4438e341
commit 3e4a2ee779
11 changed files with 158 additions and 47 deletions
@@ -181,3 +181,109 @@ const CustomFieldExtension = scaffolderPlugin.provide(
  })
 );
 ```
+
+## Previewing Custom Field Extensions
+
+You can preview custom field extensions you write in the Backstage UI using the Custom Field Explorer
+(accessible via the `/create/edit` route by default):
+
+![Custom Field Explorer](../../assets/software-templates/custom-field-explorer.png)
+
+In order to make your new custom field extension available in the explorer you will have to define a
+JSON schema that describes the input/output types on your field like in the following example:
+
+```tsx
+//packages/app/src/scaffolder/MyCustomExtensionWithOptions/MyCustomExtensionWithOptions.tsx
+export const MyCustomExtensionWithOptionsSchema = {
+  uiOptions: {
+    type: 'object',
+    properties: {
+      focused: {
+        description: 'Whether to focus this field',
+        type: 'boolean',
+      },
+    },
+  },
+  returnValue: { type: 'string' },
+};
+
+export const MyCustomExtensionWithOptions = ({
+  onChange,
+  rawErrors,
+  required,
+  formData,
+}: FieldProps<string, { focused?: boolean }>) => {
+  return (
+    <FormControl
+      margin="normal"
+      required={required}
+      error={rawErrors?.length > 0 && !formData}
+      onChange={onChange}
+      focused={focused}
+    />
+  );
+};
+```
+
+```tsx
+// packages/app/src/scaffolder/MyCustomExtensionWithOptions/extensions.ts
+...
+import { MyCustomExtensionWithOptions, MyCustomExtensionWithOptionsSchema } from './MyCustomExtensionWithOptions';
+
+export const MyCustomFieldWithOptionsExtension = scaffolderPlugin.provide(
+  createScaffolderFieldExtension({
+    name: 'MyCustomExtensionWithOptions',
+    component: MyCustomExtensionWithOptions,
+    schema: MyCustomExtensionWithOptionsSchema,
+  }),
+);
+```
+
+We recommend using a library like [zod](https://github.com/colinhacks/zod) to define your schema
+and the provided `makeJsonSchemaFromZod` helper utility function to generate both the JSON schema
+and types for your field input/output to preventing having to duplicate the definitions:
+
+```tsx
+//packages/app/src/scaffolder/MyCustomExtensionWithOptions/MyCustomExtensionWithOptions.tsx
+...
+import { z } from 'zod';
+import { makeJsonSchemaFromZod } from '@backstage/plugin-scaffolder';
+
+const MyCustomExtensionWithOptionsUiOptionsSchema = makeJsonSchemaFromZod(
+  z.object({
+    focused: z
+      .boolean()
+      .optional()
+      .describe('Whether to focus this field'),
+  }),
+);
+
+const MyCustomExtensionWithOptionsReturnValueSchema = makeJsonSchemaFromZod(
+  z.string(),
+);
+
+export const MyCustomExtensionWithOptionsSchema = {
+  uiOptions: MyCustomExtensionWithOptionsUiOptionsSchema.schema,
+  returnValue: MyCustomExtensionWithOptionsReturnValueSchema.schema,
+};
+
+export const MyCustomExtensionWithOptions = ({
+  onChange,
+  rawErrors,
+  required,
+  formData,
+}: FieldProps<
+  typeof MyCustomExtensionWithOptionsReturnValueSchema.type,
+  typeof MyCustomExtensionWithOptionsUiOptionsSchema.type
+>) => {
+  return (
+    <FormControl
+      margin="normal"
+      required={required}
+      error={rawErrors?.length > 0 && !formData}
+      onChange={onChange}
+      focused={focused}
+    />
+  );
+};
+```