Enterprise Form Builder Module

Introduction

The Form.io Enterprise Form Builder Module is a form building and form management utility that is completely embeddable within an application. This decouples the form building and form management functions from application development. It is analogous to the function of the Form.io Developer Portal, however the Enterprise Form Build Module functions entirely within the application environment.

When the form builder and manager is deployed within an application through the Enterprise Form Builder Module, the module implements custom routing to attach any created forms to a project. The forms can then be managed both through with the module's own form management tools as well as by accessing that project through the Form.io Developer Portal.

The embedded form builder and manager experience can be customized to the application context. The components and functionality can be configured to limit form builders within the application to certain components or to customize the behavior of components.

The Enterprise Form Builder Module is a separately licensed module. It requires a unique library license separate from and in addition to the platform license. For information about purchasing a license, contact [e-mail]

Overview of Features

The Enterprise Form Builder Module supports a wide range of embedded Form.io Enterprise features, such as:

• Manage Forms: Create, List, Edit, and Delete forms.

• Form Edit conflict resolution: Multiple builders can safely modify the same form at once.

• Routing logic and guards: Prompt a form user with unsaved changes before navigating away from a modified form.

• Integrated Premium Components

• Custom Form Builder configurations

• Fully customizable components and route resolvers

Components and Modules

The Enterprise Form Builder provides pre-defined modules that serve as a scaffold for embedding form building and form management functions in an application. It accomplishes this by introducing the routing logic, resolvers, and components that are used for the common CRUD operations used when managing forms. For a complete list of modules, refer to the Components section of this document.

Getting Started

The Enterprise Form Builder Module exists entirely within an applicaation external to the Form.io Platform. The following section will describe the process of embedding the Enterprise Form Builder into an application.

Prerequisites

Before proceeding, ensure the following have been completed:

1. The Form.io Platform has been deployed and is operational.

2. A Project has been created that will be used to store forms created within the Enterprise Form Builder Module.

3. A library license for the Enterprise Form Builder Module has been issued.

4. A suitable application is available. This walkthrough uses the sample Angular application created in the Create an Application procedure in the Developer Guide.

The Enterprise Form Builder Module requires the NgModule method of Angular application structure.

When creating a new Angular application, provide the following configuration to ensure it uses the NgModule method:

ng new [appname] --standalone false --routing true

Install the Enterprise Form Builder Module into the App

1. Use one of the following terminal commands to install the @formio/enterprise-builder module into the application:

npm i --save @formio/js @formio/premium @formio/enterprise-builder

or

yarn add @formio/js @formio/premium @formio/enterprise-builder

1. Install the framework-specific libraries as follows:

Angular

npm i --save @formio/angular

or

yarn add @formio/angular

React

React is currently not supported.

1. Set the license key with the following code snippet:

import { Formio } from '@formio/angular';

Formio.license = 'yourLibraryLicenseKey';

Configure the Application

To configure the sample Angular application to use the Enterprise Builder Module, complete the following steps:

1. Create a configuration file in the format of EnterpriseBuilderConfig as shown below:

Angular

app.config.ts

import { EnterpriseBuilderConfig } from '@formio/enterprise-builder/angular';
export const AppConfig: EnterpriseBuilderConfig = {
  license: '-- ENTER YOUR LICENSE HERE --',
  baseUrl: 'https://forms.example.com',
  projectUrl: 'https://forms.example.com/myproject',
  tag: 'common'
};

React

React is currently not supported.

The following configurations can be provided to the Enterprise Builder Module:

Configuration Options

Property	Description	Example
license	The license for the Enterprise Form Builder module.
baseUrl	The URL for the Form.io Enterprise deployment.	https://forms.example.com
projectUrl	The Project URL to "mount" for form management within this application.	https://forms.example.com/myproject
tag	The tag to use when searching the forms in the Forms index.	common
icons	The icon class to use in the renderer.	bi - (for Bootstrap Icons)
config	An object of configurations to pass to the Formio.config SDK used to configure how the SDK operates.
showData	A boolean to enable the Submission management as part of the mounted form mangement routes and UI.	true - To show the submission management

1. Tell the application to use this configuration when mounting the module:

Angular

