Documentation

The documentation describes Tick and all of it's views in its entirety. Not all views and functionality is available for purchase yet, they should be coming online one by one in the next weeks.

Tick

The Tick element servers as the base element of the Counter. It is the element you assign a value to and you define your callback methods on. The look 'n feel of the timer is all handled by elements added inside of the tick element. The base tick element looks like this:

<div class="tick"></div>

The size of the Tick counter can be defined with CSS font-size. By default Tick follows the base font size (and font family) of the website. Depending on the view type you'll probably have to increase the font size of the Tick counter a fair bit to make it look great. You can do so using the CSS snippet below.

.tick {
    font-size: 2em;
}

We'll now go over other configuration options for the base element, the views, the layout elements, animation options and data transforms.

The following attributes can be set on the tick element:

Attribute Description
data-value

The data-value attribute defines the initial value of the counter. You can also update this value after the counter has been initialised, Tick will automatically update the counter for you.

If no value supplied, Tick will not render anything

data-did-init

The callback function to call when the counter has initialised.

The default is no callback

<div class="tick"
     data-did-init="handleInit"
     data-value="1000">

    <span data-view="text"></span>

</div>

<script>
function handleInit(tick) {

    // The `tick` parameter contains a reference
    // to the tick element that called this method
    // this makes it easier to use a single function
    // for multiple tick elements.

}
</script>
data-did-update

A callback function to call when the value of the counter was updated.

The default is no callback

data-will-remove

A callback function to call just before the counter will be removed.

Useful for when you want to clean up some things before removal.

The default is no callback

data-did-remove

A callback function to call when the counter was removed.

The default is no callback

Tick also has a public API. The following methods are available on the Tick object:

Method Description
supported

The Tick.supported getter returns true if the current browser supports Tick.

// the supported variable will now be either true or false
var supported = Tick.supported;
DOM.create

Call Tick.DOM.create() to create a new Tick counter. The method takes two optional arguments. An element and or an options object.

More information on the tick options object

// create an empty ticker with no options
var tick = Tick.DOM.create();

// create a ticker with some options
var tick = Tick.DOM.create({
    value: 1000,
    didInit: function(tick) {
        console.log('hello!');
    }
});

// create a ticker on an element
var element = document.querySelector('#my-element');
var tick = Tick.DOM.create(element);

// create a ticker on an element with options
var element = document.querySelector('#my-element');
var tick = Tick.DOM.create(element, {
    value: 1000,
    didInit: function(tick) {
        console.log('hello!');
    }
});
DOM.destroy

Call Tick.DOM.destroy(element) to destroy the Tick counter bound to the given element.

<div class="tick"
     data-value="5"
     data-did-init="selfDestruct">

    <span data-view="text"></span>

</div>
<script>
function selfDestruct(tick) {

    var timer = Tick.helper.interval(function(){

        tick.value--;

        if (tick.value === 0) {

            // clean up timer
            timer.stop();

            // clean up tick
            tick.destroy();
        }

    },1000);

}
</script>
DOM.parse

Call Tick.DOM.parse(document.body) to search for Tick counter elements in the given context (in this case document.body) and turn found elements (elements with class .tick)into Tick counters.

DOM.find

Call Tick.DOM.find(element) to return the Tick counter bound to the given element.

helper.interval

Use Tick.helper.interval(callback, interval, options) to setup an accurate timer for updating the Tick value. The callback parameter is required, the interval defaults to 1 second if left out. The options parameter is also optional.

The function returns a timer object. The following methods are available on that object, they are pretty self explanatory:

  • start
  • stop
  • reset
  • pause
  • resume

The options object can be used to prevent the timer from automatically starting.

An example with all parameters.

var timer = Tick.helper.interval(
    // callback function receives total runtime
    function(runtime) {
    
    },
    
    // interval between ticks
    1000,
    
    // we will manually start this timer
    { autostart:false }
);

// start the timer
timer.start();

A live example with only the callback parameter.

<div class="tick"
     data-value="1000"
     data-did-init="setupInterval">

    <span data-view="text"></span>

</div>
<script>
function setupInterval(tick) {

    Tick.helper.interval(function() {

        // increase value of counter each second
        tick.value++;

    });

}
</script>
helper.date

Returns current time or date object based on ISO string.

Tick.helper.date() returns current date.

Tick.helper.date('2015-10-10T12:00:00') returns a date object (includes timezone correction) based on the given ISO 8601 compliant string.

helper.duration

Can be used for three purposes:

  • Transform a value in a unit type to a number of milliseconds
  • Convert a number of milliseconds into a duration of for instance hours or minutes or days
  • Calculate the duration between two dates based.

Tick.helper.duration(10, 'seconds') returns the 10 seconds equivalent in milliseconds.

Tick.helper.duration(10, 'seconds'); // 10000
Tick.helper.duration(1, 'minute'); // 60000
Tick.helper.duration(1, 'day'); // 86400000

Tick.helper.duration(86400000, ['h','m','s']) returns the duration in hours minutes and seconds of the given amount of milliseconds. It does not take into account leap years or other date related differences as it only has an amount of milliseconds to work with.

Tick.helper.duration(86400000, ['h','m','s']) // [24, 0, 0]
Tick.helper.duration(86400000, ['m','s']) // [1440, 0]

Tick.helper.duration(a, b, format) returns the duration between date a and date b in the given format taking in account leap years and date related differences.

  • 'y' Years
  • 'M' Months
  • 'w' Weeks
  • 'd' Days
  • 'h' Hours
  • 'm' Minutes
  • 's' Seconds
  • 'mi' milliseconds
// define date A
var a = Tick.helper.date('2016');

// define date B
var b = Tick.helper.date('2019');

// default format is days, hours, minutes.
Tick.helper.duration(a, b);
// [1096, 0, 0]

// difference in years, months, days
Tick.helper.duration(a, b, ['y', 'M', 'd']);
// [3, 0, 0]
data.request

