Dateline 2.0

Dateline is a widget for date-related data. You can create interactive timelines, which can be dragged by mouse, touch or keyboard, and displays events. The movements of two or more timelines ('bands') are synchronized. Clicking on or tapping an event displays more information or redirects you to another page.

A demo of Dateline is here.

See it in action at Moordatlas.nl (Dutch). At Weltliteratur is another nice example.

Here is Dateline's GitHub page.

Installing

Install Dateline with npm:

npm i @sjaakp/dateline

You can also manually install Dateline by downloading the source in ZIP-format.

Dependencies

Version 2.0 of Dateline has absolutely no dependencies. There is no need to load jQuery or other libraries (though it won't hurt).

Usage

Link to /dist/dateline.css in the <head> part of the page.
Create a <div> with an id.
Load /dist/dateline.js at the end of the <body> part.
Call the dateline() method.

A minimum HTML page with a Dateline would look something like this:

<html>
<head>
    <link href="/dist/dateline.css" rel="stylesheet">
</head>
<body>

	<div id="dl"></div>

	<script src="/dist/dateline.js"></script>

	<script>
		dateline("dl", /* options */);
	</script>
</body>
</html>

CDN

Dateline is available on the unpkg Content Delivery Network, so you don't have to host the dateline files on your own server. In this case, the minimum HTML page looks like this:

<html>
<head>
    <link href="//unpkg.com/@sjaakp/dateline/dist/dateline.css" rel="stylesheet">
</head>
<body>

	<div id="dl"></div>

	<script src="//unpkg.com/@sjaakp/dateline/dist/dateline.js"></script>

	<script>
		dateline("dl", /* options */);
	</script>
</body>
</html>

Bands

At this point, Dateline displays one empty band, because there are no bands defined. This is done by setting the option bands, like so:

dateline('dl', {
	bands: [
		{
        	size: '60%',
        	scale: Dateline.MONTH,
        	interval: 60
		},
		{
        	size: '40%',
        	scale: Dateline.YEAR,
        	interval: 80,
			layout: 'overview'
		}
	],
	/* more options... */
	});

bands is an array of objects, each representing a timeline, with the following properties:

interval

The length of a scale division in pixels.

scale

The scale division of the band. It can have one of the following values:

Dateline.MILLISECOND
Dateline.SECOND
Dateline.MINUTE
Dateline.HOUR
Dateline.DAY
Dateline.WEEK
Dateline.MONTH
Dateline.YEAR
Dateline.DECADE
Dateline.CENTURY
Dateline.MILLENNIUM

(Yes, Dateline's range is truly astonishing: from milliseconds to millennia.)

size

The height of the band as a CSS height-property. Pixels work, but percentages are probably easier. Take care that the band sizes add up to something sensible (like 100%).

layout

Optional. Can be one two values:

"normal" (or undefined): events are displayed with icons and text, and are clickable. This is the default value.
"overview": events are displayed in a compact ribbon, and are not clickable.

In most cases, you will want to have one normal band at the top, with several overview bands below it.

multiple

Optional. This value determines which scale divisions are displayed. If it is 2, every other division is displayed. Default value is 1, meaning that every division is displayed.

Events

Note that we're not talking about JavaScript events here!

Events are objects which are placed on Dateline's timelines. They are defined in Dateline's property events, like so:

dateline('dl', {
	bands: [ /* several band definitions... */ ],
	events: [
		{id: "49", start: "2009-07-22", text: "Windows 7 released"},
		{id: "55", start: "1997-09-15", text: "Domain google.com registered"}),
		/* more events... */
	],
	/* more options... */
});

Events have the following properties:

id

A unique identifier, probably (but not necessarily) a number.

start

The point in time the event takes place. This can be a JavaScript Date object or a string that is recognized by Date.parse().

text

The text (or actually, the HTML code) displayed on the timeline.

class

Optional. The HTML-class(es) set to the event when it's displayed in normal layout.

Duration events

Apart from the normal, instant events, Dateline also supports duration events. They have all the properties of normal events, plus the following:

stop

The point in time the event is over.

post_start

Optional. Indicates a degree of uncertainty in start.

pre_stop

Optional. Indicates a degree of uncertainty in stop.

Like start, these three properties can be a JavaScript Date object or a string that is recognized by Date.parse().

In any case, start < post_start < pre_stop < stop.

Cursor

Dateline's timelines are anchored at one point in time, called the cursor. By means of the option cursor the starting value can be set. Like the event time options, cursor can be a JavaScript Date object or a string that is recognized by Date.parse().

Dateline remembers the cursor value between visits to the page, as long as they are in one browser session. If you don't like this behavior, set the rememberCursor option to false.

Other options

Dateline has the following general options:

begin, end

Optional. The limits between where Dateline can be dragged. These options can be null, meaning no limit, or a JavaScript Date object or a string that is recognized by Date.parse(). Default: null.

size

Optional. The CSS height of Dateline. Default is "320px".

url

Optional. The url Dateline uses when an event is clicked or tapped. The url is concatenated with the value of the id property of the clicked event.

If false (default), clicking or tapping an event has no effect.

redirect

Optional. boolean.

true: Dateline redirects the browser to the location set by url.
false: an Ajax call is made to url. Dateline displays the returned HTML in a pop up 'bubble' near the event.

Default is false.

Property

cursor

Dateline's property cursor can be read or set at any time. It is a JavaScript Date object. It can be set by a Data object, or by an string that is recognized by Date.parse().

Method

find(id)

Tries to find the event with the given id property value and, if found, moves the timeline(s) to it. Return: a plain JavaScript Object with the event data, undefined if not found.

JavaScript event

datelinechange

This JavaScript event is issued whenever the cursor value is changed. The current value is sent in the detail property of the event data as a JavaScript Date object.

One way to intercept the datelinechange event would be (using jQuery):

document.addEventListener('datelinechange', e => {
        $('#somewhere').text(e.detail.toString());
    }
);

Iconizing events with Font Awesome

Normally, Dateline's events are displayed as a big dot. They can also be displayed as an icon from Font Awesome. Just make sure that Fot Awesome is loaded and set the class property of the event to something like "fas fa-xxx".

For instance, this is the way to display an event with the 'fa-anchor' icon in Font Awesome's solid style:

var _dl = dateline('dl', {
	bands: [ /* several band definitions... */ ],
	events: [
		{id: "42", start: "2009-07-22", class: "fas fa-anchor", text: "Anchor example"},
		/* more events... */
	],
	/* more options... */
	});

Icons are not displayed with duration events.

Colorizing events

By setting the class property of an event to "col-xxx", the big dot or the icon is colored. Icon classes and color classes can be combined. Available are all CSS3 named colors. They can be found in the file src/_colors.scss.

So this displays the event with a tomato red icon:

var _dl = dateline('dl', {
	bands: [ /* several band definitions... */ ],
	events: [
		{id: "42", start: ..., class: "fas fa-pizza-slice col-tomato", text: "Pizza invented"},
		/* more events... */
	],
	/* more options... */
	});

If you're using Font Awesome Duotone you can use a "col2-xxx" class to set the secondary color likewise.

Dark mode

Adding the class d-dark to initial <div> lets Dateline appear with light colored text on dark background colors.

Overflow

If there are really many events, Dateline may not be able to display them all. Whenever this occurs, is notified in the browser's console window.

Available colors

These colors are available to form the "col-xxx" and "col2-xxx" classes. Of course, some of them will be of limited use, because they will be almost invisible against Dateline's background.