Module: Countdown

Create the countdown plugin.

Sets an element to show the time remaining until a given instant.

Expects HTML like:

<div></div>

Provide inline configuration like:

<div data-countdown="name: 'value', ..."></div>
Source:
Example
$(selector).countdown({until: +300})

Extends

  • JQPlugin

Members

(inner) defaultOptions

Default settings for the plugin.
Properties:
Name Type Attributes Default Description
until Date | number | string <optional>
 The date/time to count down to, or number of seconds offset from now, or string of amounts and units for offset(s) from now: 'Y' years, 'O' months, 'W' weeks, 'D' days, 'H' hours, 'M' minutes, 'S' seconds. One of until or since must be specified. If both are given since takes precedence.
since Date | number | string <optional>
 The date/time to count up from, or number of seconds offset from now, or string of amounts and units for offset(s) from now: 'Y' years, 'O' months, 'W' weeks, 'D' days, 'H' hours, 'M' minutes, 'S' seconds. One of until or since must be specified. If both are given since takes precedence.
timezone number <optional>
 null The timezone (hours or minutes from GMT) for the target times, or null for client local timezone.
serverSync CountdownServerSyncCallback <optional>
 null A function to retrieve the current server time for synchronisation.
format string <optional>
 'dHMS' The format for display - upper case to always show, lower case to show only if non-zero, 'Y' years, 'O' months, 'W' weeks, 'D' days, 'H' hours, 'M' minutes, 'S' seconds.
layout string <optional>
 ''

Build your own layout for the countdown.

Indicate substitution points with '{desc}' for the description, '{sep}' for the time separator, '{pv}' where p is 'y' for years, 'o' for months, 'w' for weeks, 'd' for days, 'h' for hours, 'm' for minutes, or 's' for seconds and v is 'n' for the period value, 'nn' for the period value with a minimum of two digits, 'nnn' for the period value with a minimum of three digits, or 'l' for the period label (long or short form depending on the compact setting), or '{pd}' where p is as above and d is '1' for the units digit, '10' for the tens digit, '100' for the hundreds digit, or '1000' for the thousands digit.

If you need to exclude entire sections when the period value is zero and you have specified the period as optional, surround these sections with '{p<}' and '{p>}', where p is the same as above.

Your layout can just be simple text, or can contain HTML markup as well.
compact boolean <optional>
 false true to display in a compact format, false for an expanded one.
padZeroes boolean <optional>
 false true to add leading zeroes.
significant number <optional>
 0 The maximum number of periods with non-zero values to show, zero for all.
description string <optional>
 '' The description displayed for the countdown.
expiryUrl string <optional>
 '' A URL to load upon expiry, replacing the current page.
expiryText string <optional>
 '' Text to display upon expiry, replacing the countdown. This may be HTML.
alwaysExpire boolean <optional>
 false true to trigger onExpiry even if the target time has passed.
onExpiry CountdownExpiryCallback <optional>
 null Callback when the countdown expires - receives no parameters and this is the containing element.
onTick CountdownTickCallback <optional>
 null Callback when the countdown is updated - receives number[7] being the breakdown by period (years, months, weeks, days, hours, minutes, seconds - based on format) and this is the containing element.
tickInterval number <optional>
 1 The interval (seconds) between onTick callbacks.
Source:
Examples
until: new Date(2013, 12-1, 25, 13, 30)
until: +300
until: '+1O -2D'
			
since: new Date(2013, 1-1, 1)
since: -300
since: '-1O +2D'
			
timezone: +10
timezone: -60
			
layout: '{d<}{dn} {dl}{d>} {hnn}:{mnn}:{snn}'
			
onExpiry: function() {
  ...
}
			
onTick: function(periods) {
  var secs = $.countdown.periodsToSeconds(periods);
  if (secs < 300) { // Last five minutes
    ...
  }
}

(inner) name

The name of the plugin.
Default Value:
  • 'countdown'
Source:

(inner) regionalOptions

Localisations for the plugin. Entries are objects indexed by the language code ('' being the default US/English). Each object has the following attributes.
Properties:
Name Type Attributes Default Description
labels Array.<string> <optional>
 ['Years','Months','Weeks','Days','Hours','Minutes','Seconds'] The display texts for the counter periods.
labels1 Array.<string> <optional>
 ['Year','Month','Week','Day','Hour','Minute','Second'] The display texts for the counter periods if they have a value of 1. Add other labelsn attributes as necessary to cater for other numeric idiosyncrasies of the localisation.
compactLabels Array.<string> <optional>
 ['y','m','w','d'] The compact texts for the counter periods.
whichLabels CountdownWhichLabelsCallback <optional>
 null A function to determine which labelsn to use.
digits Array.<string> <optional>
 ['0','1',...,'9'] The digits to display (0-9).
timeSeparator string <optional>
 ':' Separator for time periods in the compact layout.
isRTL boolean <optional>
 false true for right-to-left languages, false for left-to-right.
Source:
Example
whichLabels: function(num) {
  return (num > 1 ? 0 : 1);
}

Methods

(inner) getTimes(elem) → {Array.<number>}

Return the current time periods, broken down by years, months, weeks, days, hours, minutes, and seconds.
Parameters:
Name Type Description
elem Element The containing element.
Source:
Returns:
The current periods for the countdown.
Type
Array.<number>
Example
var periods = $(selector).countdown('getTimes')

(inner) lap(elem)

Pause a countdown widget at the current time. Stop the display but keep the countdown running.
Parameters:
Name Type Description
elem Element The containing element.
Source:
Example
$(selector).countdown('lap')

(inner) pause(elem)

Pause a countdown widget at the current time. Stop it running but remember and display the current time.
Parameters:
Name Type Description
elem Element The containing element.
Source:
Example
$(selector).countdown('pause')

(inner) periodsToSeconds(periods) → {number}

Convert a set of periods into seconds. Averaged for months and years.
Parameters:
Name Type Description
periods Array.<number> The periods per year/month/week/day/hour/minute/second.
Source:
Returns:
The corresponding number of seconds.
Type
number
Example
var secs = $.countdown.periodsToSeconds(periods)

(inner) resume(elem)

Resume a paused countdown widget.
Parameters:
Name Type Description
elem Element The containing element.
Source:
Example
$(selector).countdown('resume')

(inner) resync()

Resynchronise the countdowns with the server.
Source:
Example
$.countdown.resync()

(inner) toggle(elem)

Toggle a paused countdown widget.
Parameters:
Name Type Description
elem Element The containing element.
Source:
Example
$(selector).countdown('toggle')

(inner) toggleLap(elem)

Toggle a lapped countdown widget.
Parameters:
Name Type Description
elem Element The containing element.
Source:
Example
$(selector).countdown('toggleLap')

(inner) UTCDate(tz, year, monthopt, dayopt, hoursopt, minsopt, secsopt, msopt) → {Date}

Convert a date/time to UTC.
Parameters:
Name Type Attributes Description
tz number The hour or minute offset from GMT, e.g. +9, -360.
year Date | number the date/time in that timezone or the year in that timezone.
month number <optional>
 The month (0 - 11) (omit if year is a Date).
day number <optional>
 The day (omit if year is a Date).
hours number <optional>
 The hour (omit if year is a Date).
mins number <optional>
 The minute (omit if year is a Date).
secs number <optional>
 The second (omit if year is a Date).
ms number <optional>
 The millisecond (omit if year is a Date).
Source:
Returns:
The equivalent UTC date/time.
Type
Date
Example
$.countdown.UTCDate(+10, 2013, 12-1, 25, 12, 0)
$.countdown.UTCDate(-7, new Date(2013, 12-1, 25, 12, 0))