Tick.data.request(url, success, error, options) is a handy helper function to do quick AJAX requests. Both url and success are required parameters, error and options can be left out.

The success callback is called when the request was successful, if not, the error callback is called. The options parameter is not an object but a function. The option function is called right after creating the XMLHttpRequest object and is given the object as it's parameter. This allows you to add your custom properties and headers to the request object without having to rewrite the request function.

// request data from the `data.php` file
Tick.data.request(
    'data.php',
    function(response) {
        // handle server response
    }
);

// add additional headers
Tick.data.request(
    'data.php',
    function(response) {
        // handle server response
    },
    null,
    function(xhr) {
        xhr.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
    }
);
data.poll

Tick.data.poll(url, success, interval) is a handy helper function that combines request and interval to poll a given URL each x amount of milliseconds. Both url and success are required parameters, if interval is left out it defaults to a minute.

count.down

Tick.count.down() counts down a given amount of milliseconds or counts down to a given date based on input parameters.

<div class="tick"
     data-did-init="startNumericCountdown">
    <span data-view="text"></span>
</div>
<script>
    function startNumericCountdown(tick) {
        var counter = Tick.count.down(10, 'seconds');
        counter.onupdate = function(value) {
            // value will contain amount of seconds left
            tick.value = value;
        };
        counter.onended = function() {
            // reached zero!
        }
    }
</script>
    

When given a date (either date object or ISO8610 string) the Tick.count.down method will count down to the given date.

<div class="tick"
     data-did-init="startDateCountdown">
    <span data-view="text"></span>
</div>
<script>
    function startDateCountdown(tick) {
        var counter = Tick.count.down('2018');
        counter.onupdate = function(value) {
            // by default value will contain an
            // array with days, hours, minutes, seconds
            tick.value = value;
        };
        counter.onended = function() {
            // reached target date!
        }
    }
</script>

You can control the time denominations by passing an options object parameter like so.

Tick.count.down('2018', {
    format: ['d','h','m','s']
});

The following additional parameters are available.

  • server
  • interval
Tick.count.down('2018', {
    // format of output
    format: ['Y','M','d','h','m','s']
    
    // set to true to use server date 
    // Date is automatically determined by parsing server response headers
    // can also be set to an ISO8601 date string
    server: false,
    
    // the interval between updates 
    interval: 1000
});
count.up

Tick.count.up() counts up from a given date string. Accepts same parameters as count down but only handles dates. Count up does not have an onended callback method.

<div class="tick"
     data-did-init="startDateCountUp">
    <span data-view="text"></span>
</div>
<script>
    function startDateCountUp(tick) {
        var counter = Tick.count.up('2017');
        counter.onupdate = function(value) {
            // by default value will contain an
            // array with days, hours, minutes, seconds
            tick.value = value;
        };
    }
</script>
count.schedule

Tick.count.schedule() counts towards a date according to a determined schedule. The schedule is given in a natural language which Tick automatically parses to find out the intended schedule.

Tick supports a the following schedule directives where all numbers and denominations are configurable. The wait statements tell Tick to wait an x amount of time before resuming countdown.

  • Daily

    • every hour
    • every 20 minutes
    • every 30 seconds
    • from 10 till 20 every hour wait 5 minutes
    • from 10:00:00 till 14:00 every 15 minutes
    • every day at 10
    • every day at 13:45:30
    • every dat at 12:00 wait 1 hour
  • Weekly

    • every wednesday at 13
    • every wednesday at 12:00 wait 10 minutes
    • wednesday every hour
    • wednesday from 10 till 14 every hour
    • wednesday 10:00 wait 2 hours
    • every wednesday every 5 minutes
    • every tuesday from 10 till 12 every 5 minutes wait 10 seconds
  • Monthly

    • every 1st day of the month at 5
    • every month on the first day
    • every month on the 12th day
    • every last day of the month at 12:00 wait 1 hour
    • every 20th day of the month
    • every 20th day of the month from 10 till 14 every hour
  • Yearly

    • every 1st of november at 13
    • every 2nd of november at 12:00
    • every first day of november at 14:00:15
    • every last day of november at 10 wait 30 minutes
    • every 20th day of november
    • every 20th day of november
    • every 20th day of november from 10 till 14 every minute
<div class="tick"
     data-did-init="startSchedule">
    <span data-view="text"></span>
</div>
<script>
    function startSchedule(tick) {
        var counter = Tick.count.schedule('every 5 minutes',{
            format:['m','s']
        });
        counter.onupdate = function(value) {
            tick.value = value;
        };
    }
</script>
plugin.add

An API endpoint to add plugins to Tick. By itself Tick only features a Text view and no custom fonts.

Tick can then be extended with plugins to render all sorts of counters. The jQuery, Kickstart and Global packages of Tick will automatically load plugins. You only need this API when you are using the CommonJS, ES2015 or AMD version of Tick.

The add function takes either three parameters or one.

With three parameters:

  • Type of plugin.
    • 'view'
    • 'font'
    • 'easing-function'
    • 'transform'
    • 'transition'
  • Name of the plugin.
  • The function that exports the plugin.

One parameter:

  • The plugin module.
// One parameter
import Dots from './tick.view.dots.module';
import HighresFont from './tick.font.highres.module';

// add the dots plugin
Tick.plugin.add(Dots);

// add the font plugin
Tick.plugin.add(HighresFont);

// Three parameters
Tick.plugin.add('view', 'dots', Dots);
Tick.plugin.add('font', 'highres', HighresFont);

A Tick instance exposes the following methods

Name Description
value

Used to set or get the value of the Tick Counter.

// set value
tick.value = 10;

// get value
var myValue = tick.value;
destroy

Destroy this tick counter.

tick.destroy();
root

Returns the root element of this tick counter.

var element = tick.root;
Method Description
// the supported variable will now be either true or false
var supported = $.tick.supported;
create

Call $(selector).tick('create') to create a new Tick counter on the element selected with the given selector. The method takes optional option object.

More information on the tick options object

// create an empty ticker with no options
var $element = $(selector).tick('create');