Set the FormioAppConfig service to use the extended EnterpriseBuilderAppConfig service, and then provide the ENTERPRISE_BUILDER_CONFIG token as follows:

app.module.ts

import { FormioAppConfig } from '@formio/angular';
import {
    EnterpriseBuilderAppConfig,
    ENTERPRISE_BUILDER_CONFIG
} from '@formio/enterprise-builder/angular';
import { AppConfig } from './app.config';

@NgModule({
    declarations: [...],
    imports: [...],
    providers: [
        ...,
        {provide: ENTERPRISE_BUILDER_CONFIG, useValue: AppConfig},
        {provide: FormioAppConfig, useClass: EnterpriseBuilderAppConfig},
        ...
    ]
})
export class AppModule {}

React

React is currently not supported.

1. Ensure that all styles added to the application are supported by the Enterprise Form Builder Module. By default, the Enterprise Form Builder Module supports Bootstrap 5. To change the CSS template, extend the components (documented further below). To enable Bootstrap, install it within the application as follows:

npm i --save bootstrap bootstrap-icons bootswatch

or

yarn add bootstrap bootstrap-icons bootswatch

1. Configure the application to use this theme with the following code:

Angular

src/styles.scss

@import "bootstrap/scss/bootstrap.scss";
@import "bootswatch/dist/cosmo/variables";
@import "bootswatch/dist/cosmo/bootstrap";
@import "@formio/js/dist/formio.full.css";
@import "bootstrap-icons/font/bootstrap-icons.scss";

This uses Bootswatch to offer multiple themes. Alter the theme by changing the word "cosmo" to the preferred theme.

React

React is currently not supported.

Once the configurations and styles in place, the next objective is to set up User Authentication within the application.

User Authentication

User authentication is required to support form management within a project. These steps will configure the project to have a User role that will manage the forms.

1. From the Developer Portal, open the associated project.

2. Navigate to Access, then click New Role under the list of existing Project Roles.

3. Enter the title Form Builder and click Create Role. Refer to Roles documentation for additional information.

1. Back on the Access page, configure permissions to add the Form Builder to the following Permission groups:

   1. Create All

   2. Read All

   3. Update All

   4. Delete All

1. Configure the Project to add these roles to the authenticated users group. Do this using the SSO configurations, or using Form.io Authentication. Either option requires modifying the User Login form to enable this authentication.

Once the Form.io project is appropriately configured, configure authentication within the host application. For this step, please follow the following instructions:

Angular

The documentation for setting up Authentication within an Angular application can be found at the Angular Authentication Documentation.

React

React is currently not supported.

With this route in place, application users can authenticate into the app and subsequently be authenticated into the Form.io Project with the appropriate privileges.

Application Alerts

Once Authentication is in place, the next objective is to bind the Enterprise Form Builder Module alert system with the host application. By default, the Enterprise Form Builder Module uses a base service for when certain alerts are triggered within the EnterpriseBuilderAlerts service.

Typically, each application will have its own "alert" notification systems. For example, an application may chose to use Toastr notifications with their applications when a notification is made. The Enterprise Form Builder Module provides a way to inject alerts generated by the Enterprise Form Builder Module into the host application's notification system. To do so, refer to the following example steps:

Angular

This example uses the ngx-toastr module to add Toastr notifications to the application.

1. Install the module with the following commands:

npm i --save ngx-toastr

or

yarn add ngx-toastr

1. Add the service to the module as follows:

app.module.ts

import { ToastrModule, provideToastr } from 'ngx-toastr';
...
...
@NgModule({
   ...
   imports: [
      ...
      BrowserAnimationsModule,
      ToastrModule.forRoot(),
      ...
   ],
   providers: [
      ...
      provideToastr(),
      ...
   ],
   ...
})
export class AppModule {}

1. Import the SCSS:

styles.scss

...
@import 'ngx-toastr/toastr';

1. Create a new wrapper Service for the EnterpriseBuilderAlerts service, like so:

ng g service app.alerts

1. Extend this service from the EnterpriseBuilderAlerts, and hook it into the ToastrService as follows:

app.alerts.service.ts

