It has been some time since I’ve last posted, I’ve been far too busy with a project I’ve been working on the past several months, but it’s almost ready and I hope I’ll get back to my weekly posting.

While working at this project, at some point I needed a countdown script to announce certain features being released on specific dates, maybe I’ve been a bit lazy and tried finding an already built countdown plugin to work with, but not much luck finding exactly what I was looking for so I’ve built my own.

Inspired from the countdown plugin video from The New Boston, I’ve decided to make this tutorial so everyone can be able to create their very own extensible jQuery countdown plugin.

If you don’t want to read the tutorial and just download the ready-to-use jQuery countdown script, then click here and read the instructions.txt file.

• Tutorial level: intermediate
• Knowledge expectations:
  • - HTML
  • - CSS
  • - a basic understanding of how jQuery works – Approaching jQuery for the first time

The point to build our own countdown script is to be able to have full control over it, to make it extensible and to be able to reuse it throughout our projects very easily.

Setting up our workspace

For this, we will obviously need the jQuery library which you can download from their website right here, but if you already have it, do make sure it’s the last stable version.

I’m assuming you already know how to create files and folders so create a folder for the CSS and one for the JavaScript files, because we want to be clean and work with unobtrusive code.

You can also download my clean workspace for this tutorial clicking here.

It’s entirely your decision where the countdown is positioned and how it is styled, but to keep this tutorial simple, we’ll use a basic look & feel and afterwards you can implement it as you wish.

Let’s create the HTML structure for the countdown:

index.html

The external stylesheet which goes in the CSS folder, containing some basic styles:

countdown.css

And in the JS folder goes the jQuery library.

Right now all we have is a static looking countdown, so let’s add the logic and build the plugin.
In the JS folder, create a file countdown.js, open it with your favorite code editor and let’s get to work.

We will build all of our code inside a plugin function that jQuery recognizes:

countdown.js

A jQuery plugin function requires a name and in our example we gave it countdown
Also, you’ll notice that the main function has a dollar sign parameter and the jQuery keyword at the end between paranthesis, if we wouldn’t have done that, we no longer could’ve used the short jQuery dollar sign namespace (i.e. $(“h1″) ) and had to use jQuery’s regular namespace (i.e. jQuery(“h1″) ).

It’s always good practice to test your functions before you start coding, a quick way to do it is to add a simple alert function and then just call it from an HTML page:

countdown.js

Now let’s test the plugin by calling it from our index.html

index.html

If you didn’t mistype anything, you should get an alert with the message “Hello!” when you open or refresh the page.

When you get different results than those mentioned in this article, try downloading the examples.

The beauty of a plugin is the control we can add to it by extending it with parameters where we can specify certain settings and a callback function that launches a code we want after it has successfully finished processing.
We’ll add two parameters to our plugin function, settings and callback.

countdown.js

Now that we have specified that our plugin requires two parameters, options and callback, let’s start adding our custom settings.
In our case, we’ll need to be able to add a date which we can make the plugin read and process.
We’ll specify our settings via an array, but we’ll start with just one setting for now:

countdown.js

By default, we’ve set it to null so it would be empty if no date will be specified when calling the plugin.
Also, you’ll notice at the begining a new variable called thisEl (which can be called whatever you want), we added the $(this) selector onto this variable so we can easily reference our countdown’s html code later on. If you do not know what this means in JavaScript, do look it up as it’s one of the key elements of JavaScript.

To make the plugin’s options parameter recognize our settings array and reference all of our settings from it, we’ll use jQuery’s $.extend function

countdown.js

We’ve told it that if the options parameter exists, then append the settings array to it.

So now we’re able to call the plugin and specify a date.

index.html

We’ve applied the plugin onto an HTML’s countdown ID that holds the HTML elements for the countdown, this way the plugin will be much faster and won’t have to tranverse through the entire DOM to find the elements that it needs to interact with.
Now that we’re done with the basics, let’s get to the real processing.

But first! Let’s see how we can read the date value we specify when calling the plugin.
We’re going to create a new function inside our plugin called countdown_proc and we’re going to alert the date.

countdown.js

Since we assigned the settings array to be the place where we specify all of our properties, to fetch the date we use settings['date']. And if you add more properties, just use settings['PROPERTY_NAME'].
Now when you open or refresh the page, it will alert the date value you specify in your html page when calling the plugin.

Remove the alert and let’s make this plugin actually do something
We’ll need two variables that will hold the current and end date. We’ll get the current date using the jQuery’s $.now() function that fetches the current date. The end date will be specified when calling the plugin so we’ll fetch it from there.

countdown.js

To avoid confusion, let’s talk about date for a bit. We created the variable eventDate and we need to asign the date we specify when calling the plugin, like mentioned in the previous example (i.e. date: “4 december 2011 11:20:00″ ).
But what we really need is a timestamp date (number of seconds). So when we fetch the date value, we’ll also convert it into a timestamp date by using the Date.parse function, this will however give us the timestamp in milliseconds so we just divide it by 1000. Thus Date.parse(settings['date']) / 1000 results the timestamp in seconds.
As for the currentDate, jQuery has a function named $.now() that fetches the current date in milliseconds, again, we divide it by 1000 to work with seconds.

We have both variables for Current Date and for End Date, we’ll need to calculate the difference so we can populate the countdown with the difference between them, the remaining time that is.
We’ll create a variable seconds where we’ll do a simple math substraction to find out the number of seconds between the current and end date.

countdown.js

Now that we know the remaining time in seconds, let’s calculate the number of days, hours, minutes and seconds and add them to variables which we can later use.

countdown.js

