JavaScript SDK

Example: Send a request to fetch submissions.

Formio.request(
  'https://examples.form.io/customers/submission?data.number=1',
  'GET',
  null,
  null,
  {
    headers: {
      'content-type': 'application/json'
    },
    mode: 'cors',
  }).then(function(result) {
    console.log(result);
  });

`Formio.makeStaticRequest(url, [method], [data], [opts])`

This static method performs an API call to the Form.io API platform. This method is very similar to other request method but will also send the request through the Form.io fetch plugin to allow any fetch plugin to intercept the request being made. Its parameters are defined as follows.

Parameter

Description

url

The URL you wish to send the request to.

method (optional)

The method of the request. GET, PUT, POST, DELETE

data (optional)

The data to include for PUT and POST requests

opts (optional)

`Formio.setToken(token)`

Helper function to retrieve all of the URL query parameters in a javascript key-value pair mapped object.

Example: Given the following url

https://yourapp.formio.com/#/home?data.firstName=Travis&sort=-created

If you run this method on that page, it will return the following.

const pageQuery = Formio.pageQuery();
console.log(pageQuery['data.firstName']); // Prints "Travis"
console.log(pageQuery.sort); // Prints "-created"

`Formio.ssoInit([type], [options])`

Initializes an SSO processes. This is used during SAML authentication processes to instantiate and continue a SAML SSO process.

Instantiate a SAML SSO process

Assuming that your project is configured for SAML, you can instantiate an SSO process by executing the following.

Formio.ssoInit('saml')

Process a SAML response

Once the SAML authentication returns to the application, you can process that response using the following.

if (Formio.pageQuery().saml) {
    const sso = Formio.ssoInit('saml');
    if (sso) {
        sso.then((user) => {
          window.location.href = '/';
        });
    }
}

The following parameters can be used.

Parameter

Description

type

The type of SAML sso authentication to instantiate. Either "saml" or "okta"

options

An object of options, which depends on the type.

For saml type:

- relay: This is the variable that will be provided to the relay of the sso process.

For okta type:

- OktaAuth: An instance of the OktaAuth javascript object provided by Okta Javascript SDK

- formio: An instance of the Form.io SDK.

- scopes: A string of CSV scopes to apply

`Formio.requireLibrary(name, property, src, [polling])`

Require an external JavaScript library for lazy-loading purposes.

Parameter

Description

name

The name of the library

property

The property that is added to the "window" object that indicates that the library has finished loading. For example, if you are wanting to load the "Lodash" library, the variable that is added to the window object is "_"

src

The URL of the library you wish to load.

polling

Creates a polling check to see if the library has finished loading.

Formio.requireLibrary(
    'lodash',
    '_',
    'https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.21/lodash.min.js',
    true
).then(function() {
    console.log(_.version); // Lodash is now part of the dom.
});

`Formio.libraryReady(name)`

Returns a promise that will resolve once the library of the provided name is ready to be used.

Parameter

Description

name

The name of the library to check if it is ready or not.

Formio.libraryReady('lodash').then((_) => {
    // Lodash is now ready!
    console.log(_);
});

`Formio.loadProjects([query], [opts])`

A static method to load all projects within the configured baseUrl of the SDK.

Parameter

Description

query (optional)

opts (optional)

`Formio.serialize(obj, [interpolate])`

A method that will serialize a data map key-value pair object into a URL query string.

Parameter

Description

obj

The object to serialize into a URL query string.

interpolate (optional)

An optional interpolation method to interpolate certain values that are added.

Project API Scope

The following API's are defined at the Project Scope. To instantiate the SDK at the project scope, you simply need to provide a Project API to the constructor as follows.

const formio = new Formio('https://forms.formio.com/myproject')

where "myproject" would be the alias name of your project. Once you have instantiated the SDK with the following URL, the following methods are now available to you at the Project Scope.

`formio.loadProject([query], [opts])`

Loads the project using the following Project Load API

Parameter

Description

