Offline Mode

This section describes how the Form.io Offline Mode system works.

Introduction

The Form.io offline mode system enables any application to render, use, and submit forms while disconnected from the internet. This works by hooking into the Form.io core renderer module system using a Fetch plugin that intercepts any API calls made by the Form.io rendering framework. While offline, any request that would normally go through the API is instead redirected to the PouchDB, a local browser based database that utilizes IndexedDB to store data. Once the device comes back online, the offline plugin will empty the queue by re-submitting the APIs. Any failed API will then be re-added to the queue.

Offline Module

To add Offline support to an application, use the Form.io Offline Module. This module requires a Library License key with the offline module enabled.

Contact [e-mail] to get the Library License key.

For more detailed information, refer to The Form.io Offline Plugin Documentation page.

Browser Compatibility

The Offline Mode plugin uses IndexedDB. Any browser that is used must support this technology. Currently, IndexedDB is compatible with all modern browsers including:

• Chrome v38+

• Safari 7.1+

• IE 11+

• Firefox 13+

Module Overview

The offline module operates in two stages: First, any submissions that fail due to a network iterruptions are queued. Next, all submissions to the server are cached so they are available within the application while still offline.

Submission Queue

While offline with the module enabled, Form submissions work differently. All form submissions, submission edits, and submission deletions are added to a queue. If the application is online, the queue will be emptied immediately, behaving transparently. When the application is offline, the submissions stay in the queue until the application goes back online. Queued form submissions will still behave as if the submission was successful.

Whenever a submission is made, the submission is added to the end of the offline queue, until the queue is flushed to the server. If a network error occurs, the process is stopped the submission will stay in the queue until the next try. The offline queue is a first-in first-out queue; the first item added will be the first sent to the server.

If a submission error occurs when attempting to send the submission to the server (such as a validation failure), the “offline.formError” event is triggered. This stops the queue flush and will wait for the user to fix the error before proceeding.

Submission Caching

When submissions are fetched from the server, the request is first sent to the server as usual. If a network error occurs, indicating the application is offline, the request is redirected to the offline submission cache, and the cached results are returned instead. If the request successfully hits the server the returned submissions are added to the offline cache, and the results are returned to the application.

Using the Offline Plugin

To use the offline module, install the offline plugin from NPM, then add the offline plugin to Formio.plugins. Retrieve the instance of your offline plugin via the Formio.getPlugin method.

Setup Offline Module

Complete the following steps to enable the Offline Module:

1. Install the offline-plugin library by running the following command:

npm install @formio/offline-plugin

1. Following the installation, integrate the module into the application with the following code:

import { Formio } from '@formio/js';
import { OfflinePlugin } from '@formio/offline-plugin';

Formio.license = 'yourLibraryLicenseKey';

Formio.setBaseUrl('baseurl');
Formio.setProjectUrl('baseurl/projectalias');

Formio.use(OfflinePlugin(
  'myproject-offline',    // The name of this offline instance.
  'baseurl/projectalias', // Your project URL
  'path/to/project.json', // If available, the exported project.json file.
  {}                      // Offline Plugin Options
));

1. Once the module has been initialized, access the instance of this plugin anywhere in the application using the getPlugin API as follows:

const offlinePlugin = Formio.getPlugin('myproject-offline');

Navigate to the following link for more information about the Form.io CDNs

Once you do this, the offline module will introduce a new global called FormioOfflinePlugin, which you can now register the OfflinePlugin as you did above using the following script.

Saving Submissions Offline

To save submission offline, simply make a submission while offline.

This can be testing using the browser's developer or advanced tools to set the connectivity throttle to to offline. Following that, make a submission using the form. Verify that this submission has been saved by using the browsers developer or advanced tools to review the application attributes and navigating to the local storage. Look for submissions in the following location:

IndexDB storage > pouchformio{projectalias}-submissionCache > by-sequence > doc_id_rev and viewing the entries there

By default when after a submission on a form, further submissions to the form will be updates (PUT) to the first submission made. To make new submissions (POST) on every click of the Submit button, reset the webform instance submission after each submit. Do this by listening to the submit event and setting the submission data to an empty object like so:

Formio.createForm(document.getElementById('formio'), 'yourformendpoint').then((form) => {
  form.on('submit', () => {
    form.submission = {data: {}};
  })
});

Viewing the Submission Count

To view the number of offline submission currently in the IndexDB, use the submissionQueueLength function provided by the offline module. To get the submission count, first get the offline plugin instance using Formio.getPlugin and then call the submissionQueueLength function, as follows:

const offlinePlugin = Formio.getPlugin('myproject-offline');
const offlineSubmissionCount = offlinePlugin.submissionQueueLength()

Submitting the Offline Submissions

Once the application is back online, the queued offline submissions will be applied when either of the following conditions are met:

1. Another submission is made to the form. This will submit all queued offline submission plus the additional submission made to the form.

2. The dequeueSubmissions function is called. When back online this function will take the queued submissions from IndexDB and submit them to the form:

const offlinePlugin = Formio.getPlugin('myproject-offline');
offlinePlugin.dequeueSubmissions();

Loading Forms and Submissions Offline

With the Offline Module registered for a particular project, all load requests for forms and submissions in that project are automatically saved and updated in an offline browser data store.

For example, to make all submissions of a form available offline, call formio.loadSubmissions() at some point in the app while online. Below is an example of loading a submission offline:

