# 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:
  - jquery.countdown.js, line 20

##### 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:
  - jquery.countdown.js, line 154

##### 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:
  - jquery.countdown.js, line 33

#### (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:
  - jquery.countdown.js, line 192

##### 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:
  - jquery.countdown.js, line 588

##### 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:
  - jquery.countdown.js, line 533

##### 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:
  - jquery.countdown.js, line 525

##### 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:
  - jquery.countdown.js, line 303

##### 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:
  - jquery.countdown.js, line 540

##### Example

    $(selector).countdown('resume')

#### (inner) resync()

Resynchronise the countdowns with the server.

Source:
  - jquery.countdown.js, line 310

##### Example

    $.countdown.resync()

#### (inner) toggle(elem)

Toggle a paused countdown widget.

##### Parameters:

Name | Type | Description
--- | --- | ---
`elem` | Element | The containing element.

Source:
  - jquery.countdown.js, line 547

##### Example

    $(selector).countdown('toggle')

#### (inner) toggleLap(elem)

Toggle a lapped countdown widget.

##### Parameters:

Name | Type | Description
--- | --- | ---
`elem` | Element | The containing element.

Source:
  - jquery.countdown.js, line 555

##### 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:
  - jquery.countdown.js, line 276

##### 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))