// create a ticker with some options
var $element = $(selector).tick('create', {
    value: 1000,
    didInit: function(tick) {
        console.log('hello!');
    }
});
destroy

Call $(selector).tick('destroy') to destroy the Tick counter bound to the given selector.

parse

Call $(document.body).tick('parse') to search for Tick counter elements in the given context (in this case document.body) and turn found elements (elements with class .tick) into Tick counters.

find

Call $(selector).tick('find') to return the Tick counter bound to the given selector.

value

Used to set or get the value of the Tick Counter.

// set value
$(selector).tick('value', 10);

// get value
$(selector).tick('value');
root

Returns the root element of the counter.

var element = $(selector).tick('root');
*

The following methods function the same as described on the Tick JavaScript API.

  • helper
    • interval
    • date
    • duration
  • data
    • request
    • poll
  • count
    • down
    • up
    • schedule
  • plugin
    • add

The only difference is that calling them when using jQuery is done with $.tick instead of Tick.

So Tick.helper.interval in jQuery becomes $.tick.helper.interval.

Tick Options

The options object takes the following properties:

Name Description
value

Used to set the initial value of the Tick Counter. Can be almost anything.

No default value

view

The view to render, only necessary when building the tick counter using JavaScript.

More information on the view property can be read below.

Uses text view by default

  • didInit
  • didUpdate
  • willRemove
  • didRemove

The callbacks as described in the Tick attribute table.

Tick View Property

The view property available on the the options object of the Tick.DOM.create(element, options) method can be used to build a tree of presenters with JavaScript. A presenter in this case is an object describing the element Tick should automatically create.

If we omit the element parameter from the Tick.DOM.create function, Tick will automatically create an element for us. The example below only contains the options parameter to keep things concise. All presenter objects are marked with comments.

Setting up a Tick counter view in JavaScript

// create Tick Counter
var tick = Tick.DOM.create({
    value: 1234,
    view: [
        // presenter object
        {
            root: 'div',
            layout: 'horizontal fill',
            children: [
                // presenter object
                {
                    view: 'flip'
                },
                // presenter object
                {
                    view: 'line',
                    root: 'div'
                }
            ]
        }
    ]
});

// add Tick Counter to body element
document.body.appendChild(tick.root);

Setting up a Tick counter view in jQuery

// create Tick Counter
$(element).tick('create', {
    value: 1234,
    view: [
        // presenter object
        {
            root: 'div',
            layout: 'horizontal fill',
            children: [
                // presenter object
                {
                    view: 'flip'
                },
                // presenter object
                {
                    view: 'line',
                    root: 'div'
                }
            ]
        }
    ]
});

A presenter is either defines a layout or defines a view. A presenter is a view if the object has a view property. Otherwise the presenter is automatically a layout.

The following properties are available on for presenter objects:

A view presenter object cannot have the following properties:

A layout presenter object cannot have these properties:

Name Description
view

The name of the view in string format.

  • text
  • swap
  • flip
  • dots
  • line
  • boom

No default value.

root

The HTML element to use for the root of this presenter. It's either a string or an HTML element.

By default this is a `span`

style

The style string to pass to the view.

By default no styles are supplied

overlay

The overlay type of this element. See data-overlay for more details on the possible values.

No default value

layout

The layout type of this element. See data-layout for more details on the possible values.

No default value

repeater

Set to true to make this a repeater presenter. Similar to data-repeater.

Default is false

children

An array of child presenters.

Default is empty array

key

A key to use when passing an object as value. Similar to data-key.

Default is null

transform

A value transform chain to apply to the value received by this presenter.

Default is null

Views

Tick Studio (not available yet) ships with five different views for presenting data. It's also possible that you've bought a single view.

Each view features different configuration options and can be combined with the other views.

You setup the view using the data-view attribute on an HTML element of your choice (within the tick element). This will most likely be a div or a span based on the type of layout you're building.

<!-- The HTML below creates a flip view -->
<div class="tick">
    <span data-view="flip"></span>
</div>

Views can be styled and configured using the data-style attribute. The data-style attribute can be updated while the counter is running to update the presented view (for instance, change color when a certain value is presented). Some views have lots of style options while others are more limited.

<!-- Set custom styles to a flip view -->
<div class="tick">
    <span data-view="flip"
          data-style="flip-duration:500ms"></span>
</div>

Text

The text view displays the given value as a simple text. The text view accepts values of type string and type number.

<div class="tick"
     data-value="Hello World">

    <span data-view="text"></span>

</div>

You can set all style aspects of the text using CSS.

<style>
#text-styled [data-view="text"] {
    font-weight: bold;
    font-family: sans-serif;
    color: red;
    letter-spacing: .25em;
}
</style>
<div class="tick"
     id="text-styled"
     data-value="Hello World">

    <span data-view="text"></span>

</div>

Swap

With the Swap view you can update text with animations. These animations can be configured with the transition, transition-in, transition-out and transition-direction properties.

Press the +1 button to view the animation example.

<div class="tick"
     data-value="1000">

    <span data-view="swap"
          data-style="transition:swap, crossfade"></span>

</div>

If you want the text to be cut of use the overflow CSS property.

<style>
#text-style-overflow [data-view="swap"] {
    overflow-y:hidden;
}
</style>
<div class="tick"
     id="text-style-overflow"
     data-value="1000">

    <span data-view="swap"
          data-style="transition:swap, crossfade"></span>

</div>

More on setting and configuring transitions can be read below in the transitions topic as they can be used in different views. The transition-direction property is text view only so we'll discuss that one here.

If you set transition-direction to detect Tick will try to detect if the value is increasing or decreasing and will switch the animation direction accordingly.

<div class="tick"
     data-value="1500">

    <span data-view="swap"
          data-style="transition-direction:detect; transition:swap, crossfade"></span>

</div>

Flip

The flip view renders the familiar classic Flip Counter. It accepts values of type string and type number.

<div class="tick"
     data-value="Hello World">

    <span data-view="flip"></span>

