search
RepositoryPortalJIRAElectron
githubEdit

ℹ️Forms

Dynamically generating forms with React and Sitecore JSS

hashtag
Creating the FormField

  1. Navigate to page http: //local.duke-energy.com:3000/home/products/outdoor-lighting/contact

    • This page calls the <SingleStepForm /> component in the layout json from Sitecore which have fields that look like this

      {
  componentName: 'ContentMain',
  content: [{
      uid: '',
      componentName: 'Single Step Form',
      dataSource: '',
      fields: {
          ModelJson: {
              value: '[ { "title":"Form Name", "fields":{ "Name":{ "label":"Form Name", "type":"input", "value":"Form Name", "name":"Name" }, "Id":{ "label":"Id", "type":"hidden", "value":"", "name":"Id" } }, "fresh":true }, { "title":"Text Input", "fields":{ "FormId":{ "label":"FormId", "type":"hidden", "value":"stepOne", "name":"FormId" }, "Name":{ "label":"Name", "type":"hidden", "value":"textinput", "name":"Name" }, "Id":{ "label":"Id", "type":"input", "value":"fixtureName", "name":"Id" }, "Label":{ "label":"Label", "type":"input", "value":"Fixture Selection", "name":"Label" }, "BackEndLabel":{ "label":"BackEnd Label", "type":"input", "value":"Fixture Selection", "name":"BackEndLabel" }, "Value":{ "label":"Default Value", "type":"input", "value":"", "name":"Value" }, "DefaultValueSource":{ "label":"Default Value Source", "type":"select", "value":[ { "value":"None", "selected":false, "label":"None" }, { "value":"cookie", "selected":true, "label":"Cookie" } ], "name":"DefaultValueSource" }, "DefaultValueKey":{ "label":"Default Value Source Key", "type":"input", "value":"fixtureName", "name":"DefaultValueKey"}]
          }
      }
  }]
}

  2. <SingleStepForm /> gets rendered via its composition file converts this JSS fields object as its props.

  3. <SingleStepForm /> checks to make sure that modelJson.value exists before parsing it from a string to actual json, creating the variable formModel.

    • fields.ModelJson ie: formModel contains data for every field and their props. It's an array of objects where each object contains information about that field. After parsing the JSS, formModel looks like this: (note - only a few fields are shown as an example here)

    [
  {
    "title": "Radio List",
    "fields": {
      "FormId": {
        "label": "FormId",
        "type": "hidden",
        "value": "stepOne",
        "name": "FormId"
      },
      "Name": {
        "label": "Name",
        "type": "input",
        "value": "Are you a customer requesting a single light for your yard or property?",
        "name": "Name"
      },
      "Label": {
        "label": "Label",
        "type": "input",
        "value": "Are you a customer requesting a single light for your yard or property?",
        "name": "Label"
      },
      "BackEndLabel": {
        "label": "BackEnd Label",
        "type": "input",
        "value": "Are you a customer requesting a single light for your yard or property?",
        "name": "BackEndLabel"
      },
      "GroupName": {
        "label": "Group Name",
        "type": "input",
        "value": "GroupName",
        "name": "GroupName"
      },
      "Value": {
        "label": "Default Value",
        "type": "input",
        "value": "",
        "name": "Value"
      },
      "Id": {
        "label": "Id",
        "type": "input",
        "value": "radiolist",
        "name": "Id"
      },
      "TooltipText": {
        "label": "Tooltip Text",
        "type": "input",
        "value": "",
        "name": "TooltipText"
      },
      "CustomValidationErrorMsg": {
        "label": "Custom Validation Err. Msg.",
        "type": "input",
        "value": "Please pick an option.",
        "name": "CustomValidationErrorMsg"
      },
      "AppearsOnFormConfirmation": {
        "label": "Appear on Confirmation",
        "type": "checkbox",
        "value": true,
        "name": "AppearsOnFormConfirmation"
      },
      "Required": {
        "label": "Required",
        "type": "checkbox",
        "value": true,
        "name": "Required"
      },
      "InputItems": {
        "label": "Items",
        "type": "radiolist",
        "value": "[{\"text\":\"Yes\",\"value\":\"Yes\"},{\"text\":\"No\",\"value\":\"No\"}]",
        "name": "InputItems"
      }
    },
    "fresh": true
  },
  {
    "title": "Section Header",
    "fields": {
      "FormId": {
        "label": "FormId",
        "type": "hidden",
        "value": "stepOne",
        "name": "FormId"
      },
      "Name": {
        "label": "Name",
        "type": "hidden",
        "value": "sectionhdr",
        "name": "Name"
      },
      "Label": {
        "label": "Label",
        "type": "input",
        "value": "Name & Address",
        "name": "Label"
      },
      "BackEndLabel": {
        "label": "BackEnd Label",
        "type": "input",
        "value": "Name & Address",
        "name": "BackEndLabel"
      },
      "Id": {
        "label": "Id",
        "type": "hidden",
        "value": "sectionhdr",
        "name": "Id"
      }
    },
    "fresh": true
  },
  {
    "title": "First Name",
    "fields": {
      "FormId": {
        "label": "FormId",
        "type": "hidden",
        "value": "stepOne",
        "name": "FormId"
      },
      "Name": {
        "label": "Name",
        "type": "hidden",
        "value": "FirstName",
        "name": "Name"
      },
      "Id": {
        "label": "Id",
        "type": "hidden",
        "value": "FirstName",
        "name": "Id"
      },
      "Label": {
        "label": "Label",
        "type": "hidden",
        "value": "First Name",
        "name": "Label"
      },
      "BackEndLabel": {
        "label": "BackEnd Label",
        "type": "hidden",
        "value": "First Name",
        "name": "BackEndLabel"
      },
      "Value": {
        "label": "Default Value",
        "type": "hidden",
        "value": "",
        "name": "Value"
      },
      "ValidationPattern": {
        "label": "Validation Rule",
        "type": "hidden",
        "value": "lettersWhiteSpace",
        "name": "ValidationPattern"
      },
      "TooltipText": {
        "label": "Tooltip Text",
        "type": "input",
        "value": "",
        "name": "TooltipText"
      },
      "CustomValidationErrorMsg": {
        "label": "Custom Validation Err. Msg.",
        "type": "hidden",
        "value": "Please enter a first name.",
        "name": "CustomValidationErrorMsg"
      },
      "AppearsOnFormConfirmation": {
        "label": "Appear on Confirmation",
        "type": "checkbox",
        "value": false,
        "name": "AppearsOnFormConfirmation"
      },
      "Required": {
        "label": "Required",
        "type": "checkbox",
        "value": true,
        "name": "Required"
      },
      "MinimumLength": {
        "label": "Min. Length",
        "type": "hidden",
        "value": "",
        "name": "MinimumLength"
      },
      "MaximumLength": {
        "label": "Max. Length",
        "type": "hidden",
        "value": "40",
        "name": "MaximumLength"
      },
      "Predefined": {
        "label": "Predefined",
        "type": "hidden",
        "value": "true",
        "name": "Predefined"
      },
      "ColumnWidth": {
        "label": "Column Width",
        "type": "select",
        "value": [
          {
            "value": "2",
            "selected": false,
            "label": "2"
          },
          {
            "value": "3",
            "selected": true,
            "label": "3"
          },
          {
            "value": "4",
            "selected": false,
            "label": "4"
          },
          {
            "value": "5",
            "selected": false,
            "label": "5"
          },
          {
            "value": "6",
            "selected": false,
            "label": "6"
          }
        ],
        "name": "ColumnWidth"
      }
    },
    "fresh": true
  }
]

  4. formModel then gets passed into createFormInit() to process all of this data into something more concise and manageable

