timeline.io v1.0.4

Timeline.io

Timeline engine for creating robust and flexible timelines with zoom and pan.

The project is designed to act as the main engine in web projects that visualize earth´s and human history.

Code re-calculates points in time on every frame using milliseconds as timescale. It does not depent on expanding divs or any other HTML elements which makes it able to zoom past most browser limits.

Timeline.io currently uses javascript Date object underneath which is limited by ECMA-262 (that is, April 20, 271821 BCE ~ September 13, 275760 CE). Hence it can currently span ±8,640,000,000,000,000 milliseconds with zero (0) being unix time 0 (Jan 1 1970).

How to use:

Module supports both ESM and UMD - please check demos.

Install ESM Module:

npm i timeline.io

ESM Setup:

<div id="timeline"></div>
<script type="module">
    import { Timeline } from 'timeline.io'

    new Timeline("#timeline", {startDate: '-500y', endDate: '500y'}, (timeline) => {
        console.log(JSON.stringify(timeline, undefined, 2));
    });
</script>

Vanilla setup:

<div id="timeline"></div>
<script src="../dist/timeline.io.umd.js"></script>
<script>
    new Timeline("#timeline", {startDate: '100bc', endDate: '100ad'}, (timeline) => {
        console.log(JSON.stringify(timeline, undefined, 2));
    });
</script>

React setup:

import { Timeline } from 'timeline.io'
import { useEffect, createRef } from 'react';

function App() {
    const myRef = createRef();

    useEffect(()=>{
        new Timeline(myRef.current)
    }, [myRef])

    return (
        <div className="App">
            <div ref={myRef}></div>
        </div>
    );
}

export default App;

Documentation:

// Constructor
new Timeline(element: HTMLElement | string, options: object, callback?: (option: ITimeline) => void)

First argument is the page container for the timeline. Eg. '#timelineContainer' | document.querySelector("#timelineContainer");

Code adds 2 absolute positioned divs to the container and vertically places them according to the 'position' parameter on the options object.

Zooming and panning is automatically activated on the whole container so that large page areas can be part of timeline.

The timeline works with 2 different date sets.

• Overall date range of allowed zooming and panning. Zooming and Panning is not allowed outside these dates.
• Specific date range for initialization. These acts as the boundaries when the timeline initalizes and creates a 'view' on the overall timeline

Second argument is a configuration object. Default configuration looks like this:

{
    labelCount: 5,                  // Defines number of 'time' labels in the timeline
    zoomSpeed: 0.025,               // How fast zooming happens
    dragSpeed: 0.003,               // How fast panning happens
    startDate: "-100y",             // When timeline should start on init. (See below for valid input)
    endDate: "10y",                 // When timeline should end on init. (See below for valid input)
    timelineStartDate: "-1000y",    // When overall timeline boundary should start. (See below for valid input)
    timelineEndDate: "1000y",       // When overall timeline boundary should end. (See below for valid input)
    minZoom: 1,                     // How far out zoom is allowed
    maxZoom: 1e11,                  // How far in zoom is allowed
    position: "bottom",             // Where to vertically place the timeline in the container. 'bottom' | 'center' | 'top'
}

Allowed values for dates:
Timeline has its own Date string parser which supports the following specials:

• 'YYYY-MM-DDTHH:mm:ss.sssZ' -> ISO 8601 string
• 'now' -> Translates to current time = new Date()
• 'min' -> Translates to minimum possible time = new Date(-8640e12)
• 'max' -> Translates to maximum possible time = new Date(8640e12)
• 'XXXy' -> any positive or negative number with a trailing 'y'. Translates relative to now. Eg. '-1000y' = Minus 1000 years from now.
• 'XXXbc' -> any positive or negative number with a trailing 'bc'. Translates into that specific year - BC. Eg. '100bc' = Year -100
• 'XXXad' -> any positive or negative number with a trailing 'ad'. Translates into that specific year - AD. Eg. '100ad' = Year 100

Third argument is a callback function that fires on every frame update It includes a 'state' object with current timeline details.

{
    options: object -> Configuration object - see above
    startDate: Date -> Current startDate for timeline view
    endDate: Date -> Current endDate for timeline view
    ratio: Number -> Current ratio for timeline view. Ratio represents the level of zooming
    pivot: Number -> Current pivot for timeline view. Pivot represents level of panning
}

Eg.

{
  "options": {
    "labelCount": 5,
    "zoomSpeed": 0.025,
    "dragSpeed": 0.003,
    "startDate": "100bc",
    "endDate": "100ad",
    "timelineStartDate": "-1000y",
    "timelineEndDate": "1000y",
    "minZoom": 1,
    "maxZoom": 100000000000,
    "position": "bottom"
  },
  "startDate": "0235-01-01T02:25:14.517Z",
  "endDate": "0342-11-17T17:48:17.787Z",
  "ratio": 28.93640073102412,
  "pivot": -3.0960720833611
}