https://gitlab.com/Zardoz89/blueboxjs

Timeline : a linear representation of important events in the order in which they occurred. [^1]

Demo

Glossary

Time unit : Or t.u. It's the unit used to measure time in the timeline. By default are the same units that uses Data object, that is milliseconds.

Time event : An event in time with a title and start date. Optionally could have a end date. For example :

{
    'title': "RMS Caronia reports",
    'start': "1912-04-14T09:00:00.000Z",
},
{
    'title': "Sinking of the Titanic",
    'start': "1912-04-14T23:39:00.000Z",
    'end': "1912-04-15T02:28:00.000Z"
},

Time mark o mark : Each mark with label on the time axis

Time window : Interval of time actually visible on the timeline

Time units per pixels : It's the result of the quotient of the time window and the widget width. This represents how many time units represents a pixel on screen

Usage

Include the JavaScript module using the <script> tag.

<script src="bluebox.js" type="module"><script/>

And insert the bluebox tag in your HTML :

<bluebox-tl />

Loading the timeline dataset

There 3 ways : src attribute, embedding JSON, and using JavaScript

Src attribute :

<bluebox-tl src="URL_THAT_RETURNS_JSON" />

Embed JSON with a script tag inside :

<bluebox-tl >
    <script type="application/json">
    [
        {
            'title': "...",
            'start': ...,
            'end': ...,

        },
        ...
    ]
    </script>
</bluebox-tl>

Using JavaScript :

    const tl = document.querySelector('bluebox-tl');
    tl.dataset = [
        {
            'title': "...",
            'start': ...,
            'end': ...,

        },
        ...
    ];

Or fetching with JavaScript :

    const tl = document.querySelector('bluebox-tl');
    tl.fetch("URL_THAT_RETURNS_JSON", {FETCH_OPTONS})
      .catch(err => console.log("Something bad happened"));

Tag parameters

| Attribute | Description | |-------------------|-----------------------------------------------------------| | src | An url that returns a valid JSON to be parsed as dataset | | selected-index =0.1 | Current time event index selected by the user | | zoom-factor = 1 | Relative scaling factor. 1 shows the entire timeline in the widget width | | min-factor = 0.5 | Minimal zoom factor. | | max-factor = 16 | Max zoom factor. | | max-rows = 6 | Max number of rows before wrapping up | | time-unit | T.u. being used by the timeline. | | mark-step-[0-5] | Number of t.u. between each time mark | | mark-threshold-[0-5] | Max number of t.u. per pixels before hiding this marks | | date-time-format | JSON representation of Intl.DateTimeFormat options, for the configuration of the default date/time formater. | | debug=[false, true, trace] | Enables console logging for debugging |

Development

Build project and start launch a localhost web server:

git clone
npm install
npm start

License

ISC

Copyright (c) 2019, Luis Panadero Guardeño <luis.panadero(at)gmail.com>

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

[^1]: WordReference Random House Unabridged Dictionary of American English © 2023