User's Guide

Welcome to the <form.io> User Guide. Here you will find summary information regarding the main elements of our platform, and how you can use it to create your own applications. Let’s get started!

Intro

To best understand the <form.io> platform, and how you can use it to build your own applications, it is helpful to understand the major components of the <form.io> system. While there are many detailed elements and features, the major components of the <form.io> system are:

These major components are described below with additional information about how to use them.

User Portal Page

When a developer logs in to the <form.io> platform, they arrive on their own individual User Portal Page. This page is the main page and has a growing amount of general content for the developer. Here you can create a new project, manage existing projects, as well as manage your TEAMs.

Customer Applications

Whenever you see the word Application used within this User Guide, it is referring to the Application that developers are building outside of <form.io>.

<form.io> major components are created within the <form.io> system, and are ultimately used in customer Application implementations. It is important to distinguish a customer Application from the work being completing within <form.io>.

When developers are working within <form.io> to create major components for their customer Applications, we refer to that work as Projects.

Projects

Projects are the main working areas within the <form.io> platform used by developers to build the <form.io> major components that will ultimately be implemented within their own customer Applications. The <form.io> system enables developers to easily build a service for their iOS, Android, Windows apps, and websites that all interact with the same <form.io> major components.

Each Project is typically associated with a single corresponding customer Application.

When a developer begins work within the <form.io> platform, they typically begin by creating a Project. Each Project will contain all of the major components for the customer Application such as Forms, Resources, Roles, etc.

Creating New Projects

New Projects can be created from the User Portal home page. To get there from any part of the portal, Click “Projects” in the header.

At the top will be a blue banner that contains the buttons to create a project. You can either create a custom project or use an application template.

When choosing an application template, the project is immediately created and ready for editing and previewing. The title and description of the newly created project may be changed by going to the project settings on the left.

When creating a custom application, you will be presented with the options for creating a project.

Project Title

The Project Title is the name that will be used to identify and access a specific Project throughout the entire life of the Project. Keeping this in mind, a sensible Project naming convention should be utilized to clearly identify the Project as being associated with the corresponding customer Application in which it will be used.

Description

The Project Description can be up to 512 characters and may be comprised of any letters, numbers, spaces, or other special characters. This description is simply used for reference within the Project, and is not utilized elsewhere.

When done, click Create Project and your new project will be created.

Project Template

Project Templates are predefined templates that specify what Resources, Forms, and Actions to automatically create for you. You may select from one of our existing project templates, or upload your own. Templates can be created by exporting an existing project. For more information on templates, see the Project Templates section.

Project Dashboard

The Project Dashboard page shows users an overview of the Projects core elements, analytics, and information.

1 project overview

Here users can see their Project Title, the Current Plan their Project is on, the amount of Submission Requests the Project has accumulated for the current month, the Project’s API Endpoint, all Roles, Forms, and Resources used within the Project, any Teams that may be assigned to this Project, and a Submission Activity graph showing submission requests for the year, month, or day.

2 project overview - submission

Project Settings

Users can configure the settings for their Projects by clicking the Settings tab within the Project at the top right of the page. The Project settings are used to configure Actions. Project settings currently include:

  • General Settings
    • Here you can change the Title, Description of the Project, and CORS options.
    • Note: Be careful when changing the subdomain, as it will change the base path of all APIs for your project. Only do this if you really know what you are doing.
    • CORS
    • CORS Note: Here you can control which domains have access to make requests to your API. This setting will be sent with all API requests in the Access-Control-Allow-Origin header.
    • You can also export and delete a project from this page. Templates can be used to create a new project. See the Project Templates section for more info.
  • Roles (see the Roles & Permissions chapter separately)
  • OAuth
    • Here you can enter your Client ID and Client Secret for the OAuth provider of your choice. These will be used in the OAuth Action
  • Email Providers
    • Here you have the flexibility to use your existing email provider to manage your communications. Enter the email credentials for the email provider of your choice and click Save Settings when done. See the Email Action on how to use these email providers.
  • File Storage
    • Form.io does not store files for your applications. If your forms contain a file component, you will need to set up where those files get stored.
  • Data Connections
    • The Data Connections allow you to configure various integrations and their settings.
      • Databases
        • Here you can provide credentials to your Microsoft SQL Server or MySQL databases to be used with SQL Actions.
      • Office 365 (Settings to integrate with Outlook and other 365 applications, see Office 365 Integration Guide)
      • Hubspot
      • Atlassian
      • SQL Connector
        • Here you can enter the credentials for your formio-sql instance.

Teams

Teams functionality allows multiple developers to collaborate on the same projects. Project administrators can create teams, assign teams with permissions to projects and add users to those teams.

Teams are limited to projects with Team Pro and Commercial plans. If you do not have any projects with Team Pro or Commercial plans, you will not be able to create a team.

Creating a Team

To create a new Team, from the portal home page, click the Create Team button.

Give the team a name and assign user accounts to the team. Currently teams are limited to registered users of the site. You can add more team members later.

Adding Accounts To A Team

To add additional accounts to a team, go to the portal home page and click your team shown on the right. Team members must be registered Form.IO users.

Add more users to the team and click Save

Assigning Teams To A Project

To add a team to a project, make sure the project is upgraded to Team Pro or Commercial. Then from the portal home page, click the Add Team button on the project.

You will then be presented with a form to add a team to a project and assign a permission.

2 team project setting

Select which team you want to add and which permission. There are three options for permissions

  • Read - This will only allow the team to read form definitions

  • Write - This will allow the team to read and write form definitions.

  • Admin - This will give the team all permissions including reading and writing forms and access to all data.

You can assign multiple teams to a single project. All members of a team have the same permissions that were assigned to that team.

Roles and Permissions

Roles and Permissions are a very important and differentiating aspect of the <form.io> platform. They provide developers many capabilities that are required for enterprise applications that are not found in other form or API platforms.

Roles

A Role is a group of users that have a shared set of defined permissions with respect to submission data within an Application.

Some common example names of Roles used in enterprise applications include Administrator, Sales Agent, Registered User, Authenticated User, Anonymous User, and many, many more.

  • A Project may have an unlimited number of Roles defined within it.
  • Users within a Role share the same permissions.
  • Users within a Role inherit the permissions associated with that Role.
  • A User may be assigned to more than one Role.

<form.io> allows developers the ability to easily define Roles to control how a group of users access submissions within their Project. A site owner can manage the user access to such tasks as creating, updating or deleting submissions by assigning a user to a specific Role. These Roles have full access to the forms within the project, but are easily edited if needed in the future. This process will be discussed with more detail in the Permissions section of this User Guide.

Default Roles

When a new Project is created, three (3) Roles are created by default:

  • Administrator
  • Authenticated
  • Anonymous

The Anonymous Role is a special Role that defines access within an Application for a User that is not authenticated. For example, a user that visits your application that has not yet registered or is not logged in. The Anonymous Role can be renamed, but not removed.

Creating and Configuring Roles

To create and configure a Role, navigate to the Settings tab located within a Project at the top right corner of the page and then click the Roles button on the left side. Select the +New Role button to add a new Role, delete a Role by selecting the Trash Icon, and edit a Role name and description by selecting the Edit button.

When naming Roles, they are organized alphabetically and capital letters will be listed before lowercase letters. Staying consistent when naming your Roles will keep the Role list organized.

3 roles

Additional Roles can be defined and added to a project at any time. In the next section, we will discuss Permissions associated with Roles to define access to the submissions within your application.

When a Resource is accessed by a User, and the User has a Role assigned to them with permissions to complete an operation they are attempting, the operation will be granted. If no Roles are defined to permissions on a given Resource, only the owner of the Resource or the Application itself will have access to that Resource.

By default, the creator of a Project will have access to every Resource associated within the Application. To receive ownership of a Resource, that Resource must be created with the “Create Own” Permission, which will assign the User initiating the request to become its owner. Additionally, a user can be defined as the owner of a Resource if they are specified as such during a Create All operation.

Permissions

There are eight (8) Permissions for each core entity within the Form.io platform. The core entities are Projects, Forms, and Submissions. The following eight permissions available for each, and are assignable on a per Role basis; Additionally, all Roles and Permissions and are self contained within each Project:

  • Create All
  • Read All
  • Update All
  • Delete All
  • Create Own
  • Read Own
  • Update Own
  • Delete Own

These Permissions grant users certain functions and behaviors that can be applied to a role within a Project and corresponding Application. As a general rule of thumb, the _all permissions are usually granted to Administrative roles, where as the _own permissions are usually configured for end users to secure each users data.

Facts to consider with the following definitions:

  • The owner of a project has full control to do any action within their Project.
  • Forms are configured to allow all roles to access their definitions by default.
  • Submission access is disabled for every form by default. E.g. to enable anonymous submissions, you need to configure the Anonymous role to have create_own or create_all access in your specific form.
  • The update_all permissions for submissions, also grants the create_all permission for submissions within the same form.
  • The read_all Project permission is currently used for determining index access for Forms and Roles.
  • Only the Project owner can delete a Project.

Each of these basic Permissions are defined below:

Submission Permissions

(Defined within each Form)

  • Create All Submission

    • The Create All Permission will allow a user, with the given role, to create a Submission. The user creating the submission may assign ownership at creation time. (Default: None)
  • Read All Permission

    • The Read All Permission will allow a user, with the given role, to view any Submission made within the Form, regardless of who owns that Submission. (Default: None)
  • Update All Submission

    • The Update All Permission will allow a user, with the given role, to update any Submission made within the Form, regardless of who owns the Submission. Additionally this Permission allows the user to change the owner of any Submission. (Default: None)
  • Delete All Submission

    • The Delete All Permission will allow a user, with the given role, to delete any Submission made within the Form, regardless of who owns the Submission. (Default: None)
  • Create Own Submission

    • The Create Own Permission will allow a user, with the given role, to create a Submission. The user will be assigned as the owner of the submission. (Default: None)
  • Read Own Submission

    • The Read Own Permission will allow a user, with the given role, to read any Submission made within the form, where they are defined as the owner. (Default: None)
  • Update Own Submission

    • The Update Own Permission will allow a user, with the given role, to update any Submission made within the form, where they are defined as the owner. (Default: None)
  • Delete Own Submission

    • The Delete Own Permission will allow a user, with the given role, to delete any Submission made within the form, where they are defined as the owner. (Default: None)

