JavaScript API

The JavaScript API is a minimalistic API library that allows you to work with the Form.io API's within JavaScript.

Usage

Creating an instance of Formio is simple, and takes only a path (URL String). The path can be different, depending on the desired output. The Formio instance can also access higher level operations, depending on how granular of a path you start with.

var formio = new Formio(<endpoint>, [options]);

Where endpoint is any valid API endpoint within Form.io. These URL's can provide a number of different methods depending on the granularity of the endpoint. This allows you to use the same interface but have access to different methods depending on how granular the endpoint url is.

The options (optional) is used to configure certain behaviors of the JavaScript API. The following options are available.

Property	Description	Type	Default	Example
base	Allows you to override the base api url.	string		https://api.form.io

Project Context

The project context is the top-most level of the Form.io API's. This context provides project level information for anything within your project. To declare the Formio object at this context, you simply need to provide the URL for your project like so.

var formio = new Formio('https://myproject.form.io');

Project APIs

formio.loadProject()

This will load the current project in context

Example

var formio = new Formio('https://myproject.form.io');
formio.loadProject().then(function(project) {
  console.log(project);
});

formio.saveProject(<project>)

Saves the parent Project, using the given payload.

Example

var formio = new Formio('https://myproject.form.io');
formio.loadProject().then(function(project) {
  project.title = 'Changed title';
  formio.saveProject(project).then(function(saved) {
    console.log(saved);
  });
});

formio.deleteProject()

Deletes the parent Project.

Example

var formio = new Formio('https://myproject.form.io');
formio.deleteProject();

formio.loadForms(<query>)

Loads all of the Forms within a project.

Example

var formio = new Formio('https://myproject.form.io');

// Load all forms within a project
formio.loadForms({params: {type: 'form'}}).then(function(forms) {
  console.log(forms);
});

// Load all resources within a project
formio.loadForms({params: {type: 'resource'}}).then(function(resources) {
  console.log(resources);
});

Form Context

Form context is provided to the Formio class by passing along the endpoint of the form you wish to reference.

var formio = new Formio('https://myproject.form.io/myform');

The following API methods are available for this context.

• All Project API's are available

formio.loadForm()

Loads the given Form.

var formio = new Formio('https://myproject.form.io/myform');
formio.loadForm().then(function(form) {
  console.log(form);
});

formio.saveForm()

Saves the given Form, using the given payload.

var formio = new Formio('https://myproject.form.io/myform');
formio.loadForm().then(function(form) {
  form.title = 'Changed title';
  formio.saveForm(form).then(function(changed) {
    console.log(changed);
  });
});

formio.deleteForm()

Deletes the given Form.

var formio = new Formio('https://myproject.form.io/myform');
formio.deleteForm();

formio.loadSubmissions(<query>)

Loads all the submissions for this specific form.

var formio = new Formio('https://myproject.form.io/myform');

// Load all submissions whose first name is "Travis"
formio.loadSubmissions({params:{'data.firstName':'Travis'}}).then(function(submissions) {
  console.log(submissions);
});

formio.loadActions(<query>)

Loads all actions available to this form.

var formio = new Formio('https://myproject.form.io/myform');

// Give me all email actions attached to this form.
formio.loadActions({params:{type: 'email'}}).then(function(emailActions) {
  console.log(emailActions);
});

formio.canSubmit()

Determines if the currently logged in user can submit this form.

var formio = new Formio('https://myproject.form.io/myform');
formio.canSubmit().then(function(canSubmit) {
  if (canSubmit) {
    console.log('This user can submit this form!');
  }
});

formio.saveSubmission(<submission>)

Saves either a new submission, or updates an existing submission. If you do not provide an _id along with the submission object, then this is a new submission, however if a _id is provided, then this becomes an update.

Creating a new submission

var formio = new Formio('https://myproject.form.io/myform');
formio.saveSubmission({
  data: {
    firstName: 'Joe',
    lastName: 'Smith'
  }
}).then(function(created) {
  console.log(created);
});

Updating an existing submission.

var formio = new Formio('https://myproject.form.io/myform');
formio.saveSubmission({
  _id: '234234234234234234',
  data: {
    firstName: 'Joe',
    lastName: 'Thompson'
  }
}).then(function(updated) {
  console.log(updated);
});

Submission Context

The submission context is provided by passing along a single submission endpoint to the Formio constructor.

var formio = new Formio('https://myproject.form.io/myform/submission/234234234234');

• All Project Context API's available
• All Form Context API's available

formio.loadSubmission()

Loads the submission.

var formio = new Formio('https://myproject.form.io/myform/submission/234234234234');
formio.loadSubmission().then(function(submission) {
  console.log(submission);
});

formio.saveSubmission(<submission>)

Saves either a new submission, or updates an existing submission. If you do not provide an _id along with the submission object, then this is a new submission, however if a _id is provided, then this becomes an update.

See examples above in the Form Context

formio.deleteSubmission()

Deletes a submission

var formio = new Formio('https://myproject.form.io/myform/submission/234234234234');
formio.deleteSubmission();

formio.getDownloadUrl()

Retrieves the PDF download url of this submission.

var formio = new Formio('https://myproject.form.io/myform/submission/234234234234');
formio.getDownloadUrl().then(function(url) {
  console.log(url);
});

Static Methods

Formio.setBaseUrl(<url>)

Sets the base URL to tell this library which root API you are talking with.

Formio.setBaseUrl('https://forms.myserver.com');

Formio.getBaseUrl()

Gets the base url configuration.

Formio.setProjectUrl(<url>)

Sets the project endpoint url.

Formio.setProjectUrl('https://myproject.form.io');

Formio.setToken(<token>)

Sets the JWT Auth token for this library.

Formio.getToken()

Gets the current users JWT token.

Formio.currentUser()

Retrieves the current user from the Project api.

Formio.currentUser().then(function(user) {
  console.log(user);
});

Formio.accessInfo()

Fetches the accessInfo from the current baseURL project.

Formio.accessInfo().then(function(access) {
  console.log(access);
});

Formio.setUser(<user>)

Sets the current user object within localStorage.

Formio.getUser()

Gets the current logged in user object out of localStorage.

Formio.loadProjects(<query>)

Loads all of the projects that your account has access to.

Formio.loadProjects().then(function(projects) {
  console.log(projects);
});

Formio.clearCache()

Clears out the static http request cache. This will ensure that the next API request actually hits the network and gets new data.

Formio.clearCache();
Formio.loadProjects().then(function(projects) {
  console.log(projects);
});

Formio.logout()

Logs out of the current API and removes the stored JWT token.

In addition, this library also provides plugin support to the submissions being made so that libraries like our Offline Mode can be utilized.