Poller

The poller component allows you to design solutions that run in the background and which show the user progress on the browser.

The general sequence of events is:

  • You start a process in the background.
  • You show a page with the poller on it.
  • The poller calls a URL to assess progress.
  • When the back-end process is complete, the user is shown a completion message and/or redirected to the next page.

There are three parts to the poller:

  • HTML markup to be inserted in the page.
  • The Poller JavaScript component that runs in the browser.
  • Conventions for returning information to the poller.

HTML markup

Poller is controlled by HTML classes and options coded into a data-options attribute. The general format of a poller markup is given below.

<div class="poller" data-options="...">
  <div class="poller-start">
    Start content, for example:
    <p>Reading file...</p>
  </div>
  <div class="poller-progress">
    Content to show during progress, for example:
    <p>Validating file...</p>
  </div>
  <div class="poller-end">
    Content to show when process has completed, for example:
    <p>Thank you for your submission.</p>
  </div>
  <div class="poller-timeout">
    Content to show when process has not ended in time, for example:
    <p>Thank you for your submission. Please check back later to see status.</p>
  </div>
  <div class="poller-fallback">
    Content to show when poller is not available, for example:
    <p>Thank you for your submission. Please check back later to see status.</p>
  </div>
  <div class="poller-finally">
    Content to show after poller-end, poller-timeout or poller-fallback,
    but only when there is no redirect, for example:
    <p><a class="btn btn-default" href="...">Continue</a></p>
  </div>
</div>

The poller-progress and poller-fallback sections are required. The other sections are optional. poller-start and poller-end both default to poller-progress. poller-timeout defaults to poller-fallback.

If the poller JavaScript component is not available, only poller-fallback and poller-finally will be available.

Poller options

The data-options attribute on the poller element control the poller functionality. This is a JSON string, with the following options:

{
  "url": "pollURL",
  "data": {
    "paramName":"paramValue",
    ...
  },
  "delay": delay,
  "interval": interval,
  "timeout": timeout,
  "endURL": "endURL",
  "fallbackURL": "fallbackURL",
  "redirectDelay": redirectDelay,
  "lock": true|false,
  "lockMessage": false|"lockMessage",
  "fallbackMessage": "fallbackMessage",
  "l10n": "l10n"
}
pollURL URL which should be called to determine the progress of the process.
data name/value pairs to be passed with the call. For a HTTP GET these will be passed in the URL. For a HTTP POST these will be passed in the body of the request using form encoding.
delay Number of seconds before the first call to the pollURL. Defaults to the same as interval.
interval Number of seconds between the end of one call to the pollURL and the next. Default is 10.
timeout Number of seconds after which the polling should be abandoned. Default is 60.
endURL URL to which to redirect user after a successful end of the processing. This can be overridden by a redirect returned from the poll call, and if not provided no redirect is performed.
fallbackURL URL to which to redirect the user if there is a timeout or error in the processing. If not provided, no redirect is performed.
redirectDelay Number of seconds to wait before performing a redirect. Default is 0. This is useful if you want to give the user an opportunity to read the end or fallback message.
lock Set to true to lock the screen while the poll is in progress. Default is false.
lockMessage Content to show if page is locked. Defaults to standard spinner. Set to false to not show content.
fallbackMessage Content to show if page is locked and fallback is reached. Default is to keep lockMessage.
l10n Localization id to be added to messages returned from the call. This is not added to the content, as appropriate localization ids need to be added to the page markup to support the default content blocks.

Call conventions

The URL called by the poller returns information using normal script conventions, plus an additional parameter to indicate whether the process is still running. The following may be returned.

running Set to true to indicate the process is still running. Any other value (included omitted) is assumed to be false.
content

If running is true, content to replace poller-progress content. Default is nothing, in which case content is not replaced.

If running is not true, content to replace poller-end content. Default is nothing, in which case content is not replaced.
message

If lock is true, message to use on the lock page.
redirect When running is not true, redirect to which to send the user. Overrides the endURL in the options. If not given and no endURL, no redirect is performed.

Generally solutions will want to return content if the lock options is not set, or message if the lock option is set.

Note that content and message should not contain HTML markup (this is restriction of content filtering).

When running is not set It can make sense to return both content (or message) and redirect, because the user will see the content while the browser loads the new page.

If the script returns an error, the error is logged in the browser console and the fallback is invoked.