Form Permissions

(Defined within each Form)

  • Read All Permission

    • The Read All Permission will allow a user, with the given role, to view the Form, regardless of who owns it. (Default: All Roles)
  • Update All Submission

    • The Update All Permission will allow a user, with the given role, to update the Form, regardless of who owns it. (Default: None)
  • Delete All Submission

    • The Delete All Permission will allow a user, with the given role, to delete the Form, regardless of who owns it. (Default: None)
  • Read Own Submission

    • The Read Own Permission will allow a user, with the given role, to read the Form, if they are defined as the owner. (Default: None)
  • Update Own Submission

    • The Update Own Permission will allow a user, with the given role, to update the Form, if they are defined as the owner. (Default: None)
  • Delete Own Submission

    • The Delete Own Permission will allow a user, with the given role, to delete the Form, if they are defined as the owner. (Default: None)

Project Permissions

(Defined within each Project)

  • Create All Permission

    • The Create All Permission will allow a user, with the given role, to create a new Project entity (Form or Role). The user creating the entity may assign ownership at creation time. (Default: Administrator)
  • Read All Permission

    • The Read All Permission will allow a user, with the given role, to view the Project definition. Note: Only Administrative users can view the Project Settings data. (Default: Administrator)
  • Update All Permission

    • The Update All Permission will allow a user, with the given role, to update the Project definition. Note: Only Administrative users can edit the Project Settings data. (Default: Administrator)
  • Delete All Permission

    • The Delete All Permission will allow a user, with the given role, to delete a Project entity (Form or Role), regardless of who owns it. (Default: Administrator)

Configuring Roles and Permissions

Once Roles have been created, there are a few different ways to configure and manage Roles/Permissions within your Project.

  1. Select Edit next to any role on your role Settings page:

    4 edit role

    This will give you a list of all forms or resources that hold the selected Role, along with their Permissions, within the entire project. Simply hit edit next to the form you want to configure and apply your changes:

    5 edit permission

    Now you can select the Roles you want to associate with each Permission.Remember to save any changes made:

    6 permission

  2. Assign permissions by clicking the Permissions button located at the top right of the page within a form or resource. Each permission may be assigned a role or more than one role, by clicking in the Roles field. After assigning roles to your Permissions, click the Save button at the bottom. Remember, you can always add, delete, and edit a role at anytime.

The Project owner will have all permissions to any Form and Resource submissions by default.

Role Assignment

Once Roles and Permissions have been configured, you can implement your configurations to a Resource or Form by adding an Authentication Action or a Role Assignment Action. To add an Action, click the Action tab on the top right of the page within a Form or Resource. Click the Select an Action button for a list of available Actions.

More information about the Authentication Action and Role Assignment Action can be found in the Actions Section.

Submission Resource Permissions

Submission Resource Permissions allow specific Resources (e.g. users), to access specific Submissions. A Resource with Resource Permissions may access a Submission without having Roles and Permissions configured for the Form, which the submission is a child of. Submission Resource Permissions are useful in a scenerio where access is needed, but for few members, which makes a new role less applicable.

There are three permission types for Submission Resource Permissions:

  • Read: The Resource(s) defined with access, may read all the contents of the given submission.
  • Write: The Resource(s) defined with access, may read all the contents of the given submission, and edit any information, with the exception of the Submission Resource Permissions and the owner property.
  • Admin: The Resource(s) defined with access, may read and edit all of the contents of the given submission.

Permission Assignment


Submission Resource Permissions can be configured on any Form with a resource select component. In the Form permission editor, Submission Resource Access will be available for configuration. For each permission, you will see a unique list of each resource select component within the current Form. Selecting any resource for one of the permissions, will grant any selected resources on a new submission, that specific access to the submission.

In the following example, the users resource select component is being assigned to the Read permission. On any following form submission, all of the selected users resources will be granted read access to that individual submission, regardless of the forms existing roles and permissions. The Submission Resource Permissions settings are configured on a per form basis, but the individual access is contained within each form submission.

Groups

Groups are collections of users which you want to share equal access, but the relationship doesn’t warrant the creation of a specific role. Group based permissions can be achieved with Submission Resource Permissions.

Note: Only users with edit access to a group can add users to the group itself.

Group Structure

Groups can be configured in three ways:

  • Groups and Users (Resources)
    • Add Users to groups on creation
  • Groups, Users, and GroupUsers (Resources)
    • Add Users to groups after creation
  • Groups, Users, PublicUsers, and GroupUsers (Resources)
    • Allows non-Administrative users to create and maintain groups of users.

The benefit of using a third and forth resource, PublicUsers and GroupUsers, is that they act like join tables and allow you to make groups at will. With four resources, you can safely allow non-administrative users to configure groups (selectively filtering sensitive data). Since non-administrative configuration is most commonly used, we will cover that here. Below are the following Required resources, their components, actions and any permissions, necessary for Groups to work; You may add any additional components and actions that you would like.

Note: Making a Group Resource, with a multi-select for users wont properly propagate the permissions, you must use the GroupAssignment Action for Group based permissions.

Users (Default Resource)

Components

  • Email (Email component)
  • Password (Password component)

Actions

  • Save Submission Action

Submission Permissions

  • Anonymous Users
    • create_own
    • read_own
    • update_own

Groups (Resource)

Components

  • Name (Text component)
  • Users (Select / Resource component -> GroupUsers)

Actions

  • Save Submission Action

Submission Permissions

  • Authenticated Users
    • create_own
    • read_own
    • update_own
    • delete_own

PublicUsers (Resource)

Components

  • User (Select / Resource component -> Users)
    • Each user should be able to read their own submission via the read_own permission.
    • Use the select fields to only grab each _id, and each email

Submission Permissions

  • Authenticated Users
    • create_own
    • read_all
      • Each user should be able to see all the submissions, so they can see the pool of users to add to their group.
    • update_own
    • delete_own
      • Allows a user to remove themselves from the pool of users available to assign to groups

GroupUsers (Resource)

Components

  • Group (Select / Resource component -> Groups)
  • User (Select / Resource component -> PublicUsers)

Actions

  • Save Submission Action
  • Group Assignment Action

Submission Permissions

  • Authenticated Users
    • create_own
    • read_own
    • update_own
    • delete_own

Making PublicUsers

The PublicUsers resource is important, because it allows you to proxy non-sensitive data from the User Resource into a separate Resource which is publicly available to your users.

PublicUsers can be created programmatically or by each user, with benefits for each. If you choose to do it within your app, then you can make all users available for group access. If you choose to make each users enable it, then it can be a premium feature, or you can allow users to turn their group access off.

Without the PublicUser resource, then groups are dependent on Administrative users for configuration or you need to make your user table available to Authenticated users with read_all, which you don’t generally want to do!

Making GroupUsers

GroupUsers are the link between each Group and User. Through the GroupAssignment action, each group and user is linked together to share permissions on designated resources. To link a user to a group, the user submitting the form, must have edit access to the group, that is to say they must have a role with update_all/update_own or be assigned with write/admin permissions through resource submission permissions.

Assigning Group Access

To assign group access, you need to include a Group Select or Resource component in the Form where you would like to grant group access.

Note: You can hide this field during the form render if desired.

Once the Group resource has been attached to the form, the access settings for the form must be updated. In the form access page, use the Submission Resource Access panel to select your group component.

Once the Access is configured you may add group permissions to any new or existing submission to the form, by selecting the group which should have access (Enabling multiple will also work for multiple groups).

Resources

Resources are used to define an object within <form.io>. This is done by adding Form components to a Resource. Follow the same instructions for Forms when creating Resources. The Form components that are placed onto a Resource determine what the Resource object looks like.

The primary difference between Resources and Forms is that Resources can be embedded in other Resources and Forms while Forms cannot be.

Use Resources when you are creating a primary object that will be interacting within your system, such as a User, a Movie, or a Todo Item.

Forms

Forms are the primary interface within the system. Design a Form by dragging and dropping Form components onto the Form component area. Form components that are placed onto a Form will determine what that Form object looks like. You do not need to create an API before creating the Form. A compatible API will automatically be mapped out for you as you design your Form.

Creating a Form

Forms can be created from the Project home page. Get to this page by clicking on the Project name from the User Portal page or clicking the edit tab at the top right of the page while within the Project.

At the bottom of the list of Forms, click the New Form button to begin creating a Form.

7 create form

Title

Enter a title for your Form. This will help you identify it later.

Name

This is the machine name for your Form. It can only contain alphanumeric characters and will be automatically populate from the title you enter in camel cased (where the first word is lower cased and each subsequent word starts with a capital letter). Form Names can be changed if you do not wish to carry the Title. The Name field will be used when embedding the Form into your application.

API Path

The API Path is the endpoint for accessing the Form and Form submissions. Choose the endpoint you’d like to use.

Adding Form Components

Drag and Drop Form components on to your Form. See Form Components for more information on types of components and how to configure them.

Advanced Settings

Enter any settings desired in the advanced settings section. Currently custom submission URL is the only option for Advanced Settings. Saving a URL in this setting will send submissions to that URL instead of <form.io>. This is helpful if you want to handle the Form submissions within your own service or if you wish to pre-process the data before sending it to <form.io>. Use this only if you know what you are doing.

Editing a Form

Forms can be edited from the Project home page. Get to this page by clicking on the Project name from the User Portal.

In the list of forms, click the Edit button to start editing a form.

When you are done editing, click the Save button.

Deleting a Form

Forms can be deleted from the Project home page by clicking on the trash icon next to the form. You will be prompted to confirm the form deletion.

Deleting a form cannot be undone. Use caution.

Copy a form

There are many situations where you would like to copy an existing form into a new form within your project, or between projects. Because of the cross project nature of this operation, the best way to accomplish this is to use the Form.io Command Line tool. First install the command line using the following command in your command prompt.

npm install -g formio-cli

Once you have the command line installed, you will then need to create the form which will serve as the destination form. You do not need to add any components to this form, but just keep it blank since the copy command will populate the destination forms components. Once you have the destination form created, you will then use the formio copy form command to copy your forms using the following syntax.

formio copy form <source> <destination>

As an example, the following command will copy a from in project.

formio copy form https://myapp.form.io/source https://myotherapp.form.io/destination

Form Components