import { Injectable } from "@angular/core";
import { ToastrService } from "ngx-toastr";
import { EnterpriseBuilderAlerts, Alert } from '@formio/enterprise-builder/angular';

@Injectable({
    providedIn: 'root'
})
export class AppAlertsService extends EnterpriseBuilderAlerts {
    constructor(public toastr: ToastrService) {
        super();
    }

    override add(alert: Alert) {
        this.toastr[alert.level](alert.message, alert.title);
        super.add(alert);
    }
}

1. Provide this in the application as follows:

app.module.ts

import { EnterpriseBuilderAlerts, ... } from '@formio/enterprise-builder/angular';
import { AppAlertsService } from './app.alerts.service';
...
@NgModule({
    ...
    providers: [
        ...
        {provide: EnterpriseBuilderAlerts, useClass: AppAlertsService},
        ...
    ],
    ...
})
export class AppModule {}

Now, any alerts triggered by the Enterprise Form Builder Module will show within the host application alert system using the Toastr module.

React

React is currently not supported.

Mounting the Form Management UI

Next , "mount" the Form Management UI within the host application's routing system. This allows application users to navigate to a specific route within the application to see the Form Building UI provided by the Enterprise Form Builder Module. To do so, complete the following steps:

Angular

In Angular, use the @angular/router module for all routing for the Enterprise Form Builder Module. To accomplish this, complete the following steps:

1. Create a new Angular module that will encapsulate the forms module within the Enterprise Form Builder Module, using the following CLI command:

ng g module forms

1. Mount the FormRoutes in the RouterModule within the FormsModule using the following code:

forms/forms.module.ts

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { RouterModule } from '@angular/router';
import { 
  FormsModule as EnterpriseBuilderFormsModule,
  FormRoutes
} from '@formio/enterprise-builder/angular';

@NgModule({
  imports: [
    CommonModule,
    EnterpriseBuilderFormsModule,
    RouterModule.forChild(FormRoutes())
  ]
})
export class FormsModule {}

A later section will cover how all of the components at each route can be overridden and modified. For now, leave the defaults.

1. Mount this module within the routes using the app-routing.module.ts.

app-routing.module.ts

...
const routes: Routes = [
  {
    path: 'auth',
    loadChildren: () => import('./auth/auth.module').then(m => m.AuthModule)
  },
  {
    path: 'forms',
    loadChildren: () => import('./forms/forms.module').then(m => m.FormsModule)
  }
];
...

React

React is currently not supported.

With the Enterprise Form Builder Module in place, navigate to the "forms" path within the host application (after authenticating) to see the full Form Building and Management UI as follows:

Submission Management

By default, only the Form Management UI components are enabled. To enable the Submission management UI inside of this module, provide the following within the configurations:

Angular

app.config.ts

import { EnterpriseBuilderConfig } from '@formio/enterprise-builder/angular';
export const AppConfig: EnterpriseBuilderConfig = {
  license: '-- ENTER YOUR LICENSE HERE --',
  baseUrl: 'https://forms.example.com',
  projectUrl: 'https://forms.example.com/myproject',
  tag: 'common',
  showData: true
};

React

React is currently not supported.

Once enabled, the following UI is now available within each Form context:

If not data is visible, or the table is stuck loading, make sure that the appropriate submission read permissions are set within the form.

Components

The Enterprise Form Builder Module includes many different Components, mounted at different routes, that can be configured and overridden by the application embedding the module. The following components are included at the following routes:

The path of the route is determined by the host application; ":host" is used to indicate the path at which the module is mounted.

For example, if FormsModule is mounted at the "forms" path within the application, then the placeholder ":host" would be replaced with ":forms".

Component Overview

The following components are available. More detailed information about these components is included at the end of this document.

