Offline Mode

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

Introduction

The Form.io offline mode system enables any application to disconnect from the internet and still be able to load forms, load submissions, and submit forms while the device is offline. This works by hooking into the Form.io core renderer module system by creating a Fetch plugin that intercepts any API calls made by the Form.io rendering framework, where once offline, any request that would normally go through the API's instead redirected to the PouchDB which is a local browser based database that utilizes IndexedDB to store data. Then, 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 your application, you must use the Form.io Offline Module. To use this application, you should have a Library License key with offline module enabled.

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

Installation

npm install @formio/offline-plugin

Once this library is installed, you can now use it within your application using the following code.

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

Formio.license = 'yourLibraryLicenseKey';
Formio.use(OfflinePlugin(
  'myproject-offline',         // The name of this offline instance.
  'https://myproject.form.io', // Your project URL
  'path/to/project.json'       // If available, the exported project.json file.
));

For more detailed information, you can go to The Form.io Offline Plugin Documentation page.

Browser Compatibility

Since our 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+

The offline plugin operates in two parts. First, queueing any submissions that fail due to a network connect, and second, caching all submissions from the server so they are available when offline.

Submission Queue

Whenever a submission is made, the submission is added to the end of the offline queue, and the queue is attempted to be flushed to the server. If a network error occurs it will simply stop and leave the submission in the queue for the next try. The offline queue is a first-in first-out queue so 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 will be triggered. This will then stop the queue flush and 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. If a network error occurs the request is redirected to the offline submission cache and the cached results are returned instead. If the request succeeded from the server the returned submissions are added the the offline cache and the results are returned to the application.

Using the Offline Mode Plugin

To use this module, you will use the same process described @ https://help.form.io/developers/modules#using-a-module but for this module. This will look like the following in your application.

import { Formio } from 'formiojs';
import { OfflinePlugin } from '@formio/offline-plugin';
Formio.use(OfflinePlugin(
  'myproject-offline', // The name of this offline instance.
  'https://myproject.form.io', // Your project URL
  'path/to/project.json' // OPTIONAL: the exported project.json file.
));

The arguments that you provide for the OfflinePlugin method are found below in the SDK section.

If you are using any of the Angular or React, wrappers, you may need to import the Formio instance from those modules instead as follows.

import { Formio } from '@formio/angular';

Accessing the module

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

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

Embedding

This plugin can be embedded within a website where it renders a form with offline mode enabled. This can be done with the following syntax.

<script src="https://cdn.form.io/formiojs/formiojs.form.min.js"></script>
<script src="https://yourdomain.com/assets/offline/formio.offline.min.js"></script>

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.

<script type="application/javascript">
  Formio.use(FormioOfflinePlugin.OfflinePlugin('myproject-offline', 'https://myproject.form.io', 'path/to/project.json'));
</script>

You can now embed your form as you normally would and it will use the offline mode system.

Deployed Servers

Deployed installations may also need to provide baseUrl and projectUrl. These tell the renderer the Base URL as well as the project URL being used when embedding the offline script.

<script type="application/javascript">
  Formio.setBaseUrl('https://forms.yourdomain.com');
  Formio.setProjectUrl('https://forms.yourdomain.com/yourproject');
  Formio.use(FormioOfflinePlugin.OfflinePlugin('myproject-offline', 'https://forms.yourdomain.com/yourproject', 'path/to/project.json'));
</script>

SDK

OfflinePlugin(name, projectUrl, [projectJsonPath])

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 you come up with to contextualize your 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 your project. You can get this by exporting your project. If you do not provide this, then your 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.

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 your project. You can get this by exporting your project. If you do not provide this, then your 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.

Saving forms and submissions offline

Once you register a plugin for a particular project, all load requests for forms and submissions in that project will automatically save and update in an offline browser data store.

For example, you can have all submissions for a form available offline if you call formio.loadSubmissions() at some point in your app while online.

Loading forms and submissions offline

When your app goes offline, requests to load a form or submission will automatically return the data cached offline, if available.

Prefetching Forms

When utilizing Offline mode, utilize the Prefetch method, which embeds the Form JSON instead of the embed URL. This will ensure that API fetch-based components, like the Select Resource component will function properly. Prefetching will save the state of the API-driven value. Configure the form for offline mode:

Embed the Form JSON inside the form:any bracket

Submitting forms offline

Form submissions work a little bit differently when this plugin is registered. All form submissions, submission edits, and submission deletions are added to a queue. If the app is online, the queue will be emptied immediately and behave like normal. But when the app is offline, the submissions stay in the queue until the app goes back online. Until then, Formio.js will behave as if the submission was successful.

The queue will automatically start to empty when a submission is successfully made online, or you may manually start it.

Contact [e-mail] for access to the offline repository

Deleting submissions offline

When you delete a submission offline, this won't be deleted from the local DB, it will be just marked as '_deleted'. The submission will be deleted from the local DB only in online when the 'DELETE' request is sent. You can prevent showing deleted submissions in offline by setting the 'notToShowDeletedOfflineSubmissions' flag in the plugin's config to 'true'.

Handling submission queue errors

Some queued submissions may fail when they are sent online (ex: unique validation fails on the server). In the event a queued submission fails, the queue is stopped and events are triggered to allow your app to resolve the bad submission before continuing. It's up to your app to decide how to handle these errors. Your app may decide to prompt the user to fix the form submission or simply ignore the submission, and restart the queue.

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()

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.

You can 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.

You can 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: if you are using the Angular ngFormio library, you can 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

You may set 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.