Overview

Hello! This is a demo page of jQuery-backward-timer. It is a small plugin for jQuery JavaScript library. As you may have already guessed, this plugin gives an ability to create controlled backward timers on web pages.

With this plugin you will be able to:

• Start, cancel, resume and reset timer.
• Specify timer's timeout.
• Specify timer's step.
• Set output format.
• Allow timer to count down to negative infinity.
• Handle timer's events of starting, cancellation, exhausting and ticking.

Before you will start using this plugin, make sure you've included jQuery at first:

You can use div,  span,  input or any other element as a container to render your timer:

Then you can easily make an initialization:

Default initialization

By default, timer has a timeout of 5 seconds, output format is 'H:MM:SS' and initial value is the representation of the initial timeout.

If you have cancelled the timer, you can resume it by starting it again.

When the timer is exhaused and you need to rerun it, reset it first. You can also reset the timer while it is running.

The source code for the example above is listed below. Take a look at timer's initialization at the line #13.

How to set timeout value

To specify timer's timeout value, pass an object with seconds attribure to the initialization function:

See it in action:

How to set output format

By default, timer's output format is h%:m%:s%, which results in displaying hours without leading zero, minutes and seconds with leading zero, all separated by colons.

If timer's timeout has days, then they will be converted to hours, e.g.

will result into:

If you want to display days explicitly, then you have to change output format. Days pluralization is up to you. Below you can see the initialization of the same timer as above, but with another output format for handling days. Hours will have leading zero now.

Actually, you may use any format and set placeholders for time intervals in any order:

Handling start event

For some reason you may need to trigger some action when your timer starts. If you do not want to call it every time manually, you may set an  on_start callback function during plugin's initialization:

Callback function accepts timer argument, which is an instance of timer plugin. Its properties will be discussed later. Now note, that it can access target property, which in this case is equal to calling $('#timer_on_start').

Handling event of cancellation

You may also need to trigger some action when timer is being cancelled. Here on_cancel callback will help you:

And this is hot it works:

Handling event of exhausting

Very probably, you will want to do some action, when your timer is exhausted. Use on_exhausted callback for this:

Let's see how this works:

Handling tick events

If you need to perform some action on each tick, while your timer is working, you can set a callback for that event as well.

This will change color of the timer's value each second. Give it a try:

How to set timer's step

Timer's value is rendered each second by default. If it's too fast for you, you can set timer's step (in seconds):

Here we have a timer which works for 1 minute and renders own value each 5 seconds.

Number of seconds is usually multiple of timer's step. I.e., if we set step to 5 then it will be nice to use number of seconds which is multiple of 5: 5, 10, 15, etc.

But this is not obligatory. For example, if you set 10 for seconds and 4 for step, timer will correctly count 10, 6, 2, 0. Even if your step is greater than number of seconds, this is still valid.

Counting down to infinity

You may be surprised, but this plugin allows you to go on counting below zero. This feature was implemented due to issue #6.

To enable such behaviour, set stop_at_zero parameter to false:

See how this works:

Callback argument: the man behind the curtain

As you may noticed, callback functions have timer as an input argument. It is an instance of the plugin applied to your element, which was created during plugin's initialization. If you dir its attributes (e.g., via console.dir(timer)) you will see all the guts of the plugin:

Two of them you are familiar with. They are  target and  seconds_left. Former is an object the plugin is applied to. As you can see, it is a  span element with an ID of  #timer_1 and with a  timer class. Latter is the current value of seconds, which are left before the timer is considered to be exhausted. timeout is the ID of current timer, created by  setTimeout() method. settings store output format, initial amount of seconds to count and other stuff, which was discussed in last examples. methods object contains all the public and private methods of the plugin.

Credits

Alexander Oblovatniy (@oblalex) has created jQuery-backward-timer and these fine people have contributed.

The end

So, here you are. At the end of the documentation for backward timer. From now, you may know everything about it. Thanks for reading and good luck with usage!