How to use jQuery countdown plugin

Install

We provide two installation methods:

Bower

bower install jquery.countdown

Manual

Download the files and add a script to your
html:

<script src="/bower_components/jquery.countdown/dist/jquery.countdown.js"></script>

Requirements

The latest versions
supports jQuery from 1.7 up
to >= 2.1. For legacy support (<= 1.6) please use the
version 1.0.2.

Introduction

For each DOM in your selector chain, an instance of the
countdown will be created with an interval, that sends signals (events) with the
time remaining components has weeks, days, hours, so on so forth (for more
details see Event
object section). The countdown is wrapped within the DOM
and will auto delete itself when the DOM is removed.

$('div#clock').countdown(finalDate[, callback]);

With the legacy approach you will need to handle all
events in a single callback (update, finish or stop) through
the event.typeproperty,
if you prefer an event orieted programming style, this plugin also support the
default jQuery on method to register your
callbacks.

$('div#clock').countdown(finalDate)
    .on('update.countdown', callback)
    .on('finish.countdown', callback);

To start the countdown the only requirement is
the finalDate, but you
still need register a callback to manipulate/update the DOM.

Arguments

finalDate

The target date that you are seeking to countdown. This
argument can be one of the following:

• A native date object
• The milliseconds from Epoch time
• String formatted as following:
  • YYYY/MM/DD
  • MM/DD/YYYY
  • YYYY/MM/DD
hh:mm:ss
  • MM/DD/YYYY
hh:mm:ss

callback

A function that will handle the event triggered, despite the
fact we have three event types, all of them will have the same object properties
(as described bellow), where you can access the offset calculation.

function(event) { ... }

Configuration object

The plugin accepts some configuration passing by an
object has the function second argument. This way one can control the precision
the plugin will have and allow customizations:

$('div#clock').countdown(finalDate, {
  elapse:     '{bool} Allow to continue after finishes',
  precision:  '{int} The update rate in milliseconds',
  defer:      '{bool} Deferred initialization mode'
})

The configuration mode is only available with the new
style of initialization.

Elapse mode

The elapse mode allows the plugin to continue counting
even after reaches its finish. One can control the render within the callback
using the event.elapsed property.

$('div#clock').countdown(finalDate, {elapse: true})
  .on('update.countdown', function(event) {
    if (event.elapsed) { // Either true or false
      // Counting up...
    } else {
      // Countdown...
    }
  });

Be aware that no finish event will be
dispatched at this mode!

Deferred initialization

The deferred initialization mode allows you to register
the callback before the countdown actually starts, this is useful when one wants
to render the proper HTML the exact time the countdown starts, (i.e. when the
countdown are really short time <= 60s).

Just be aware that the
developer MUST call
the start method manually to
begin the countdown:

// It will render correctly since the start of the plugin.
$('div#clock').countdown(finalDate, {defer: })
  .on('update.countdown', function() {
    // render something
  })
  .countdown('start');

Events

This plugin will trigger an event whenever some state
change like:

• Update:
  Triggered to update the DOM
• Finish:
  Triggered when finished
• Stop:
  Triggered that paused

To register a callback use the
following event.type:

• update.countdown
• finish.countdown
• stop.countdown

Be aware
that ALL events should be
registered with the namespace *.countdown.

Event object

Most of the time you will be using
the event.strftime function to
render the countdown, the next section goes deeper in this subject. But you can
access all raw values:

{
    type:           '{String} The namespaced event type {update,finish,stop}.countdown',
    strftime:       '{Function} The formatter function',
    finalDate:      '{Date} The parsed final date native object',
    elapsed:        '{bool} Passed away the final date?',
    offset: {
        seconds     : '{int} Seconds left for the next minute',
        minutes     : '{int} Minutes left for the next hour',
        hours       : '{int} Hours left until next day',
        days        : '{int} Days left until next week',
        daysToWeek  : '{int} Days left until next week',
        daysToMonth : '{int} Days left until next month',
        weeks       : '{int} Weeks left until the final date',
        weeksToMonth: '{int} Weeks left until the next month',
        months      : '{int} Months left until final date',
        years       : '{int} Years left until final date',
        totalDays   : '{int} Total amount of days left until final date',
        totalHours  : '{int} Total amount of hours left until final date',
        totalMinutes: '{int} Total amount of minutes left until final date',
        totalSeconds: '{int} Total amount of seconds left until final date'
    }
}

Formatter (event.strftime)

A simple formatter that helps keep your code more
semantic and avoid repetitive tasks.

It formats the offset date according to the directives
in the given format string. The directive consists of a percent (%)
character. Any text not listed as a directive will be passed through to the
output string.

event.strftime('%W weeks %-d days %-H h %M min %S sec');
// => 1 week 2 days 3 h 04 min 05 sec

All the directives contains zero-padded (01, 02, 03, …,
10) and blank-padded (1, 2, 3, …, 10) versions, to use the latter please use the
dash - modifier.

The formatter is also capable of handle pluralization
through the bang ! modifier, by default always
return the s character, if you need a
complex logic please read
the Pluralization topic of
this section.

Modifier	Description
-	Blank padding
!	Pluralization plugin

Directives

Directive	Blank-padded	Description
%Y	%-Y	Years left *
%m	%-m	Months left *
%n	%-n	Days left until the next complete month *
%w	%-w	Weeks left
%W	%-W	Weeks left until the next complete month *
%d	%-d	Days left (taking away weeks)
%H	%-H	Hours left
%M	%-M	Minutes left
%S	%-S	Seconds left

* Due to their non linear
constrains the calculation does not have precision and it’s pretending to be
used as a approximation or not use at all.

There are another set of directives that returns the
full count of the time component till the end of the countdown:

Directive	Blank-padded	Description
%D	%-D	Total count of days till the end
%I	%-I	Total count of hours thill the end
%N	%-N	Total count of minutes till the end
%T	%-T	Total count of seconds till the end

Pluralization

The support for pluralization is built in the formatter
by adding the ! (bang) modifier to the
directive, the default behavior is to return
the s character, it’s also
possible to customize the return using the suffix :...;.

The table bellow show the supported use cases of the
pluralization plugin.

Directive	Description
%!H	Return s when the hour is different than 1
%!S:plural;	Return plural when seconds if different than 1
%!d:singular,plural;	Return singular when day is 1 and plural otherwise

event.strftime('%-D day%!D %H:%M:%S');
// => 1 day 23:45:56 (or) 2 days 23:45:56

// Now in german
event.strftime('%-D tag%!D:e; %H:%M:%S');
// => 1 tag 23:45:56 (or) 2 tage 23:45:56
event.strftime('%S %!S:sekunde,sekunden;');
// => 01 sekunde (or) 02 sekunden

Controls

The methods pause/resume allows to control the
execution flow of the countdown:

// Pause the countdown
$('div#clock').countdown('pause');
// Resume the countdown
$('div#clock').countdown('resume');

There also the aliases stop/start for the same
functionality:

// Pause the countdown
$('div#clock').countdown('stop');
// Resume the countdown
$('div#clock').countdown('start');

To set a new final date for the countdown, call the
plugin initialization function with a valid date string:

$('div#clock').countdown('2010/10/10');
// Then ...
$('div#clock').countdown('2012/20/20 12:34:56');