Getting Started

An overview of Form.io, how to use, basic templates and examples, and more. Learn basic concepts and how things work together.

Welcome to <form.io>!

<form.io> is a form and API platform designed simplify the creation of Web 3.0 applications. It does this by providing a simple embed code into your web applications, dynamically rendering the forms and automatically generating a Rest API behind the form. In addition form.io provides many custom actions that can occur when users interact with the forms.

Use this guide to get acquainted with the features and functionalities of form.io and how to go from start to finish with a project.

How it works

To get started, skim through the following slides to get a better understanding at how Form.io works. Click on the following, then press your Right arrow key to move through the presentation.

Form Embedding

The most simple explanation of form.io is that it is a form creation and embedding platform. It is different than most form systems however in that forms are not embedded with iframes. Instead, forms are rendered using a front end library such as angular or react and connected to a backend API to handle the data submissions.

After building a form with the drag and drop form builder, forms are embedded in an application or directly on a website. The form definitions themselves are actually json objects that define what fields should be on a form, what types of validations should occur, and where the data should submit to. Each form will have a URL associated with it that points to the json object definition of the form. This is how it is embedded.

Before forms can be embedded, the ngFormio library and all of its dependencies need to be included on the page and an angular application needs to be created.

There are typically two cases where form embeds occur. The first is in a non existing angular website or application and the second is in an existing angular application. Let’s take a look at how to set each up to be ready to embed form.io forms.

Website or New Angular Application Setup

When embedding a form in a non existing angular website or application, the easiest way to do it is to include the formio-full.js file. This file can be found at https://github.com/formio/ngFormio/tree/develop/dist.

Either download this file and include it locally or use a CDN by adding this somewhere in the body of the page.

<script src="https://cdn.rawgit.com/formio/ngFormio/develop/dist/formio-full.min.js"></script>

Next, you will need to create an angular application and add formio as an included module. Add this below the include tag.

<script type="text/javascript">
  var app = angular.module('formApp', ['formio']);
</script>

Finally, add the app to the web page by adding the following code:

<div ng-app="formApp" class="well">
  <!-- Ths is where to embed forms -->
</div>

Now load the web page in the browser and the formio library with all of its depenencies will be loaded, an angular application will be created and embedded on the page.

Here is a jsfiddle of a simple embed.

Existing Angular Application Setup

If you already have an angular application and want to add form.io forms to your application, follow the instructions in this section. This is more advanced and will outline the requirements without making assumptions about how your application is being built.

First you will need to include the https://github.com/formio/ngFormio library in your application. You can do this with bower by bower install formio or manually downloading the files.

Additionally you will need to add all of the ngFormio dependencies. These are listed in the bower.json file within the repo and currently consist of the following:

  • angular
  • angular-sanitize
  • angular-bootstrap
  • angular-moment
  • angular-ui-mask
  • angular-ui-select
  • bootstrap
  • bootstrap-ui-datetime-picker
  • ng-file-upload
  • signature_pad
  • ui-select

You’ll need to load all of those dependencies into your project and add <script> tags for them so they are included in the app. You can do this with bower and wiredep or another way as you prefer. For examples on how to do this, check out our demo apps at https://github.com/formio?utf8=%E2%9C%93&query=formio-app-.

Next, add formio module to your app definition. For example.

app.module('MyAwesomeApp', [
  'one-module', 
  'two-module', 
  'formio'
]);

Once the formio library is loaded on the page and added as a dependency in the angular app you are ready to add form embeds within your application.

Doing the form embed

Lets take a look at an embed code.

<formio src="'https://myapp.form.io/user/register'">

The <formio> HTML tag works very much like an <img> tag, but instead of providing the source to the image in the src attribute, you provide the API url to the form within Form.io. Here is an example of what the path may look like without a variable.

<formio src="'https://myapp.form.io/user/register'"></formio>

This does a couple of things…

  • Dynamically renders the form provided the JSON schema from the API.
  • Automatically hooks up the I/O for the form to Form.io to provide Actions and Submissions when the form is submitted.

Notice how there is a double quote with a single quote inside it for the src. This is so that angular.js knows the value is a string. It is also possible to set it to a scope variable like this where $scope.userRegisterForm = 'https://myapp.form.io/user/register'; is set in a controller.

