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.

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.

(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.

on()

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.

Methods

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. :)