Let’s explain days and you’ll figure out the rest of the math. To calculate the number of days, we used a simple math calculation where we divided the total number of seconds by a day (in seconds). A day has 86400 seconds, but just so we don’t have to remember how many seconds a period of time has, we just used (hours * minutes * seconds), equaling the number of seconds in a day. Thus, number of seconds divided by (60 * 60 * 24) => seconds / seconds in a day. Wow, I think I’m being way too explanatory here.
The Math.floor function that surrounds our math calculation does nothing more but to remove the remainder from our result and consider only the floor value of it, just so we won’t get results such as 3.3164400 days.

You’ll notice the seconds variable right afterwards, doing a math calculation with -=. What that does is remove the number of seconds used in the days variable so we can have an updated seconds variable without the number of days in order to continue calculating the hours, minutes and seconds.

is the same as

And the process repeats for hours, minutes.

Finally the fun part, let’s populate our countdown’s html span values:

countdown.js

If everything went well, each time you refresh the page and you should see the countdown updated with the remaining time.
We’ve used the thisEl variable to start working directly with the code of our countdown html portion, using .find to find the elements we want to update.

We do need to make the countdown update itself each second though, so we’ll just loop the process every second with the help of JavaScript’s setInterval function, we’ll add it after the countdown_proc function:

countdown.js

Now you should see the countdown updating itself each second.

setInterval requires the code you want to run and at what interval you want it to run (in milliseconds).
We’ve run it by also adding it to an interval variable so we can have control over it and in our case, stop it whenever the countdown finishes.

Even though the countdown’s working now, we still have a few more things to fix, or at least to consider.

If you’ll call the plugin with an event date that happens in a minute or so, you’ll notice that once it reaches time 0, it will not stop and start showing negative values. Let’s fix that.

Right after the eventDate and currentDate variables, let’s add the following condition

countdown.js

What the condition basically does, is check whether the eventDate variable (that holds the timestamp date value of our event) is equal or less than the currentDate variable, if so, run the callback (the one we’ll specify when we’ll call the script in out html page) and also to clear the interval, at that point we no longer need the interval to keep looping our countdown script since the countdown ended.

Hoping that all of that was clear, let’s test it one more time and also make it alert a message when the countdown ends.

index.html

countdown.js

As callback, we added an alert with the message “Countdown finished” that will show up when the countdown ends.
Now you have a functional countdown which you can use to announce features on a website, or perhaps the launch of an website itself.

We can however enhance this countdown even further.

Constant double digits setting

Depending on how you style the countdown, it can become inconsistent if the time displays both in single and double digits (i.e. 5:0:54 / 17:15:54), or maybe you want it to aways display with double digits for visual reasons only.
To achieve that, we’ll extend this plugin by adding one more setting, that is to turn on and off the display of double digits.
We’ll start by adding format as our new setting name with the value of null, in our settings array:

countdown.js

We’ve set the value to null because we want it to hold no value as long as we do not set it when we call the plugin.
In our countdown.js script file, right after the last seconds variable we will add the following condition:

countdown.js

The reason why we want to have this condition set after the days, hours, minutes, seconds variables is because we want those variables to already exist and hold the real countdown values so we can now check whether their values are formed by two digits or not, and if not, we’ll add the missing 0.
So what we’ve done is to check if the format settings is set to ON and if so, check whether the values are formed by two digits and if not, add the missing zero.
The condition is quite simple and it’s exacty as an if-and-else statement.

Basically:

Is the same as:

So if the days variable has two digits or more, leave it as it is, otherwise it must be made of just 1 character so append a 0 to it.

As a result we should have:

countdown.js

and to force it to display two digits, we’ll call the plugin by specifying our format setting to ON.

index.html

Now the plugin has two settings to play with.
But it’s not yet an entirely fail-safe plugin, I say we should add a warning in case the date that’s added when calling the plugin is incorrect.
To do so all we have to do is wrap our *.text() methods in a condition where we check whether our eventDate variable is a number, if it’s not, that means the specified date is invalid and has been no longer successfully converted into a numerical timestamp.

countdown.js

We used the isNaN function (which means is Not a Number) and prepended an exclamation mark to it to reverse the condition, so now it’s checking whether it is a number (!isNaN = if it’s not Not a Number).
And if it’s not, we just apply an alert with a warning and clear the interval to stop the timer.

What about the S endings of day(s) minute(s) when it actually display 1 as value?
We should make it display day when it shows 1 day and days when there are more days left.

Conditioning the Ss

To start, we’ll need to add a different class for each time reference (timeRef for days will become timeRefDays, for hours it will be timeRefHours and so on).

index.html

countdown.css

We already have access to our variables that display the coundown time, all we have to check is whether it’s 1 or not. If any time duration is 1, remove the s, otherwise show it.
Right before our format setting code, let’s add conditions for each time reference:

countdown.js

And there we have it! Man, me and my long articles :/
I hope that all the details at each step somehow helped you and didn’t actually clutter your mind more hehe

Here’s the final code:

index.html

countdown.css

countdown.js

Once you’ve read the entire tutorial, all the code should no longer look difficult at all, in fact, keep spending some time playing with it, get comfortable with it, add more control as needed.

In fact, I’ll reward the first person who makes the countdown change its color once it’s about to end, and the time that it should start changing its color should be specified as a setting.

Reward: A free link in the footer of this blog for 3 whole months*

* Yes, that little pesky star, I’ll have to specify that I won’t be accepting any website that contains rude, obscene or racist content.

The code is free to use for both personal and commercial purposes, however, do try to subscribe, tweet, like and so on… share the love!

Good luck!