Learn Background requests

A background request is a request the user is not actively waiting for, like preloading a link or polling a fragment. Background requests never show the progress bar, and they wait while requests for the user's own clicks and submissions are sent first.

What changes for a background request

Unpoly treats a background request differently in two ways:

• It never shows the progress bar. A background request does not emit an up:network:late event, no matter how long it takes. The progress bar only appears for requests the user is waiting for.
• It has a lower priority. Unpoly sends at most 6 requests at the same time. When more requests are waiting, requests in the foreground are sent first. A background request is only sent when no foreground request is waiting.

Loading in the background does not change how a request is aborted, cached or styled with feedback classes. up.network.isBusy() also returns true while a background request is loading.

Which requests load in the background

The following requests load in the background by default:

• Requests from preloading a link.
• Requests from polling a fragment.
• Requests that revalidate cached content after it was rendered.

Links, forms and deferred content load in the foreground by default. A slow request from one of them shows the progress bar.

Loading in the background

To load a link, form or deferred element in the background, set an [up-background] attribute. From JavaScript, pass a { background: true } option to a rendering function or to up.request().

For example, a form that publishes a post can save a draft while the user types. The user is not waiting for the draft to be saved, so it should not show the progress bar or delay the user's clicks:

<form method="post" action="/posts" data-autosave="/drafts">
  <textarea name="text"></textarea>
  <button type="submit">Publish</button>
</form>

A compiler watches the form and sends its fields to the draft URL in the background:

up.compiler('form[data-autosave]', function(form, { autosave: url }) {
  up.watch(form, { delay: 2000 }, function() {
    up.request(url, { method: 'post', params: up.Params.fromForm(form), background: true }) // mark: background: true
  })
})

To load a polling request in the foreground, set [up-background="false"] on the [up-poll] element.

When the user waits for a background request

Sometimes the user needs the response of a request that is still loading in the background. For example, the user hovers over a link and Unpoly starts preloading it. Before the preload request has finished, the user clicks the link.

Unpoly does not make a second request in this case. The click reuses the preload request from the cache, and the preload request is moved into the foreground. From then on it is treated like any other foreground request:

• When the request takes longer than usual, the progress bar appears.
• When the request is still waiting to be sent, it is sent before any background request.

This happens whenever a foreground request reuses a cached request that is still loading in the background.

Detecting background requests

To check if a request is loading in the background, read its up.Request#background property. Network events like up:request:load or up:fragment:loaded give you the request as event.request.

For example, an app that warns users before their session times out may restart its idle timer with every request. Requests from polling or preloading are not user activity, so the listener skips them:

up.on('up:request:load', function(event) {
  if (!event.request.background) { // mark: event.request.background
    restartIdleTimer()
  }
})

The property is false for a background request that was moved into the foreground.