Skip to content

Creating a React Component

Prerequisites

Before developing React components, it's best to become familiar with the following:

  • npm - This is a collection of modules that can be installed in applications built using Node.js. It is described at https://www.npmjs.com/
  • the Yarn package manager: This installs modules from npm but https://yarnpkg.com
  • React - you can run through the tutorial at https://reactjs.org/tutorial/tutorial.html. You can also get a feel for React development using StackBlitz, at https://stackblitz.com/. This is good for creating simple test pages.

Creating a React Component

  1. Make sure you've got Node.js 12 and npm installed.

  2. Install @angular-devkit/schematics with:

    npm install @angular-devkit/schematics-cli -g
    
  3. Install the formbird schematics with:

    npm install @formbird/schematics -g
    

React

To generate a React component:

  1. Run the schematic with:

    schematics @formbird/schematics:react-component
    
  2. You will be prompted for the component name. Enter a hyphenated component name that is all lower-case, with the first section of the name being a prefix for your set of components. Formbird uses "sc" as a prefix for standard components, but third-parties can use a prefix for their company or project name to identify their own set of components. Choose a component name that is unique. Component names are hyphenated and have a prefix followed by the name of the component. The prefix is usually two letters but can be more and is named in a grouping of the components. This can be an abbreviation of the company name or another grouping of the components. For this example you can use your initials in the component name (Jordan D):

    jd-monaco-editor
    

    We have used a prefix of jd and called the component monaco-editor because we are going to develop a test compoennt that uses the Monaco editor at https://microsoft.github.io/monaco-editor/index.html

    After entering the component name, you will be promted for the library base path with 'https://fileshare.formbird.com/fb/react' as default and then a series of files will be generated:

    Component Name

    If you are working with local server and doesn't have fileshare access you can enter this path:

    vendor/custom-component-modules
    

    e.g.

    ? Enter the library base path? vendor/custom-component-modules
    
  3. Upload the following generated files through the formbird template editor:

    a) json/jd-monaco-editor.component.json - the component document for the component b) json/jd-monaco-editor.template.json - a simple test template that can be used to load the component in formbird

  4. Navigate to the folder for the component and run yarn to install the node modules:

    yarn
    
  5. Then build the component with:

    yarn watch
    

    This will build the component in watch mode, where any changes to the component code will cause the component to be rebuilt. Watch mode is useful when working on the component so you don't have to keep running the build command on every change. If you don't want to run the build in watch mode, Eg. if doing a one-off build, you can run the production build.

    If you are working with local server you need to copy the built component's directory to:

    server/public/vendor/custom-component-modules
    

    So from dist/jd-monaco-editor you copy this to

    server/public/vendor/custom-component-modules/jd-monaco-editor
    
  6. Load the component in formbird by reading the documentId from the template file that was uploaded in step 3a, at json/jd-monaco-editor.template.json:

    "documentId": "c6385ead-7b5c-458f-8421-ca017465bb1e",

    The url will be https://<'server-name'>/form/c6385ead-7b5c-458f-8421-ca017465bb1e . Eg. https://branch.formbird.com/form/c6385ead-7b5c-458f-8421-ca017465bb1e

  7. You should see a simple component with the following text:

    jd-monaco-editor works. Please edit src/components/JdMonacoEditor.tsx to make changes

    You can now edit the tsx file for the component, at JdMonacoEditor.tsx, to make changes. Try making a simple change to the JSX for the component at src/components/JdMonacoEditor.tsx like changing the text. You should see the following:

    Component Works

Tutorials

Creating a Production Build

You can run the prodcution build with:

yarn build

Components for production should be built with this to make it faster. This creates an optimised build of the component and should be used in testing at all stages after the initial development.

Appendices

Appendix A: Formbird Standard Variables

These are the variables you can use when developing a component.

javascript const JdMonacoEditor = ({ document, fieldValue, template, fieldName, formParameters, key, responsiveLayouts, message, componentDefinition }) => {

Variable Type Description
document object The current document in the form
template object The current template in the form
fieldName string The component's name
formParameters object Template Component's formParameters value
fieldValue any The component's value
responsiveLayouts object Core's responsiveLayouts value
message string Component's validation message
componentDefinition object Component's whole definition

Appendix B: Testing

A test file is generated during the creation of the component package. This can be found under spec folder ex. spec/JdMonacoEditor.spec.ts. Playwright is used as testing framework which supports multiple browser.

To create a test:

  1. Run the the create test script:

    yarn create-test
    

    This will display an empty browser and another window that contains the generated code. This will record your activity while testing the component.

    Recorder

  2. Enter the component test template's url ex.

    https://branch.formbird.com/form/c6385ead-7b5c-458f-8421-ca017465bb1e

    Perform the login and test the component.

    RecorderLogin

  3. Copy the generated code and paste it to the test file under spec folder and run:

    yarn test
    

    this will re-execute the activity you made in step 2. You can then add assertions to check if component is properly displayed. See assertions at https://playwright.dev/docs/assertions

    To know more about Playwright you can check https://playwright.dev/docs/intro/?_highlight=record#record-scripts

Appendix C: Troubleshooting

Problem Solution
No component displayed due to wrong libraryBasePath. NotFound This is a common error when working with a local server and libraryBasePath was set to https://fileshare.formbird.com/fb/react. Update the component's vendorLibraries and set the correct path ex. /vendor/custom-component-modules/jd-monaco-editor/dist/jd-monaco-editor.js