EasyTimer.js

Easy to use Timer/Chronometer/Countdown library compatible with AMD and NodeJS

Introduction

EasyTimer.js is a simple library for counting time in five different units: tenth of seconds, seconds, minutes, hours and days. It has interesting features:

  • The refresh interval can be configured in tenth of seconds, seconds, minutes and hours.
  • Dispatches events when timer starts, stops, pauses and when every type of unit changes.
  • A custom callback can be defined and it will be executed every timer refresh.
  • Two timer modes: Regular and Countdown.
  • Configurable start and target values.

EasyTimer.js released under the MIT license

Examples

Library Load

The library can be loaded using NodeJS, RequireJS or classic script

Source code

require(['lib/easytimer/dist/easytimer.min.js'], function (Timer) {
    var timer = new Timer();
});
                    

var Timer = require('lib/easytimer/dist/easytimer.min.js')
                    

<script src="lib/easytimer/dist/easytimer.min.js"></script>
<script>
    var timerInstance = new Timer();
</script>
                    

Basic Usage

Starting a timer is very simple. You only have to get a new instance of Timer and invoke the start method. The timer will update the values every second and it will dispatch a secondsUpdated event that you can listen using the addEventListener method. You can get the time values using getTimeValues method.

Source code

var timer = new Timer();
timer.start();
timer.addEventListener('secondsUpdated', function (e) {
    $('#basicUsage').html(timer.getTimeValues().toString());
});
                

<div id="basicUsage">00:00:00</div>
                

Result

00:00:00

Getting Time Values

In this example you can see how to get the time counters of the timer instance. The getTimeValues method returns the time values in "clock" format. For example, every 60 seconds the seconds counter will be set to 0 and 1 minute will be added to the minutes counter. The getTotalTimeValues method returns the total of the counters. For example, if the counter has counted 2 minutes, there will be 120 seconds in the seconds counter. These methods return a object of type TimeCounter, and has five properties (days, hours, minutes, seconds and tenth of seconds) and a toString method, that return the counters in string format.

Source code

var timer = new Timer();
timer.start({precision: 'seconds'});
timer.addEventListener('secondsUpdated', function (e) {
    $('#gettingValuesExample .days').html(timer.getTimeValues().days);
    $('#gettingValuesExample .hours').html(timer.getTimeValues().hours);
    $('#gettingValuesExample .minutes').html(timer.getTimeValues().minutes);
    $('#gettingValuesExample .seconds').html(timer.getTimeValues().seconds);
    $('#gettingValuesExample .secondTenths').html(timer.getTimeValues().secondTenths);

    $('#gettingTotalValuesExample .days').html(timer.getTotalTimeValues().days);
    $('#gettingTotalValuesExample .hours').html(timer.getTotalTimeValues().hours);
    $('#gettingTotalValuesExample .minutes').html(timer.getTotalTimeValues().minutes);
    $('#gettingTotalValuesExample .seconds').html(timer.getTotalTimeValues().seconds);
    $('#gettingTotalValuesExample .secondTenths').html(timer.getTotalTimeValues().secondTenths);
});
                

<div><strong>Values:</strong></div>
<div id="gettingValuesExample">
    <span class="days">0</span><span> days</span>
    <span class="hours">0</span><span> hours</span>
    <span class="minutes">0</span><span> minutes</span>
    <span class="seconds">0</span><span> seconds</span>
    <span class="secondTenths">0</span><span> tenth of seconds</span>
</div>
<div><strong>Total Values:</strong></div>
<div id="gettingTotalValuesExample">
    <span class="days">0</span><span> days</span>
    <span class="hours">0</span><span> hours</span>
    <span class="minutes">0</span><span> minutes</span>
    <span class="seconds">0</span><span> seconds</span>
    <span class="secondTenths">0</span><span> tenth of seconds</span>
</div>
                

Result

Values:
0 days 0 hours 0 minutes 0 seconds 0 tenth of seconds
Total Values:
0 days 0 hours 0 minutes 0 seconds 0 tenth of seconds

Start, Pause, Stop and Reset (Chronometer)