query (optional)

opts (optional)

formio.loadProject().then((project) => {
    // Prints the project JSON
    console.log(project);
});

`formio.saveProject(project, [opts])`

Creates or Updates a project depending on if the _id of the project is provided (upsert).

Example: Create a new project

const formio = new Formio('https://api.form.io');
formio.saveProject({
    "title": "New Project",
    "name": "proj980",
    "description": "An example application",
    "settings": {
        "cors": "*"
    }
}).then((project) => {
    // Prints the project that was saved via API.
    console.log(project);
});

Example: Update an existing project.

const formio = new Formio('https://forms.formio.com/myproject');
formio.loadProject().then((project) => {
    project.title = 'Updated Title';
    formio.saveProject(project).then((updated) => {
        // Prints the updated project json.
        console.log(updated);
    });
});

Parmameters

Description

project

The project JSON you wish to create or update. If an "_id" is provided within the json, an update operation will be executed, otherwise it will create a new project.

opts (optional)

`formio.deleteProject([opts])`

Deletes a project.

var formio = new Formio('https://myproject.form.io');
formio.deleteProject().then(() => {
    console.log('The project has been deleted!');
});

Parmameters

Description

opts (optional)

`formio.loadForms([query], [opts])`

Loads all the forms within a project. This implements the List Forms API.

Parameter

Description

query (optional)

opts (optional)

Example: List all Resources within a project, sort them based on created date, and only return the "title" and "path" of those forms

formio.loadForms({
  params: {
    type: 'resource',
    select: 'title,path',
    sort: '-created'
  }
}).then((resources) => {
  console.log(resources);
});

Example: List all Forms within a project, limit them to 20, and only return the "title" of those forms.

formio.loadForms({
  params: {
    type: 'form',
    select: 'title',
    limit: 20
  }
}).then((forms) => {
  console.log(forms);
});

`formio.getTempToken(expire, allowed, [options])`

Retrieves a temporary auth token which can be used in conjunction with the PDF API's to download a PDF output of a submission.

formio.getTempToken(
    3600, 
    'GET:/project/234234234234234/form/234234234234234/submission/234234234234234/download'
).then((tokens) => {
    console.log(tokens);
});

`formio.loadRoles([opts])`

Loads a list of roles for the provided project. Implements the List Roles API

Parameter

Description

opts (optional)

`formio.getProjectId()`

Returns the Project ID of the project in context, even if the URL provided to the constructor uses the project alias.

const formio = new Formio('https://forms.formio.com/myproject');
formio.getProjectId().then((projectId) => {
    // Prints the project id for the "myproject" project.
    console.log(projectId);
});

`formio.accessInfo()`

Retrieve the access information for a project. This method implements the Project Access Info API

formio.accessInfo().then((accessInfo) => {
    // Output the role information for this project.
    console.log(accessInfo.roles);
});

`formio.currentUser()`

Based on the JWT token stored within the localStorage, this method will retrieve the current user metadata and information.

formio.currentUser().then((user) => {
    // The current user.
    console.log(user);
});

Form API Scope

The following API's are available when the Form.io SDK is instantiated with the form scope like the following illustrates

const formio = new Formio('https://forms.formio.com/myproject/myform');

`formio.loadForm([query], [opts])`

Loads a form json

Parameter

Description

query (optional)

opts (optional)

`formio.saveForm(form, [opts])`

Creates or Updates a form depending on if an "_id" property is provided within the form json.

Parameter

Description

form

The JSON of the form to save or update. If an "_id" is provided as a property of the form json, then an update operation is performed, otherwise, it will create a new form.

opts (optional)

Example: Create a new form

// Project scope is only required for creating new forms.
const formio = new Formio('https://forms.formio.com/myproject');

formio.saveForm({
  title: 'Registration',
  path: 'registration',
  name: 'registration',
  components: [
    {type: 'textfield', key: 'firstName', label: 'First Name'}
    {type: 'textfield', key: 'lastName', label: 'Last Name'}
  ]
}).then((form) => {
  // Prints out the saved form object.
  console.log(form);
});

