Instance Settings
A separate countdown instance is created for each targetted division or span:
$(selector).countdown({until: liftoffTime});Each instance may have different settings, e.g.
$(selector).countdown({until: liftoffTime, format: 'HMS'});Below are the options that may be applied to each countdown instance.
A note on Date - the JavaScript Date constructor expects
the year, month, and day as parameters. However, the month ranges from 0 to 11.
To make explicit what date is intended (does a month of 3 mean March or April?)
I specify the month from 1 to 12 and manually subtract the 1.
Thus the following denotes 25 December, 2014.
$(selector).datepick({minDate: new Date(2014, 12-1, 25)});alwaysExpire | compact | compactLabels | description | digits | expiryText | expiryUrl | format | isRTL | labels | labels1 | layout | onExpiry | onTick | padZeroes | serverSync | significant | since | tickInterval | timeSeparator | timezone | until | whichLabels
| Name | Type | Default | Comments |
|---|---|---|---|
| until | Date or string or number | null | Set the time at which the countdown expires. This may be an absolute date,
e.g. new Date(2010, 1 - 1, 1), or a value relative to the
current time. Provide a numeric value to offset by that many seconds,
e.g. +300, or a string value to indicate both the type of units
and the amount, e.g. '+2d'. Use 'y' for years, 'o' for months,
'w' for weeks, 'd' for days, 'h' for hours, 'm' for minutes, or 's' for seconds.
Upper or lower case characters may be used.
Multiple offsets may be combined into one setting, e.g. '+2h +30m'.
When providing an actual date you can use the
UTCDate function
or the timezone setting
to take account of a different timezone for the expiry.One of since or this setting should always be supplied.
The countdown displays zeros if this time has passed.Since 1.2.1 - setting as a relative value. |
| since | Date or string or number | null | Set the time from which the countdown counts up. This may be an absolute date or a
value relative to the current time (see until
for more information).One of until or this setting should always be supplied.
If both are provided, since has priority.
The countdown displays zeros if this time has not yet arrived.
The onExpiry event is never triggered.Since 1.2.0. Since 1.2.1 - setting as a relative value. |
| timezone | number | null | Set the time zone offset from GMT, either as hours or minutes, for the countdown/up.
For example, a target time in Sydney, Australia, would have a value of +10 or +600.
If not specified no offset is applied.
Alternately, use the UTCDate
function to set the target time directly.Since 1.5.1 - replaces serverTime. |
| serverSync | function | null | Synchronise the client's time with that of the server by providing
a function that returns the current server date and time.
This date and time should take into account the server's timezone
and any difference between that time and the client's is applied
to the countdown when it is started or changed. Note that this function is only called once per server and the value is cached and used for all subsequent countdowns for that server. The following example uses a PHP program on the server to return the current server time in a format that can be used directly by the JavaScript callback. You should make sure that your server call is synchronous. Since 1.5.4. Since 1.5.7 - only called once. |
| format | string | 'dHMS' | The format for the countdown display. Use the following characters
(in order) to indicate which periods you want to display:
'Y' for years, 'O' for months, 'W' for weeks, 'D' for days,
'H' for hours, 'M' for minutes, 'S' for seconds. Use upper-case characters for mandatory periods, or the corresponding lower-case characters for optional periods, i.e. only display if non-zero. Once one optional period is shown, all the ones after that are also shown. The default format indicates that days is the maximum unit to display, and then only if non-zero, and always show hours, minutes, and seconds. If not showing seconds, any left overs cause the next level up to be rounded up (if counting down), meaning that ultimately the countdown shows '1' for that level throughout the last period. Since 1.1.0 - prior to this you used the showDays ('always' | 'never' | 'asNeeded')
and showSeconds (boolean) settings.Since 1.5.5 - rounding up. |
| padZeroes | boolean | false | Set to true to pad values with zeroes for a minimum of two digits.Since 2.0.0. |
| layout | string | '' | A customised layout for more control over the countdown appearance.
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 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. Leave as blank to use the built-in layouts. Since 1.4.0. Since 1.5.0 - refactored to use '{pv}' notation. Since 1.5.3 - added desc,
sep, pnnn, and pd substitutions.Since 1.5.5 - added p1000 substitutions. |
| compact | boolean | false | Indicate whether or not the countdown should be displayed in a compact format. |
| significant | number | 0 | The number of significant (non-zero) periods to show, or zero for all.
For example, if the current period values are 1 month, 0 days, 5 hours,
and 23 minutes, a value of 1 would only show the month value,
while a value of 2 would show the month and hours values.
Note that this doesn't affect compact
countdowns, other than to zero out periods past the significant setting.
When combined with a custom layout, you must use the
'{p<}...{p>}' construct to suppress insignificant sections.Since 1.5.8. |
| labels | string[7] | ['Years', 'Months', 'Weeks', 'Days', 'Hours', 'Minutes', 'Seconds'] | The display text for the various parts of the countdown.
This is one of the
regional settings fields. You can also specify additional labelsn
attributes, where n is a number, to handle specialised plural terms for that number,
such as those found in Slavic languages for the numbers 2 to 4.Since 1.1.0 - prior to this it only contained 'Days' to 'Seconds'. Since 1.4.2 - additional labelsn settings. |
| labels1 | string[7] | ['Year', 'Month', 'Week', 'Day', 'Hour', 'Minute', 'Second'] | The display text for the various parts of the countdown if there is only one of them.
This is one of the
regional settings fields. Since 1.2.1 - originally labelsSingle.Since 1.4.2 - replacing labelsSingle. |
| compactLabels | string[4] | ['y', 'm', 'w', 'd'] | The display text for the years, months, weeks, and days in the compact format.
This is one of the
regional settings fields. You can also specify additional compactLabelsn attributes,
where n is a number, to handle specialised plural terms for that number,
such as those found in Slavic languages for the numbers 2 to 4.Since 1.1.0 - prior to this you used the compactDays (String) setting.Since 1.4.2 - additional compactLabelsn settings. |
| whichLabels | function | null | Determine which set of labels to use for a given period amount.
The default mapping (when this option is null) is to use
labelsn,
where n is the amount, if available, and
labels if not. Some languages have
a more complicated plural form that does not easily fit this pattern.
For example, Polish uses one form for the value one, a second form for values
two to four, 22 to 24, 32 to 34, etc., and a third form for the rest.
The function takes the amount as a parameter and returns the n
value used above to locate the relevant labels, or zero to use the defaults.Since 1.5.8. |
| digits | string[] | ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] | The strings to use to represent the numeric digits.
This is one of the
regional settings fields.Since 1.6.0. |
| timeSeparator | string | ':' | The separator between the various parts of the countdown time in the compact format. This is one of the regional settings fields. |
| isRTL | boolean | false | Set to true for languages that read right-to-left, or false for left-to-right.
This is one of the
regional settings fields. Since 1.4.2. |
| description | string | '' | The descriptive text shown below the countdown timer. This value can contain HTML markup. |
| expiryText | string | '' | A message to display when the countdown reaches zero,
replacing the countdown periods. It may contain HTML markup. Since 1.5.2. |
| expiryUrl | string | '' | A URL to load when the countdown reaches zero, replacing the current page. Since 1.1.0. |
| alwaysExpire | boolean | false | If true, the onExpiry event
is triggered even when the counter starts after the target time.
If false, the event only triggers if the counter actively times out.Since 1.2.1. |
| onExpiry | function | null | A callback function that is invoked when the countdown reaches zero.
Within the function this refers to the division that holds the widget.
No parameters are passed in. Use the
expiryText or
expiryUrl settings for
basic functionality on expiry. |
| onTick | function | null | A callback function that is invoked each time the countdown updates itself.
Within the function this refers to the division that holds the widget.
The array of current countdown periods (int[7] - based on the
format setting)
is passed as a parameter: [0] is years, [1] is months, [2] is weeks,
[3] is days, [4] is hours, [5] is minutes, and [6] is seconds.Since 1.1.0 - prior to this only days through to seconds were passed as the parameter. |
| tickInterval | number | 1 | Set the interval in seconds between callbacks to the
onTick function.
Note that the period resolution is limited to the minimum value displayed in your
format. So, if you are not showing seconds,
you should only use intervals that are multiples of a minute (60).Since 1.5.7. |