A Form component collects user data and serves as the display or user interface within the system. Form components define the type of widget that users will enter their data and will automatically add a property to the resource endpoint to interact with the Form component.

Adding a Form Component

To add a form component to a form, drag and drop the component from the left column into the desired location within the form.

Each new form starts with a submit button automatically added to it. This can be removed or edited as necessary.

7 drag component

Editing a Form Component

To edit a form component on a form, hover over the component and click the gear icon. You will then be presented with a settings form for the component.

8 edit component

The settings for a form component are different for each component type.

Textfield

A textfield can be used for short and general text input. There are options to define input masks and validations, allowing users to mold information into desired formats.

9 textfield edit settings

Label

The name or title for this component.

Placeholder

The placeholder text that will appear when this field is empty.

Input Mask

An input mask helps the user with input by ensuring a predefined format. For a phone number field, the input mask defaults to (999) 999-9999.

  • 9: numeric
  • a: alphabetical
  • *: alphanumeric

Example telephone mask: (999) 999-9999

See the jquery.inputmask documentation for more information.

Prefix

The text to show before a field. An example is ‘$’ for money

Suffix

The text to show after a field. An example would be ‘lbs’ for weight.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Multiple Values

If checked, multiple values can be added in this field. The values will appear as an array in the API and an “Add Another” button will be visible on the field allowing the creation of additional fields for this component.

Unique

If checked, this field will be enforced as unique for this form. Submissions will be checked to see if an existing value matches. This validation is currently server side only.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by viewing the form submissions.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

10 validation

Required

If checked, the field will be required to have a value upon submission.

Minimum length

The minimum number of characters required to be entered for this field.

Regular Expression Pattern

The regular expression pattern test that the field value must pass before the form can be submitted. See regex101.com for help with writing regex expressions.

Custom Validation

You can use javascript to perform validation on a field. The way to respond is by setting the valid variable. If it is set to true then the validation passes. If you set it to a string, the validation fails and the validation message is set to whatever the valid variable is set to.

In addition, input variable is set to the value that has been entered in the field. The component variable is set to the definition of the field.

You can also reference other resources and properties for validation. For example, if there is a user resource with a password field, you can use its value with user.password

Button

Buttons can be added to perform various actions within the form.

11 button

Label

This is the label or title that will appear on the button.

Action

This is the action that will be performed. Currently there are two actions that can be performed, submit and reset.

Submit

A submit action submits the form to either the form.io server or a custom callback url that has been priorly set up.

Reset

Reset the form fields back to their original state.

OAuth

Opens an OAuth authentication popup. This will only work after it has been assigned to an OAuth Action. See the OAuth guide for more information on how to set up OAuth in your project.

Theme

Set a theme (color) for the button. These options currently map to Bootstrap classes that will be added to the button.

Size

Set the size of the button. These options currently map to Bootstrap classes that will be added to the button.

Left Icon

If you have an icon library and would like to include an icon to the left of the button label, you can do so by adding the icon class here.

Right Icon

If you have an icon library and would like to include an icon to the right of the button label, you can do so by adding the icon class here.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Block

If checked, the display of the button will be set to “block” which will cause it to span the full width of the container.

Disable on Form Invalid

If checked, this button will be disabled if any of the client side validation fails. This is useful for preventing the submission of a form that has invalid data entered.

Content

Content may be added to a form to provide non-field information. For example, if you need instructions at the top of a form that are for display only, use a Content component. There are no settings for a Content component and the value is not submitted back to the server.

A WYSIWYG editor has been provided to help with formatting the content. If you use the HTML view of the editor, note that all unsafe HTML is stripped before rendering to prevent cross-site scripting exploits. This includes tags like <script>, <embed>, and <style>, and attributes like onmouseover or onload.

Custom

Custom components allow creating a form field with a custom JSON schema that can be rendered as anything within a frontend application. This is usefully for special or complex form fields that don’t already exist in form.io. Using this type, any kind of field can be created.

To use a custom component, create a JSON definition of the field with the information needed to render it. Create a custom field and paste the JSON object into it. This must be a valid JSON object.

{
  "type": "custom",
  "isNew": true,
  "key": "custom",
  "protected": false,
  "persistent": true
}

There are several properties that are required but you may add any additional properties that you would like.

Type

The type property will be used to select which component to render on the frontend. It cannot be an existing field type.

Key

The key field is where the data will be saved to. This must be unique per field. For example, if key = 'customers' then the value of the field will be saved in data.customers.

Persistent

This will determine whether or not the value is saved to the main database. This is useful for using Remote Middleware, verify password fields or sending the data in an action but not saving it.

Protected

This will determine whether or not the field will be visible from the API. If it is a protected field then it will only be writeable but not readable.

Rendering

In order to render the custom component, the frontend application must register the component template. This is done in the config step with the formioComponentsProvider.

app.config([
  'formioComponentsProvider',
  function (formioComponentsProvider) {
    formioComponentsProvider.register('checkmatrix', {
      title: 'Check Matrix',
      template: 'formio/components/check-matrix.html',
      settings: {}
    });
	}
]);

The template will then be used to render the component. In addition, a controller may be added to the template to create more interactive form elements.

This is a working example of a custom component. It is a Matrix checkbox that changes the number of columns and rows based on two other form fields.

Email

The email component is nearly identical to the text field component. The Email component has a custom validation setting that, if set up correctly, can ensure the value entered is a valid email address. The email component can also more easily be integrate into a form’s email action. Use this component when you want an email address field for your form.

Realtime Email Validation using Kickbox.io

In addition to the normal email format validation, we are excited to bring real-time Email validation through our integration with Kickbox.io. For more information on how this works, please checkout the Kickbox Integration section.

File

A file field allows users to upload and download files to a form. In order to use a file field, file storage must be set up. This can be done from the project settings. See File Storage for the types of providers supported.

Form.io does not host any files itself. Files are stored on the storage provider which allows uploading and downloading files to and from it. Form.io only stores a reference to the files which allows seamless integration into your app.

12 s3

Label

The label for this field that will appear next to it.

Storage

This is the storage provider where the file will be stored and accessed from. Select the appropriate provider. All providers besides Url require additional configuration in project settings.

Upload Url

If Url is selected in Storage, enter the Url of the service. It must be compatible with the ng-file-upload service and return an object that includes the url to access the file.

Directory

This field will append all files with the string so that they are in a directory on the storage provider. Must end in “/”.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Multiple Values

If unchecked, only one file per field is allowed. If checked, multiple are allowed.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by going to the submissions for a form.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

Image

Images within Form.io are created on the Form using the File component, which is capable of uploading images.

Displaying the images, however, is done within the implementation of the application retrieving the data. As an example, here is an Angular directive which illustrates how an image can be loaded within a <img> tag within your application dynamically from the file component on the form.

Hidden

A hidden field can be added to a form to create a resource property that can be custom set in the form. You can use javascript to set the value on the client side and when the form is submitted the value will be set on the resource. There is no front end widget for hidden fields.

13 hidden

Name

The name for a hidden field is not displayed on the client side and is used for administration purposes only. The name is used to generate the automatic property name but this can be changed on the API tab on the component settings modal.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Unique

If checked, this field will be enforced as unique for this form. Submissions will be checked to see if an existing value matches. This validation is currently server side only.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by going to the submissions for a form.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

HTML Element

An HTML Element component may be added to a form to display a single HTML element. This is useful if you wish to quickly insert and configure some HTML in your form. All unsafe HTML is stripped before rendering to prevent cross-site scripting exploits. This includes tags like <script>, <embed>, and <style>, and attributes like onmouseover or onload.

If you wish to insert more complicated HTML in your form, see the Content component

HTML Tag

The name of the HTML tag to display.

CSS Class

The CSS class to add to the HTML element. You may specify multiple classes by separating them with single spaces.

Attributes

Attributes and their values to add to the HTML element. This is commonly used to add href attributes to <a> tags, or src attributes to <img> tags.

Content

The text content of the HTML element. While adding more child HTML tags here will properly display them, it is recommended you use the Content component to easily write and preview more complex HTML.

Password

The password field has the same options as a text field component. It differs from a text field in that its html <input> type will be password instead of text. This will cause the field to display asterisks instead of the value entered.

Radio

Radio form components should be used when presenting a list of options from which one should be chosen.

14 radio

Label

The label for this field that will appear next to it.

Values

These are the values that will be selected on this field. The Value column is what will be stored in the database and the Label is what is shown to the users.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Inline Layout

If checked, this field will layout the radio buttons horizontally instead of vertically.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by going to the submissions for a form.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

15 radio validation

Required

If checked, the field will be required to have a value.

Custom Validation

You can use javascript to perform validation on a field. The way to respond is by setting the valid variable. If it is set to true then the validation passes. If you set it to a string, the validation fails and the validation message is set to whatever the valid variable is set to.

In addition, input variable is set to the value that has been entered in the field. The component variable is set to the definition of the field.

You can also reference other resources and properties for validation. For example, if there is a user resource with a password field, you can use its value with user.password

Select

A select field will display a list of values in a drop down list to users. Users can select one of the values.

16 select

Label

The label for this field that will appear next to it.

Placeholder

The placeholder text that will appear before an option is selected.

Data Source Type

Select the type of data the options will be pulled from.

Values

These are the values that will be selected on this field. The Value column is what will be stored in the database and the Label is what is shown to the users.

Raw Json

Enter a JSON Array to use. It should be formatted as an array of objects with named properties.

URL

Enter a url with a data source in JSON Array format. This can be used to populate a Select list with external JSON values. For example, suppose you wish to populate your select drop down with a list of all States within the U.S. You can use an external JSON array like the following.

https://cdn.rawgit.com/mshafrir/2646763/raw/states_titlecase.json

And place that within the URL of the select drop down Data Source URL. You will then need to provide the Value Property as well as change the Item Template so that it will pull the right value as well as display correctly within the dropdown. The following image shows how the configuration would look for this particular setup.

Select URL JSON Source

This will now turn your select dropdown into a list of available States within the US.

Value Property

If Raw JSON or URL is selected, enter the name of the property on the objects that will contain the value that will be stored in the database.

Search Query Name

If URL is selected, enter the name of the search query parameter to filter requests with. Example, if your url is http://api.dogs.com/dogs, and this option is set to type, and the user types nice in the select field, then this component will send a request to http://api.dogs.com/dogs?type=nice and update the select items with the results. If this option is omitted, no new requests will be made when user enters text in the select field.

