Add support for customizing Add component buttons (#455)

#274: Add support for customizing Add popover radio options

Author: nateplusplus

.gitignore

@@ -13,5 +13,6 @@ example/build
 
 .DS_Store
 *.swp
+.vscode
 
 npm-debug.log*

docs/Mods.md

@@ -14,6 +14,9 @@ declare type Mods = {|
     [string]: FormInput,
     ...
   },
+  components?: {|
+    add?: (properties: { [string]: any }) => void,
+  },
   tooltipDescriptions?: {|
     add?: string,
     cardObjectName?: string,
@@ -31,6 +34,8 @@ declare type Mods = {|
     displayNameLabel?: string,
     descriptionLabel?: string,
     inputTypeLabel?: string,
+    addElementLabel?: string,
+    addSectionLabel?: string,
   |},
   showFormHead?: boolean,
   deactivatedFormInputs?: Array<string>,
@@ -185,3 +190,5 @@ The text for the labels of a few of the inputs in the Form Builder can similarly
 - `displayNameLabel` - The label for the "Display Name" field.
 - `descriptionLabel` - The label for the "Description" field.
 - `inputTypeLabel` - The label for the "Input Type" field.
+- `addElementLabel` - The label for the popover option when adding a new form element.
+- `addSectionLabel` - The label for the popover option when adding a new form section.

docs/Usage.md

@@ -306,6 +306,119 @@ mods = {
 
 will set the UI schema for a new element to use the `customWidget` widget.
 
+### Customizing "Add" buttons
+
+This form builder includes a button to add new form elements or sections (the button with a + symbol). In some cases you may want to modify this feature or provide custom button components. There are a few options to customize this component.
+
+#### **1. Custom Labels**
+
+One simple way to provide customization is to change the labels for "Add form element" and "Add form section". You can update these labels with the following mods:
+
+```js
+const mods = {
+  //...
+  labels: {
+    //...
+    addElementLabel: 'my element label',
+    addSectionLabel: 'my section label',
+  }
+}
+```
+
+#### **2. Invoking the "add" functions**
+
+You can invoke the following two functions anywhere in your app in order to add form elements and/or sections within the Form Builder component:
+
+```js
+import { addCardObj, addSectionObj } from '@ginkgo-bioworks/react-json-schema-form-builder';
+```
+
+Both of these functions require the following properties:
+
+```js
+type properties = {
+  schema: object, // FormBuilder schema
+  uischema: object, // FormBuilder uiSchema
+  mods: object, // FormBuilder mods
+  onChange: (newSchema: object, newUiSchema: object) => {
+    // update schemas when button clicked...
+  },
+  definitionData: string, // see: schema.definitions
+  definitionUi: string, // see: uischema.definitions
+  categoryHash: [string], // see: FormBuilder.onMount()
+};
+```
+
+The `categoryHash` helps FormBuilder match input types and is generated by FormBuilder upon rendering. You can get the generated hash through the `onMount` callback.
+
+Example:
+
+```js
+<FormBuilder
+  //...
+  onMount={({ categoryHash }) => {
+    // Here you can save categoryHash to props or state
+    setCategoryHash(categoryHash);
+  }}
+/>
+```
+
+#### **3. Overriding the "Add" component**
+
+By providing a custom component through `mods`, you can completely override the `Add` component.
+
+To do this, provide a callback function to the `components.add` mod. This callback should expect one argument, which provides properties that are required to add elements and sections to the form builder.
+
+```js
+import { addCardObj } from '@ginkgo-bioworks/react-json-schema-form-builder';
+
+mods = {
+  components: {
+    add: (properties) => <MyComponent onClick={() => { addCardObj(properties) }} />
+  }
+}
+```
+
+Putting it all together, the following snippet is an example showing two fully functioning buttons:
+
+```js
+import React, { useState } from 'react';
+import { addCardObj, addSectionObj } from '@ginkgo-bioworks/react-json-schema-form-builder';
+
+const mods = {
+  //...
+};
+
+function MyFormBuilder() {
+  const [schema, setSchema] = useState({});
+  const [uiSchema, setUiSchema] = useState({});
+  const [categoryHash, setCategoryHash] = useState('');
+
+  mods.components: {
+    add: (addProps) => {
+      return (
+        <div>
+          <Button onClick={() => { addCardObj(addProps) }}>Add Form Element</Button>
+          <Button onClick={() => { addSectionObj(addProps) }}>Add Form Section</Button>
+        </div>
+      );
+    },
+  };
+
+  return (
+    <FormBuilder
+      schema={JSON.stringify(schema)}
+      uischema={JSON.stringify(uiSchema)}
+      mods={mods}
+      onChange={(newSchema, newUiSchema) => {
+        setSchema(JSON.parse(newSchema));
+        setUiSchema(JSON.parse(newUiSchema));
+      }}
+    />
+  );
+}
+```
+
 ### Styling
 
 To avoid collisions with existing CSS styles, this app uses [react-jss](https://cssinjs.org/react-jss/?v=v10.5.0) in order to generate class names avoiding overlap with others in the global scope. Using CSS to style FormBuilder and PredefinedGallery components will not work and is not supported. The ability to "skin" the FormBuilder and PredefinedGallery components may be a feature in the future.

src/formBuilder/Add.js

@@ -14,6 +14,7 @@ import FontAwesomeIcon from './FontAwesomeIcon';
 import FBRadioGroup from './radio/FBRadioGroup';
 import { getRandomId } from './utils';
 import type { Node } from 'react';
+import type { ModLabels } from './types';
 
 const useStyles = createUseStyles({
   addDetails: {
@@ -38,10 +39,12 @@ export default function Add({
   addElem,
   hidden,
   tooltipDescription,
+  labels,
 }: {
   addElem: (choice: string) => void,
   hidden?: boolean,
   tooltipDescription?: string,
+  labels?: ModLabels,
 }): Node {
   const classes = useStyles();
   const [popoverOpen, setPopoverOpen] = useState(false);
@@ -76,11 +79,11 @@ export default function Add({
             options={[
               {
                 value: 'card',
-                label: 'Form element',
+                label: labels?.addElementLabel ?? 'Form element',
               },
               {
                 value: 'section',
-                label: 'Form section',
+                label: labels?.addSectionLabel ?? 'Form section',
               },
             ]}
             onChange={(selection) => {

src/formBuilder/Card.js

@@ -113,6 +113,7 @@ export default function Card({
   allFormInputs,
   mods,
   showObjectNameInput = true,
+  addProperties,
 }: {
   componentProps: {
     [string]: string | number | boolean | Array<string | number>,
@@ -132,6 +133,7 @@ export default function Card({
   mods?: Mods,
   allFormInputs: { [string]: FormInput },
   showObjectNameInput?: boolean,
+  addProperties?: { [string]: any },
 }): Node {
   const classes = useStyles();
   const [modalOpen, setModalOpen] = React.useState(false);
@@ -249,13 +251,12 @@ export default function Card({
           TypeSpecificParameters={TypeSpecificParameters}
         />
       </Collapse>
-      {addElem ? (
+      {mods?.components?.add && mods?.components?.add(addProperties)}
+      {!mods?.components?.add && addElem && (
         <Add
           tooltipDescription={((mods || {}).tooltipDescriptions || {}).add}
           addElem={(choice: string) => addElem(choice)}
         />
-      ) : (
-        ''
       )}
     </React.Fragment>
   );

src/formBuilder/CardGallery.js

@@ -71,61 +71,49 @@ export default function CardGallery({
     </div>
   ));
 
+  const hideAddButton =
+    !!definitionSchema && Object.keys(definitionSchema).length !== 0;
+
+  const addProperties = {
+    schema: { properties: definitionSchema },
+    uischema: definitionUiSchema,
+    mods: mods,
+    onChange: (newDefinitions, newDefinitionUis) => {
+      const oldUi = newDefinitionUis;
+      const newUi = {};
+
+      Object.keys(oldUi).forEach((definedUiSchemaKey) => {
+        if (!['definitions', 'ui:order'].includes(definedUiSchemaKey))
+          newUi[definedUiSchemaKey] = oldUi[definedUiSchemaKey];
+      });
+      onChange(newDefinitions.properties, newUi);
+    },
+    definitionData: definitionSchema,
+    definitionUi: definitionUiSchema,
+    categoryHash,
+  };
+
   return (
     <div className='form_gallery'>
       {componentArr}
       {componentArr.length === 0 && <h5>No components in "definitions"</h5>}
       <div className='form_footer'>
-        <Add
-          tooltipDescription={((mods || {}).tooltipDescriptions || {}).add}
-          addElem={(choice: string) => {
-            if (choice === 'card') {
-              addCardObj({
-                schema: { properties: definitionSchema },
-                uischema: definitionUiSchema,
-                mods: mods,
-                onChange: (newDefinitions, newDefinitionUis) => {
-                  const oldUi = newDefinitionUis;
-                  const newUi = {};
-
-                  Object.keys(oldUi).forEach((definedUiSchemaKey) => {
-                    if (
-                      !['definitions', 'ui:order'].includes(definedUiSchemaKey)
-                    )
-                      newUi[definedUiSchemaKey] = oldUi[definedUiSchemaKey];
-                  });
-                  onChange(newDefinitions.properties, newUi);
-                },
-                definitionData: definitionSchema,
-                definitionUi: definitionUiSchema,
-                categoryHash,
-              });
-            } else if (choice === 'section') {
-              addSectionObj({
-                schema: { properties: definitionSchema },
-                uischema: definitionUiSchema,
-                onChange: (newDefinitions, newDefinitionUis) => {
-                  const oldUi = newDefinitionUis;
-                  const newUi = {};
-
-                  Object.keys(oldUi).forEach((definedUiSchemaKey) => {
-                    if (
-                      !['definitions', 'ui:order'].includes(definedUiSchemaKey)
-                    )
-                      newUi[definedUiSchemaKey] = oldUi[definedUiSchemaKey];
-                  });
-                  onChange(newDefinitions.properties, newUi);
-                },
-                definitionData: definitionSchema,
-                definitionUi: definitionUiSchema,
-                categoryHash,
-              });
-            }
-          }}
-          hidden={
-            !!definitionSchema && Object.keys(definitionSchema).length !== 0
-          }
-        />
+        {!hideAddButton &&
+          mods?.components?.add &&
+          mods.components.add(addProperties)}
+        {!mods?.components?.add && (
+          <Add
+            tooltipDescription={((mods || {}).tooltipDescriptions || {}).add}
+            addElem={(choice: string) => {
+              if (choice === 'card') {
+                addCardObj(addProperties);
+              } else if (choice === 'section') {
+                addSectionObj(addProperties);
+              }
+            }}
+            hidden={hideAddButton}
+          />
+        )}
       </div>
     </div>
   );