// While online
const formio = new Formio('baseurl/projectalias/formalias');
formio.loadSubmissions(); // Loads and caches the submissions
// Then when offline
new Formio('baseurl/projectalias/formalias/submission/submissionid');
formio.loadSubmission().then((submission) => {
    console.log(submission); // Cached submission
});
// When your app goes offline, requests to load a form or submission will automatically return the data cached offline, if available.

Below is an example of loading a form offline using formio.loadForm():

// While online
const formio = new Formio('baseurl/projectalias/formalias');
formio.loadForm();
// While offline
Formio.createForm(document.getElementById('formio'), 'baseurl/projectalias/formalias');
// This creates a new form even though you are offline.
// Because you called loadForm while offline, this has cached the form in IndexDB.
// Any future requests to the same form endpoint will look in IndexDB for the form json

Deleting Submissions Offline

When a submission is deleted while offline, it won't be deleted from the local DB, but it is marked as '_deleted'. The submission will then be deleted from the local DB only when the application is back online and the 'DELETE' request is sent.

To prevent showing deleted submissions in offline mode, set the notToShowDeletedOfflineSubmissionsflag in the Offline plugin's config to 'true':

Formio.use(OfflinePlugin(
  'myproject-offline',
  'baseurl/projectalias',
  '',
  {notToShowDeletedOfflineSubmissions: true}
))

Handling Submission Queue Errors

Some queued submissions may fail when they are sent once the application is online (for example, unique validation fails on the server). In the event a queued submission fails, the queue is automatically stopped and events are triggered to allow the application to resolve the failed submission before continuing.

Applications using the Offline Module must implement a process to handle these errors. The application may decide to prompt the user to fix the form submission or simply ignore the submission and restart the queue.

SDK

Review the following information to successfully integrate the Offline Module within an application.

OfflinePlugin(name, projectUrl, [projectJsonPath], [options])

Factory method that returns a Form.io Module which contains a new instance of the FormioOfflinePlugin class, which controls the offline mode for this project.

• name: This is a name determined by developers to contextualize the offline mode for this project.

• projectUrl: This is the URL of the project this offline mode plugin is attached to.

• projectJson (optional): Providing this will provide the default project.json of the project. Get this by exporting the project. Without providing this this, the application will need to request the Form online before it will cache that form to be used offline. By providing the URL to this file, the offline mode will use the offline form by default and not have to send a request to the API.

• options (optional): optional configurations to the offline plugin

new FormioOfflinePlugin(projectUrl, [projectJsonPath])

Creates a new offline module instance for a project.

• projectUrl: This is the URL of the project this offline mode plugin is attached to.

• projectJson (optional): Providing this will provide the default project.json of the project. Get this by exporting the project. Without providing this, then the application will need to request the Form online before it will cache that form to be used offline. By providing the url to this file, the offline mode will use the offline form by default and not have to send a request to the API.

Plugin methods

plugin.forceOffline(offline)

Forces all requests for this plugin's project into offline mode, even when a connection is available.

plugin.isForcedOffline()

Returns true if this plugin is currently forced offline.

plugin.clearOfflineData()

Clears all offline data. This includes offline cached forms and submissions, as well as submissions waiting in the offline queue.

plugin.dequeueSubmissions(skipError: boolean, fromIndex: number, forceDequeue: boolean, predicate: any)

Starts to process the submission queue. All requests in the offline submission queue will be sent in the order they were made. Successful requests will either resolve their original promise or trigger the offline.formSubmission event from Formio.events. A failed request will stop processing the queue and trigger the offline.formError event. The app must handle this event to resolve the failing requests and restart the queue.

plugin.submissionQueueLength()

Returns the number of submission requests currently in the offline queue.

plugin.getNextQueuedSubmission()

Returns the next request in the submission queue.

plugin.setNextQueuedSubmission(request)

Sets the next request in the submission queue to request.

Use this to fix a failed submission and then call dequeueSubmissions() to resubmit and continue the queue.

plugin.skipNextQueuedSubmission()

Discards the next request in the submission queue.

Use this to ignore a failed submission and then call dequeueSubmissions() to continue to the next queued request.

Events

You can listen to these events by adding listeners to the Formio.events EventEmitter.

NOTE: When using the Angular ngFormio library, listen for these events in the Angular scope by adding formio. before each event name.

offline.queue

Triggered when a submission is added to the submission queue.

offline.dequeue

Triggered when the submission queue starts to process a submission.

offline.requeue

Triggered when a submission fails and is added back to the front of the submission queue.

offline.formSubmission

Triggered when a queued submission is successfully submitted. This is not called if the original promise of the request can be resolved (in which case it behaves like a normal online submission).

offline.formError

Triggered when a queued submission returns an error. This means the app needs to either fix the submission or skip it, and restart the queue.

offline.queueEmpty

Triggered when the queue becomes empty after dequeuing.

Request Options

skipQueue

YSet skipQueue to save a submission immediately, skipping the queue. This will disable offline queuing for that submission. For example:

formio.saveSubmission(submission, {skipQueue: true});

If you are using the Angular ngFormio library, you can set the skipQueue option with formio-options:

<formio src="userLoginForm" formio-options="{skipQueue: true}"></formio>

FAQs

Where is the form/submission data stored offline?

This plugin uses IndexedDB to store data.

How can I tell if my requests were loaded from the offline cache?

Requests that return data stored offline will have the offline property set to true.

Can I login while offline?

Unfortunately, authentication will not work in offline mode. It is highly recommended to use the skipQueue option when submitting authentication forms.