Component	Description	Route
FormsComponent	Provides the index of forms.	:host
FormBuildComponent	The component used to create a new form, that shows the form builder.	:host/build
FormComponent	The wrapper component for all child route components within the Form context. This provides the navigation UI for the "view", "edit" "delete", "settings" tabs for a specific form.	:host/:formId
FormViewComponent	The component used to view (or use) a form.	:host/:formId/view
FormEditComponent	Used to edit a form, allowing the builder to edit the current Form JSON.	:host/:formId/edit
FormDeleteComponent	Confirms and processes Form deletion.	:host/:formId/delete
FormChangesComponent	Notifies a form user that a form has been changed when they attempt to navigate away from the form context. It allows them to go back to the form context, or discard the form changes.	:host/:formId/changes
FormConflictComponent	Shown to the user when a form conflict is identified between the form being saved to the server, and the form that already exists on the server, indicating that someone has already made changes to the form.	:host/:formId/conflict
FormSettingsComponent	Provides an interface to allow a user to modify the metadata for the current form such as the title, name, path, tags, etc.	:host/:formId/settings
FormSubmissionsComponent	Provides a view of the submissions for a form.	:host/:formId/submission
FormSubmissionComponent	The wrapper component for a Form Submission. Provides the navigation UI for the other child components such as view, edit, and delete. It also provides a button for downloading the submission as a pdf	:host/:formId/submission/:submissionId
FormSubmissionViewComponent	The component used to view an existing submission within a form.	:host/:formId/submission/:submissionId
FormSubmissionEditComponent	Used to allow the user to edit an existing submission.	:host/:formId/submission/:submissionId/edit
FormSubmissionDeleteComponent	The component that provides an interface to the user to delete a submission.	:host/:formId/submission/:submissionId/delete

Overriding Components

Each component can be overridden when the Enterprise Form Builder Module is embedded within the application. The following process is an example of how to override one of the components for the framework:

Angular

To override the UI when a Form is being viewed, alter the FormViewComponent by extending it.

1. Create a new component within the form module using the CLI tool as follows:

ng g component forms/view

1. This component can now extend the Enterprise Form Builder FormsViewComponent as follows:

forms/view/view.component.ts

import { Component } from '@angular/core';
import { FormViewComponent } from '@formio/enterprise-builder/angular';

@Component({
  selector: 'app-view',
  templateUrl: './view.component.html',
  styleUrl: './view.component.scss'
})
export class ViewComponent extends FormViewComponent {}

1. Open a new browser tab and copy the existing HTML template found in the FormViewComponent by starting with the code available on the Form.io GitHub: https://github.com/formio/enterprise-builder/blob/main/projects/enterprise-builder/src/form/view/view.component.html
2. Paste the code in the overridden view.component.html like so:

forms/view/view.component.html

<div class="bg-body rounded shadow-sm p-2">
    <formio [src]="service.formUrl()" [form]="service.form"
            (submit)="onSubmit($event)" (error)="onFormError($event)"></formio>
</div>

1. Modify the component as needed, for example:

forms/view/view.component.html

<h3>{{ service.form.title }}</h3>
<div class="bg-body rounded shadow-sm p-2">
    <formio [src]="service.formUrl()" [form]="service.form"
            (submit)="onSubmit($event)" (error)="onFormError($event)"></formio>
</div>

1. Tell the Enterprise Form Builder Module to use the modified component instead of the default FormViewComponent. Do this in the Forms module, where FormRoutes is mounted. This function takes a configuration; provide the form view component as follows:

form/form.module.ts

...
import { FormioEmbedModule } from '@formio/angular/embed';
import { FormsModule as EnterpriseBuilderFormsModule, FormRoutes } from '@formio/enterprise-builder/angular';
import { ViewComponent } from './view/view.component';

@NgModule({
  imports: [
    CommonModule,
    FormioEmbedModule,
    EnterpriseBuilderFormsModule,
    RouterModule.forChild(FormRoutes({
      view: ViewComponent
    }))
  ],
  declarations: [
    ViewComponent
  ]
})
export class FormsModule {}

React

React is currently not supported.

Following a similar process, the following configurations can override any component within the Enterprise Form Builder Module:

