For simplicity I’m going to demonstrate this with a brand new application created using create-react-app and will be using the Atlaskit package to render the forms (but remember that you have the choice of using other renderers or even provide your own).
PLEASE NOTE: This example only shows the creation of a form with a single field but to leverage the full capabilities of React Forms Processor you will want to define multiple fields with relationships between them. I haven’t shown the creation of a more complex example because this article focuses on how to import and use the components in an application — not on what forms you can build.
Create a new app
Start by creating a new React app…
Your browser of choice should automatically now display the basic application you’ve just started.
Import and use the components
Now open the project folder in the editor of your choice (in this example I’m using VSCode) and open the App.js file.
Update the source code to import Forms from react-forms-processor and renderer and FormButton from react-forms-processor-atlaskit.
Now add a Form component setting the imported renderer as the renderer prop. Add a FormButton component as a child of the Form component.
Build a new form using the GUI
Go to the Form Builder tab on online demo and use it to create the form of your choice. The Tutorial tab on the online demo provides examples of what capabilities are available — but one of the capabilities of the React Forms Processor is to be able to build relationships between fields in the form and you can do this through the Attributes tab for each field you add in the builder.
For each field you add there are 5 tabs:
- Basics (labels, descriptions, identifiers, etc)
- Options (for defining static options for fields that can use them — select fields, radio buttons, etc)
- Attributes (the visibility, requirement and disablement — including the ability to define rules that control them)
- Validation (to ensure the user enters the expected data)
- Advanced (controlling when data is included in the form value and how to handle multiple selection values)
To the right of the Form Builder you’ll see a preview of the form that you are defining. Underneath the Form Builder you’ll see the the JSON that defines the form you have created.
Pass the form definition to the component
Copy the JSON from the Form Builder into a new const in the App.js component and pass that const to the defaultFields prop of the Form component.
When you view the application in the browser you will see that the form you have defined has been successfully rendered.
You can capture the value of the form by passing a callback function to the onChange prop of the Form component or you can handle the user submitting the form by passing a callback function to the onClick prop of the FormButton component.
This will allow you to either immediately respond to any changes or to handle changes when the user is happy with the data they’ve provided. Notice that the FormButton component is only enabled if all of the fields in the Form contain valid data — this information is automatically passed through the React context provided by the Form.
Instead of passing the JSON definition to the defaultFields prop of the Form component you can alternatively split the definition into multiple parts and pass each part to a FormFragment component.
FormFragment components can be placed anywhere within a Form component to allow complex layouts. You can see a good example of this in the Form Builder (that is itself rendered using React Forms Processor) — where fields for defining a form are split across several tabs (Basics, Options, Attributes, etc).
In this example fields are passed to separate FormFragment components that are placed in a column layout — what is important to note that they are part of the same form and relationships can be defined in fields in different fragments.
Hopefully this should give you a good overview of how to import and use React-Forms-Processor components in your application. In my next post I’ll aim to provide some real-world examples of use cases that you can easily implement.
In the meantime I would be really grateful to anyone who is able to try it a spin and let me know what they think — any and all feedback is really appreciated!