Documentation
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 anid
. - 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"
(orundefined
): 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 byurl
.false
: an Ajax call is made tourl
. 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.
- aliceblue
- antiquewhite
- aqua, cyan
- aquamarine
- azure
- beige
- bisque
- black
- blanchedalmond
- blue
- blueviolet
- brown
- burlywood
- cadetblue
- chartreuse
- chocolate
- coral
- cornflowerblue
- cornsilk
- crimson
- darkblue
- darkcyan
- darkgoldenrod
- darkgray, darkgrey
- darkgreen
- darkkhaki
- darkmagenta
- darkolivegreen
- darkorange
- darkorchid
- darkred
- darksalmon
- darkseagreen
- darkslateblue
- darkslategray, darkslategrey
- darkturquoise
- darkviolet
- deeppink
- deepskyblue
- dimgray, dimgrey
- dodgerblue
- firebrick
- floralwhite
- forestgreen
- fuchsia, magenta
- gainsboro
- ghostwhite
- gold
- goldenrod
- gray, grey
- green
- greenyellow
- honeydew
- hotpink
- indianred
- indigo
- ivory
- khaki
- lavender
- lavenderblush
- lawngreen
- lemonchiffon
- lightblue
- lightcoral
- lightcyan
- lightgoldenrodyellow
- lightgray, lightgrey
- lightgreen
- lightpink
- lightsalmon
- lightseagreen
- lightskyblue
- lightslategray, lightslategrey
- lightsteelblue
- lightyellow
- lime
- limegreen
- linen
- maroon
- mediumaquamarine
- mediumblue
- mediumorchid
- mediumpurple
- mediumseagreen
- mediumslateblue
- mediumspringgreen
- mediumturquoise
- mediumvioletred
- midnightblue
- mintcream
- mistyrose
- moccasin
- navajowhite
- navy
- oldlace
- olive
- olivedrab
- orange
- orangered
- orchid
- palegoldenrod
- palegreen
- paleturquoise
- palevioletred
- papayawhip
- peachpuff
- peru
- pink
- plum
- powderblue
- purple
- red
- rosybrown
- royalblue
- saddlebrown
- salmon
- sandybrown
- seagreen
- seashell
- sienna
- silver
- skyblue
- slateblue
- slategray, slategrey
- snow
- springgreen
- steelblue
- tan
- teal
- thistle
- tomato
- turquoise
- violet
- wheat
- white
- whitesmoke
- yellow
- yellowgreen