const createdFields = useMemo(() => createFormInit(formModel, false), []);

  • The formModel array will get passed into parseFields()

  • parseFields() will then run each of the form objects that are inside the formModel through yet another and final parser, createForm(). It will then save these objects to a new array and filter out any nulls generated by createForm() and return this array back to <SingleStepForm />

  • This function uses a Typescript overload to determine the correct return type depending on which multi boolean is passed in

\

hashtag
Side note: Important info

  1. Since there is a lot of very important information missing from the fields.ModelJson, (input type, hidden fields, etc) from Sitecore we need a way to dynamically figure all of this out the best we can, with what we've been given. This is where mapping.ts comes in. This file contains 3 sections:

    • inputMap

      • inputMap is an object with field names as a key and their dataMap type as the value. These are basically fields that we've determined to be non-input type fields, such as select, checkbox, heading, etc... or fields that are hidden or unimportant

const inputMap: CFMappingType["inputMap"] = { alternatephone: "phone", "alternate_phone_#": "phone", captcha: "recaptcha", checkbox: "checkbox", checkbox_list: "checkboxGroup",

// ... };

  • regexMap

    • regexMap is an object with either a validationPattern name or input type as the key with the value being an object containing an error message and RegEx pattern to be used in validation

const regexMap: CFMappingType["regexMap"] = { email: { message: "Not a valid email format", value: /^[^\s@]+@[^\s@]+.[^\s@]{2,}$/, }, lettersWhiteSpace: { message: "Can only be letters and spaces", value: /^[a-zA-ZáéíóúüÁÉÍÓÚÜñÑ-]+(\s+[a-zA-ZáéíóúüÁÉÍÓÚÜñÑ]+)*$/, }, notSameDigits: { message: "Can only contain numbers", value: /^(\d)\d*(?!\1)\d+$/, },

// ... };

const { file, props } = dataMap[inputType];

const Component = loadable(() => import(src/components/Form/${file}));

  • Component: The React component that was dynamically imported

  • data: An object containing details about the field such as maxLength, minLength, placeholder, required, etc..

  • file: The name of the component that was dynamically imported

  • id: A unique id for each field since sitecore doesn't return usable id's

  • props: The props returned from the dataMap lookup along with the column width for each field

  • validations: Will either be null or an object that contains if it should show on the confirmation screen and the validationPattern if any

  1. <SingleStepForm /> then iterates through the createdFields array and will:

    • pass the props.columns value to <FieldWrapper /> to determine how wide the field should be in CSS

    • inside <FieldWrapper /> it will nest the dynamic <Component /> that was returned and will pass in some props, those are:

      • data: The data object returned from createForm()

      • errors: This is an object created by react-hook-form that contains key/value pairs of the field name and the error message

      • name: The name of the field from the data object. react-hook-form requires the name prop to exist at this point

      • props: The props object returned from createForm()

      • register: A function from react-hook-form that will eventually get passed all the way down to the input to be called on that input's ref. It has:

        • pattern: A regex pattern matching validation

        • required: A boolean or error message

        • validate: custom function that passes the field's value through a method that returns a boolean

hashtag
Inside the FormField

  1. Inside the /components/Form folder are all of the FormField components. These components are the default exports from each of these files such as <FormInput />

    • The purpose of these components is to take the createForm() generated props that were passed in via the <SingleStepForm /> and to 'normalize' them into simpler generic props for the <Input /> for example. Each file will have a Form[Input] component with its related Input component. This Input component will then be used in tests and storybook stories.

const FormInput = ({ data, errors, name, props, register, validations, }: FormInputProps) => {

const { mask, type } = props || {};

const { label = "", maxLength, required, toolTipText } = data;

const propData = { error: { hasError: Boolean(errors[name]?.message), errorMessage: errors[name]?.message, }, id: label, label, mask, maxLength, name, register, required, type, validations, };

hashtag
MultiStepForm

The <MultiStepForm /> is nearly identical to <SingleStepForm /> except that it has multiple steps to the form. Like <SingleStepForm />, the fields data will also get pushed to createFormInit() and from there to multiStepFormFields(). It's here that the fields will be parsed through parsedFields() and then afterwards they will be separated into an array that contains the <FormStepper /> fields first and then the fields for the first screen, second screen and so on. This array will look something like this:

When this array is finally returned back to <MultiStepForm>, the form stepper data is parsed out and passed into the <FormStepper /> component and the first array of field objects in the remaining array will be rendered out.

We need to map through the outer array first and then loop through each of the inner array's to render each of the fields. The fields that are not shown on the current step will get a class added to FieldWrapper as hidden, all of the other fields will get the class, block. Since react-hook-form tracks our inputs via a ref, its much easier to just build out all of the steps of the form at once and just hide/show the active fields via CSS. This way we don't lose the ref when the fields get mounted/unmounted from the DOM.

We also need to account for required fields that are now 'hidden' due to not being contained in the activeStep. This will cause an error in the browser saying that a required field is not focusable. We get around that by toggling the 'required' prop for that field depending on whether or not its currently in the activeStep

React | Typescript | Tailwind | Forms | Unit Tests

PreviousREADMENextReact

Last updated