Installation

Getting Started

The Enterprise Form Builder Module exists entirely within an application 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.

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:

npm i --save @formio/angular

yarn add @formio/angular

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:

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'
};

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

Configuration Options

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

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 {}

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:

@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";

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:

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:

npm i --save ngx-toastr

yarn add ngx-toastr

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

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

ng g service app.alerts

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);
    }
}

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

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:

ng g module forms

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 {}

...
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)
  }
];
...

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:

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
};

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

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:

Component Overview

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

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:

ng g component forms/view

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 {}

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

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

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

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.

FormBuildComponent

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

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.

FormViewComponent

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

FormEditComponent

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

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.

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.

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

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.

FormSubmissionsComponent

Provides an index of the submissions for a provided form context

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.

FormSubmissionViewComponent

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

FormSubmissionEditComponent

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

FormSubmissionDeleteComponent

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