FlipClock.js 0.8.0 Beta

Why FlipClock.js?

So why use this library when there are many others with the same name? Well, this library was created because the other solutions weren’t abstract enough to provide a deep level of customization without rewriting the code. (Besides the domain was available, who could pass it up?). Some libraries have a huge cascade of conditionals, while others simply hard-code too much into their scripts. Most projects had a very narrow scope. After reviewing as many of the existing solutions as possible, it was determined a proper extendible API needed to be written to create any kind of clock or counter (and the flip effect is just cool). The following are the logical requirements that were considered when creating the API.

  • Use as a clock
  • Use as a timer
  • Use as a countdown
  • Themeable using pure CSS
  • Clean & Dry Syntax
  • Abstract everything into reusable objects
  • Full-Featured Developer API to create custom “Clock Faces”

Authors


Contributions

Big thanks to all the examples on the Internet. But in particular, a huge thanks goes out to Adem Ilter who built this example, which provided the best animation and least amount of code to prove the concept.


Requirements


Basic Example

Loading the Scripts

FlipClock.js requires a few files to work properly. The minified source contains all the clock faces for maximum portability.


<html>
	<head>
		<link rel="stylesheet" href="/assets/css/flipclock.css">
	</head>
	<body>
		<div class="your-clock"></div>
		
		<script src="/assets/js/libs/jquery.js"></script>
		<script src="/assets/js/flipclock/flipclock.min.js"></script>
	</body>
</html>

Instantiating

FlipClock.js requires jQuery for DOM manipulation. It works a typical jQuery plugin, but instead of returning a jQuery object, a FlipClock object is returned.


var clock = $('.your-clock').FlipClock({
// ... your options here
});

var clock = new FlipClock($('.your-clock'), {
// ... your options here
});

Note, both these examples would produce the example same thing. Use the syntax that works best for you.


Options

Factory Options

The factor options will change the way the FlipClock.Factory object is instantiated.

classes
(object) This is an object of CSS classes to use to append to DOM objects
clockFace
(string) This is the name of the clock that is used to build the clock display. The default value is HourlyCounter.
clockFaceOptions
(object) An object of options to be passed to the clock face. Each clock may implement its own unique set of options.
defaultClockFace
(string) This is the default clock face to use if the defined clock face does not exist. The default value is HourlyCounter.

Default Clock Face Options

Each clock face inherits a base set of clock face options, but each clock face choose to implement them or not, in addition to other options that are unique that specific clock face. Check the docs for the clock face you are using if you are looking for more options.

autoPlay
(boolean) If this is set to false, the clock will not automatically add the play class to start the animation. If the play class is not added, the clock value can still change but with no animation. The default value is true.
autoStart
(boolean) If this is set to false, the clock will not automatically start. The default value is true.
countdown
(boolean) If this is set to true, the clock will count down instead of up. The default value is false. Note, the default animation will always visually flip downwards.
defaultLanguage
(string) Override the default language value. The default value is "english".
language
(string) This is the language you want to use. If the specified language doesn't exist, the default language will be used. Use this value to set the language. Only override the defaultLangauge parameter if you have a real need to do so.
minimumDigits
(int) The number of minimum digits to display on the clock face. The default value is 0.

Events

FlipClock has a full featured events API. Events are triggered by virtually every object and for every action that is performed. By design, it’s encouraged to always use events over callbacks if you are in a situation asking yourself which one to use. If an event is missing that you need, be sure to submit a pull request or issue on Github.

Full Event Reference

on()

Bind an event to an object and return a new FlipClock.Event object.


var event = clock.on('some:event' function() {
	// This code will trigger every time this event is triggered.
});

once()

Bind an event to an object to only be triggered once and return a new FlipClock.Event object.


clock.once('some:event' function() {
	// This code will be triggered once
});

off()

Remove all the events by a specific name created for the object. This method is chainable.


clock.off('some:event');

trigger()

Trigger an event for the object. This method is chainable.


clock.trigger('some:event', 'some_value');

Callbacks

Callbacks are commonly used troughout JavaScript libraries so it was necessary to include them in FlipClock. Callbacks are simple and relatively straight forward but there are lot of use cases that callbacks make difficult. Before you use a callback, you should consider using events.

onDestroy
This callback is triggered when the timer is destroyed
onCreate
This callback is triggered when the clock face is created
onInit
This callback is triggered when the FlipClock object is initialized
onInterval
This callback is triggered with each interval of the timer
onStart
This callback is triggered when the clock is started
onStop
This callback is triggered when the clock is stopped
onReset
This callback is triggered when the timer has been reset

var clock = new FlipClock($('.clock'), 100, {

	// Create a minute counter
	clockFace: 'MinuteCounter',

	// The onStart callback
	onStart: function() {
		// Do something
	},

	// The onStop callback
	onStop: function() {
		// Do something
	},

	// The onReset callback
	onReset: function() {
		// Do something
	}
});

Methods

The following methods all belong to the FlipClock.Factory class.

Chainable Methods

If a method is chainable then it can be executed with the following syntax. Note, just because you *can* do something (like the example), doesn't always mean you should. Readible code is the name of the game. :)


clock.stop().setFaceValue(100).start(function() {
	setTimeout(function() {
		clock.stop().reset().start();
	}, 3000);
});

start()

Start the clock. This method is chainable.


clock.start(function() {
// Optional callback will fire when the clock starts
});

stop()

Stop the clock. This method is chainable.


clock.stop(function() {
// Optional callback will fire after the clock stops
});

reset()

Reset the clock back to the original value. This method is chainable.


clock.reset(function() {
// Optional callback will fire after the clock resets
});

getFaceValue()

Returns the clock face's value.


var time  = clock.getFaceValue();

setFaceValue(value)

Set the clock face value. This method is chainable.


clock.setFaceValue(value);

getCountdown()

Returns the true or false and indicates if the clock face is counting down.


clock.setCountdown(true);

setCountdown(value)

Sets the clock face to a countdown if true, or forces the clock to count up if false.


clock.setCountdown(true);