<formio src="userRegisterForm"></formio>

For more information on how to embed forms in an application or directly into a website go to Angular Embedding.

Dynamic Form Rendering

Once a form is embedded within an application or website, it is dynamically rendered by angular.js or react.js each time the page is viewed. Forms are not generated into html and then inserted into the page, nor are they embedded with iframes. They will query the src url for the current form definition and render accordingly.

For the form at https://todo.form.io/todo here is definition.

{
   "_id":"55673ecf4f0405dd28205bba",
   "modified":"2015-09-04T17:32:22.473Z",
   "title":"Todo",
   "type":"resource",
   "name":"todo",
   "path":"todo",
   "project":"55673df34f0405dd28205bb8",
   "created":"2015-05-28T16:14:07.911Z",
   "components":[
      {
         "tableView":true,
         "type":"textfield",
         "validate":{
            "customPrivate":false,
            "custom":"",
            "pattern":"",
            "maxLength":"",
            "minLength":"",
            "required":true
         },
         "persistent":true,
         "unique":false,
         "protected":false,
         "defaultValue":"",
         "multiple":false,
         "suffix":"",
         "prefix":"",
         "placeholder":"enter the todo",
         "key":"title",
         "label":"Title",
         "inputMask":"",
         "inputType":"text",
         "input":true
      },
      {
         "type":"textfield",
         "validate":{
            "customPrivate":false,
            "custom":"",
            "pattern":"",
            "maxLength":"",
            "minLength":"",
            "required":false
         },
         "persistent":true,
         "unique":false,
         "protected":false,
         "defaultValue":"",
         "multiple":false,
         "suffix":"",
         "prefix":"",
         "placeholder":"enter a description",
         "key":"description",
         "label":"Description",
         "inputMask":"",
         "inputType":"text",
         "tableView":true,
         "input":true
      },
      {
         "tableView":false,
         "type":"button",
         "input":true,
         "label":"Submit",
         "key":"submit",
         "size":"md",
         "leftIcon":"",
         "rightIcon":"",
         "block":false,
         "action":"submit",
         "disableOnInvalid":true,
         "theme":"primary"
      }
   ]
}

What this allows is for developers to create the structure of an application and embed forms within and have admins that may or may not know how to program or deploy an application but are now able to update a form and have those changes immediately reflected in the application or website.

This is also true for iOS, Android and other mobile applications using WebView to build an app. You can use form.io to generate the form definitions and automatically update your applications without the need to recompile and deploy the apps through an app store.

Automatic Rest APIs

As each form is built out, a Rest API is automatically built out for it as well and is connected to the form so that all submissions and data access are through that Rest API.

Form.io provides a Swagger UI to browse the API endpoints. You can view and interact with the form data using this UI.

The Rest API will repeat all validations from the front end as well as run the unique validation and any custom and hidden validations specified in the field configuration. This ensures that data is checked both on the front end to give a good user experience, and on the backend to ensure data is correct.

Custom Actions

As data is created, updated, or deleted with a form, actions can be configured to perform steps with that data. Form.io has many actions designed around getting your data where it needs to go.

Some of the types of actions that can happen are:

  • Email - Sending an email with the form information either to the person submitting the form or to a project administrator.

  • Data Sync - Sending the data either to an external database or external service like Microsoft Office 365 or Hubspot.

  • Authentication - Performing User authentication with an external service such as github, facebook or twitter.

  • Webhook - Calling a custom URL in your system to do something with the form data.

This allows the complete circle of using form.io. The forms are created, embedded, rendered, sent to form.io for validation and then sent to wherever you need the data to be.

Find out more about actions in the Actions Section of the User’s Guide .

Exploring the portal

Resources

Resources are reusable objects that can be used to create complex data structures within your application. The fields within a resource can be reused within other forms, as well as linked together to create complex nested resource relationships.

One example is a user resource with login and register forms.

Resource

  • User(user)
    • Name field (name)
    • Email field (email)
    • Password field (password)

Forms

  • Register
    • user.name
    • user.email
    • user.password
  • Login
    • user.email
    • user.password

Another example is having multiple resources embedded in the same form. This example has a customer, product, and order resources with an order form.

Resources

  • Customer (customer)
    • name
    • address
  • Product (product)
    • id
    • description
    • price
  • Order (order)
    • ordernum
    • date
    • total

