Add ability to customize form section tooltips and Form Name and Form Description labels. Add ability to hide form head.

raymond-lam · raymond-lam · commit 9842ec238afc · 2021-03-03T09:36:24.000-05:00
diff --git a/docs/Mods.md b/docs/Mods.md
@@ -1,16 +1,12 @@
-# Plugins
+# Mods
 
-Plugins allow the definition of custom input types. The documentation on the [Background](Background.md) of the Form Builder lists the set of input types supported by default, but for different use cases, the `FormBuilder` may be more useful to Form Builders if certain custom types can be inserted. This allows, for example, the definition of an input type that is associated with specific code in ui schema or data schema.
-
-One example is the `Time` input type - it is a string type element in JSON schema, but is associated with the `format: date-time` property in the data schema at all times. This means that whenever a `Time` Input type is defined by a form builder, it is rendered accordingly by whatever form rendering software is used (`react-jsonschema-form`, for example, renders this as an input line that only allows time value to be entered).
-
-Custom input types are encoded in exactly the same way the Default input types are encoded, and the Default input types are all available in the `default` directory [here](https://github.com/ginkgobioworks/react-json-schema-form-builder/tree/main/src/formBuilder/defaults).
+Mods provide for the customization of the Form Builder component, such as the definition of custom input types.
 
 ## Type Definition
 
 Flow type defintions are available via [flow-typed](https://github.com/flow-typed/flow-typed).
 
-Recall that the plugin input types are passed into `mods`, as a property called `customFormInputs`,into the `FormBuilder` (see [Usage](Usage.md)). The type definition is as follows:
+The type definition for Mods is as follows:
 
 ```react
 declare type Mods = {|
@@ -24,10 +20,20 @@ declare type Mods = {|
     cardDisplayName?: string,
     cardDescription?: string,
     cardInputType?: string,
+    cardSectionObjectName?: string,
+    cardSectionDisplayName?: string,
+    cardSectionDescription?: string,
+  |},
+  labels?: {|
+    formNameLabel?: string,
+    formDescriptionLabel?: string,
   |},
+  showFormHead?: boolean,
 |};
 ```
 
+`tooltipDescriptions` and `labels` describe how some of the labels and tooltips in the Form Builder are to be customized. `showFormHead` is a boolean which controls whether the top section of the Form Builder, which contains inputs for the Form Name and Form Description, are show. It is set to `true` by default.
+
 A single `FormInput` has a type definition as follows:
 
 ```react
@@ -81,7 +87,17 @@ declare type DataType =
 
 `cardModal` refers to the React component that appears inside the modal that appears when the form builder clicks on the pencil icon. This React component also receives the same `Parameters` object, which is explained in further detail in the *Parameters* section.
 
-## Matching Algorithm
+The `FormBuilder` component takes a prop `mods`, which is a `Mods` type object.
+
+## Custom Form Inputs
+
+The documentation on the [Background](Background.md) of the Form Builder lists the set of input types supported by default, but for different use cases, the `FormBuilder` may be more useful to Form Builders if certain custom types can be inserted. This allows, for example, the definition of an input type that is associated with specific code in ui schema or data schema.
+
+One example is the `Time` input type - it is a string type element in JSON schema, but is associated with the `format: date-time` property in the data schema at all times. This means that whenever a `Time` Input type is defined by a form builder, it is rendered accordingly by whatever form rendering software is used (`react-jsonschema-form`, for example, renders this as an input line that only allows time value to be entered).
+
+Custom input types are encoded in exactly the same way the Default input types are encoded, and the Default input types are all available in the `default` directory [here](https://github.com/ginkgobioworks/react-json-schema-form-builder/tree/main/src/formBuilder/defaults).
+
+### Matching Algorithm
 
 The `matchIf` array in a `FormInput` contains a series of `MatchType` objects, which represent different possible 'scenarios' that the `FormBuilder` may encounter when parsing a set of Data and UI Schema. The `MatchType` is defined as follows:
 
@@ -108,7 +124,7 @@ declare type MatchType = {|
 
 `enum` is a boolean that evaluates to true if the component has a property `enum` in the Data Schema.
 
-## Component Types
+### Component Types
 
 `cardBody` and `modalBody` are components whose props have a type of `CardBodyProps`:
 
@@ -135,3 +151,20 @@ declare type Parameters = {|
 
 It can hold any number of keys pointing to specific values. One common example is `parameters.default`, which stores the default value specified by the builder for this `FormInput`.
 
+## Tooltips and Labels
+
+By passing in alternative text to the `tooltipDescriptions` object of the `mods` prop, the text for various tooltips in the Form Builder can be customized:
+
+- `add` - The tooltip when hovering over the button to add a new element/section.
+- `cardObjectName` - The tooltip for the "Object Name" field for a form element.
+- `cardDisplayName` - The tooltip for the "Display Name" field for a form element.
+- `cardDescription` - The tooltip for the "Description" field for a form element.
+- `cardInputType` - The tooltip for the "Input Type" field for a form element.
+- `cardSectionObjectName` - The tooltip for the "Object Name" field for a form section.
+- `cardSectionDisplayName` - The tooltip for the "Display Name" field for a form section.
+- `cardSectionDescription` - The tooltip for the "Description" field for a form section.
+
+The text for the labels of a few of the inputs in the Form Builder can similarly be customized by specifying a `labels` object of `mods`.
+
+- `formNameLabel` - The label for the input for the name/title of the entire form.
+- `formDescriptionLabel` - The lable for the input for the description of the entire form.
diff --git a/docs/Usage.md b/docs/Usage.md
@@ -172,11 +172,11 @@ export default function Example() {
 
 ## Advanced
 
-### Plugins
+### Custom Form Inputs
 
 In addition to the default types of form inputs (Time, Checkbox, Radio, Dropdown, Short Answer, Long Answer, Password, Integer, Number, Array), custom form inputs can also be specified. These form inputs are defined in a JS object that is passed into the `FormBuilder` component (and the `PredefinedGallery` component if it's being used) as part of a `mods` property, which has a comprehensive type definition in [src/formBuilder/types.js](https://github.com/ginkgobioworks/react-json-schema-form-builder/blob/main/src/formBuilder/types.js) as `Mods`.
 
-#### Example Plugin
+#### Example Custom Form Input
 
 ```react
 const customFormInputs = {
@@ -266,10 +266,10 @@ export type Mods = {
 }
 ```
 
-The `customFormInputs` define the logic that translates abstract "Input Types" into raw data schema and ui schema. For more information about these "Plugin" input types, see the page [here](Plugins.md).
+The `customFormInputs` define the logic that translates abstract "Input Types" into raw data schema and UI schema. For more information about these Custon Form Inputs, see the page [here](Mods.md).
 
 The `tooltipDescriptions` allows an implementation of the `FormBuilder` that changes the tooltip descriptions that appear on hover over certain areas of the tool. The `add` popup appears when hovering over the plus buttons, the `cardObjectName` is the name of the back end name that appears in every card object input, the `cardDisplayName` allows rewriting the description of the display name tooltip, the `cardDescription` option allows overwriting the tooltip for the description, and the `cardInputType` allows setting a custom tooltip for the Input Type dropdown.
 
 ### 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.
+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.
diff --git a/flow-libdef/@ginkgo-bioworks/react-json-schema-form-builder_v1.x.x/flow_v0.92.x-/react-json-schema-form-builder_v1.x.x.js b/flow-libdef/@ginkgo-bioworks/react-json-schema-form-builder_v1.x.x/flow_v0.92.x-/react-json-schema-form-builder_v1.x.x.js
@@ -66,7 +66,15 @@ declare module '@ginkgo-bioworks/react-json-schema-form-builder' {
       cardDisplayName?: string,
       cardDescription?: string,
       cardInputType?: string,
+      cardSectionObjectName?: string,
+      cardSectionDisplayName?: string,
+      cardSectionDescription?: string,
     |},
+    labels?: {|
+      formNameLabel?: string,
+      formDescriptionLabel?: string,
+    |},
+    showFormHead?: boolean,
   |};
 
   declare type FormBuilderProps = {|
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -9,11 +9,11 @@ nav:
   - Installation: Installation.md
   - Background: Background.md
   - Usage: Usage.md
-  - Plugins: Plugins.md
+  - Mods: Mods.md
   - Contributing: https://github.com/ginkgobioworks/react-json-schema-form-builder/blob/main/CONTRIBUTING.md
   - Bugs: https://github.com/ginkgobioworks/react-json-schema-form-builder/issues
   - Repository: https://github.com/ginkgobioworks/react-json-schema-form-builder
 
 markdown_extensions:
   - toc:
-      permalink: true
+      permalink: true
diff --git a/src/formBuilder/FormBuilder.js b/src/formBuilder/FormBuilder.js
@@ -318,44 +318,58 @@ export default function FormBuilder({
           <li key={index}>{message}</li>
         ))}
       </Alert>
-      <div className={classes.formHead}>
-        <div>
-          <h5>Form Name</h5>
-          <Input
-            value={schemaData.title || ''}
-            placeholder='Title'
-            type='text'
-            onChange={(ev: SyntheticInputEvent<HTMLInputElement>) => {
-              onChange(
-                stringify({
-                  ...schemaData,
-                  title: ev.target.value,
-                }),
-                uischema,
-              );
-            }}
-            className='form-title'
-          />
+      {(!mods || mods.showFormHead !== false) && (
+        <div className={classes.formHead} data-test='form-head'>
+          <div>
+            <h5 data-test='form-name-label'>
+              {mods &&
+              mods.labels &&
+              typeof mods.labels.formNameLabel === 'string'
+                ? mods.labels.formNameLabel
+                : 'Form Name'}
+            </h5>
+            <Input
+              value={schemaData.title || ''}
+              placeholder='Title'
+              type='text'
+              onChange={(ev: SyntheticInputEvent<HTMLInputElement>) => {
+                onChange(
+                  stringify({
+                    ...schemaData,
+                    title: ev.target.value,
+                  }),
+                  uischema,
+                );
+              }}
+              className='form-title'
+            />
+          </div>
+          <div>
+            <h5 data-test='form-description-label'>
+              {mods &&
+              mods.labels &&
+              typeof mods.labels.formDescriptionLabel === 'string'
+                ? mods.labels.formDescriptionLabel
+                : 'Form Description'}
+            </h5>
+            <Input
+              value={schemaData.description || ''}
+              placeholder='Description'
+              type='text'
+              onChange={(ev: SyntheticInputEvent<HTMLInputElement>) =>
+                onChange(
+                  stringify({
+                    ...schemaData,
+                    description: ev.target.value,
+                  }),
+                  uischema,
+                )
+              }
+              className='form-description'
+            />
+          </div>
         </div>
-        <div>
-          <h5>Form Description</h5>
-          <Input
-            value={schemaData.description || ''}
-            placeholder='Description'
-            type='text'
-            onChange={(ev: SyntheticInputEvent<HTMLInputElement>) =>
-              onChange(
-                stringify({
-                  ...schemaData,
-                  description: ev.target.value,
-                }),
-                uischema,
-              )
-            }
-            className='form-description'
-          />
-        </div>
-      </div>
+      )}
       <div className={`form-body ${classes.formBody}`}>
         <DragDropContext
           onDragEnd={(result) =>
diff --git a/src/formBuilder/FormBuilder.test.js b/src/formBuilder/FormBuilder.test.js
@@ -18,6 +18,7 @@ describe('FormBuilder', () => {
     document.body.appendChild(div);
     const wrapper = mount(<FormBuilder {...props} />, { attachTo: div });
     expect(wrapper.exists('.form-body')).toBeTruthy();
+    expect(wrapper.exists('[data-test="form-head"]')).toBeTruthy();
   });
 
   it('renders the appropriate number of cards', () => {
@@ -140,4 +141,38 @@ describe('FormBuilder', () => {
     expect(mockEvent).toHaveBeenCalledTimes(1);
     mockEvent.mockClear();
   });
+
+  it('renders custom labels in the form head', () => {
+    const div = document.createElement('div');
+    document.body.appendChild(div);
+    const wrapper = mount(
+      <FormBuilder
+        {...props}
+        mods={{
+          labels: {
+            formNameLabel: 'test name label',
+            formDescriptionLabel: 'test description label',
+          },
+        }}
+      />,
+      { attachTo: div },
+    );
+    expect(wrapper.find('[data-test="form-name-label"]').text()).toEqual(
+      'test name label',
+    );
+    expect(wrapper.find('[data-test="form-description-label"]').text()).toEqual(
+      'test description label',
+    );
+  });
+
+  it('does not render the form head if showFormHead is false', () => {
+    const div = document.createElement('div');
+    document.body.appendChild(div);
+    const wrapper = mount(
+      <FormBuilder {...props} mods={{ showFormHead: false }} />,
+      { attachTo: div },
+    );
+    expect(wrapper.exists('.form-body')).toBeTruthy();
+    expect(wrapper.exists('[data-test="form-head"]')).toBeFalsy();
+  });
 });
diff --git a/src/formBuilder/Section.js b/src/formBuilder/Section.js
@@ -232,11 +232,19 @@ export default function Section({
             ) : (
               ''
             )}
-            <div className='section-entry'>
+            <div className='section-entry' data-test='section-object-name'>
               <h5>
                 Section Object Name{' '}
                 <Tooltip
-                  text='The key to the object that will represent this form section.'
+                  text={
+                    mods &&
+                    mods.tooltipDescriptions &&
+                    mods.tooltipDescriptions &&
+                    typeof mods.tooltipDescriptions.cardSectionObjectName ===
+                      'string'
+                      ? mods.tooltipDescriptions.cardSectionObjectName
+                      : 'The key to the object that will represent this form section.'
+                  }
                   id={`${keyName}_nameinfo`}
                   type='help'
                 />
@@ -255,11 +263,19 @@ export default function Section({
                 readOnly={hideKey}
               />
             </div>
-            <div className='section-entry'>
+            <div className='section-entry' data-test='section-display-name'>
               <h5>
                 Section Display Name{' '}
                 <Tooltip
-                  text='The name of the form section that will be shown to users of the form.'
+                  text={
+                    mods &&
+                    mods.tooltipDescriptions &&
+                    mods.tooltipDescriptions &&
+                    typeof mods.tooltipDescriptions.cardSectionDisplayName ===
+                      'string'
+                      ? mods.tooltipDescriptions.cardSectionDisplayName
+                      : 'The name of the form section that will be shown to users of the form.'
+                  }
                   id={`${keyName}_titleinfo`}
                   type='help'
                 />
@@ -280,11 +296,19 @@ export default function Section({
                 className='card-text'
               />
             </div>
-            <div className='section-entry'>
+            <div className='section-entry' data-test='section-description'>
               <h5>
                 Section Description{' '}
                 <Tooltip
-                  text='This will appear as gray text in the service request form'
+                  text={
+                    mods &&
+                    mods.tooltipDescriptions &&
+                    mods.tooltipDescriptions &&
+                    typeof mods.tooltipDescriptions.cardSectionDescription ===
+                      'string'
+                      ? mods.tooltipDescriptions.cardSectionDescription
+                      : 'A description of the section which will be visible on the form.'
+                  }
                   id={`${keyName}_descriptioninfo`}
                   type='help'
                 />
diff --git a/src/formBuilder/Section.test.js b/src/formBuilder/Section.test.js
@@ -33,6 +33,36 @@ describe('Section', () => {
     expect(wrapper.exists('.section-container')).toBeTruthy();
   });
 
+  it('uses mods.tooltipDescriptions', () => {
+    const div = document.createElement('div');
+    document.body.appendChild(div);
+    const wrapper = mount(
+      <Section
+        {...props}
+        mods={{
+          tooltipDescriptions: {
+            cardSectionObjectName: 'test object name',
+            cardSectionDisplayName: 'test display name',
+            cardSectionDescription: 'test description',
+          },
+        }}
+      />,
+      { attachTo: div },
+    );
+    expect(
+      wrapper.find('[data-test="section-object-name"] Tooltip').props()
+        .children,
+    ).toEqual('test object name');
+    expect(
+      wrapper.find('[data-test="section-display-name"] Tooltip').props()
+        .children,
+    ).toEqual('test display name');
+    expect(
+      wrapper.find('[data-test="section-description"] Tooltip').props()
+        .children,
+    ).toEqual('test description');
+  });
+
   it('calls the delete function on delete', () => {
     const div = document.createElement('div');
     document.body.appendChild(div);
diff --git a/src/formBuilder/types.js b/src/formBuilder/types.js
