durations.js - animated durations library.

durations.js is a tiny library to help provide animated durations functionality for those that do not currently use another solution.

Table of Contents

1. Basic Info
2. Features
3. Getting Started
4. Installation
5. Usage
6. Examples
7. Documentation
8. Changelog
9. License

Basic Info

An animated durations library built to provide convenience for developers.

Visit the landing page at durationsjs.com to see a demo of the library in action!

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 library 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

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

Please see durationsjs.com for some examples and a demo of them working on the website.

Documentation

Documentation to be added with the next npm version.

/**
 * 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 (c) 2018 Purplest, Inc.