Basic Info
A animated durations library built to provide convenience for developers.
If you like the smooth scrolling functionality found here you may like our scrolls.js smooth scrolling library!
Features
- Plug-and-play (unless you have other JavaScript that uses
durations()
already...) - Selector-based targeting
- Allows a function to be called when an animated duration has started and/or ended
- Customizeable before start and after end text
- Customizeable before duration and after duration text
- Customizeable start and end dates, of course
- Fully open source
Getting Started
Installation
You can install the libaray via npm:
npm i durations.js
or via CDN:
<!-- Source Version -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/durations.js"></script>
<!-- Minified Version -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/durations.min.js"></script>
Usage
// Initialize a duration
durations('h2', {
date: 'July 27, 2018 12:00:00 (EST)',
text: 'Coming Soon!'
}, {
date: 'July 28, 2018 12:00:00 (EST)',
text: 'The launch is over!'
}, true);
Examples
Time since January 1st, 1970 (UTC)
Loading...
HTML:
<p class="js-duration-since">Loading...</p>
JS:
<script src="https://cdn.jsdelivr.net/npm/[email protected]/durations.min.js"></script>
<script>
durations('.js-duration-since',{
date: 0
},{
afterText: ' since the beginning of JS time.',
beforeText: 'There has been ',
date: 0
}, false);
</script>
Time until December 31st, 9999
Loading...
HTML:
<p class="js-duration-until">Loading...</p>
JS:
<script src="https://cdn.jsdelivr.net/npm/[email protected]/durations.min.js"></script>
<script>
durations('.js-duration-until',{
afterText: ' until December 31st, 9999.',
beforeText: 'There are ',
date: 'July 28, 2018 12:00:00 (EST)'
},{
date: 'Dec 31, 9999',
text: 'The event has ended.'
}, true);
</script>
Documentation
/**
* Animates a duration change among two dates based on the current time.
*
* @param {String} selector - Element(s) to add the duration message
* @param {Object} start - Object of start date, before text, after text, text
* to display if before the start date, and a callback
* function to execute when animated duration starts
* @param {Object} end - Object of end date, before text, after text, text to
* display when past the end date, and a callback function
* to execute when the end date has been passed
* @param {Boolean} stop - Whether duration should stop or not, if not then it
* will continue counting without ever displaying the
* end text
*/
// selector would be any DOM selector you wish, on our landing page we use
// ".js-duration". The selector value must be supplied.
// start object can be as follows but should at least include a start date.
// Defautls to displaying the duration and if before the start date of
// July 30, 2018 12:00:00 (EST) it will display "Coming Soon!".
{
afterText: ' until the event occurs.',
beforeText: 'There are ',
callback: () => {
return navigator.sendBeacon('/api/log', { start: true });
},
date: 'July 27, 2018 12:00:00 (EST)',
text: 'The new event is coming soon!!'
}
// end object can be as follows but should at least include an end date.
// Defaults to displaying the duration and when past the text
// "Event has passed.".
{
afterText: ' since the event occurred.',
beforeText: 'There have been ',
callback: () => {
return navigator.sendBeacon('/api/log', { end: true });
},
date: 'July 28, 2018 12:00:00 (EST)',
text: 'The event has ended.'
}
// stop boolean tells the function whether or not it should continue counting
// after the end date has passed, possibly so you can let people know how much
// time has passed since the event. Defaults to true.
true
// Putting it together now!
durations('.js-duration',{
afterText: ' until the event occurs.',
beforeText: 'There are ',
callback: () => {
return navigator.sendBeacon('/api/log', { start: true });
},
date: 'July 27, 2018 12:00:00 (EST)',
text: 'The new event is coming soon!!'
},{
afterText: ' since the event occurred.',
beforeText: 'There have been ',
callback: () => {
return navigator.sendBeacon('/api/log', { end: true });
},
date: 'July 28, 2018 12:00:00 (EST)',
text: 'The event has ended.'
}, true);
Changelog
Please see CHANGELOG.md for details.
License
MIT
Copyright © 2018 Purplest, Inc.