Age of Article Warning:
This article was originally published 21 months ago. The tips and techniques explained may be outdated, or information may longer be applicable. Please consider this when viewing the below content.

If you host an event on your website, perhaps run a competition or maybe set a product launch date, then you will need a countdown timer.

One great little countdown timer is jQuery TimeCircles. It lets you set a future date and time, or otherwise you can set the timer based on number of seconds. If you set a date and time, then the countdown will finish at the set date and time. If you set a timer based on seconds, then it will start when the page loads.

What I like about TimeCircles is that it looks great, functions well and is responsive for different size devices (if you are using a responsive WordPress theme). I use this counting timer for my webcast replays, so that members know how long they’ve got to watch after the live webcast.

Here is an example of what it looks like, with the timer set for 120 seconds or 2 minutes, and at the end of the countdown it plays a sound and pops up with a message.

How to add jQuery TimeCircles to WordPress?

It is really easy to add this to your WordPress website. If you have been following along with previous tutorials then you probably already have an idea what procedure we are going to use.

First you will need to download the necessary script files to upload to your website. Then create a script file for the options, then add a couple of functions to your childtheme’s functions.php file, one to register the necessary scripts and styles ready to enqueue in our shortcode function, and the other to add the shortcode function with some basic attributes.

Step 1: Get the materials
Download zip file from the TimeCircles website and extract the files. Next create a new folder inside your WordPress childtheme’s folder called “js”. You may already have this folder created.

Now create a folder inside this “js” folder and call it “TimeCircles”. This is where we will upload our scripts and styles for TimeCircles. Go ahead and upload TimeCircles.css and TimeCircles.js into this folder.

Step 2: Prepare our settings
Ok now we need to create our script file for our TimeCircle options. Create a file called timecirclescript.js and insert the following javascript into it:

/* script for countdown shortcode */
var timecircleanimation = timecircledata2.time_animation;
var timestop = timecircledata2.timestop;
var timemessage = timecircledata2.message;
jQuery(document).ready(function($) {
    $(".timecircle").TimeCircles({
        animation: timecircleanimation,
        count_past_zero: parseInt(timestop,10)
    }).addListener(function(unit, value, total) {
        if(total === 0) {
            document.getElementById('timerend').play();
            alert(timemessage);
        }
    });
});

Now upload this file also into the TimeCircles folder.
Note: you may notice that I’ve set some variables in the script with values such as “timecircledata2.time_animation”. This data is passed across from the wp_localize_script function that we will use in our shortcode. If you are familiar with passing parameter from a shortcode to javascript, then you will understand this. If not then have a read of the article that talks about this.

Step 3: Create the functions
Now edit your childtheme’s functions.php file and add the following 2 functions:

function scripts_for_countdownclock() {
    wp_register_style('timecirclecss',get_stylesheet_directory_uri().'/js/TimeCircles/TimeCircles.css');
    wp_register_script('timecirclejquery',get_stylesheet_directory_uri().'/js/TimeCircles/TimeCircles.js',array('jquery'),'',true);
    wp_register_script('timecirclescript',get_stylesheet_directory_uri().'/js/TimeCircles/timecirclescript.js',array('timecirclejquery'),'',true);
}
add_action('wp_enqueue_scripts','scripts_for_countdownclock');

function countdown_shortcode($atts, $content = null){
    $timecircledata = shortcode_atts(array(
        'data_date' => '0',
        'data_timer' => '0',
        'time_animation' => 'ticks',
        'timestop' => '0',
        'message' => 'time has ended'
    ),$atts);
    wp_enqueue_style('timecirclecss');
    wp_enqueue_script('timecirclejquery');
    wp_enqueue_script('timecirclescript');
    wp_localize_script('timecirclescript','timecircledata2',$timecircledata);
    $d_date = $timecircledata['data_date'];
    $d_timer = $timecircledata['data_timer'];
    if ($d_timer !=='0') { 
        $countdownoutput = '<div class="timecircle" data-timer="'.$d_timer.'"></div>';
    }
    elseif ($d_date !=='0') {
        $countdownoutput = '<div class="timecircle" data-date="'.$d_date.'"></div>'; 
    }
    else {
        $countdownoutput = '<div class="timecircle" data-timer="3600"></div>';
    }
    return $countdownoutput . '<audio id="timerend" src="LINK TO YOUR AUDIO FILE" preload="auto"></audio>';
}
add_shortcode('time-circle','countdown_shortcode');

The first function above takes care of registering our 2 script files and our css file. Make sure that the path to the files matches where you have uploaded the files.

The second function is our shortcode function that sets the attributes, enqueues the files when the shortcode is on a page, and also includes a handy use of wp_localize_script so that we can access some parameters in our script file.

Make sure to upload an audio sound file for playing at the end of countdown, and add that to the function where it says “LINK TO YOUR AUDIO FILE”.

Step 4: Using the shortcode
Simply add [time-circle data_timer="ADD NUMBER OF SECONDS HERE"]

Optional settings:
data_date="" //must be in the format yyyy-mm-dd hh:mm:ss
data_timer="" //default is 3600 seconds (1 hour)
time_animation="" //default is “ticks”; alternative option is “smooth”
timestop="" //default “0” to stop timer when reaches 0; set to “1” for timer to continue counting upwards from 0
message="" //add a custom message that pops up when timer reaches 0

Important note: do not use both “data_timer” and “data_date” in the same shortcode, only choose one. Only use the shortcode once on a page, otherwise there will be unexpected results for localized data, as the variable name will be the same with different values.

Feel free to customise your TimeCircles even further, by editing the settings script in step 2 above, or by adding extra attributes to the shortcode function.

Add a jQuery TimeCircle Countdown Timer to WordPress was last modified: September 6th, 2016 by David Tiong
Add a jQuery TimeCircle Countdown Timer to WordPress