jCountdown - jQuery Plugin

Description

jCountdown is a simple jQuery Countdown plugin (Renamed from the obvious jQuery Countdown Plugin to avoid confusion with another developers plugin). With it you can counting up or down to a date or time. You can also attach events for when the countdown time changes and completes.

I first wrote this plugin for work about a year ago, although back then it wasn’t a plugin. After I thought it was quite good to port as a simple plugin and share with the world.

I’ve added this project page for this plugin to be the main page for its development.

Information

Reporting Bugs

If you find any bugs please don’t comment on this page. Report any bugs through Github.

Versions

Current Version – 1.4.2

Links:

Download via Github Page

Version 1.4

1.4 is a major rewrite of the API meaning how you would use it has slightly changed. Please see the changelog for more information.

Usage

Options

date - Default: null
       (Must be a valid date string or Date object)

updateTime - Default: 1000
       (Interval in milliseconds when the Countdown should update the time)

htmlTemplate - Default: "%d <span class=\"cd-time\">days</span> %h <span class=\"cd-time\">hours</span> %i <span class=\"cd-time\">mins</span> %s <span class=\"cd-time\">sec</span>"
         Example: "%d <span class=\"cd-time\">days</span>" (DOM String with tokens)
         Tokens available: %y = years, %m = months, %d = days, %h = hours, %i = minutes, %s = seconds

minus - Default: false
        (Boolean. Whether the Countdown should have to go into minus figures, especially when counting down to a date)

onChange - Default: null
           (Callback function for when the Countdown time updates)
           onChange(event, settings)
onComplete - Default: null
             (Callback function for when the Countdown time updates)
             onComplete(event)

onPause - Default: null
          (Callback function for when the Countdown Plugin is paused )
          onPause(event)

onResume - Default: null
           (Callback function for when the Countdown Plugin is resumed from pause)
           onResume(event)

leadingZero - Default: false
              (Boolean. Whether time values should have a leading zero for values < 10. e.g 09)

offset - Default: null
         int or float (Offset in hours, can be used for setting countdown time to match server

servertime - Default: null
		 int or function (servertime in milliseconds, e.g (time() * 1000) in PHP. Or a callback function that sets the time, via an ajax request for example. Used to match countdown across devices where local time can be different.

direction - Default: "down"
            Countdown Direction, "down" for down to a date, and up for "up" from a date

hoursOnly - Default: false (New in 1.3.1)
            (Boolean. If set to true, jCountdown ignores days left and add converts to hours and adds this to the hours left)

minsOnly - Default: false (New in 1.4.1)
           (Boolean. If set to true, jCountdown ignores days/hours and add converts to minutes and adds this to the minutes left)

secsOnly - Default: false (New in 1.4.1)
            (Boolean. If set to true, jCountdown ignores days/hours/minutes left and converts to seconds and adds this to seconds left)

yearsAndMonths - Default: false
             (Boolean. If set to true, jCountdown counts down the years/months as well)

Methods

changeSettings - Accepts an object map, the same as when first initialising the plugin
    Example: $("#time").countdown("changeSettings", options);

getSettings - Returns setting/settings from countdown plugin, as well as the timer
    Example: var currentSettings = $("#time").countdown("getSettings");
    Example: var dateSetting = $("#time").countdown("getSettings", "date");

resume - Resumes the countdown, if previously pauses, otherwise this method does nothing
    Example: $("#time").countdown("resume");

pause - Pauses the countdown, simple as
    Example: $("#time").countdown("pause");

complete - Triggers the complete event and ends the countdown early. Also removes timer and unbinds any events.
    Example: $("#time").countdown("complete");

destroy - Removes timer and unbinds any events, puts the DOM Element back to its original HTML state
    Example: $("#time").countdown("destroy");

Basic Example

$(document.ready(function(){
    $("#time").countdown({
        "date" : "july 30, 2011"
    });
});

Settings you can access in onChange event through settings object

daysLeft
hrsLeft
minsLeft
secLeft
timer (id for Interval)
offset
updateTime
hoursOnly (boolean)
date
minus (boolean)
htmlTemplate

Advanced Example

$(document.ready(function(){
    //Count DOWN to a date
    $("#time").countdown({
        "date" : "july 30, 2011",
        "offset" : 2,
        "leadingZero" : true,
        "onChange" : function(event, settings){
           if( countdownShouldEnd() ) {
               //countdownShouldEnd is not a real function
               //just shows an example of usage
               $(this).countdown("complete");
           }
        },
        "onComplete" : function(event) {
            $(this).html("Completed");
        }
    });

    //Count UP from a date
    $("#time").countdown({
        "date" : "january 1, 2009",
        "offset" : 2,
        "direction" "up",
        "leadingZero" : true,
        "onChange" : function(event, settings){
           if( countdownShouldEnd() ) {
               //countdownShouldEnd is not a real function
               //just shows an example of usage
               $(this).countdown("complete");
           }
        },
        "onComplete" : function(event) {
            $(this).html("Completed");
        }
    });

});

Versions 1.3.x and below