Item Template

If Raw JSON or URL is selected, use the template field to determine how the values will be displayed in the select box. You can use the item variable to access the current object in the array. For example, you can embed the value by using {{ item.value }} in a template.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Required

If checked, the field will be required to have a value.

Dynamic Select Filtering

A very common use case that many people have in forms is to dynamically filter a Select dropdown based on the selection of another select dropdown. The typicaly usecase is a form that provides the Make, Model, and Year of automobiles where when you select the Make dropdown, it filters the Model dropdown for those that are within that Make. This functionality can be achieved using the following method. We will use the Make, Model, Year as an example use case for this docs.

Step 1: Create a Make Resource to hold all of the vehicle makes. Create Vehicle Resource

Step 2: Create some Vehicle make records. Create Vehicle Makes

Step 3: Create a Model Resource to hold all of the vehicle models. Create Vehicle Model

Step 4: Create some Vehicle model records. Create Vehicle Model

Step 5: Create the Vehicle Resource to hold all of the vehicles. Create Vehicle Resource

with the following settings for Make:

Data Resource Type: Resource Resources: Make Value: Make

Vehicle Make Settings

and the following settings for Model

Data Resource Type: Resource Resources: Model Value: Model Refresh on: Make

Input a Filter Query: data.make={{ data.make }}

Vehicle Model Settings

Step 6: Create a bunch of records within Vehicle resource. Create Vehicle Records

Step 7: Create a new form called Vehicle Select Vehicle Select Form

Step 8: Add the Make dropdown with the following field settings.

Data Resource Type: Resource Resources: Make Value: Make

Make Field

Step 9: Add the Model dropdown

Data Resource Type: Resource Resources: Model Value: Model Refresh on: Make

Input a Filter Query: data.make={{ data.make }}

Model Field

Step 10: Add the Year dropdown

Data Resource Type: Resource Resources: Vehicle Value: Year Refresh on: Model

Input a Filter Query: data.make={{ data.make }}&data.model={{ data.model }}

Year Field

You are done! Your form now will dyanamically filter based on what is selected.

Text Area

A textarea has the same options as the textfield form component. The difference is that it will be a multi-line input field that allows for longer text.

Creating a WYSIWYG Editor

The textarea component can also be used to create a WYSIWYG editor within your application using the famous CK Editor. This works by enabling a hidden wysiwyg flag on the textarea component. Currently, there is not a UI to make this change, so this will require you to use our API’s to make that change. Using Postman, we can first get the form we want to modify as follows.

You can then copy the Body of the form, change the URL to a PUT command, and then paste the body into the payload while changing that paramter to “true” like the following.

The next thing you will need to do is to add the following libraries to your front-end Angular.js application.

bower install --save ng-ckeditor

You will then need to add both CKEditor and the ng-CKEditor libraries to the page as follows.

<script src="//cdn.ckeditor.com/4.5.8/standard/ckeditor.js"></script>
<script src="./bower_components/ng-ckeditor/ng-ckeditor.js"></script>

And then initialize it within your Angular application as follows.

angular.module('myApplication', [
    'formio',
    'ngFormioHelper',
    'ngCkeditor'
  ])

Once you do this, your TextArea will show up as a WYSIWYG editor!

Address

The address form component is a special component that does lookups for addresses entered. It can be entered in free form and will save the address as well as geolocation and other information.

17 address

Label

The label for this field that will appear next to it.

Placeholder

The placeholder text that will appear when this field is empty.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Allow Multiple Addresses

Allow multiple addresses to be entered into the field.

Unique

If checked, this field will be enforced as unique for this form. Submissions will be checked to see if an existing value matches. This validation is currently server side only.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by going to the submissions for a form.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

Required

If checked, the field will be required to have a value.

Check Box

A check box is a boolean value input field. It will either be on or off.

18 checkbox

Label

The label for this field that will appear next to it.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by going to the submissions for a form.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

19 checkbox validation

Required

If checked, the field will be required to be checked. If it is required, you may not need to persist the value as it can be assumed to be checked when a form was submitted or it will not submit.

Select Boxes

The Check Boxes form component works like the Radio component, but allows the user to check multiple values.

20 select box

Label

The label for this field that will appear next to it.

Values

These are the values that will be selected on this field. The Value column is what will be stored in the database and the Label is what is shown to the users.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Inline Layout

If checked, this field will layout the checkboxes horizontally instead of vertically.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by going to the submissions for a form.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

21 select box vali

Required

If checked, the field will be required to have at least one box checked. If it is required, you may not need to persist the value as it can be assumed to be checked when a form was submitted or it will not submit.

Custom Validation

You can use javascript to perform validation on a field. The way to respond is by setting the valid variable. If it is set to true then the validation passes. If you set it to a string, the validation fails and the validation message is set to whatever the valid variable is set to.

In addition, input variable is set to the value that has been entered in the field. The component variable is set to the definition of the field.

You can also reference other resources and properties for validation. For example, if there is a user resource with a password field, you can use its value with user.password

Date/Time

Date/Time form components can be used to input dates, times or both dates and times.

22 date time

Label

The label for this field that will appear next to it.

Default value

The default value for the date component. You can put new Date(); for the current date or use a few of Moment.js functions to set the date to a specific date. For example: moment().add(50, 'days').calendar(); You can use the add or subtract function to go forward or backwards in dates.

Placeholder

The placeholder text that will appear when this field is empty.

Date Format

The format for displaying this field’s date. The format must be specified like the AngularJS date filter.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by going to the submissions for a form.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

23 date

Enable Date Input

If this is checked, dates can be entered for this field.

Initial Mode

When the date picker appears, this sets the initial view of the picker.

Minimum Date

A value of the date that this field’s value must be after.

Maximum Date

A value of the date that this field’s value must be before.

Starting Day

On the calendar, select the day of the week that should start the week. In Europe this is typically Monday and in the US this is typically Sunday.

Minimum Mode

Limit the datepicker modes to a minimum of this value.

Maximum Mode

Limit the datepicker modes to a maximum of this value.

Maximum Years Displayed

The maximum number of years to display in the datepicker.

Show Week Numbers

If this is checked, when in Day mode, the datepicker will display the week number on the left hand side of the datepicker.

24 time

Enable Time Input

Allow entering a time as part of this field.

Hour Step Size

The number of hours to increment/decrement in the time picker.

Minute Step Size

The number of minutes to increment/decrement in the time picker.

12 Hour Time (AM/PM)

If checked, time will be displayed in 12 hour (am/pm) time. If not checked, it will appear in 24 hour time.

Read Only Input

If checked, users cannot directly enter a time. They can only use the increment/decrement controls to change the time. If unchecked, users can directly enter time values.

26 date time vali

Required

If checked, the field will be required to have a value.

Custom Validation

You can use javascript to perform validation on a field. The way to respond is by setting the valid variable. If it is set to true then the validation passes. If you set it to a string, the validation fails and the validation message is set to whatever the valid variable is set to.

In addition, input variable is set to the value that has been entered in the field. The component variable is set to the definition of the field.

You can also reference other resources and properties for validation. For example, if there is a user resource with a password field, you can use its value with user.password

Number

Number fields should be used whenever a field should be limited to a type of number.

26 number

Label

The label for this field that will appear next to it.

Placeholder

The placeholder text that will appear when this field is empty.

Increment (Step)

If set, the number field will be required to be an increment of this number. For example, if Increment is set to 5, possible values would be 0, 5, 10, 15, etc.

Prefix

The text to show before a field. An example is ‘$’ for money

Suffix

The text to show after a field. An example would be ‘lbs’ for weight.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Multiple Values

If checked, multiple values can be added in this field. The values will appear as an array in the API and an “Add Another” button will be visible on the field.

Table View

If checked, this value will show up in the table view of the submissions list.

27 number vali

Required

If checked, the field will be required to have a value.

Minumum Value

If a number is entered, then the value input on the form must be greater than or equal to this value.

Maximum Value

If a number is entered, then the value input on the form must be less than or equal to this value.

Custom Validation

You can use javascript to perform validation on a field. The way to respond is by setting the valid variable. If it is set to true then the validation passes. If you set it to a string, the validation fails and the validation message is set to whatever the valid variable is set to.

In addition, input variable is set to the value that has been entered in the field. The component variable is set to the definition of the field.

You can also reference other resources and properties for validation. For example, if there is a user resource with a password field, you can use its value with user.password

Curreny

The Currency component should be used when a field should display currency amounts on a form. This component holds a numeric input mask that allows two decimal values and automatically adds commas as a user inputs a currency amount.

currency

Label

The name or title for this component.

Placeholder

The placeholder text that will appear when this field is empty.

Prefix

The text to show before a field. An example is ‘$’ for money

Suffix

The text to show after a field. An example would be ‘lbs’ for weight.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Multiple Values

If checked, multiple values can be added in this field. The values will appear as an array in the API and an “Add Another” button will be visible on the field allowing the creation of additional fields for this component.

Table View

If checked, this value will show up in the table view of the submissions list.

Phone Number

The phone number form component can be used to enter phone numbers in a form.

28 phone number

A textfield can be used for general text input that is shorter than a sentence. There are options to define input masks and validations so information can be molded into desired formats.

9 textfield edit settings

Label

The label for this field that will appear next to it.

Placeholder

The placeholder text that will appear when this field is empty.

Input Mask

An input mask helps the user with input by ensuring a predefined format. For a phone number field, the input mask defaults to (999) 999-9999.

  • 9: numeric
  • a: alphabetical
  • *: alphanumeric

Example telephone mask: (999) 999-9999

See the jquery.inputmask documentation for more information.

Prefix

The text to show before a field. An example is ‘$’ for money

Suffix

The text to show after a field. An example would be ‘lbs’ for weight.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Multiple Values

If checked, multiple values can be added in this field. The values will appear as an array in the API and an “Add Another” button will be visible on the field.

Unique

If checked, this field will be enforced as unique for this form. Submissions will be checked to see if an existing value matches. This validation is currently server side only.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by going to the submissions for a form.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

29 phone vali

Required

If checked, the field will be required to have a value.

Resource

A resource field allows users to reference other resources in your project. For example, if you have a Director resource and a Movie resource, you can add a resource field on the Movie to reference the Director.

