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

• AMD
• Node
• Script

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

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

<script src="lib/easytimer/dist/easytimer.min.js"></script>
<script>
    var timerInstance = new easytimer.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

• Javascript
• HTML

var timer = new Timer();
timer.start();

timer.addEventListener('secondsUpdated', function (e) {
    $('#basicUsage').html(timer.getTimeValues().toString());
});

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

Result

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

• Javascript
• HTML

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

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

• Javascript
• HTML

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

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

• Javascript
• HTML

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

• Javascript
• HTML

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

• Javascript
• HTML

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(['days', '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

• Javascript
• HTML

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

Default Parameters

You can initialize the Timer instance with default parameters. When the timer starts, you can pass other parameters that will be merged with the default parameters. If you don't pass any parameter in the start function, the default parameters will be used.

In the following example, the timer instance's configuration has 2 default parameters: countdown timer and a start value of 5 seconds. But when the timer starts, the timer's configuration changes to a start value of 30 seconds (it replaces the 5 seconds) and a target value of 10 seconds.

Source code

• Javascript
• HTML

var timer = new Timer({ countdown: true, startValues: { seconds: 5 } });

timer.start({ startValues: { seconds: 30 }, target: { seconds: 10 } });
$('#defaultParamsExample .values').html(timer.getTimeValues().toString());

timer.addEventListener('secondsUpdated', function (e) {
  $('#defaultParamsExample .values').html(timer.getTimeValues().toString());
});

timer.addEventListener('targetAchieved', function (e) {
  $('#defaultParamsExample .values').html('The bomb has been defused!');
});

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

Result