Soon
Documentation
Documentation
You can configure soon manually or use the visual builder. The visual builder is the adviced method as it's way easier to finetune your countdown component that way.
If you're using the visual builder extras/builder.html
or are going to copy paste HTML from this document you can use the extras/setup.html
template as a starting point.
The easiest way to manually work with Soon is by writing HTML, once Soon runs it will pickup all HTML nodes with the .soon
class and turn them into counters. If you want more control you can use jQuery or the Soon API to create your counters manually.
Add an HTML node to your website with the class .soon
like this <div class="soon"></div>
. Soon will pick it up immidiately and render a simple clock. This is the default state and it quickly tells you everything is working.
You can turn the clock into a countdown by adding the data-due
attribute. If you want to count up from a date, set the data-since
attribute instead.
The data-due
and data-since
attributes can be set in ISO 8601 format. This may sound adventurous but don't worry it's actually pretty easy.
A couple of example date are shown below:
2016
counts to a certain year.2016-11
counts to a specific month, in this case November.2016-11-25
counts to a specific day.2016-11-25T22:10
counts to a specific time.For cases where you need to set a timezone just add it after the time +05:00
.
2016-11-25T22:10+05:00
The data-due
attribute also accepts two other ways of defining a due date. You can can set it to count down a fixed amount of time from page load.
in 10 seconds
in 5 minutes
in 6 hours
in 1 hour
Or you can count down to a certain time on a certain day.
at 12
12 o'clock each dayat 9
9 o'clock each daymonday at 10:30
monday at 10:30at 15:10:05
each day at 15:10:05sunday at 10 zone +01:00
10 o'clock on sunday with fixed timezonePrepend reset if you want to reset the counter when it reaches zero.
reset monday at 10:30
will count to next monday at 10:30 once it's monday 10:30:01.Below you can see Soon's default state (the current time) and what happens after you add a due date or a since date.
<!-- no date set -->
<div class="soon"></div>
<!-- due date set -->
<div class="soon" data-due="2017"></div>
<!-- due date set -->
<div class="soon" data-due="in 5 minutes"></div>
<!-- due date set -->
<div class="soon" data-due="at 23:30"></div>
<!-- due date set -->
<div class="soon" data-due="monday at 12:00"></div>
<!-- due date set -->
<div class="soon" data-due="reset monday at 12:00"></div>
<!-- since date set -->
<div class="soon" data-since="2014"></div>
Soon can be used with jQuery, but this is not a requirement.
If you want to use jQuery you can create Soon counters using the script shown in the codeblock below. Read more about jQuery methods in the Create section of the documentation.
<script>
$(document).ready(function() {
// create a simple soon counter on the supplied element
$(".your-counter").soon().create({
due:"2017",
layout:"group"
});
// create a more advanced counter
$(".your-advanced-counter").soon().create({
due:"2017-11-25",
layout:"group tight",
face:"flip color-light corners-sharp shadow-soft",
separateChars:false,
eventComplete:function(){ alert("done!"); }
});
});
</script>
You can pick different ways to present your counter by setting the data-face
attribute. By default Soon uses text
. After choosing a face type the specific type can then be customized to your liking with additional animation and visual options. We'll get to that in the Making it visually unique topic.
Currently available face types:
text
defaultslot
animates changes between characters, you can pick from a diverse set of animations and animation directions.flip
a beautiful flip counter, available in black and white.matrix
a dot matrix counter, real old school.<!-- text -->
<div class="soon" data-due="2017"
data-face="slot">
</div>
<!-- slot -->
<div class="soon"
data-due="2017"
data-face="slot">
</div>
<!-- flip -->
<div class="soon"
data-due="2017"
data-face="flip">
</div>
<!-- matrix -->
<div class="soon"
data-due="2017"
data-face="matrix">
</div>
To spice up your counter you can pick from two different visuals. A ring and a fill visual. Both show the individual progress for each group of values. As with the views, these two can also be customized, this we'll dive into in the Making it visually unique topic.
<!-- the ring visual -->
<div class="soon"
data-due="2017"
data-face="slot"
data-visual="ring">
</div>
<!-- the fill visual -->
<div class="soon"
data-due="2017"
data-face="slot"
data-visual="fill">
</div>
There's a whole set of options to configure the way Soon formats the countdown.
You can set the date format by supplying the data-format
attribute. By default it renders days, hours, minutes and seconds. You can also have it show years, months, weeks and milliseconds by using the y
, M
, w
and ms
formatters.
<!-- only show days -->
<div class="soon" data-due="2017" data-format="d"></div>
<!-- hours and minutes -->
<div class="soon" data-due="2017" data-format="h,m"></div>
<!-- only seconds -->
<div class="soon" data-due="2017" data-format="s"></div>
<!-- milliseconds -->
<div class="soon" data-due="2017" data-format="h,m,s,ms"></div>
<!-- show years -->
<div class="soon" data-due="2018" data-format="y,d,h,m,s"></div>
By default Soon cascades values. This means that if you disable the day in the data-format
attribute the amount of days will be shown as hours. Sometimes you may not want to do this, in that case you can set the data-cascade
attribute to false
.
<!-- only show days -->
<div class="soon" data-due="2017" data-format="d"></div>
<!-- hours and minutes -->
<div class="soon" data-due="2017" data-format="h,m,s"></div>
<!-- hours and minutes, no cascade -->
<div class="soon" data-due="2017" data-format="h,m,s" data-cascade="false"></div>
With cascade
Without cascade
Charachter separation allows you to control if Soon will put each character in it's own slot. See below for an example using the flip face.
<div class="soon"
data-due="2017"
data-face="flip">
</div>
<div class="soon"
data-due="2017"
data-separate-chars="false"
data-face="flip">
</div>
What if you want to use a :
or .
between character groups? Use the data-separator
property. Any value set will be put between the character groups.
<div class="soon"
data-separator="/"
data-due="2017"
data-face="text">
</div>
<div class="soon"
data-separator=":"
data-due="2017"
data-face="text">
</div>
Use the attributes shown in the example HTML to control the names shown in the labels. You can supply a single value if you're only gowing to use plurals. If you intend to use singular labels you can supply two values by separating them with a comma.
<div class="soon"
data-due="2017"
data-labels-days="Dia,Dias"
data-labels-hours="Hora,Horas"
data-labels-minutes="Minuto,Minutos"
data-labels-seconds="Segundo,Segundos">
</div>
Controls the use of singular and plural terms in labels. If set to true
Soon will use singulars when a counter reaches 1. The default state is false
.
<div class="soon"
data-due="2017"
data-singular="true"
data-face="slot">
</div>
Allows you to put zeros in front of values. Or disable padding altogether by setting the data-padding
attribute to false
.
<!-- no padding -->
<div class="soon"
data-padding="false">
</div>
<!-- minute and second padding -->
<div class="soon"
data-padding-minutes="00"
data-padding-seconds="00">
</div>
Each type of face comes with a set of configuration options to make it unique for your use case.
The following options can be applied to all counter types
Add a data-layout
attribute to control the counter layout. Default layout is group
, the other option is inline
which puts the counter on a single row.
<div class="soon"
data-due="2017"
data-layout="line">
</div>
<div class="soon"
data-due="2017"
data-layout="group">
</div>
Soon will automatically scale the counter to fit the parent container. You can control the maximum size of the counter by setting the data-scale-max
attribute to xxl
, xl
, l
, m
(default value when not set), s
, xs
and xxs
. You can set the value to fill
if you want Soon to take up all available space.
If the counter does not fit Soon will automatically hide unused groups. If for instance the format is set to "year, day, hour, minute" and the years are at 0, Soon will hide the year group on small containers. If all groups contain values Soon will hide values from the right side, so minutes will be hidden. You can prevent the later behaviour by setting data-scale-hide
to empty
. If you don't want to allow hiding of any groups set the value to none
.
Add the values overlap
, adjacent
, tight
or spacey
to control the room between the counter groups when in group
layout mode.
If labels start overlapping you can adjust this using the label size configuration below.
<div class="soon"
data-due="2017"
data-layout="spacey">
</div>
<div class="soon"
data-due="2017">
</div>
<div class="soon"
data-due="2017"
data-layout="tight">
</div>
<div class="soon"
data-due="2017"
data-layout="adjacent">
</div>
<div class="soon"
data-due="2017"
data-layout="overlap">
</div>
Control the way labels are positioned by adding the attribute values label-hidden
, label-small
and label-big
. If you want to put the labels above the numbers use the label-above
value.
Control label casing with the label-uppercase
and label-lowercase
attributes.
Combine these values with the spacing parameters if labels overlap.
<div class="soon"
data-due="2017"
data-layout="label-hidden">
</div>
<div class="soon"
data-due="2017"
data-layout="label-small">
</div>
<div class="soon"
data-due="2017">
</div>
<div class="soon"
data-due="2017"
data-layout="label-big">
</div>
<div class="soon"
data-due="2017"
data-layout="label-above">
</div>
You can have the counter reflect by adding the data-reflect
attribute and setting the value to true
.
<div class="soon"
data-due="2017"
data-layout="label-hidden"
data-reflect="true">
</div>
The flip counter can be configured by adding the following parameters to the data-face
attribute.
color-light
or color-dark
.shadow-hard
or shadow-soft
.fast
or faster
attribute.corners-sharp
and corners-round
values.Of course you can also fine tune all these values using CSS. See the presets page for some examples.
<div class="soon"
data-due="2017" data-face="flip color-light corners-round shadow-soft">
</div>
<div class="soon"
data-due="2017" data-face="flip color-dark corners-sharp shadow-hard fast">
</div>
The slot counter can be configured with the following parameters.
shadow-hard
, shadow-soft
or glow
.fade
, slide
, rotate
, roll
and doctor
.slide
and roll
by adding up
, down
, left
or right
.rotate
with left
and right
.fast
or faster
attribute.Of course you can also fine tune all these values using CSS. See the presets page for some examples.
<div class="soon"
data-due="2017"
data-face="slot shadow-soft fade fast">
</div>
<div class="soon"
data-due="2017"
data-face="slot rotate left">
</div>
<div class="soon"
data-due="2017"
data-face="slot roll down fast">
</div>
<div class="soon"
data-due="2017"
data-face="slot doctor">
</div>
<div class="soon"
data-due="2017"
data-face="slot roll left">
</div>
<div class="soon"
data-due="2017"
data-face="slot shadow-hard slide up">
</div>
The dot matrix visual can be tweaked as well.
spacey
and tight
values.5x7
or 3x5
settings.shadow-soft
, shadow-hard
and glow
.dot-round
and dot-square
.color-light
and color-dark
.slide
and it's modifiers up
, down
, left
and right
.<div class="soon"
data-due="2017"
data-face="matrix color-light dot-round">
</div>
<div class="soon"
data-due="2017"
data-face="matrix color-dark spacey slide left">
</div>
<div class="soon"
data-due="2017"
data-face="matrix color-light shadow-soft">
</div>
<div class="soon"
data-due="2017"
data-face="matrix tight dot-square slide">
</div>
<div class="soon"
data-due="2017"
data-face="matrix 3x5 spacey dot-square">
</div>
The ring visual can be configured by adding the following parameters to the data-visual
attribute.
color-light
and color-dark
for light and dark color variants.progress-shadow-hard
, progress-shadow-soft
or progress-glow
.background-shadow-hard
, background-shadow-soft
or background-glow
.width-thick
and width-thin
to render a different width ring. When using the visual biulder it is possible to fine tune both the progress and the background width independently.cap-round
to render rounded ring end points.offset-{percentage}
to define the starting point of the ring.length-{percentage}
to define the length of the ring.gap-{percentageg}
to define the size of the gaps between the progress bar and the background.flip
value to flip the progress bar in the other direction and make it fill the ring instead of run empty.Of course you can also fine tune all these values using CSS. See the presets page for some examples.
<div class="soon"
data-due="2017"
data-visual="ring cap-round">
</div>
<div class="soon"
data-due="2017"
data-visual="ring shadow-hard flip">
</div>
<div class="soon"
data-due="2017"
data-visual="ring color-dark length-50 gap-2,5">
</div>
<div class="soon"
data-due="2017"
data-visual="ring color-dark shadow-soft offset-25 cap-round">
</div>
<div class="soon"
data-due="2017"
data-visual="ring color-light width-thin glow">
</div>
<div class="soon"
data-due="2017"
data-visual="ring color-dark cap-round width-thick gap-5">
</div>
The fill visual can be configured with the following parameters.
color-light
and color-dark
for light and dark color variants.corners-round
and corners-sharp
to control the box corner style.to-top
, to-top-right
, to-right
, to-bottom-right
, to-bottom
, to-bottom-left
, to-left
and to-top-left
to control the direction of the background fill.Of course you can also fine tune all these values using CSS. See the presets page for some examples.
<div class="soon"
data-due="2017"
data-face="slot"
data-visual="fill corners-sharp color-light to-top">
</div>
<div class="soon"
data-due="2017"
data-face="slot"
data-visual="fill to-top-right color-dark ">
</div>
<div class="soon"
data-due="2017"
data-face="slot"
data-visual="fill corners-sharp color-light to-right corners-round ">
</div>
<div class="soon"
data-due="2017"
data-face="slot"
data-visual="fill corners-sharp color-dark to-bottom">
</div>
<div class="soon"
data-due="2017"
data-face="slot"
data-visual="fill color-light to-left">
</div>
These options are often related to connections with other systems and you'll probably only need them if you're an experienced developer.
If you want to use text within the soon element you can decide where the counter should be created by adding the <span class="soon-placeholder"></span>
element. Soon will replace that element with the counter. You can add your own HTML around it.
<div class="soon" data-due="in 10 minutes" data-layout="line" data-format="m,s">
Product launch in <span class="soon-placeholder">10 minutes</span>
</div>
Sometimes you want to control the current date yourself instead of relying on the browser date. The data-now
attribute allows you to set a server date. It accepts the same format as the data-due
attribute.
If you want to create a Soon element manually, you can call the Soon.create(element,options)
method and pass a reference to the element as a paremeter the second parameter contains all the options. If you're using jQuery you can call $(selector).soon().create(options)
.
<script>
// available options
var options = {
// data-since
since:null,
// data-due
due:"2017",
// data-now
now:null,
// data-layout
layout:"group",
// data-face
face:"text",
// data-visual
visual:null,
// data-format
format:null,
// data-singular
singular:false,
// data-reflect
reflect:false,
// data-scale-max
scaleMax:"m",
// data-scale-hide
scaleHide:null,
// data-separate-chars
separateChars:true,
// data-cascade
cascade:true,
// data-separator
separator:"",
// data-labels-*
labelsYears:null,
labelsDays:null,
labelsHours:null,
labelsMinutes:null,
labelsSeconds:null,
// data-padding
padding:true,
// data-padding-*
paddingDays:null,
paddingHours:null,
paddingMinutes:null,
paddingSeconds:null,
// data-event-complete
eventComplete:null,
// data-event-tick
eventTick:null
};
</script>
<!-- example -->
<div id="my-soon-to-be-counter"></div>
<script>
// get the element
var element = document.getElementById('my-soon-to-be-counter');
// turn it into a Soon counter
Soon.create(element,{
'due':'in 10 seconds'
});
</script>
If you want to remove a Soon element, you can call the Soon.destroy(element)
method and pass a reference to the element as a paremeter. If you're using jQuery you can also call $(selector).soon().destroy()
If you want to pause the timer you can use the freeze
call. Soon.freeze(element)
, if you want to have the timer resume use the unfreeze
call Soon.unfreeze(element)
. When pausing the time is just frozen, the countdown will recalculated the passed time on unfreeze and will jump the amount of seconds you paused the timer.
If you want to redraw the Soon element, for instance after you've modified or resized the parent DOM element, you can call the Soon.redraw(element)
method and pass a reference to the element as a paremeter. If you're using jQuery you can also call $(selector).soon().redraw()
. Soon calls this method when automatically on page load and when the browser window is resized.
You can use the setOption
call to change a setting after you've created the counter. Soon.setOption(element,'due','2017')
or $(element).soon().setOption('due','2017')
will change the due date to 2017. Setting multiple properties at once can be done with the setOptions(optionsObject)
call. For instance Soon.setOptions(element,{'due':'2017','padding':false})
.
If you want to run JavaScript after the counter has run out you can bind your function to the onComplete
callback using the data-event-complete
attribute.
<script>
function happyNewYear() {
alert('Cheers!');
}
</script>
<div class="soon"
data-due="2017"
data-event-complete="happyNewYear">
</div>
You can bind a JavaScript function to the counter tick event. Use the data-event-tick
attribute or the matching option. See the example Complete Event for similar example code.
<script>
function tick(milliseconds, due) {
document.getElementById('soon-seconds').innerHTML = milliseconds;
}
</script>
<div id="soon-seconds"></div>
<div class="soon"
data-due="in 30 seconds"
data-event-tick="tick">
</div>
If you want to prevent the automatic loading of Soon elements on the page add the data-auto="false"
attribute to the soon script tag.
<script src="soon.min.js" data-auto="false"></script>
when the timer runs out, show a message and hide the timer.
<div style="display:none;" id="soon-message">
<p>Hello!</p>
</div>
<div class="soon"
id="soon-counter"
data-due="in 5 seconds"
data-event-complete="showMessage">
</div>
<script>
function showMessage() {
document.getElementById('soon-message').style.display = '';
document.getElementById('soon-counter').style.display = 'none';
}
</script>
When the timer has only 5 seconds left, change the color to red.
<div class="soon"
id="soon-counter"
data-due="in 10 seconds"
data-event-tick="testEnd">
</div>
<script>
function testEnd(secondsLeft) {
if (secondsLeft <= 5000) {
document.getElementById('soon-counter').style.color = 'red';
}
}
</script>
Pause and resume the countdown with a button. The timer will not continue where it was paused as the time till the due date has changed while being paused. For this reason the functions are named freeze and unfreeze.
<div class="soon"
id="soon-counter"
data-due="2017">
</div>
<button type="button" id="toggle-button">toggle</button>
<script>
var frozen = false;
var counter = document.getElementById('soon-counter');
var button = document.getElementById('toggle-button');
button.addEventListener('click',function(){
if (frozen) {
Soon.unfreeze(counter);
}
else {
Soon.freeze(counter);
}
frozen = !frozen;
});
</script>