Ajax.PeriodicalUpdater
new Ajax.PeriodicalUpdater(container, url[, options])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, 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 PeriodicalUpdater
You can pull the brake on a running 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).