FormRoutes({
    index: MyFormsComponent,                // extend FormsComponent
    build: MyFormBuildComponent,            // extend FormBuildComponent
    form: MyFormComponent,                  // extend FormComponent
    view: MyFormViewComponent,              // extend FormViewComponent
    edit: MyFormEditComponent,              // extend FormEditComponent
    delete: MyFormDeleteComponent,          // extend FormDeleteComponent
    changes: MyFormChangesComponent,        // extend FormChangesComponent
    conflict: MyFormConflictComponent,      // extend FormConflictComponent
    settings: MyFormSettingsComponent,      // extend FormSettingsComponent
    submission: {
        index: MySubmissionsComponent,      // extend FormSubmissionsComponent
        submission: MySubmissionComponent,  // extend FormSubmissionComponent
        view: MySubmissionViewComponent,    // extend FormSubmissionViewComponent
        edit: MySubmissionEditComponent,    // extend FormSubmissionEditComponent
        delete: MySubmissionDeleteComponent // extend FormSubmissionDeleteComponent
    }
})

Available Components

The following components are available:

• FormsComponent
• FormBuildComponent
• FormComponent
• FormViewComponent
• FormEditComponent
• FormSettingsComponent
• FormChangesComponent
• FormConflictComponent
• FormDeleteComponent
• FormSubmissionsComponent
• FormSubmissionComponent
• FormSubmissionViewComponent
• FormSubmissionEditComponent
• FormSubmissionDeleteComponent

FormsComponent

This component provides the index for the forms.

The FormsComponent UI

Route	:host
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/forms.component.ts
Template	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/forms.component.html

FormBuildComponent

This component is used to create new forms in your application.

The FormBuildComponent UI

Route	:host/build
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/build/build.component.ts
Template	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/build/build.component.html

FormComponent

The wrapper component for all child route components within the Form context. This provides the UI for the navigation to the "edit", "settings", etc for a specific form.

FormComponent UI

Route	:host/:formId
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/form/form.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/form/form.component.html

FormViewComponent

The component used to view (or use) a form.

FormViewComponent UI

Route	:host/:formId/view
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/view/view.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/view/view.component.html

FormEditComponent

The component used to edit a form providing the builder to edit the current Form JSON.

FormEditComponent UI

Route	:host/:formId/edit
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/edit/edit.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/edit/edit.component.html

FormSettingsComponent

Provides an interface to allow a user to modify the metadata for the current form in context such as the title, name, path, tags, etc.

FormSettingsComponent UI

Route	:host/:formId/settings
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/settings/settings.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/settings/settings.component.html

FormChangesComponent

The component shown to a user when a form has been changed and the user attempts to navigate away from the form context. It allows them to either cancel the navigation away, or cancel their form changes.

FormChangesComponent UI

Route	:host/:formId/changes
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/changes/changes.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/changes/changes.component.html

FormConflictComponent

This component is shown to the user when a form conflict has been identified between the form being saved to the server and the form that already exists on the server (meaning that someone has saved the form before the user saved their version).

FormConflictComponent UI

Route	:host/:formId/conflict
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/conflict/conflict.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/conflict/conflict.component.html

FormDeleteComponent

The component used to ask the user if they wish to Delete the form, and if they confirm, performs the deletion of the form.

FormDeleteComponent UI

Route	:host/:formId/delete
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/delete/delete.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/delete/delete.component.html

FormSubmissionsComponent

Provides an index of the submissions for a provided form context

FormSubmissionsComponent UI

Route	:host/:formId/submission
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/submissions/submissions.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/submissions/submissions.component.html

FormSubmissionComponent

The wrapper component for a Form Submission in context. Provides the navigation UI for the other child components such as view, edit, and delete.

FormSubmissionComponent UI

Route	:host/form/:formId/submission/:submissionId
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/submission/submission.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/submission/submission.component.html

FormSubmissionViewComponent

The view component to view an existing submissions within a form.

FormSubmissionViewComponent UI

Route	:host/form/:formId/submission/:submissionId
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/view/view.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/view/view.component.html

FormSubmissionEditComponent

The component used to allow the user to edit an existing submission.

FormSubmissionEditComponent UI

Route	:host/form/:formId/submission/:submissionId/edit
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/edit/edit.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/edit/edit.component.html

FormSubmissionDeleteComponent

The component that provides an interface to the user to ask them if they wish to delete a submission or not.

FormSubmissionDeleteComponent UI

Route	:host/form/:formId/submission/:submission/delete
Code	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/delete/delete.component.ts
Template HTML	https://github.com/formio/enterprise-builder/blob/main/angular/src/projects/enterprise-builder/src/form/submissions/delete/delete.component.html