</div>

Note that this is the exact HTML as shown in the text example but we've replaced the word text with flip. We could even render both a text and a flip counter by adding another view node.

<div class="tick"
     data-value="Hello World">

    <span data-view="flip"></span>

    <span data-view="text"></span>
    
</div>

Alright, let's revert back to showing only the Flip Counter. Tick will render and animate a subtle shadow below the flipper so it feels like it has depth.

You can tweak the flip counter to your liking with the following style properties flip-duration, flip-easing, shadow and rounded.

flip-duration controls the duration of the flip which can be set in milliseconds. The default value is 800 milliseconds.

flip-easing allows you to set different easing methods for the flip animation. By default Tick uses a bounce ease called ease-out-bounce. You can view three other easing functions below.

shadow controls the shadows displayed. Default value is all shadows, you can set it to inner to only render inner shadows or none to remove all shadows.

The rounded property can be set to none to remove all rounded corners, or panels to add rounded corners to the panels themselves.

Here we define different easing modes on the flipper.

<div class="tick"
     data-value="1000">

    <span data-view="flip"
          data-style="flip-easing: ease-linear"></span>

    <span data-view="flip"
          data-style="flip-easing: ease-in-circ"></span>

    <span data-view="flip"
          data-style="flip-easing: ease-in-out-quart"></span>

</div>

Styling of the flip counter can be done with CSS.

/* distance from other flippers */
.tick-flip {
  margin-left: .0625em;
  margin-right: .0625em;
}

/* border radius of the flipper */
.tick-flip {
  border-radius: .125em;
}

/* color of the flipper */
.tick-flip-panel {
  color: #eee;
  background-color: #333;
}

/* shadow behind the flipper */
.tick-flip-shadow {
  box-shadow: 0 0 1em #000;
}

/* padding in the flipper (both values should be the same) */
.tick-flip {
  letter-spacing: .25em;
  text-indent: .25em;
}

An example when we change the color, increase the padding and spacing between the characters and make the corners more round.

<style>
/* rounder corners */
#my-flip {
    /* increase border radius */
    border-radius:.3125em;

    /* increase spacing between letters */
    letter-spacing: .5em;
    text-indent: .5em;
}

/* black on white colors */
#my-flip .tick-flip-panel {
    color: #555;
    background-color: #fafafa;
}
</style>

<div class="tick"
     data-value="1000">

    <span id="my-flip" 
          data-view="flip"></span>

</div>

Dots

The dots view displays passed values in a led matrix display.

It can display numeric values, spaces, dashes dots and commas.

<div class="tick"
     data-value="12.345,50">

    <div data-view="dots" data-style="font:highres"></div>

</div>

You can define the border-radius, color, size, and distance between the pixels using CSS.

Use width and height to set the dot size, use margin to define the distance between the dots.

By default the size of the dots is set to 5px, the distance between them is 1px. The color of the dots is derived from the text color.

<style>
#dots-size .tick-dots-dot {
    width: 10px;
    height: 10px;
    margin: 2px;
    border-radius: 25%;
    background-color: red;
}
</style>
<div class="tick"
     id="dots-size"
     data-value="123">

    <span data-view="dots"></span>

</div>

The distance between the characters is defined with CSS as well. The default distance is 0.05em.

<style>
    #dots-distance .tick-dots-character {
        margin:0 1em 0 0;
    }
</style>
<div class="tick"
     id="dots-distance"
     data-value="123">

    <span data-view="dots"></span>

</div>

The dots view has the following style properties:

The transition properties take care of the animation between the dot off and dot on state. By default dots are faded out when turned off and faded in when turned on.

Name Description
font

The font to render the text in. Choose between lowres or highres.

Default is highres

shape

The shape of the dots. auto means that it's defined in CSS. Set to circle or square to set the matching dot shape.

With small dot sizes browser rendering might turn circle shaped dots into slightly square dots.

Default is 'auto', slightly rounded corners with CSS

<style>
    #dots-shape .tick-dots-dot {
        width:10px;
        height:10px;
    }
</style>
<div class="tick"
     id="dots-shape"
     data-value="123">

    <span data-view="dots"
          data-style="shape:circle"></span>

</div>
color

The color of the dots. Any valid CSS color value.