Example: Update an existing form

const formio = new Formio('https://forms.formio.com/myproject/myform');
formio.loadForm().then((form) => {
  form.title = 'Updated title';
  formio.saveForm(form).then((updated) => {
    console.log(updated);
  });
});

`formio.deleteForm([opts])`

Deletes a form

Property

Description

opts (optional)

const formio = new Formio('https://forms.formio.com/myproject/myform');
formio.deleteForm().then(() => {
    console.log('Form was deleted!');
});

`formio.getFormId()`

Returns the form Id of the form in context even if the form alias was provided for this form.

const formio = new Formio('https://forms.formio.com/myproject/myform');
formio.getFormId().then((formId) => {
    // Prints the form id for "myform"
    console.log(formId);
});

`formio.loadSubmissions([query], [opts])`

Loads a view of submissions for a form. This implements the Get Submissions API

Parameter

Description

query (optional)

opts (optional)

Example: Load first 10 submissions, sort by descending created date

formio.loadSubmissions({
  params: {
    sort: '-created'
  }
}).then((submissions) => {
  console.log(submissions);
});

Example 2: Load first 20 submissions where the form field age is greater than 18, and sort by modified.

formio.loadSubmissions({
    params: {
        sorted: 'modified',
        'data.age__gt': 18,
        limit: 20
    }
}).then((submissions) => {
    console.log(submissions);
});

`formio.loadActions([query], [opts])`

Loads the Actions for a given form. This implements the List Actions API

Parameter

Description

query (optional)

opts (optional)

Examples will be very similar to the loadSubmissions API, but will query against the action json objects instead.

`formio.availableActions()`

Returns a list of available actions that can be added to this form. Implements the Available Actions API.

`formio.actionInfo(name)`

Returns the action information for a specific action including the settings form. This implements the Action Info API

Parameter

Description

name

The name of the action you would like to retrieve information on.

Submission API Scope

The following API's are available when the Form.io SDK is instantiated with the submission scope like the following illustrates

const formio = new Formio('https://forms.formio.com/myproject/myform/submission/234234234234234');

`formio.loadSubmission([query], [opts])`

Loads a submission for a given form.

Parameter

Description

query (optional)

opts (optional)

Example: Load the submission

const formio = new Formio('https://forms.formio.com/myproject/myform/submission/234234234234234');
formio.loadSubmission().then((submission) => {
    console.log(submission);
});

`formio.saveSubmission(submission, [opts])`

Creates or Updates a submission depending on if an "_id" property is provided within the submission json.

Parameter

Description

submission

The JSON of the submission to save or update. If an "_id" is provided as a property of the submission json, then an update operation is performed, otherwise, it will create a new submission.

opts (optional)

Example: Create a new submission

// Form scope is only required for creating new submissions.
const formio = new Formio('https://forms.formio.com/myproject/myform');

formio.saveSubmission({
  data: {
    firstName: 'Joe',
    lastName: 'Smith'
  }
}).then((submission) => {
  // Prints out the saved submission object.
  console.log(submission);
});

Example: Update an existing submission

const formio = new Formio('https://forms.formio.com/myproject/myform/submission/234234234234234');
formio.loadSubmission().then((submission) => {
  submission.data.firstName = 'Updated Name';
  formio.saveSubmission(submission).then((updated) => {
    console.log(updated);
  });
});

`formio.deleteSubmission([opts])`

Deletes a submission

Property

Description

opts (optional)

const formio = new Formio('https://forms.formio.com/myproject/myform/submission/234234234234234');
formio.deleteSubmission().then(() => {
    console.log('Submission was deleted!');
});

`formio.getDownloadUrl([form])`

Retrieves a PDF download url for a specific form.

Parameter

Description

form

The form JSON to retrieve a download url from. If none is provided, then it will use the form that is in scope.