30 resource

Label

The label for this field that will appear next to it.

Placeholder

The placeholder text that will appear when this field is empty.

Resource

Select the type of resource to reference. This must be an existing resource within your project.

Search Expression

A regular expression to filter the results with. If you don’t want to show all possible resources within the Resource type selected in Resource you can limit which ones will appear in the options by enter a Regular Expression.

Select Fields

Select which properties on the resource to return as part of the options. Select whichever fields you want to display in the template.

Search Fields

A list of search filters based on the fields of the resource. See the Resource.js documentation for the format of these filters.

Item Template

How an item should appear in the list. Use {{}} brackets to reference variables to display. Be sure to use “Select Fields” above to select the fields to display.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Allow Multiple Resources

If checked, more than one value will be allowed to be entered.

Table View

If checked, this value will show up in the table view of the submissions list.

Signature

A signature field is a special field that allows someone to sign the field with either their finger on a touch enabled device or with the mouse pointer. This signature will be converted into an image and stored with the form submission.

31 signature

You can enter a short instruction here.

Width

How wide the signature area should be. This can be in pixels or percents.

Height

How high the signature area should be. This can be in pixels or percents.

Background Color

The Background color of the signature area. This can be an RGB value in RGB(255,255,255) format, a hex value like #000000 or the name of a color.

Pen Color

The pen color in the signature area. This can be an RGB value in RGB(255,255,255) format, a hex value like #000000 or the name of a color.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Table View

If checked, this value will show up in the table view of the submissions list.

Component API

Form components directly translate to a resource property on the API that is generated for the form. By default a property name is generated by camel casing the field title. You can change the property name by going to the API tab in the form component settings.

31 api path

Component Layout Settings

In addition to Layout Components, which are detailed in the next section of this guide, you can marginally change the arrangement of the components on your Form within the Layout settings. Each component allows for marginal layout changes from top, bottom, left, and right.

To change the layout, simply input a margin amount in the Top, Right, Bottom, or Left field. Components will be arranged accordingly depending on what margin field you input to. Set margins must be a valid CSS measurement input like “10px” in order to render properly.

layout

Conditional Components

The conditional component requires an API key to be configured to function correctly.


Any form component can use conditional logic to determine when to hide or display itself. The settings for a conditional field, are configured on the component itself, and can be found by viewing the Conditional tab within the components settings.

The conditional logic is based on the following rules:

  • Each field can hide or display.
  • The visibility is dependent on another component defined within the form.
  • The logic is activated when the configured field contains the plaintext value defined in the settings.

In addition to Simple Conditional logic, you can also use Advanced Conditional logic, which uses actual JavaScript for any combination of conditions.

JavaScript conditional logic requires you to set the value of show to either true or false. You have access to the current value of any form component via the data object, and the components API key. Advanced Conditional logic will only work, if Simple Conditional logic isn’t already defined.

When using Advanced Conditional logic with the select boxes form component, you must use the following syntax to get the value of the select box, which will always be true or false, depending on if it is checked or not: data.selectbox_component.selectbox_value


Calculated Value

Caclulated values allow calculating values based on the values in other fields of the form. Calculated values uses plain javascript and can return any value to the field. There are two variables available to calculate off of, data and row. data is the full data in the form. You can access values within it by using the field keys. For example data.myfieldkey. If you field is within a datagrid, there is an additional variable available of row which contains the values for that row of the datagrid. You can access the values the same as with data as row.myfieldkey. The values are also in data.mydatagrid[0].myfieldkey and data.mydatagrid[1].myfieldkey plus each additional row as the index.

Return the calculated value in the value variable and it will be set. Each time the form values change it will be recalculated. You do NOT need to watch form fields as you do for other custom logic in your form. It will automatically update.

It is very common to disable the field using calculated values.

Layout Components

Layout Components are used to change the general layout of the Form.

Columns

The Column layout component can be used to split any area into two columns. Simply drag and drop the Column button onto the form and the area you drop it on will be split in two.

Field Set

A fieldset can be used to create a title of an area of the form. This is useful to put inside Layout components or in between lots of related fields. This form component is display only and will not be saved to the api.

32 field set

Fieldset Legend

Enter the legend that will appear for the fieldset.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Panels

Panels are used to wrap groups of fields with a title and styling. These currently map to Bootstrap Panels.

33 panels

Panel Title

Enter the panel title that will be displayed at the top of the panel.

Theme

The theming of the panel. Select one of the options to have the class added to the wrapper div.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Table

The table component allows creating a table with columns and rows that allow adding additional components within it.

34 table

Number of Rows

The number of rows on the table. This can be adjusted at any time.

Number of Columns

The number of columns on the table. This can be adjusted at any time.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Striped

Whether or not the table is striped for odd and even rows.

Bordered

Whether or not the table has a border set on it. (This can be changed by your own CSS as well)

Hover

Whether or not to add a hover class on rows when the mouse hovers over them.

Condensed

Whether or not to condense the size of each sell by removing padding.

Well

Wells are wrapped in a div with a class. These currently map to Bootstrap Wells.

Container

A container is a wrapper around a set of fields similar to a fieldset. The major way they are different is the way that the data is stored. For most layout components field values are stored directly in the data of the submission.

For example, a fieldset with the following fields

firstName = First Name field lastName = Last Name field Would submit as { data: { firstName: “Joe”, lastName: “Smith” } }

However, with a container, the fields are put into an object with the container key. This is useful for creating more complex objects within your form.

For example, a container with the key user and the same fields above would submit as { data: { user { firstName: “Joe”, lastName: “Smith” } } }

Label

The name or title for this component. Here label is only display at the time of creating or editing a form to represent container while adding form elements to it. It will later disappear in live.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by going to the submissions for a form.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this value will show up in the table view of the submissions list.

Data Grid

Data Grids allow you to add multiple components on to a line item grid. Once components are in place, users can add multiple sets of these grids as they see fit. This is especially useful when needing the ability to add multiple sets of the same fields within a form.

data grid view

Label

The name or title for this data grid.

Add Another Text

Text that will display for the Add Another

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Striped

Whether or not the table is striped for odd and even rows.

Bordered

Whether or not the table has a border set on it. (This can be changed by your own CSS as well)

Hover

Whether or not to add a hover class on rows when the mouse hovers over them.

Condensed

Whether or not to condense the size of each sell by removing padding.

Protected

If checked, the fields in the data grid are for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by viewing the form submissions.

Persistent

If checked, the fields in the data grid will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Table View

If checked, this fields in the data grid will show up in the table view of the submissions list.

Existing Resource Fields

Existing Resource Fields allow components within your Resources to be reutilized in other Forms or Resources. Existing Resource Fields carry over component settings like validation and input masks you have already configured. Although the components settings are carried over, they do not link Forms or Resources in any other way.