Form

  • Order Form
    • customer.name
    • customer.address
    • product.id
    • product.description
    • product.price
    • order.ordernum
    • order.date
    • order.total

Resources are very similar to forms in the way that they are built, their rendering, and their APIs. There is one fundamental difference and that is that resource fields can be embedded in other resources or forms.

Forms

Forms provide a mechanism for user input within your application. Form.io provides a form builder interface which allows you to drag and drop form components as well as reuse Resource fields to create robust, manageable, and reusable form interfaces for your web application.

For more information on creating and using forms, go to the Forms Section of the User’s Guide.

Data

The Data page has two purposes. The first is to show the API usage for a project and the second is to allow viewing form submission data for a project.

Analytics

The analytics data for a project shows the number of submission calls that have occurred. All API operations dealing with submissions, including Create, Read, Update, and Delete each count as one API operation. Any operations on the form definition do not count as an API operation.

Analytics data can be drilled down into by clicking on the dot or using the dropdown to zoom in on the data.

Data Grid

Click on any Resource or Form to view the data that has been submitted to the corresponding API. This data is displayed in a data grid that allows filtering, sorting and editing the data. Click the arrow to the right of each column to sort or filter that column.

You can also export the full data as a CSV or JSON file using this page.

App Preview

For projects from application templates, the Preview page allows seeing a working application without having to build and host an app somewhere. Each application template comes with a corresponding app that is used for the preview. This is an angular application that already has all the forms embedded and user authentication set up.

The Preview is a live working app that directly interfaces into your project. You can log in and create, edit and delete data within your project. Any changes made to the forms will immediately be reflected within the app.

When the time comes to make major changes to the app or to deploy to your own systems, the template can be cloned from github and all needed modifications can be made.

API

As forms and resources are created, a Rest API is automatically created for it. This page shows the API details so that it can easily be explored.

Each endpoint can be directly queried from the endpoints. Use caution as this is against live data.

Use this page to experiment with how to access form data. For more information go to the Developer API Guide.

Customizing your app

Updating a form

Once you have a project created and have explored the options available in the portal, it is time to see form updates in action.

Start by going to the edit page of any form that is contained within the project. Create or edit a field on that form.

Be sure to save the form after editing it.

Now go directly to the Preview page on the left side of the portal. You should immediately see the changes you made to the form.

As you continue to make changes to the forms within your project, you can view the changes directly in the preview.

Modifying the App

At some point in development you will reach a point where you will want to change more than just the contents of a form. This could be changing the CSS of the application or adding an entirely new section to the app. This is when it is time to clone the application repo locally and switch to local development of the app.

To do this, you will need node.js installed. See the nodejs installation page for information on how to do this.

You will also need git, a source code manager. Many operating systems come with git pre-installed. If you don’t have it already, you can get it at https://git-scm.com/.

Once you have node and git installed, you are ready to copy down the application repository and make customizations.

The Preview window has the URL of the template repo used for the preview. Copy that URL and do a git clone. For example:

git clone git@github.com:formio/formio-app-todo.git

Inside the /src/config.js file you will need to set the APP_URL which says where your project is on form.io. This is the url at the top of your project page or it can be found on the Preview page.

var APP_URL = 'https://todo.form.io';

Then run the following commands which will download all dependencies and start a local server.

npm install -g gulp npm install gulp serve

You can now make any modifications to the application you need and preview them locally on your computer. Form modifications are still done on form.io.

Deploying an App

Once finished making modifications to an app, it is time to deploy it to a website. There are two steps to this. Building the app and deploying the built files to a server.

Building the App is relatively straightforward. If you have already set up the tools in the above section for modifying your app you should have Node, Git and Gulp installed. Then run this command.

gulp build

This will update the /dist folder with any changes you have made to the app.

Deploying the app is as simple as copy the contents of the /dist folder to any server capable of serving files. This can be an Apache, Nginx or other web server. It can also be any other type of CDN such as Amazon S3 or Github pages. There are no special requirements beyond being able to serve files.

Once copied to the server the app should be accessible on the internet. The app will use form.io to manage all of the API and data. If you would like to host your own version of the form.io server, you can either check out the open source version or our docker deployments for enterprise.