jCounter

Updating to v0.1.4 – Stand by…

THIS LIBRARY IS NO LONGER MAINTAINED!

What is jCounter?

jCounter is a simple light-weight extensible jQuery plugin that helps you create various date-based countdowns, countups and custom timers.
It comes with server-side timezone support to display accurate countdowns across the globe.


Download jCounter

jCounter v0.1.4 (beta)

How to use

Download the jCounter archive and unzip it (this is mandatory).
Add the jCounter-*.*.*.js file in your html page in the head section and make sure you load
the jQuery library before it.


Add in the necessary HTML for jCounter to work:


Call jCounter with the desired options:


IMPORTANT!

jCounter uses the dateandtime.php file that needs to be on a PHP-supported server, to retrieve an accurate current time to display exact countdowns with timezone support.

By default, jCounter assumes the dateandtime.php file is on the same server in the web root directory (where the main index page is usually located), if you placed it somewhere else, just specify the location when calling jCounter with serverDateSource: “http://my-domain.com/path/to/dateandtime.php”

If jCounter can’t find the dateandtime.php or if something simply goes wrong, it will use the client-side time as fallback. To avoid this, when first installing/running jCounter, use it with debugLog: true and check your Console Log for errors.


jCounter options

Option Default value Info
animation null Accepts: slide
NOTE: slide only works for slide-ready themes (iOS Dark & iOS Light)
callback null Accepts an anonymous function to run after the counter finishes.
customDuration null The number of seconds which to count to 0
Accepts: an integer (number of seconds)
customRange null customRange helps you build, not only countdowns, but countups as well, from a specific number seconds to another.
Accepts a string of two values separated by a colon (i.e. ’10:90′)
date null Uses a date format to calculate and display a countdown with the remaining time.
Accepts a string of a date format (i.e. ’01 january 2013 12:00:00′)
debugLog false Displays jCounter Activity and Errors via console.log
Accepts: true or false
format ‘dd:hh:mm:ss’ The time format which to use and calculate the remaining time.
Accepts: A string of any format formed by DD, HH, MM, SS, separated by a colon (i.e. ‘mm:ss’ or ‘dd:ss’ and so on…)
serverDateSource ‘dateandtime.php’ The source where to grab the dateandtime.php file from. The file is found in the download.
Accepts: Path to dateandtime.php i.e. ‘http://mydomain.com/dateandtime.php’
timezone ‘Europe/London’ Accepts a string of all PHP supported timezones.
View list: PHP supported timezones
twoDigits ‘on’ If ‘on’, the counter will force the display of minimum two characters (i.e. 01:43:04 instead of 1:43:4)
Accepts:‘on’ or ‘off’


jCounter demos

DATE-BASED COUNTDOWN

HTML:

jCounter call


CUSTOM-RANGE COUNT UP (10 => 999)

HTML:

jCounter call


CUSTOM-DURATION COUNTER (9 minutes)

HTML:

jCounter call


Tips & Tricks

For customDuration-based countdowns, you can use arithmetical calculations to set the duration. For example, if you’d like a custom countdown for 1 hour, instead of adding the number of seconds 3600, just add 60*60, or for 3 days you can add 60*60*24*3 and so on.

To internationalize the countdown and have it in another language, just edit line #20 and #21 from jquery.jCounter-v*.*.*.js, those are two arrays holding both plural and singular labels.

Always start jCounter with the property debugLog: true when first installing jCounter on a page and make sure there are no errors (some errors are subtle and it’s best to consult yourself with the Console Log).


Change log

2012.10.28 – v0.1.4 (beta)

  • fixed: The slide-ready themes could not be used without the slide effect turned on.
  • fixed: The reset method had a glitch when resetting a sliding counter.

2012.10.27 – v0.1.3 (beta)

  • updated setting: fallback (renamed from fallback to callback) – it’s a callback after all…
  • new theme: iOS dark
  • new theme: iOS light
  • new setting: animation (slide)
  • Changes: jCounter now uses dateandtime.php locally by default! Which means you need to point the setting serverDateSource to dateandtime.php (it needs to be on a server that’s running PHP, preferrably on the server that jCounter is running on). If no path or an incorrect path will be specified, then jCounter will use the client-side date to retrieve the current time, which is not as accurate as some would expect, nor it would supply support for timezones.

2012.10.21 – v0.1.2 (beta)

  • new theme – dark scoreboard (default)
  • new theme – white scoreboard

2012.09.26 – v0.1.1 (beta)

  • fixed the date-based fallback, it used to show negative numbers when refreshing

2012.09.26 – v0.1.0 (beta)

  • complete rewrite
  • added: real server-side timezone support for date-based instances
  • updated: the twoDigits setting (renamed from format to twoDigits)
  • new setting: timezone
  • new setting: format
  • new setting: customDuration
  • new setting: customRange
  • new setting: fallback
  • new setting: dateSource
  • new method: pause
  • new method: stop
  • new method: reset
  • new method: start

2011.11.22 – v0.0.1

  • initial write of plugin as a tutorial [ lacked many things:) ]


License

Licensed under The MIT License

In other words, use it for both personal and commercial purposes, but don’t remove the credits.


Thanks to

A big thanks to Alexandru Mesu for contributing to jCounter’s design! (hence the new themes!)
You can get in touch with him via LinkedIn

Thanks to Alexandru Margarit for all his invaluable support!




For feature requests, bug reports or support, you can use this contact form

Be notified with jCounter updates!

Opt-in
Name
Email Address *