Time-machine-masonry NPM

Time Machine

Time machine is a webcomponent you can use to add historic context to a web page. The webcomponent is a custom html element that you use in your html. You only need to specify what date or period it should display and that's it.

Usage

The internal name of an historic fact is incident and each incident is displayed in a tile. A tile consists of a title, an optional image and optional text block over the image.

Load the component

First load the javascript magic that defines our web component:

<script defer="defer" src="https://www.unpkg.com/time-machine-masonry@4.1.1"></script>

Use the new html tag

After this you can use a HTML element called 'time-machine' in your html page in which the incidents of a certain date (or date range) will be displayed. E.g.

<time-machine date="1993-03-03"></time-machine>

The time-machine element will use all the space it has been granted. To control this you can use css styling on the time-machine element itself or wrap it in a container that has controlled dimensions:

<div class="small-container">
    <time-machine class="small" date="1993-03-03" country="nl" category="newsItem"
        no-image-src="https://tee-e.com/images/pic01.jpg" show-icons></time-machine>
</div>

Please refer to index.html of this repo for a complete example.

Control the behaviour

Set attributes statically

The time-machine element accepts parameters to control it's behaviour:

date : a specific date you want to retrieve incidents for. Format: yyyy-mm-dd
from and to : a period you want to retrieve incidents for. Format: yyyy-mm-dd
limit : maximum amount of incidents that should be retrieved. Default: 20
country : fetch incidents that where newsworhty in this country(ies). Reference https://swagger.tee-e.com for a list of supported countries.
category : fetch incidents for this category(ies). Reference https://swagger.tee-e.com for a list of supported categories.
emotion : fetch incidents that match this emotion(s). Reference https://swagger.tee-e.com for a list of supported emotions.
impact : fetch incidents had this impact(s). Reference https://swagger.tee-e.com for a list of supported emotions.
shuffle : shuffle the results before displaying
show-icons : show the icons that correspond to the category
suppress-images : do not show any images
no-image-src : what image should be shown when an incident's image is broken. Use a url or base64 encoded image
report-broken-images : report broken images back to the server so that they can be repaired

Set attributes dynamically

The time-machine element listens for 'set time machine attribute' CustomEvents. The elements expects a property detail which holds property key and value. To change all the time window for all the time-machine elements on the page at once do:

const timeMachineElements = document.querySelectorAll('time-machine') || [];
timeMachineElements.forEach((element) => {
    element.dispatchEvent(new CustomEvent('set timemachine attribute', {
        bubbles: true,
        composed: true,
        detail: {
            'from' : '1990-03-12',
            'to': '1990-04-12'
        }
    }));
});

Adjust the styling

The time-machine element accepts css parameters to specify (significant parts of) it's styling:

--time-machine-title-color : the text color of the title of the tile
--time-machine-title-background-color: the background color of the title of the tile
--time-machine-title-font-size : the font size of the title text of the tile
--time-machine-text-color : the color of the content text of the tile
--time-machine-text-background-color : the color of the background of the content of the tile
--time-machine-text-font-size : the size of the title text of the tile
--time-machine-text-max-height : the maximum height of the text of the tile
--time-machine-background-color : the color of the background of the tile
--time-machine-image-min-height : the minimum height of the image
--time-machine-ruler-color : the color of the ruler that is displayed between two incidents vertically
--time-machine-icon-color : the color of the incident's category icon
--time-machine-attribution-font-size : the font size of the list of attributions / sources
--time-machine-attribution-font-color : the font color of the list of attributions / sources

Development

Fetch all packages: npm ci
Run the application: npm run develop
Navigate to http://localhost:8000

Publication

Fetch all packages: npm ci
Version the application: npm version major|minor|patch
Build the application: npm run build:prod
Publish the application: npm publish