Each Resource within your project will display when the Existing Resource Fields tab is clicked. When a Resource is clicked, it will display the components found in that particular Resource. Simply drag a field just like any other component to add to a form. Because these components are tied to an existing Resource, the API key for the component can not be changed. ![existing - show](https://cloud.githubusercontent.com/assets/13321142/15560509/d3c0861a-22b1-11e6-8e4d-4b65891eacba.png)

Actions

Actions are ways of extending <form.io> to do actions when a form is submitted. For example, you can authenticate a user account against your User Resource, send an email or fire off a webhook to send the data to an external system.

Adding an Action

35 action

To add an action, go to the Actions tab of a form. Select the type of action to add and the click Add Action button. You can add multiple actions to run on each form submission.

Authentication Action

The authentication action allows you to do user authentication within your application against a User Resource. When a user authenticates, they will be issued a JSON Web Token (JWT) which will authorize access to parts of the system.

Resource Association

The resource association will determine how the authentication is handled with the submission. Use New Resource for forms like Registration forms. This will create a new submission and perform the authentication against the new resource. This will both create the user account and log them in. Use Existing Resource for forms like Login forms where users should be checked against existing submissions.

Role

The selected role will be added to all new resources created by the form with this Authentication Action.

Username Field

This is the field on the form that contains the username. If there are embedded resources within the form, you can authenticate against that embedded resource instead of the current form.

Password Field

This is the field on the form that contains the password.

Email Action

The email action allows sending an email when an event occurs on a form.

36 email settings pt 1

Handler

The handler determines when the email will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

Method

When to run this action. Select which system events will trigger this action.

Transport

Select which email transport to use. These need to be configured in your project settings. Transports will not be available for selection if you haven’t configured them.

From

Enter the from email address for the emails.

To

Enter the email addresses to send to. You can use fields from the form by using {{ data.email }} where the field name is email.

Subject

The subject of the email. You may use fields from the form using {{ data.fieldname }}

Message

The message in the email. You may use fields from the form using {{ data.fieldname }}

Nunjucks Templating

All of the email fields are sent through a templating engine called Nunjucks. It is recommended that you read through the documentation of this templating language to understand how it can be utilized to produce very complex templates for your emails using form data. This documentation can be found @ https://mozilla.github.io/nunjucks/templating.html. You can use the following variables which are provided to each template.

data The submission data which maps to the data object of the submission. Example: {{ data.firstName }} would map to the data provided in the "First Name" field if one is provided in your form.
id The ID of the submission being submitted.
{{ data.[RESOURCE]Obj }} Because all of the nested resources will only show their "template" data, every nested resource also has an object property assigned to the data to give you access to the full resource object assigned to that submission. For example, if you have a **Customer** resource field assigned to an **Order** resource, and you sent an email from the order. {{ data.customer }} would only show the templated customer, however {{ data.customerObj }} would contain the full customer object. In this case, you could type {{ data.customerObj.data.email }} to get the customers email address within the template.
form The form object that this email is being sent from. {{ form.components }} would provide you with all the components within the form.
req This is a stripped down request object that contains the following parameters.
user The currently logged in user object. Example: {{ req.user.data.email }} would print out the users email address.
params The request parameters. For example, for url https://myproject.form.io/myform, {{ req.params.formId }} would be the Id of that form
query The request query. For example, for url https://myproject.form.io/myform?testparam=1, {{ req.query.testparam }} would be 1
mail The current mail object being sent. Example {{ mail.to }} would contain the email address who the message is being sent to.

Webhook Action

The Webhook action allows you to integrate form submissions into your custom application, by providing a means to call your external API with the form submission data in real time. In order for the Webhook action to function properly, make sure the API endpoint can be accessed publicly.

Webhooks can not be performed within the “Form Editor”. However, you can see the action take place within the Preview section of your Project.

Handler

The handler determines when the webhook request will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

Method

When to run this action. Select which system events will trigger this action.

Webhook URL

The url of the external system that will handle the web hook.

Authorize User

If you are using Basic Access Authentication for the web hook url, enter the username here.

Authorize Password

If you are using Basic Access Authentication for the web hook url, enter the password here.

Webhook Reciever

In order to receive webhooks, we have created a library that serves to provide a reciever for them. You can download this library at https://github.com/formio/formio-webhook-receiver. Please read the README documents on how to utilize this library.

Testing Webhooks

In order to test webhooks, it is beneficial to point them to your local computer so that you can see them in action. We recommend installing the Webhook Receiver on your local machine and then install and run it using the following command.

npm install
node index.js

This will run the receiver on your Local machine. To connect your local computer to the internet, we recommend using a tool called NGROK. You can download and run the proxy by following the instructions @ https://ngrok.com/download. Once you have this running, you will want to expose the port from the local webhook reciever by typing the following.

ngrok http 4001

You will then see the following…

Version                       2.1.14
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://941a7c65.ngrok.io -> localhost:4001
Forwarding                    https://941a7c65.ngrok.io -> localhost:4001

This tells me that I can now go to http://941a7c65.ngrok.io and it will hit my local reciever. I can now configure the webhook settings with the following settings.

  • Webhook URL: http://941a7c65.ngrok.io
  • Authorize User: test
  • Authorize Password: password123

The username and password can be changed in the config.json of the webhook reciever library.

You can now submit the form and see the data come through your local machine!

SQL Query Action

The email action allows sending an email when an event occurs on a form.

Handler

The handler determines when the query will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

Method

When to run this action. Select which system events will trigger this action.

SQL Server Type

Select the type of server the query will be sent to. Currently two types are supported. MySQL and Microsoft SQL Server. Each type will only be available for selection if you have configured the database credentials in your Project Settings. If you need another type, please contact us.

These are the credentials you may configure in Project Settings:

Server Host

The URL of the server host. This must be publically accessible.

Server Port

The port the server is listening on. This must be open to any firewalls.

Database Name

The name of the database the Query will be run on.

User

The database user name.

Password

The database user password.

Secure Connection (Azure)

If you are using Microsoft Azure and are using a secure connection, check this box.

Query

Enter the SQL query to run. You can use substitutes from the form submission using {{ data.fieldname }}

External ID Field

Many times external databases will generate and return an id when an item is inserted. If you’d like to store this in form.io to associate the two databases together, enter the field name here to store the external id in.

Role Assignment Action

The Role Assignment Action allows for the modification of a submissions roles, when an event occurs on a form.

Resource Association

The resource association will determine if a new or existing resource will be modified.

Action Type

What type of role assignment action to take. The available options are Add Role and Remove Role.

Role

The role to use when performing the role assignment.

Note: The Role Assignment Action requires a Resource Form component with the API key, ‘submission’, to modify existing Resource submissions.

OAuth Action

The OAuth action allows you to do user authentication within your application against an OAuth provider. When a user authenticates, a popup window will ask them to log into the configured OAuth provider’s website, and authenticates them into your application on successful login. This allows users to register and login to your application without having to create a new account.

OAuth Provider

The OAuth Provider to authenticate against. This is the service that users will log into when authenticating via OAuth. You will need to register your application with these providers before you can use OAuth. See the OAuth guide for more information. We currently support the following OAuth providers:

Action

The action to perform after the user has authenticated against the OAuth provider.

Register New Resource

This will create a new submission and perform authentication against the new resource. Use this action for forms like Registration forms. This will create the user account, link the authenticated OAuth provider account, and log them in.

Login Existing Resource

This will attempt to authenticate an existing resource via OAuth. Use this action for forms like Login forms. This will search for a user account that is linked to the authenticated OAuth provider account, and log them in.

This will link an OAuth provider account to the currently logged in user. Use this to allow users who have authenticated via the Authentication Action with an email and password to also login to their account via OAuth.

Role

The selected role will be added to all new resources created by the form with this Authentication Action.

Sign-in with OAuth Button

In order to use the OAuth Action in a form, you must choose a Button component with the action setting OAuth to start the OAuth sign in process. When a user clicks the provided button, the OAuth authentication process will begin by opening a popup of the OAuth provider login page.

Autofill Fields

Depending on which OAuth provider you select, and if you select the Register New Resource action, a number of Autofill Field options may appear. These settings allow you to automatically retrieve data from the OAuth provider account that is used to authenticate and fill in fields in your form before the new resource is created. For example, a GitHub OAuth Registration form may use the Autofill Email Field to assign the email of the GitHub account that was used to authenticate into a field of the new Resource that is created.

Autofill Fields will not always guarantee that they will find a value to fill, as the OAuth provider account may not have any information. For example, a Facebook account may not always fill the Autofill Email Field because some Facebook accounts are created with phone numbers.

Office 365 Contact

The Office 365 Contact action allows you to integrate form submissions into your Office 365 Contact list. When a new submission is made, this action will add a contact to your Office 365 Contact list. When a submission is updated/deleted, it will update/delete the corresponding Office 365 Contact.

Handler

The handler determines when the contact request will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

Method

When to run this action. Select which system events will trigger this action.

Authentication Method

The method of authentication to use with Office 365.

OAuth Delegated

This method will use the currently logged in user’s OAuth token to authenticate with Office 365. This effectively logs into Office 365 as the current user, and will store all contacts under their account. This is useful if your users will be logging in through Office 365, and you want them to manage their own contacts.

For more information on setting up Office 365 OAuth, see the OAuth guide.

OAuth Delegated requires that users log in via Office 365 OAuth.

Application Certificate

This method will use a client certificate to perform server-to-server authentication with Office 365. This effectively logs into Office 365 as an application, and will store all contacts in a single account. This is useful if you do not want to require that your users log into <form.io> via Office 365 OAuth, and you want to manage your contacts from a single location.

For more information on setting up Office 365 client certificates, see the Office365 guide.

Office 365 Fields

These are all the Office 365 Contact fields you may map your form components to. For example, mapping the Email Address field to an Email component in your form will set the contact’s Email Address field with the data submitted in the Email component.

Office 365 Calendar

The Office 365 Calendar action allows you to integrate form submissions into your Office 365 Calendar. When a new submission is made, this action will add a calendar event to your Office 365 Calendar. When a submission is updated/deleted, it will update/delete the corresponding calendar event.

Handler

The handler determines when the calendar event request will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

Method

When to run this action. Select which system events will trigger this action.

Authentication Method

The method of authentication to use with Office 365.

OAuth Delegated

This method will use the currently logged in user’s OAuth token to authenticate with Office 365. This effectively logs into Office 365 as the current user, and will store all calendar events under their account. This is useful if your users will be logging in through Office 365, and you want them to manage their own calendar events.

For more information on setting up Office 365 OAuth, see the OAuth guide.

OAuth Delegated requires that users log in via Office 365 OAuth.

Application Certificate

This method will use a client certificate to perform server-to-server authentication with Office 365. This effectively logs into Office 365 as an application, and will store all calendar events in a single account. This is useful if you do not want to require that your users log into <form.io> via Office 365 OAuth, and you want to manage your calendar events from a single location.

For more information on setting up Office 365 client certificates, see the Office365 guide.

Subject

The subject of the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

Body

The body of the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

Attendees

The attendees of the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

Time Zone

The time zone of the created event.

Start Time Field

The form field that contains the start date of the created event. This field must be a Date/Time Component.

End Time Field

The form field that contains the end date of the created event. This field must be a Date/Time Component.

Location Field

The form field that contains the location of the created event. This field must be an Address Component.

Categories

The categories of the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

The web link to provide for the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

Atlassian Jira

The Jira Action allows you to integrate form submissions with Jira’s issue tracking. When a submission is made, this action will create a linked issue, in the Jira platform. When a submission is updated/deleted, this linked issue will also be updated/deleted. To get started with the Jira connection, the Atlassian Data Connection is required in the corresponding projects settings.

The Jira action configuration page has the following settings: Blocking: - Whether or not the submission request should block for a Jira response. Useful if you want to confirm a ticket was created. Project: - The Project within Jira that the issue will be associated with. Issue Type: - The type of issue that new issues will be created as, e.g. bug, story, etc. These are pulled from your Jira Project. Summary: - The input field on the form, that you want the issue text to be supplied with.


To use OAuth authentication with Jira, you must first configure your project settings in Form.io, and then in Jira itself. You can start by generating an RSA Keypair.

On OSX/Linux the following will generate a Keypair: Create a key pair openssl genrsa -out key.pem 2048

Extract the public key from the pair openssl rsa -in key.pem -pubout

Display the private key cat key.pem

Copy the contents of the private key, to the project settings for Atlassian. While editing the atlassian settings, add your host name and a random string of letters for your consumer key.

Now login to Jira to create an Application link:

Edit the contents of the connection, to update the Incoming Authentication:

With the application link created, you can now interact with Jira via the Jira Action from within Form.io, using OAuth!

SQL Connector

The SQL Connector Action allows you to integrate form submissions with your own SQL based database and requires your project to be on the Team Pro plan or Above; The SQL Connector Action currently supports Microsoft SQL, MySQL, and PostgreSQL. When a submission is created, it will be created in your database for your consumption via formio-sql. To get started with the SQL Connector, the SQL Connector Data Connection is required in the corresponding projects settings. Once the settings are configured, you can map your Form.io form to your Table Columns.

Additionally the formio-sql server must have access to your database and be configured with your settings, see formio-sql for more information. When you start the formio-sql server, it will authenticate to Form.io and grab the dynamically generated routes with SQL query strings

Submissions

Submissions are the values that were submitted to the form you built. These can be thought of as “objects” within the system and operate very much like them. You can get to an administrative view of submissions by clicking the Data tab on the navigation bar. Here you can see a graph which displays submission requests by year, month, or day.

1 data tab

You can access submissions by clicking the data button next to the desired Form or Resource, or utilize the Export button to export CSV or JSON files for the submissions. You can also embed submissions directly using a <formio> Angular directive or you can query the API directly. See Application Embedding and Developer API for more information.

2 data export

Viewing Submissions

Think of the submissions view as administrative access to the database. This should not be used for typical interaction with the application and is not designed for end user use.

The Submissions page gives you an administrative overview of submissions to your forms.

You can see a table view of the fields that had “Table view” selected on them. To add or remove fields from this display, edit the field on the Form Edit page and uncheck “Table View”

From the Submissions overview page you can also view, edit and delete individual submissions to your forms. Use the icons on the right to perform these actions.

Exporting Submissions

Use the two buttons at the top of the submissions list to export all of your data for a form. These operations are streamed from the database which means they should start very quickly and will work on very large datasets without having to write everything out to the server before starting the download.

Export JSON

JSON is Javascript Object Notation and is a way of representing data in a common way for javascript applications. Many other programming languages are able to read in JSON as well. Since data in Form.io is stored in JSON format, this will be the truest form of the data.

Export CSV

CSV is Comma Separated Values and data is squashed down to rows of values with commas between them. This may not work well for complex data structures as it is essentially a flat file. CSV files can be opened by spreadsheet applications like Excel.

Docker Deployments

We offer docker deployments as part of the commercial plans. This allows on premise deployments for companies and organizations that do not want or cannot store their data in the cloud.

In order to access the docker image for on premise deployments you must have a commercial plan. See plans and pricing for more information.

Docker Engine

Docker instances are run inside a Docker Engine. There are many options for where and how to run a docker instance. Depending on which Docker Engine you are using, the formio server configuration will be different.

Using Cloud Hosted Docker

If you are using a cloud hosted Docker Engine, please follow the appropriate steps to set up the formio server Docker container.

Using a Linux Server

Docker Engine runs natively on the Linux architecture. Docker requires a 64-bit installation regardless of your Distrubution version. Additionally, your kernel must be 3.10 at minimum. The latest 3.10 minor version or a newer maintained version are also acceptable.

https://docs.docker.com/engine/installation/linux/ubuntulinux/

Quick install

To do a quick install, run the following command. It will download, configure and install the Docker Engine on Linux hosts.

sudo curl -sSL https://get.docker.com/ | sh

Any distrubutions running systemd, which includes Ubuntu 15.04 and later, should run this command to ensure that the Docker Engine is started on reboot.

systemctl enable docker

Optionally, If you would like to run docker commands without sudo, add your user to the docker group.

sudo usermod -aG docker myusername

Using a Mac OS X computer

Running Docker Engine on a Mac has two options. We highly recommend using Docker for Mac instead of Docker Toolbox. Docker for Mac will run Docker natively on a Mac instead of through a Virtualbox which greatly simplifies setting up and running containers.

Download and install Docker for Mac from https://docs.docker.com/docker-for-mac/

See Using a Virtualbox Docker Engine below if you want to use Docker Toolbox.

Other Operating Systems

Docker Engine can be run on many different systems. See Docker’s Official Documentation for more information on running Docker.

https://docs.docker.com/engine/understanding-docker/

Using a Virtualbox Docker Engine

While it is possible to run the formio server in a Docker Engine inside of Virtualbox, this configuration adds an additional level of abstraction and networking that complicates getting things running correctly. You can use the information below to run formio server in a Virtualbox but our ability to support the server will be reduced.

Running Containers

Accessing the docker image

Once on the commercial plan, you will have access to the docker repository. Our docker images are located on docker’s hub.

https://hub.docker.com/r/formio/formio-server/

Since the image is a private docker respository, you will need to log in with your docker account and test pulling the image. If you are unable to pull the image, please contact support with your username and account information.

docker login
docker pull formio/formio-server

Create a docker network to contain all the docker instances.

A typical Form.io installation includes a Redis, MongoDB, and a Node.js API Server. If your environment is fully dockerized, you can spin up the stack using the following example commands.

This will create an isolated network for just the formio services that are required to run the server. In addition, it will provide for an easy way to link the services together.

docker network create formio

Create the Mongo instance.

Run mongodb with a volume mount for data. This will store the data in the host machine at /opt/mongodb. If the mongodb instance is restarte or replaced, the data still exists and can be restarted with a different mongodb instance.

On Mac OS running native docker engine, be sure to add /opt/mongodb to File Sharing list in Docker->Preferences->File Sharing. You may use a different path if desired.

mkdir /opt/mongodb
# Double check permissions on /opt/mongodb
docker run -itd  \
  --name formio-mongo \
  --network formio \
  --volume /opt/mongodb:/data/db \
  mongo;

Create the Redis instance.

docker run -itd \
  --name formio-redis \
  --network formio \
  redis;

Start the formio-server instance.

Before running this command, replace all the CHANGEME secrets with your own custom random strings. This will ensure that the server remains secure.

Set protocol, port and domain to the address where they will be accessible on the external network. For development it is recommended to use port 3000 and for production, use port 80. Configure in your domain name system to point that domain to the server running this docker engine. If you want to support subdomains, set the wildcard subdomain to also point at the server. See #docker-dns for more information.

First time install Set ADMIN_EMAIL and ADMIN_PASS the first time formio-server is run in a mongodb collection to set the primary account information. ADMIN_EMAIL and ADMIN_PASS may be removed after the initial install.

docker run -itd \
  -e "PROTOCOL=http" \
  -e "DOMAIN=localhost" \
  -e "PORT=80" \
  -e "JWT_SECRET=CHANGEME" \
  -e "JWT_EXPIRE_TIME=240" \
  -e "DB_SECRET=CHANGEME" \
  -e "ADMIN_EMAIL=admin@example.com" \
  -e "ADMIN_PASS=CHANGEME" \
  --name formio-server \
  --network formio \
  --link formio-mongo:mongo \
  --link formio-redis:redis \
  -p 3000:80 \
  formio/formio-server;

Testing the installation

You should now have an instance of the formio-server running in your environment. To test it, go to http://localhost:3000. You should see a response with information about the primary project.

Configuring

The formio server is configured with environment variables. When using Docker, you can set these by using the -e flag. Many Docker hosting platforms have easier ways of setting environment variables for your docker containers.

Installation

Variables

  • ADMIN_EMAIL: The email address for the root account.
  • ADMIN_PASS: The password for the root account.

If your mongodb connection is to an empty database, you will need to set these two variables to set up a root account. This account is used later to deploy projects to the server. Once the installation is completed, these variables can be removed.

MongoDB Connection

Variables

  • MONGO1: Directly connect to a mongo connection string. Example: “mongodb://localhost:27017”
  • MONGO_PORT_27017_TCP_ADDR: The address of the mongodb server. Defaults to “localhost”
  • MONGO_PORT_27017_TCP_PORT: The port of the mongodb server. Defaults to “27017”
  • MONGO_COLLECTION: Which db to use on the mongo server. Defaults to “formio”

Formio Server supports three different ways of connecting to a mongodb server.

Formio server prefers to connect via Docker network links. These allow connecting inside an isolated network and is the most current technology. To use it, create a Docker network and link within it.

Example:

docker network create formio
docker run -d --network formio --name formio-mongo mongo
docker run -d --network formio --link formio-mongo:mongo formio/formio-server

Formio server supports legacy Docker links. These can only be used on the default bridge network. To link, use the mongo link name.

Example:

docker run -d --name formio-mongo mongo
docker run -d --link mongo:formio-mongo formio/formio-server
MONGO1 Variable

If you have a mongodb server available, you can connect directly to it by setting the MONGO1 envinronment variable to the mongodb connection string.

Example:

docker run -d -e “MONGO1=mongodb://localhost:27017” formio/formio-server

Redis Connection

Variables

  • REDIS_ADDR: The address of the redis server. Example: ‘localhost’.
  • REDIS_PORT: The port of the redis server. Defaults to ‘6379’.
  • REDIS_PASS: (Optional) If you redis server has a password, set it with this.

Formio Server supports three different ways of connecting to a redis server.

Formio server prefers to connect via Docker network links. These allow connecting inside an isolated network and is the most current technology. To use it, create a Docker network and link within it.

Example:

docker network create formio
docker run -d --network formio --name formio-redis redis
docker run -d --network formio --link formio-redis:redis formio/formio-server

Formio server supports legacy Docker links. These can only be used on the default bridge network. To link, use the redis link name.

Example:

docker run -d --name formio-redis redis
docker run -d --link redis:formio-redis formio/formio-server
REDIS_ADDR and REDIS_PORT Variables

If you have a redis server available, you can connect directly to it by setting the REDIS_ADDR and REDIS_PORT envinronment variables.

Example:

docker run -d -e "REDIS_ADDR=localhost" -e "REDIS_PORT=6370" formio/formio-server

Server URL settings.

Variables

  • PROTOCOL: The protocol the server is running. Defaults to “https”
  • DOMAIN: The domain name the server is running on. Defaults to “form.io”
  • PORT: The port the server is running. Note: This is the port that is publically accessible, not the port that docker is running. It is common to have docker running on a port but be externally available on a different port. Defaults to “80”

You will need to set up information about what host name and protocol your server is running on. Use these environment variables.

Secrets

Variables

  • JWT_SECRET: The secret key used to encrypt the Json Web Token used for user authentication. If this is changed all existing tokens will immediately expire.
  • JWT_EXPIRE_TIME: How long, in minutes, the JWT is valid. Defaults to 240.
  • DB_SECRET: Project settings in the database are encrypted. Set the DB_SECRET to encrypt the settings.
  • DB_SECRET_OLD: If you need to change the DB_SECRET, set the old value here and it will decrypt with the old and encrypt with the new the next time the server is started. Once changed, you can remove the DB_SECRET_OLD.

There are several places where a secure secret is needed to encrypt parts of the application. These should be unique to your instance.

DNS

In order to run a docker version of the form.io server, a domain name needs to be set up for it. For testing purposes this may simply be localhost. However, one of the features of our server is that it allows having multiple projects on the same server. These can be accessed by subdomains or by the project path. To access a project by its path, use the format /project/{projectId}. You can get the project id by querying the /project endpoint after logging in to the server. (See Exploring Docker below).

For the following scenarios, assume the following project was created on the docker instance.

{
    "title": "My Project",
    "name": "myproject",
    "_id": "55882653b213f00a2641585d"
}

Localhost

For local testing, localhost would seem like a logical solution, however, since formio server relies on subdomains to manage projects and localhost does NOT support subdomains, it becomes a lot of work to constantly add additional lines to the /etc/hosts file each time a project is created.

Instead, we recommend using a domain name with wildcard subdomain support already set up that points to 127.0.0.1. This will allow using a real domain name but will point at your localhost.

http://lvh.me is the domain we recommend. If you run the server and use this domain to point to it, the server with subdomains will work correctly.

To access a project, use the project name and lvh.me

GET http://lvh.me:3000/project/55882653b213f00a2641585d
GET http://myproject.lvh.me:3000/

If you do not want to use lvh.me or a similar domain, you may use the /etc/hosts file (or the Microsoft Windows equivalent).

To use localhost, add the following items and any other project subdomains created on the server.

127.0.0.1   localhost
127.0.0.1   formio.localhost
127.0.0.1   api.localhost
127.0.0.1   myproject.localhost

Then, to access the project, use one of the following methods

GET http://localhost:3000/project/55882653b213f00a2641585d
GET http://myproject.localhost:3000

Each time a new project is added to the server for testing, be sure to add another entry to /etc/hosts.

Public Domains

For publically available servers such as testing and production, set up a wildcard subdomain to point to the server. This will allow subdomains to route correctly to your server. For example, you should have something like this in your DNS settings:

*.example.com.   3600 IN  MX 10 host1.example.com.

See https://en.wikipedia.org/wiki/Wildcard_DNS_record for more information on setting up a wildcard DNS entry.

Then, to access the project, use one of the following methods

GET https://example.com/project/55882653b213f00a2641585d
GET https://myproject.example.com

For all domains other than localhost it is best practice to set up SSL Certificates and run the server over https. This both keeps communication secure and also some browsers are starting to require https for certain cross browser requests.

Deploying

Use our formio-cli tool to deploy to the docker server. To install this, you will need Node.js installed.

Then type the following command on the command line.

npm install -g formio-cli

Now you can use the formio command to deploy a project from one server to another server. formio deploy https://myproject.form.io http://myproject.localhost:3000

Each server will require authentication so you will be asked twice, once for the source server and once for the destination server.

Exploring

Once the server is setup, running and has the DNS configured for it, you can start exploring the server.

By default, the main endpoint will respond with the primary project installed on the server. For new installs, this is the formio project. This project is meant to manage “Administrator” level accounts for who can login and manage projects on the server.

GET http://localhost:3000

Response:

[
    {
        "_id":"5751c2df5717292c84f4211c",
        "name":"formio","title":"Formio",
        "description":"The primary project for new installs.",
        "url":"http://localhost:3000/project/5751c2df5717292c84f4211c",
        "alias":"http://formio.localhost:3000"
    }
]

Using either the url or alias properties plus “/form” (depending on whether your DNS is set up with subdomains or not), you can view the forms in the primary project.

GET http://localhost:3000/project/5751c2df5717292c84f4211c/form

Response:

[  
  {  
    "_id":"5751c2e05717292c84f42120",
    "title":"User",
    "type":"resource",
    "name":"user",
    "path":"user",
    "project":"5751c2df5717292c84f4211c",
    "components":[  
      {  
        "validate":{  
          "required":true
        },
        "type":"email",
        "persistent":true,
        "unique":false,
        "protected":false,
        "defaultValue":"",
        "suffix":"",
        "prefix":"",
        "placeholder":"Enter your email address",
        "key":"email",
        "label":"Email",
        "inputType":"email",
        "tableView":true,
        "input":true
      },
      {  
        "validate":{  
          "required":true
        },
        "type":"password",
        "persistent":true,
        "protected":true,
        "suffix":"",
        "prefix":"",
        "placeholder":"Enter your password",
        "key":"password",
        "label":"Password",
        "inputType":"password",
        "tableView":false,
        "input":true
      },
      {  
        "type":"button",
        "theme":"primary",
        "disableOnInvalid":true,
        "action":"submit",
        "block":false,
        "rightIcon":"",
        "leftIcon":"",
        "size":"md",
        "key":"submit",
        "tableView":false,
        "label":"Submit",
        "input":true
      }
    ]
  },
  {  
    "_id":"5751c2e05717292c84f42121",
    "title":"User Login",
    "type":"form",
    "name":"userLogin",
    "path":"user/login",
    "project":"5751c2df5717292c84f4211c",
    "components":[  
      {  
        "validate":{  
          "required":true
        },
        "type":"email",
        "persistent":true,
        "unique":false,
        "protected":false,
        "placeholder":"Enter your email address",
        "key":"email",
        "label":"Email",
        "inputType":"email",
        "tableView":true,
        "input":true
      },
      {  
        "validate":{  
          "required":true
        },
        "type":"password",
        "persistent":true,
        "protected":true,
        "placeholder":"Enter your password",
        "key":"password",
        "label":"Password",
        "inputType":"password",
        "tableView":false,
        "input":true
      },
      {  
        "type":"button",
        "theme":"primary",
        "disableOnInvalid":true,
        "action":"submit",
        "block":false,
        "rightIcon":"",
        "leftIcon":"",
        "size":"md",
        "key":"submit",
        "tableView":false,
        "label":"Submit",
        "input":true
      }
    ]
  }
]

As we can see from the response by default there are two forms created within the primary project. The first is the User resource and the second is the User Login form. The User Login form allows users to log in and get an access token.

Using the information from these forms you can now log in and get an access token.

The path of the User Login form is “/user/login” so now we can construct the path to log in. Please note that you will need to add “/submission” to access the submissions of a form instead of the form definition itself. Any of the following will work (depending on DNS settings).

POST http://localhost:3000/project/5751c2df5717292c84f4211c/form/5751c2e05717292c84f42121/submission
POST http://localhost:3000/project/5751c2df5717292c84f4211c/user/login/submission
POST http://formio.localhost:3000/form/5751c2e05717292c84f42121/submission
POST http://formio.localhost:3000/user/login/submission

Payload:
{  
  "data":{  
    "email":ADMIN_EMAIL,
    "password":ADMIN_PASS
  }
}

(Be sure to set the Content-Type header to “application/json”)

Use the same ADMIN_EMAIL and ADMIN_PASS from the installation section above.

Response:

{
  "_id": "5751ddbe797c15868646d766",
  "modified": "2016-06-03T19:42:54.771Z",
  "form": "5751c2e05717292c84f42120",
  "data": {
    "email": "test@example.com"
  },
  "created": "2016-06-03T19:42:54.771Z",
  "externalIds": [],
  "access": [],
  "roles": [
    "5751ddbe797c15868646d75e"
  ],
  "owner": null
}

In addition, the response will have a “x-jwt-token” header. This is the most important part. In all further requests, if you use the x-jwt-token header with that value it will authenticate you as the admin user. Please note that the token does expire but every request returns a refreshed token.

Now that you have a jwt token, you can fully explore the API as an authenticated user. For example, to see what projects a user has deployed to the server, do this:

``` headers: x-jwt-token: (very long jwt hash)

GET http://api.localhost:3000/project

PaaS Deployment

Now that you have deployed locally, the next step is to deploy your project within a live Platform as a Service (PaaS). There are many available services which provide Docker deployments such as Amazon AWS, IBM BlueMix, and may others. Read below full tutorials on how to deploy Form.io within those environments.

Environment Switcher

Environment Switcher allows connecting the formio portal to an on premise serve backend such as those using Docker. The Portal app will be the same but the user accounts, projects, forms and submissions will all be stored on the on premise server. This makes managing on premise servers much simpler.

To use the Environment Switcher, go to https://portal.form.io and in the header select Environments->Add Environment. Enter a name and url for your on premise server.

The URL must include the protocol (http or https) as well as the domain name. The domain name must only include two parts such as example.com or test.me.

Please use http://lvh.me instead of localhost.

Correct URLS

  • http://lvh.me:3000
  • https://example.com
  • https://test.me

Incorrect URLS

  • lvh.me
  • http://test.co.uk
  • http://localhost

Once an environment is set up, simply select it to switch to the Server. You will be logged out of the old server before being switched to the new server since the new server contains different user accounts.

Environments must be set up on each browser used to log in to the server. They may be added and removed at any time.

Question: Does my server need to be publicly available to use Environment Switcher?

Answer: No. The server only needs to be accessible from the browser accessing the on premise server. This is because the Portal application is downloaded from our servers and run in the browser. The app within the browser itself is the only thing connecting to your on premise server so the server does NOT need to be accessible on the internet.

Question: Does Environment Switcher work with the open source formio server?

Answer: No. The Environment Switcher will only work with Servers running our Commercial servers.

Project Templates

Project templates are a very convenient way to replicate projects. Templates are JSON files that define what Roles, Resources, Forms, and Actions to create. The easiest way to generate a template is to create a project, create all the Roles, Resources, Forms, and Actions you want the template to have, and export that project. Creating new projects with this template will clone the original project it was exported from.

Template Previews

Templates can also specify a preview application. If a project is created from a template that provides a preview app, then it can use that app to preview what the project looks like, live. There are a couple of steps to set up a preview app.

Setup Your Preview App

A preview application should be a publicly hosted instance of the application that you want your projects to be used with. This can be any kind of web application that integrates into <form.io>.

In order to serve as a preview app, your application should be able to point to any provided <form.io> project. When your preview app is used to preview a specific project, your project will receive two query parameters:

appUrl
The url to your project on <form.io>.
apiUrl
The url to the <form.io> API server. For most cases, you may ignore this parameter.

For example, if your preview app is hosted at http://preview.example.com, and you preview your project at https://myproject.form.io, then the user will open your app at http://preview.example.com?appUrl=https://myproject.form.io&apiUrl=https://api.form.io (properly escaped, of course). Your preview app must be able to read these parameters and apply them in your app to connect to the given project.

Setup your Template

Next, you must add the url to your project template. Add an object to the preview key in the root of your template. That object should contain a url key set to the url to your preview app. You may also have a repo key that points to the source code of your app if you want to display a link to it when previewing. An example is shown below:

{
  "title": "Example",
  "name": "example",
  "description": "An example template.",
  "preview": {
    "url": "http://preview.example.com",
    "repo": "http://github.com/example/preview"
  },
  // Your roles, forms, resources, and actions go here...
}

Now anytime you create a new project with this template, a new button will appear on the <form.io> project page to preview the app.