API Handling network issues

Unpoly lets you handle many types of connection problems. The objective is to keep your application accessible as the user's connection becomes flaky or goes away entirely.

Disconnects

In a vanilla HTML document, clicking a link while offline will replace your app with a standard error screen, no questions asked:

Interacting with an Unpoly-enhanced link or form while offline will not change the page. Instead Unpoly lets you define your own disconnect handling. E.g. you may choose to display an error, or to offer a button that retries the failed request.

To handle connection loss, pass an { onOffline } option or set an [up-on-offline] attribute. When the device gets disconnected before or during a request, the callback is called with an up:fragment:offline argument:

<a href="/path" up-follow up-on-offline="if (confirm('You are offline. Retry?')) event.retry()">
  Post bid
</a>

You may also configure a global handler that listens to up:fragment:offline:

up.on('up:fragment:offline', function(event) {
  if (confirm('You are offline. Retry?')) event.retry()
})

You may also do something other than retrying, like substituting content:

up.on('up:fragment:offline', function(event) {
  up.render(event.renderOptions.target, { content: "You are offline." })
})

Expired pages remain accessible while offline

Even without a connection, cached content will remain navigatable for 90 minutes. This means that an offline user can instantly access pages that they already visited this session.

While offline, cache revalidation of expired content will fail.

When revalidation fails, or when accessing uncached content, Unpoly will run onOffline() callbacks and emit up:fragment:offline. The page will not be changed unless your code says so.

Limitations to offline support

While Unpoly lets you handle disconnects, some parts are missing for full "offline" support:

• To fill up the cache the device must be online for the first part of the session (warm start)
• The cache is still in-memory and dies with the browser tab

For a comprehensive offline experience (cold start) we recommend a service worker or a canned solution like UpUp (no relation to Unpoly).

Flaky connections

Often our device reports a connection, but we're effectively offline:

• Smartphone in EDGE cell
• Car drives into a tunnel
• Overcrowded Wi-fi with massive packet loss

Unpoly handles flaky connections with timeouts. Timeouts will also run onOffline() callbacks and emit up:fragment:offline. This means that your existing disconnect handling (see behavior) can also be used to handle flaky connections.

All requests have a default timeout of 90 seconds. You may use different timeouts for individual requests by passing an { timeout } option or by setting an [up-timeout] attribute.

Slow server responses

Even with a great network connection, your server make take long to render expensive pages.

When requests are taking too long to respond, an animated progress bar is shown.

You may also style fragments while they are loading.