const formio = new Formio('https://forms.formio.com/myproject/myform/submission/234234234234234');
formio.getDownloadUrl().then((url) => {
    // This will print the PDF download url, which also includes the temp token.
    console.log(url);
});

`formio.uploadFile(storage, file, fileName, dir, progressCallback, url, options, fileKey, groupPermissions, groupId, uploadStartCallback, abortCallback)`

Uploads a file to the provided storage system. See File Component for specific usage and implementation details.

`formio.downloadFile(file, [options])`

Downloads a file from the provided storage system. See File Component for specific usage and implementation details.

`formio.deleteFile(file, [options])`

Deletes a file from the provided storage system. See File Component for specific usage and implementation details

Action API Scope

The following API's are available when the Form.io SDK is instantiated with the action scope like the following illustrates

const formio = new Formio('https://forms.formio.com/myproject/myform/action/234234234234234');

`formio.loadAction([query], [opts])`

Loads an action for a given form.

Parameter

Description

query (optional)

opts (optional)

Example: Load the action

const formio = new Formio('https://forms.formio.com/myproject/myform/action/234234234234234');
formio.loadAction().then((action) => {
    console.log(action);
});

`formio.saveAction(action, [opts])`

Creates or Updates an action depending on if an "_id" property is provided within the action json.

Parameter

Description

action

The JSON of the action to save or update. If an "_id" is provided as a property of the action json, then an update operation is performed, otherwise, it will create a new action.

opts (optional)

Example: Create a new action

// Form scope is only required for creating new actions.
const formio = new Formio('https://forms.formio.com/myproject/myform');

formio.saveAction({
	"data": {
		"name": "email",
		"title": "Email",
		"method": ["create"],
		"handler": ["after"],
		"priority": 0,
		"settings": {
			"emails": ["test@example.com"],
			"from": "np-reply@form.io",
			"message": "{{ submission(data, form.components) }}",
			"subject": "New submission for {{ form.title }}.",
			"transport": "default"
		}
	}
}).then((action) => {
  // Prints out the saved action object.
  console.log(action);
});

Example: Update an existing submission

const formio = new Formio('https://forms.formio.com/myproject/myform/action/234234234234234');
formio.loadAction().then((action) => {
  action.title = 'Updated Action Title';
  formio.saveAction(action).then((updated) => {
    console.log(updated);
  });
});

`formio.deleteAction([opts])`

Deletes an action

Property

Description

opts (optional)

const formio = new Formio('https://forms.formio.com/myproject/myform/action/234234234234234');
formio.deleteAction().then(() => {
    console.log('Action was deleted!');
});

Role API Scope

The following API's are available when the Form.io SDK is instantiated with the role scope like the following illustrates

const formio = new Formio('https://forms.formio.com/myproject/role/234234234234234');

`formio.loadRole([opts])`

Loads a role json.

Parameter

Description

opts (optional)

Example: Load the role

const formio = new Formio('https://forms.formio.com/myproject/role/234234234234234');
formio.loadRole().then((role) => {
    console.log(role);
});

`formio.saveRole(role, [opts])`

Creates or Updates a role depending on if an "_id" property is provided within the role json.

Parameter

Description

role

The JSON of the role to save or update. If an "_id" is provided as a property of the role json, then an update operation is performed, otherwise, it will create a new role.

opts (optional)

Example: Create a new role

// Project scope is only required for creating new roles.
const formio = new Formio('https://forms.formio.com/myproject');

formio.saveRole({
	title: 'Employee',
  description: 'A person who belongs to a company.'
}).then((role) => {
  // Prints out the saved role object.
  console.log(role);
});

Example: Update an existing role

const formio = new Formio('https://forms.formio.com/myproject/role/234234234234234');
formio.loadRole().then((role) => {
  role.title = 'Manager';
  formio.saveRole(role).then((updated) => {
    console.log(updated);
  });
});

`formio.deleteRole([opts])`

Deletes a role

Property

Description

opts (optional)