Welcome to <Form.io> !
Before you begin building your first Progressive Web application on <form.io>, it is beneficial to understand the underlying concepts of how <form.io> works. While this platform provides a very simple and easy to use form builder interface, there are many unique developer features to it that enable it to address customized business process applications, and complex data management applications. Because of this, it can be integrated into a wide variety of enterprise-class platform applications spanning across many different industry sectors. Spending the time to gain a deeper understanding of how to utilize the many features and capabilities of the platform is the best way to position yourself to utilize this powerful platform to its fullest potential.
While this next generation of the web has been positive for a number of reasons, it did however, create a gap in the web development industry where building data driven form based applications became a significant challenge. Form.io was created to fill this gap, by creating a platform that bridges the client based applications with backend services, through a common connective tissue found in every data driven application. Forms.
Now that we have an idea of how Form.io works, let's learn about the most important fundamental concepts of the Form.io platform, Forms and Resources.
At the heart of the Form.io platform, is the ability for web application developers to create the Resources and Forms for their application using our simple drag-and-drop form builder.
Using the form builder to create a new Resource called "Employee"
While Resources and Forms share the same structure and form building process, they are distinctive from one another in how they are utilized. It is important to understand what they are, how they are used, and also what makes them different so that you can construct your project with a structure that can support your Progressive application requirements. Resources and Forms are defined as follows.
Resources are the "structured" data objects that support your application. Anything that has a static data structure can be defined as a Resource. For example, Users within your application have a data "structure" as follows, and therefore are considered Resources within Form.io.
Forms represent the "unstructured" data that is used to supplement a Resource. For example, a Customer Survey may have free-form questions (fields) like "Did you enjoy your visit?", and those free-form fields should be associated to the Customer who submitted it. In this example, a Customer Survey would be a Form that references the Customer Resource.
To help explain these concepts, let us provide a real world example.
Let’s suppose you are a developer responsible for building a multi-tenant Clinic patient onboarding application. In this application, each patient must fill out a form and will then be assigned a Physician. The Physician will only be given permissions to see the Patient information for the patients which he/she has been assigned.
In this example, we can easily identify the “structured” objects that would be used to construct a working application. Each of these objects may relate to one another, but should be stored as individual database collections (or tables). These “structured” objects would be defined as the following Resources.
The person who needs to be seen by a Physician
The person who is going to be assigned a Patient.
The person who is responsible for collecting and managing the Patient information per Clinic.
Since this is a multi-tenant application, we would need the ability to have several Clinics managed by the applications.
This would be used as the entity used to assign a patient to the physician at a specific time (appointment). This would also be used to assign the "Patient Onboarding" form.
In this example, we also talked about “unstructured” data forms such as the Patient Onboarding Forms in which the Patient would need to create submissions and then be able to manage their data. These should be “unstructured” data collection mechanisms and must be capable of being flexible and in some cases created by the Clinic administrative person. These are your Forms
The Patient Onboarding form
Proof of Insurance PDF
A PDF of the proof of insurance
This will be the form that the Physician uses during the appointment
Form.io allows you to build a Progressive Web Application by consciously separating these two constructs to help you organize how the Forms and Resources can be used together to create a flexible and robust Data Management platform.
Technically Resources and Forms are the same thing. The simplicity and power of the Form.io platform treats them both the same from an API perspective, but they were separated to assist the developer to keep track of them as separate entities since they are used differently within the Progressive Web Application.
One major capability of Form.io is that it leverages an easy to drag-and-drop form builder to dynamically create the Forms and Resources for your application.
Drag and Drop Form Builder
Our form builder, however, is very special where instead of building an HTML form, it instead generates a JSON schema representation of the form or resource. A very simple example of what a schema looks like is as follows.
"label": "First Name",
"label": "Last Name",
By creating this schema, this form is now capable of being dynamically rendered within the Progressive Web Application (using Angular, React, etc), but is also used to automatically generate the REST API to support this form using the same JSON schema. This API can be viewed as follows.
Form.io Swagger 2.0 API Specification
For an example application that illustrates how the Form Builder works in creating JSON schemas, please go to the following site.
Once a form is submitted by the user, the data is sent to the API server where it is then processed through Actions. Everything from Sending Emails, Authentication, and even Saving the submissions in the database are configured through independent actions associated with the Form or Resource. Another way to think about actions, is that they serve as configurable middleware that can be attached to a Form, which perform tasks and data manipulation on the submission payload. Every Form and Resource can have an unlimited amount of Actions attached to them, and every action is sequentially executed in the order they are “stacked”.
Here is an example screenshot of the Actions associated with an Employee Application form, where we would like to Save their record, Send an email to an administrator of their registration, as well as send an email to the application, and then finally send that application information to an external CRM (such as Salesforce) for the application to then process.
Here is a list of some actions that can be executed on every Form or Resource.
- Email - Sending an email with the form information either to the person submitting the form or to a project administrator.
- Save Submission - Saves the submission payload to either this form, or forward it along to a Resource
- Login - Authenticate a user by generating a JWT token for the submission payload that was submitted.
- Webhook - Trigger a REST API call to an external system when an action is executed.
- Integrations - We offer a number of integrations that will send the form submission data to 3rd party providers.
- SQL Connection - Connect a form submission to an external SQL database including PostgreSQL, MYSQL, and MSSQL
For a more detailed walkthrough and examples into the Form Actions, please go to the Form Actions User Guide
The Form.io User Authentication system is very unique from other platforms. While other platforms have distinct User entities, and are managed within their own API and Database namespaces; Form.io is different in that a User is actually a Submission within a Resource form. This allows any Resource to define a structure of a User account, as well as have many different kinds of user models within your application. This becomes very useful if your data management application needs to keep track of multiple User models as well as manage the different ways in which users can be assigned access to other forms and submission data.
For a more detailed walkthrough and examples of User Authentication, please go to the User Authentication User Guide.
Every project within Form.io can provide custom Roles which users can be assigned when they authenticate into the platform. These roles can be used to categorize users based on what access they should have within the Data management functions of the API platform. Essentially, Form.io provides a way to create dynamic Roles, assign those Roles to Users, and then designate what Permissions each role should be allowed to do within the platform.
The Permissions a role has is configured on a per-form basis, which allow access control on who can perform certain functions on that form or submissions within that form. These permissions are based on CRUDI operations (Create, Read, Update, Delete, and Index), and are able to be associated to both Forms as well as Submissions. In addition, each permission is configured based whether a user is trying to perform those actions on their OWN records or other peoples records (ALL). In aggregate, this provides a total of 20 different permissions that can be configured on a per-form basis.
There are many ways that Form.io can be utilized, but the three most common deployments of Form.io are the following.
This is used if you wish to launch a single form that can be consumed and submitted by end users. For example, if you wish to create a single Registration form for a company event, you can launch a single form and send the "launch" url to people to submit.
This method is used if you wish to take a form created within Form.io and then embed this form within your own website.
This is the most common use case of Form.io. This method allows for you to build your own stand alone Progressive Web Application, and embed a number of forms within that application. This enables you to utilize the many framework wrappers that Form.io has available for frameworks such as Angular, React, and Vue to name a few.