You can start, pause, stop and reset the timer using the methods of same name. After each action, the timer will dispatch started, paused, stopped and reset events, respectively.

Source code

var timer = new Timer();
$('#chronoExample .startButton').click(function () {
    timer.start();
});
$('#chronoExample .pauseButton').click(function () {
    timer.pause();
});
$('#chronoExample .stopButton').click(function () {
    timer.stop();
});
$('#chronoExample .resetButton').click(function () {
    timer.reset();
});
timer.addEventListener('secondsUpdated', function (e) {
    $('#chronoExample .values').html(timer.getTimeValues().toString());
});
timer.addEventListener('started', function (e) {
    $('#chronoExample .values').html(timer.getTimeValues().toString());
});
timer.addEventListener('reset', function (e) {
    $('#chronoExample .values').html(timer.getTimeValues().toString());
});
                

<div id="chronoExample">
    <div class="values">00:00:00</div>
    <div>
        <button class="startButton">Start</button>
        <button class="pauseButton" >Pause</button>
        <button class="stopButton">Stop</button>
        <button class="resetButton">Reset</button>
    </div>
</div>
                

Result

00:00:00

Start and Target Values

When you start the timer, you can pass a javascript object with configuration values. In this examples, you pass the start value (90 seconds) and the target values (120 seconds). As you can see, the timer starts with 1 minute and 30 seconds and stops at 2 minutes. You can pass the units you like in these two parameters (days, hours, minutes, seconds and secondTenths)and the Timer will convert these units into the correct ones for each counter. When the counter achieves the target, it will dispatch targetAchieved event.

Source code

var timer = new Timer();
timer.start({precision: 'seconds', startValues: {seconds: 90}, target: {seconds: 120}});
$('#startValuesAndTargetExample .values').html(timer.getTimeValues().toString());
timer.addEventListener('secondsUpdated', function (e) {
    $('#startValuesAndTargetExample .values').html(timer.getTimeValues().toString());
    $('#startValuesAndTargetExample .progress_bar').html($('#startValuesAndTargetExample .progress_bar').html() + '.');
});
timer.addEventListener('targetAchieved', function (e) {
    $('#startValuesAndTargetExample .progress_bar').html('COMPLETE!!');
});
                

<div id="startValuesAndTargetExample">
    <div class="values"></div>
    <div class="progress_bar">.</div>
</div>
                

Result

.

Countdown Timer

The timer can act as countdown timer if the countdown parameters is passed with a truly value to the start method. The minimum target value of the countdown timer is 0.

Source code

var timer = new Timer();
timer.start({countdown: true, startValues: {seconds: 30}});
$('#countdownExample .values').html(timer.getTimeValues().toString());
timer.addEventListener('secondsUpdated', function (e) {
    $('#countdownExample .values').html(timer.getTimeValues().toString());
});
timer.addEventListener('targetAchieved', function (e) {
    $('#countdownExample .values').html('KABOOM!!');
});
                

<div id="countdownExample">
    <div class="values"></div>
</div>
                

Result

Callback

If you prefer a callback instead of event listeners, you can pass a function with the callback parameter, and this callback will be executed every timer refresh.

Source code

var timer = new Timer();
timer.start({callback: function (timer) {
    $('#callbackExample .values').html(
        'Hello, I am a callback and I am counting time: ' + timer.getTimeValues().toString(['hours', 'minutes', 'seconds', 'secondTenths'])
    );
}});            

<div id="callbackExample">
    <div class="values"></div>
</div>
                

Result

Interval of Tenth of Seconds

The precision of the timer can be changed with the precision parameter. The accepted values of the precision parameters are seconds (default value), tenth of seconds, minutes and hours. In this example is passed precision with the value secondTenths. The timer will update the counters 10 times per second.

Source code

var timer = new Timer();
timer.start({precision: 'secondTenths'});
timer.addEventListener('secondTenthsUpdated', function (e) {
    $('#secondTenthsExample .values').html(timer.getTimeValues().toString(['hours', 'minutes', 'seconds', 'secondTenths']));
});            

<div id="secondTenthsExample">
    <div class="values"></div>
</div>
                

Result

00:00:00:00