Creating a React Component

Option 1 - Developing Remotely in VSCode (Recommended for Beginners)

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:

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

Make sure you've got Node.js 12 and yarn installed.
In your terminal, install @angular-devkit/schematics with:
```
yarn global add @angular-devkit/schematics-cli
```
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:

Run the schematic with:

schematics @formbird/schematics:react-component

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:

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
```
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
Navigate to the folder for the component and run yarn to install the node modules:
```
yarn
```
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
```
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
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:

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.

Formbird Services

DocumentModalService

This service can be added to scr/services/index.ts

export const documentModalService = (anyWindow.FormbirdServiceInjector).get('DocumentModalService');

and can be imported in the component file.

import { changedDocumentService, documentModalService } from '../services';

To view and edit a document in a modal, you can call documentModalService.openDocumentInModal(documentId) where first paramter is the documentId of document to be viewed. There is a second optional parameter called "options" documentModalService.openDocumentInModal(documentId, options). The options parameter should be an object and can be { unsavedDocumentList: formParameters.unsavedDocumentList }

If a new unsavedDocumentList is created, the modal can be made to save the document and any children in the modal on modal close. If the same unsavedDocumentListId as the main document is passed in, the document will be saved when the save button is clicked.

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:

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.
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.
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.	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