You can also set gradients. There are two types of gradients to choose from:

  • horizontal-gradient(red, green, blue)
  • vertical-gradient(#ff0000, green, rgba(0,0,255,.5))

Horizontal will draw from left to right, where vertical will draw from top to bottom. You can set percentage values to define where each color should start like so follow-gradient(red, green 20%, orange, 40%, blue)

The default background color is 'auto' which means the color is defined in CSS

<div class="tick" data-value="123">

    <div data-view="dots" data-style="color:#ec3bbd"></div>

    <div data-view="dots" data-style="color:horizontal-gradient(red 0, #ff59f1 25%, blue 100%)"></div>

    <div data-view="dots" data-style="color:vertical-gradient(orange, #f00)"></div>

</div>
align

The alignment of the text in the matrix display, mostly relevant for animation purposes. Set to either 'left' or 'right'.

Default is 'left'

dot-update-delay

The delay between dot updates in milliseconds. Set to a higher value to slow down the character update animation.

Default is 10

<div class="tick"
     data-value="199">

    <span data-view="dots" 
          data-style="dot-update-delay:100"></span>

</div>
character-update-delay

The delay between character updates in milliseconds. Combine with align to animate from the right direction.

Default is 0

<div class="tick"
     data-value="109">

    <span data-view="dots"
          data-style="character-update-delay:1000; align:right"></span>

</div>
transition

The transition to use when animating between dot states, The default transition is set to crossfade. For more about transitions read the transition documentation

Default is 'crossfade'

<div class="tick"
     data-value="109">

    <span data-view="dots"
          data-style="transition:swap(y, -.5), crossfade(.5)"></span>

</div>

Line

The line view is especially good in showing percentages. It accepts a value between 0 and 1 and cannot be used to present text.

It's best to use div as a base element to apply the meter view to. By default the line view presents data in a horizontal progress bar.

Below we present the value 0.25 in a default line view. It renders a horizontal bar with a foreground and background color. You can feed other values into a meter (they don't have to be between 0 and 1), we'll get into that in the value transform section of the documentation.

<div class="tick"
     data-value=".25">

    <div data-view="line"></div>
    
</div>

The line view can also be rotated vertically or transformed into a circle.

<div class="tick"
     data-value=".25">

    <div data-view="line" 
         data-style="orientation:vertical"></div>

</div>

I've added a div around the circular meter to make it a more acceptable size.

<div class="tick"
     data-value=".25">

    <div style="max-width:5em;">
        <div data-view="line" 
             data-style="shape:circle; rail-color:#fff"></div>
    </div>

</div>

The default rectangle shaped progress bars take the following style values:

Name Description
fill-color

The color of the progress fill. By default it's styled with CSS.

The default is none

rail-color

The color of the background of the meter. By default it's styled with CSS.

The default is none

cap-style

The shape of the meter start and end. Can be either auto, round or butt.

If set to auto you can define the shape in CSS.

The default is 'auto'

orientation

Either horizontal or vertical, the orientation of the bar.

The default is 'horizontal'

The circular shaped progress bar exposes the following style properties:

Name Description
offset

Defines the starting point of the circle in a value between 0 and 1.

The default is 0

length

Defines the length of the circle in a value between 0 and 1.

The default is 1

gap

Defines the gap between the fill and rail in a value between 0 and 1.

The default is 0

flip

Makes the progress indicator move in the opposite direction.

The default is false

invert

Switches the fill and rail from position.

The default is false

align

The alignment of the fill and the rail. Can be either center, top, inside or bottom.

The default is 'center'

padding

The padding of the draw area, useful in combination with align option if ring is drawn outside of canvas. Can be any CSS unit.

The default is 0

cap-style

The shape of the meter start and end. Can be either round or butt.

The default is 'butt'

fill-color

The color of the progress fill. Any valid CSS color value.

You can also set a gradients. There's three types of gradients to choose from:

  • horizontal-gradient(red, green, blue)
  • vertical-gradient(#ff0000, green, rgba(0,0,255,.5))
  • follow-gradient(#f00, #0f0, #00f)

The follow gradient will draw a gradient along the circular progress line. Horizontal will draw from left to right, where vertical will draw from top to bottom. You can set percentage values to define where each color should start like so follow-gradient(red, green 20%, orange, 40%, blue)

The default background color is #333

<div class="tick"
     data-value=".85">

    <div data-layout="horizontal fill pad">

        <div data-view="line"
             data-style="
                shape:circle; 
                fill-color:follow-gradient(red 10%, green 20%, blue 50%); 
                rail-color:white">
        </div>

        <div data-view="line"
             data-style="
                shape:circle; 
                offset:.25;
                length:.5;
                fill-color:follow-gradient(red, green, blue); 
                rail-color:white">
        </div>

    </div>

    <div data-layout="horizontal fill pad">

        <div data-view="line"
             data-style="
                shape:circle; 
                fill-color:horizontal-gradient(red 0, 
                green 20%, blue 100%); 
                rail-color:white">
        </div>

        <div data-view="line"
             data-style="
                shape:circle; 
                fill-color:vertical-gradient(red, green, blue); 
                rail-color:white">
        </div>

        <div data-view="line"
             data-style="
                shape:circle; 
                fill-color:vertical-gradient(green, blue); 
                rail-color:white">
        </div>

    </div>

    <div data-layout="horizontal fill pad">

        <div data-view="line"
             data-style="
                shape:circle; 
                fill-color:red; 
                rail-color:white">
        </div>

    </div>
    
</div>
fill-width

The width of the fill in CSS units of choice.

The default is .125em

fill-shadow

The shadow thrown by the fill. A normal CSS shadow 1em 0 3px rgba(0, 0, 0, .333).

Tick will automatically scale down the ring to make the shadow fit the drawing area.

The default is none

<div class="tick" data-value=".75">
    
    <div data-layout="horizontal fill pad">
        
        <div data-view="line"
             data-style="shape:circle;
                         fill-shadow:0 .125em .25em #000">
            
        </div>

        <div data-view="line"
             data-style="shape:circle;
                         fill-shadow:0 -.325em .125em rgba(0,0,0,.25)">

        </div>

        <div style="background-color:#222">
            <div data-view="line"
                 data-style="shape:circle;
                             gap-size:.01;
                             rail-color:#333;
                             fill-color:#fff;
                             fill-shadow:0 0 .25em #fff">
    
            </div>
        </div>
        
    </div>

    <div data-layout="horizontal fill pad">

        <div data-view="line"
             data-style="shape:circle;
                         rail-color:#fff;
                         rail-shadow:0 .125em .125em rgba(0,0,0,.25)">

        </div>

        <div data-view="line"
             data-style="shape:circle;
                         fill-color:#eee;
                         rail-color:transparent;
                         fill-shadow:0 -.125em .125em rgba(0,0,0,.5)">

        </div>

        <div style="background-color:#222">
            <div data-view="line"
                 data-style="shape:circle;
                             gap-size:.01;
                             rail-color:orangered;
                             rail-shadow:0 0 .25em orangered;
                             fill-color:springgreen;
                             fill-shadow:0 0 .5em springgreen">

            </div>
        </div>

    </div>
    
</div>
rail-color

The color of the background of the meter. Any CSS color value.

The default is #eee

rail-width

The width of the rail in CSS units of choice.

The default is .125em

rail-shadow

The shadow thrown by the rail. A normal CSS shadow 1em 0 3px rgba(0, 0, 0, .333).

The default is none

Boom

The boom view is used to play an audio fragment on value update. It is used in conjunction with other views as you can see in the example below.

For instance a "ka-tjing" sound when a new donation is made. Press the plus button below for a test.

This view does not function on IE11

<div class="tick"
     data-value="1000">

    <span data-view="text"></span>

    <span data-view="boom" 
          data-style="sample: url(/media/bell.m4a), url(/media/bell.ogg);">
        
    </span>

</div>

The quicker you press the button in succession the higher pitched the bell sound becomes. This is controlled with the pitch-step, pitch-threshold and pitch-max properties.

The following properties are available on the audio view.

Name Description
sample

The sample property defines the audio sample to use. You can supply multiple formats using a comma separated list of url().

By default there are no audio files loaded. These will have to be supplied.

volume

The volume of the audio in a range from 0 to 1. Best to set it a bit lower than master volume level as to not startle your users.

The default is .5

pitch-threshold

The max time in milliseconds between each value change for the pitch to increase.

The default is 1 second

pitch-step

The amount of pitch increased per time.

The default is .05

pitch-max

The maximum amount of pitch increase.

The default is 1.35

Layouts

So, with all the views discussed let's move on to defining a counter layout.

Elements

Tick contains a couple default layout attributes to position views. These attributes can be used anywhere within the tick element and are applied with the data-layout attribute.

We can position counters below each other using the data-layout="vertical" attribute.

<div class="tick"
     data-value="Hello World">

    <div data-layout="vertical">
        <span data-view="flip"></span>
        <span data-view="text"></span>
    </div>

</div>

There's three types of layouts.

The horizontal layout value will place all sub views on a line next to each other. Positioning of these sub views can then be handled with:

So horizontal right will align all sub views on a single line to the right. The fill value will divide all space among the available sub views. The baseline value will align items vertically by baseline offset.

The vertical layout value will place all sub views beneath each other. Positioning of these sub views is done with the following additional values:

Setting vertical bottom right will align all items to the bottom right of the element (if it's bigger then the space the elements themselves take up).

The overlay value will place elements on top of each other. Below we build a presenter with a double progress bar and a centered text view. The center and stretch values for the data-overlay attribute as set on the views take care of positioning the elements correctly.

In this case, we want the first line to define the space of the counter (there for it has no data-overlay attribute). The text we want to center on the meter, and the second meter we want to stretch so it fills all available space.

<div class="tick"
     data-value=".25">

    <div style="max-width:8em">
        
        <div data-layout="overlay">
            
            <span data-overlay="center" data-view="text"></span>
            
            <div data-view="line"
                 data-style="shape:circle; rail-color:#fff"></div>
            
            <div data-overlay="stretch"
                 data-view="line"
                 data-style="padding:1em; shape:circle; rail-color:#fff"></div>
            
        </div>
        
    </div>

</div>

There's one last attribute available for layout views called data-value-mapping. It controls how the element will pass on it's received value to it's children. By default all children receive the value the parent receives.

When the parent element value is in array form and data-value-mapping is set to "indexes" the parent element will assign each index of the array to an element.

If you explicitly set the value to "none" the parent element will ignore child keys (see the Group tab).

Repeat

To create a repeat element we set the data-repeat attribute to true. The repeater splits an incoming value into separate characters and creates a view for each of the characters.

You can use the repeater with any child view (or group of child views).

Below we can see the left element is a normal flip counter. The second one is wrapped in a repeater. The repeater then automatically generates a flip element for each character.

<div class="tick"
     data-value="1500">

    <span data-view="flip"></span>

    <span data-repeat="true">
        <span data-view="flip"></span>
    </span>
    
</div>

Group

Groups are used to bind values to certain child views.

Say you're value is an object and you want to assign properties of that object to different views then you can use the data-key attribute to handle that. Set the value of the tick base element with an object either to JavaScript or using the format as shown below, then assign the correct keys to the presenters.

<div class="tick"
     data-value="progress:.75, text:200">

    <div data-layout="vertical center fill">
        
        <div data-view="line"
             data-key="progress"></div>

        <span data-repeat="true" 
              data-key="text">
            <span data-view="flip"></span>
        </span>
        
    </div>

</div>

Value Transforms

The value you set to the data-value attribute can be transformed to be presented in all sorts of ways. We can do this using the data-transform attribute. This attribute alone is the hearth of Tick and adds all the power and flexibility to it.

The transform attribute transforms the value it receives to another value we can then be presented by a view.

Let's use our progress indicator from the admin panel demo as an example. I've shown a simplified version of the code below. I've added a style property with a max-width to limit the size of the circular progress indicator.

<div class="tick"
     data-value="45">

    <div data-layout="overlay center" 
         style="max-width:5em">

        <div data-view="line"
             data-style="shape:circle; rail-color:#fff"></div>

        <span data-view="text"
              data-overlay="center"></span>

    </div>

</div>

We've set 45 as the value. And we can see our text view renders it nicely. But, our line is completely filled while we would expect it to be near half filled.

What's happening? Our line expects a value between 0 and 1, where 0 is empty and 1 is full.

This is where the data-transform attribute comes into play. We can add that attribute to the line to transform the value into the right format.

<div class="tick"
     data-value="45">

    <div data-layout="overlay center"
         style="max-width:5em">

        <div data-view="line"
             data-style="shape:circle; rail-color:#fff"
             data-transform="fraction(0,100)"></div>

        <span data-view="text"
              data-overlay="center"></span>

    </div>

</div>

Alright, we've added the fraction transform.

The transform will take the received value and turn it into a fraction between the given min and max values, in this case 0 and 100. This will result in a value of 0.45 which then gets send to the line.

Now it would be nice if our text showed a percentage sign. We can accomplish this with the format transform.

<div class="tick"
     data-value="45">

    <div data-layout="overlay center"
         style="max-width:5em">

        <div data-view="line"
             data-style="shape:circle; rail-color:#fff"
             data-transform="fraction(0,100)"></div>

        <span data-view="text"
              data-overlay="center" 
              data-transform="format('$0%')"></span>

    </div>

</div>

The format transform takes a string value (in this case '$0%' and replace the $0 part with the received value.

If we tap the plus button for long enough the value will get higher then 100, we can prevent this with the limit transform. Note that this only presents values outside of the limit range from being presented, the value of Tick will still be what you set to it.

<div class="tick"
     data-value="45">

    <div data-layout="overlay center"
         data-transform="limit(0,100)"
         style="max-width:5em">

        <div data-view="line"
             data-style="shape:circle; rail-color:#fff"
             data-transform="fraction(0,100)"></div>

        <span data-view="text"
              data-overlay="center"
              data-transform="format('$0%')"></span>

    </div>

</div>

If you look closely you'll notice the data-transform has been added to the layout presenter. Transforms can be added on every element and the transformed value will be passed on to the child presenters. This allows us to create complex transform structures.

Let's take a look. We'll move the fraction transform to the layout presenter next to the limit transform. We can chain transforms with an arrow ->. Then we'll a arrive transform which will interpolate between the current value and the next value using an arrival animation.

<div class="tick"
     data-value="45">

    <div data-layout="overlay center"
         data-transform="limit(0,100) -> fraction(0,100) -> spring"
         style="max-width:5em">

        <div data-view="line"
             data-style="shape:circle; rail-color:#fff"></div>

        <span data-view="text"
              data-overlay="center"
              data-transform="format('$0%')"></span>

    </div>
</div>

Our text presenter is now totally out of control. It now presents a value between 0 and 1 and during the animation it just shows a crazy bunch of decimals. Let's correct this with the multiply and round transforms.

<div class="tick"
     data-value="45">

    <div data-layout="overlay center"
         data-transform="limit(0,100) -> fraction(0,100) -> arrive"
         style="max-width:5em">

        <div data-view="line"
             data-style="shape:circle; rail-color:#fff"></div>

        <span data-view="text"
              data-overlay="center"
              data-transform="multiply(100) -> round(1) -> format('$0%')"></span>

    </div>
    
</div>

The value received by the text view is now multiplied by a 100 using the multiply transform, then it's rounded to one decimal place using the round transform. Last but not least, our format transform adds the percentage sign.

Now our numbers are beautifully and nicely animated in between updates.

Tick ships with the following transform components:

That's quite a list, let's see what each of those does and what values they accept.

The table below shows the name of the transform, the input type(s) it accepts and the output type it produces. When chaining transforms keep in mind that the transforms should fit together like Domino's, the output type of the preceding transform should match the input type of the next transform. See the example below.

In this example we've set our data-value to 4, which Tick will automatically interpreted as of type number.

transform value
4
multiply(5) 20
limit(0, 15) 15
number 15.000,00
split(',') "15.000", "00"
Name Input Output Description
input * *

Returns the value it receives.

// 1 to 1
input
value * *

Returns a static value no matter what input value is received.

// 1 to "days"
value(days)
upper string number string

Returns the value it receives in Uppercase.

// day to DAY
upper
lower string number string

Returns the value it receives in Lowercase.

// Day to day
lower
substring string number string

Returns a part of the input value. Functions the same as JavaScript substring method.

// Day to Da
substring(0,2)
abs number number

Turns negative numbers into positive numbers.

// -1 to 1
abs
add number number

Adds a fixed value to the input value.

add(10)
subtract number number

Subtracts a fixed value to the input value.

subtract(10)
multiply number number

Multiply input value with a fixed value.

multiply(5)
divide number number

Divide input value with a fixed value.

divide(2)
modulus number number

Returns what whole integer remains after dividing input value by given number.

// 5 to 1
modulus(2)
round number number

Round input value to a certain amount of decimal places.

// to 0 decimal places
round // 1.25 to 1

// to 1 decimal place
round(1) // 1.25 to 1.3
floor number number

Round down input value.

floor // 1.75 to 1
ceil number number

Round up input value.

ceil // 1.25 to 2
limit number number

Limit value between min and max. Default values are 0 and 1.

limit(2, 5) // 6 to 5
fraction number number

Calculates fraction of input value between a min and max. Default values are 0 and 100.

fraction(0, 200) // 100 to .5
percentage number number

Calculates percentage of input value between a min and max. Default values are 0 and 100.

fraction(0, 200) // 100 to 50
arrive number number

Interpolates between the previous input value and the new input value. Slowly accelerates towards the new value when halfway starts decelerating.

arrive
spring number number

Interpolates between the previous input value and the new input value using spring physics.

spring
step number number

Interpolates between the previous input value and the new input value using a fixed step size.

step(.05)
tween number number

Interpolates between the previous input value and the new input value over a given duration.

Accepts three properties, duration, ease.

tween(.5s, ease-out-bounce)
plural number string

Outputs either value a or value b depending on if the received value is 1 or another value.

If input value is equal to 1, outputs value a, else outputs value b.

plural('second', 'seconds')
number number string

Formats the input value as a number (currency).

First arguments is decimal separator, second argument is thousands separator. The default values are . for decimals and , for thousands. The third argument defines the amount of decimals (0 or 2).

Note that the output value is a string.

// 1000 to "1.000,00"
number(',', '.')
pad string number string

Pads the input value with the given string from the right side.

Note that the output value is a string.

// 50 to "0050"
pad('0000')
replace string number string

Replaces the supplied needle with the given replacement in the input value.

// "50,00" to "50.00".
replace(',', '.')
format string number string

Replaces the $0 placeholder with the received input value.

// 50 to "$ 50"
format('$ $0')
duration number array

Turns input value into a duration in requested format.

// 5000 to [5]
// 5 seconds
duration('s')

// 65000 to [1, 5]
// one minute 5 seconds
duration('m', 's')
split string number array

Splits the input value with the given character.

This is useful for feeding data to a repeater element or preparing it for a transform that only accepts an array as input.

// 5000 to [5, 0, 0, 0]
split

// 18-08-2015 to [18, 08, 2015]
split('-')
reverse array string number array string

Reverses the input value.

This is useful for feeding data to a repeater element or preparing it for a transform that only accepts an array as input.

// "5000" to "0005"
// [1, 0, 0] to [0, 0, 1]
// 100 to "001"
reverse
delay array array

Holds previous value and slowly updates the old array with the values in the newly received array.

The delay transform takes three parameters. order, min delay and max delay.

Order defines the order in which the old array is updated with the new array. This can be ltr (left to right), rtl (right to left) or random, default value is rtl.

min delay and max delay define the delay in milliseconds between updates. Tick will pick a random value between the min and max value. For fixed delay set both to the same value. The default delay is 50 milliseconds.

// random updates with random
// delay between 100 and 200
// milliseconds
delay('random', 100, 200)
keys array object

Applies keys to received array values.

// [1, 'Days'] > { value: 1, label: 'Days'}
keys(value, label)
map array array

Runs a transform function on each value of the given array.

Transforms should be given parenthesis when used as parameters.

// ['day', 'hour'] > ['DAY', 'HOUR']
map(upper())
rotate array array

Runs a transform function on each value of the given array rotating the transform functions when the end of the array is reached.

Transforms should be given parenthesis when used as parameters.

// ['Day', 'Hour', 'Minute'] > ['DAY', 'hour', 'MINUTE']
rotate(upper(), lower())
transform * *

Runs a set of transform functions against the input value returning the return value

Transforms separated by a comma will run in parallel and will cause the function to return an array.

Transforms should be given parenthesis when used as parameters.

// 'Day' > ['DAY','day']
transform(upper(), lower())

// 'Day' > 'days'
transform(format('$0s') -> lower())

Transitions

Tick ships with a set of preset transitions, transforms and easing functions.

When configuring the presets and transforms you can use all CSS units (px, em, %, etc.) as you would when defining the transitions in CSS.

Transitions are available on the swap and dots view.

Presets

Preset transitions combine a in and out transform into an animation.

Every preset animation duration is 1 second by default. Preset animations take a animation duration factor parameter which can be used to reduce the default animation speed. For instance a factor of .5 makes the animation run in 500 milliseconds instead of 1 second.

The preset animations also take a delayIn and delayOut parameter which can be used to delay the intro and outro animations separately. Values are in seconds (1s) or milliseconds (1000ms), similar to how they are defined in CSS.

Tick ships with the following preset transitions:

The available presets can be combined in the transition property. You can set one or multiple, all set presets will be run at the same time (of course set delays will be taken into account).

// single preset animation
transition: crossfade;

// multiple presets
transition: crossfade, swap;

// multiple presets with custom values
transition: crossfade(.5), swap(x);

The table below shows the available configuration options for each preset.

Name Description
crossfade

New value fades in, old value fades out.

Takes 3 optional arguments:

  • animation speed factor
  • intro delay
  • outro delay
// default
transition: crossfade;

// play in half of the normal animation duration
transition: crossfade(.5);

// play normal speed, delay intro animation
transition: crossfade(1, .25s) ;
swap

New value moves into view (over x or y axis) from position -100% to 0, old value moves from 0 to plus 100%.

Takes 5 optional arguments:

  • axis
  • distance factor
  • animation speed factor
  • intro delay
  • outro delay
// default
transition: swap;

// animate over x axis
transition: swap(x);

// animate over y axis at 50% of default distance
transition: swap(y, .5);
revolve

New value rotates into view (over x, y or z axis) from -90deg to 0, old value rotates from 0 to 90deg.

Takes 5 optional arguments:

  • axis
  • distance factor
  • animation speed factor
  • intro delay
  • outro delay
// default
transition: revolve;

// animate over z axis
transition: revolve(z);

// animate over x axis at 50% of default distance
// play in a quarter of normal animation duration
transition: revolve(x, .5, .25);

Transforms

Instead of using the preset transition you can also build you're own animations using the transition-in and transition-out properties. These can be defined with the following transforms:

Please keep in mind that these transforms are not available for the transition property, the transition property only takes presets.

Like with presets you can supply multiple, comma separated, values to transition-in and transition-out. But unlike presets the transition properties take additional arguments like duration, ease function and delay.

The possible arguments (and order) for the transition in and out styles are shown below.

transition-in: transform | origin | duration | ease | delay;

An example of building a real intro transition:

// move from -20px to position 0
transition-in: move(-20px, 0);

// do it in 500 milliseconds
transition-in: move(-20px, 0) 500ms;

// with a cubic easing function
transition-in: move(-20px, 0) 500ms ease-in-cubic;

// wait 250 milliseconds before starting
transition-in: move(-20px, 0) 500ms ease-in-cubic 250ms;

// also fade in the new value
transition-in: move(-20px, 0) 500ms ease-in-cubic 250ms, fade(0, 1) 500ms;

If you want to rotate elements it's often handy to be able to set the transform origin of a transition. You can do so with the origin argument.

// rotate element into view over z axis with the top right corner as the transform origin
transition-in: rotate(-45deg, 0, z) origin(top right) 500ms;
Name Description
move

The move transition moves an element from position start to position end.

By default it transforms from 0 to 100% over the y axis.

// move element from the left to the center in 500ms
transition-in: move(-1em, 0, x) 500ms;
rotate

The rotate transition rotates an element from start angle to end angle.

By default it transforms from 0 to 90deg over the x axis.

// element is faced backwards and flips into
// view over y axis in half a second
transition-in: rotate(-180deg, 0, y) .5s;
scale

The scale transition scales an element from start size to end size.

By default it transforms from 0 to 1 over both the x and y axis.

// element is scaled from 75% size to 100% in
// 1.25 seconds with bounce easing
transition-in: scale(.75, 1) 1.25s ease-out-bounce;
<div class="tick"
     data-value="2">

<span data-view="swap"
      data-style="
      transition-in: 
        scale(.8, 1) .75s ease-out-bounce .5s, 
        fade(0, 1) .25s .5s;
      
      transition-out: 
        fade(1, 0) .5s">
    
</span>

</div>

Easing

Transitions can make use of easing functions to make the animations look more natural. Tick ships with the following ease functions which are available everywhere an easing function can be set:

The website easings.net features a clear overview of these functions and their effect on a transition.