constructor new Ajax.PeriodicalUpdater

View source on GitHub →

new Ajax.PeriodicalUpdater(container, url[, options])
  • container (String | Element) – The DOM element whose contents to update as a result of the Ajax request. Can be a DOM node or a string that identifies a node's ID.
  • url (String) – The URL to fetch. When the same-origin policy is in effect (as it is in most cases), url must be a relative URL or an absolute URL that starts with a slash (i.e., it must not begin with http).
  • options (Object) – Configuration for the request. See the Ajax for more information.

Creates a new Ajax.PeriodicalUpdater.

Periodically performs an AJAX request and updates a container's contents based on the response text. Offers a mechanism for "decay," which lets it trigger at widening intervals while the response is unchanged.

This object addresses the common need of periodical update, which is used by all sorts of "polling" mechanisms (e.g. in an online chatroom or an online mail client).

The basic idea is to run a regular Ajax.Updater at regular intervals, monitoring changes in the response text if the decay option (see below) is active.

Additional options

Ajax.PeriodicalUpdater features all the common options and callbacks (see the Ajax for more information), plus those added by Ajax.Updater. It also provides two new options that deal with the original period, and its decay rate (how Rocket Scientist does that make us sound, uh?!).

Option Default Description
frequency 2 Okay, this is not a frequency (e.g 0.5Hz), but a period (i.e. a number of seconds). Don't kill me, I didn't write this one! This is the minimum interval at which AJAX requests are made. You don't want to make it too short (otherwise you may very well end up with multiple requests in parallel, if they take longer to process and return), but you technically can provide a number below one, e.g. 0.75 second.
decay 1 This controls the rate at which the request interval grows when the response is unchanged. It is used as a multiplier on the current period (which starts at the original value of the frequency parameter). Every time a request returns an unchanged response text, the current period is multiplied by the decay. Therefore, the default value means regular requests (no change of interval). Values higher than one will yield growing intervals. Values below one are dangerous: the longer the response text stays the same, the more often you'll check, until the interval is so short your browser is left with no other choice than suicide. Note that, as soon as the response text does change, the current period resets to the original one.

To better understand decay, here is a small sequence of calls from the following example:

new Ajax.PeriodicalUpdater('items', '/items', {
  method: 'get', frequency: 3, decay: 2
});
Call# When? Decay before Response changed? Decay after Next period Comments
1 00:00 2 n/a 1 3 Response is deemed changed, since there is no prior response to compare to!
2 00:03 1 yes 1 3 Response did change again: we "reset" to 1, which was already the decay.
3 00:06 1 no 2 6 Response didn't change: decay augments by the decay option factor: we're waiting longer now…
4 00:12 2 no 4 12 Still no change, doubling again.
5 00:24 4 no 8 24 Jesus, is this thing going to change or what?
6 00:48 8 yes 1 3 Ah, finally! Resetting decay to 1, and therefore using the original period.
Disabling and re-enabling a Ajax.PeriodicalUpdater

You can pull the brake on a running Ajax.PeriodicalUpdater by simply calling its stop method. If you wish to re-enable it later, just call its start method. Both take no argument.

Beware! Not a specialization!

Ajax.PeriodicalUpdater is not a specialization of Ajax.Updater, despite its name. When using it, do not expect to be able to use methods normally provided by Ajax.Request and "inherited" by Ajax.Updater, such as evalJSON or getHeader. Also the onComplete callback is hijacked to be used for update management, so if you wish to be notified of every successful request, use onSuccess instead (beware: it will get called before the update is performed).