Skip to content

Creating a React Component

To start developing component without setting up prerequisites for local development, download and install VSCode from https://code.visualstudio.com/download and follow Starting Component Development to connect via ssh.

To learn react please go to https://reactjs.org/docs/getting-started.html or skip if you already have a background on react component development. It is suggested to try out the playgrounds linked to in the React documentation to get a feel for how React works before developing components in formbird.

Then you can proceed to create React Component with formbird schematics.

Option 2 - Developing Locally

Prerequisites

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

Creating a React Component

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

  2. In your terminal, install @angular-devkit/schematics with:

    yarn global add @angular-devkit/schematics-cli
    
  3. Install the formbird schematics with:

    yarn global add @formbird/schematics
    

React

Formbird allows components to be developed in React, which is a library that allows the development of fast and secure components that manage the updating of the look of the components when the data changes.

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 component that uses the Monaco editor at https://microsoft.github.io/monaco-editor/index.html

    After entering the component name, you will be prompted 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 a 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 a 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 production build with:

yarn build

Components for production should be built with this to make it faster. This creates an optimized 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 the spec folder ex. spec/JdMonacoEditor.spec.ts. Playwright is used as a testing framework which supports multiple browsers.

To create a test:

  1. Run 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 the 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 a 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 the 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