Skip to content
Snippets Groups Projects
Select Git revision
  • develop default
  • feature/json
  • main
  • feature/simplification
  • 1.1.5-sr10
  • 1.1.5-sr9
  • 1.1.5-sr8
  • 1.1.5-sr7
  • 1.1.5-sr6
  • 1.1.5-sr5
  • 1.1.5-sr4
  • 1.1.5-sr3
  • 1.1.5-sr2
13 results
Compare History
user avatar
📝 Create the new readme
Giildo authored
0595634d
Name Last commit Last update
.husky
public/img
src
tests
types
viewer
.env
.gitignore
.gitlab-ci.yml
LICENSE.txt
Readme.md
env.d.ts
eslint.config.mjs
index.html
package.json
tsconfig.json
vite.config.ts
vitest.config.ts
vitest.jestDom.ts
vitest.workspace.ts
Readme.md

TimelineJS

Coverage

main

production pipeline state production coverage

develop

develop pipeline state develop coverage

Projet

Ce projet permet de créer une frise qui va afficher des événements sur une ligne temporelle. On peut interagir avec les événements pour déclencher des événements JavaScript.

Elle a été créée par l'équipe de développement de l'Université de Strasbourg en s'inspirant de la frise créée par les Universités de Chicago et de San Francisco via le KnightLab.

Le projet initial était en JS sans description TS, peu maintenue, compilée avec Webpack et surtout les calculs de la frise se font côté client ce qui peut poser des problèmes de performance en cas de frise avec beaucoup d'événement.

Installation

Le package n'est pour l'heure publié ni sur NPM, ni sur gitlab. Pour l'utiliser, il faut le cloner et l'utiliser en local dans le projet destinataire, par exemple avec un workspace pnpm.

Lien local

Avec un lien relatif vers le dossier dans le package.json. Par exemple, dans le dossier parent, on peut faire (selon les droits que vous avez) :

git clone https://git.unistra.fr/vue-unistra/timelinejs.git

# ou 

git clone git@git.unistra.fr:vue-unistra/timelinejs.git

# ou 

git clone https://github.com/unistra/timelinejs.git

# ou 

git clone git@github.com:unistra/timelinejs.git

Dans le package.json de notre projet :

{
  "dependencies": {
    "@vue-unistra/timelinejs": "file:../timelinejs"
  }
}

Workspace PNPM

Vous créez un dossier pour le workspace. On crée un fichier pnpm-workspace.yaml. On crée deux dossiers : apps et libs et on les ajoute dans le dossier du workspace :

pnpm-workspace.yaml

packages:
  - apps/*
  - libs/*

Dans apps vous avez votre projet et dans libs vous clonez la frise (exemple avec un dépôt, pour voir les autres cf. ci-dessus) :

git clone git@git.unistra.fr:vue-unistra/timelinejs.git libs/timelinejs

Dans le package.json du projet :

{
  "dependencies": {
    "@vue-unistra/timelinejs": "workspace:*"
  }
}

Utilisation

Pour utiliser la Timeline, on doit implémenter un objet à partir de la classe Timeline. Elle prend trois paramètres :

Paramètre Type Besoin Définition
container HTMLElement Requis Élément HTML sur lequel la Timeline sera branchée.
data TimelineData Requis Données qui permettront à créer la Timeline. Elles contiennet les événements, les différents niveau de zoom...
options TimelineOptions Facultatif Option pour customiser sa Timeline.

Exemple d'implémentation :

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <title>TimelineJS: API Test</title>
  <meta charset="utf-8">
  <meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0" name="viewport">
  <script src="./main.ts" type="module"></script>
</head>
<body>
<div id="timeline"></div>
</body>
</html>

main.ts

import '@vue-unistra/timelinejs/timeline.css'
import zooms from './data/zooms.json'
import type { TimelineServerData } from '@vue-unistra/timelinejs'
import { Timeline } from '@vue-unistra/timelinejs'

const timelineContainerCanvas = document.getElementById('timeline')! as HTMLDivElement

new Timeline(timelineContainerCanvas, zooms as unknown as TimelineServerData)

TimelineData

Les données à fournir doivent avoir le format suivant :

Paramètre Type Besoin Définition
events TimelineServerEvent[] Requis Liste des événements qui seront affichés dans la Timeline.
initialZoom Zoom Requis Zoom initial pour avoir la vue "idéale" dans la Timeline. Doit être une valeur dans la liste ci-dessous.
isOnGoing boolean Requis Est-ce qu'au moins un événement de la Timeline est noté "en cours".
zooms Record<Zoom, ZoomServerData> Requis Liste des zooms avec les coordonées liées aux événements.

TimelineServerEvent

Paramètre Type Besoin Définition
date TimelineServerEventDates Requis Date de début et de fin de l'événement.
id string Requis id sous forme d'UUID.
isOnGoing boolean Requis L'événement est identifié comme "en cours", quand c'est le cas, sa date de fin sera affichée à la date du jour.
next string | null Requis Identifiant de l'événement suivant. null si l'événement est le dernier.
previous string | null Requis Identifiant de l'événement précédent. null si l'événement est le premier.
title string Requis Texte qui sera affiché dans la "case" de l'événement.

[! note]
Si l'événement est isOnGoing il doit avoir sa date de fin à null

[! warning]
isOnGoing peut ralentir la frise si beaucoup d'événements le sont car le calcul de la position de fin est calculée côté client.

TimelineServerEventDates

Paramètre Type Besoin Définition
start TimelineServerEventDate Requis Date de début l'événement.
end TimelineServerEventDate | null Requis Date de fin de l'événement.

TimelineServerEventDate

Paramètre Type Besoin Définition
date string Requis Date au format ISO 8601 (ex : 2025-02-01T18:00:00:000Z pour le 1er février 2025 à 18h au niveau du fuseau horaire UTC).
display string | null Requis Si ce champ est non nul, la date sera affichée avec ce texte. Ex : "Année 2025"

Zoom

Les zooms qui sont pris en charge actuellement sont :

  • millennium
  • halfMillennium
  • bicentenary
  • century
  • biDecade
  • decade
  • lustrum
  • biennial
  • year

Un zoom correspond à la durée de temps affichée sur la largeur d'un écran.

[! note]
Si la frise est sur le zoom Millenium, si elle commence en 2000, elle affichera sur une largeur d'écran de 2000 à

ZoomServerData

Paramètre Type Besoin Définition
diffDivision number Requis Nombre de mois ou d'années séparant deux crans de la frise. Associé à divisionType pour savoir s'il s'agit de mois ou d'années.
divisionNb number Requis Nombre de division que compte la frise entre le début du premier événement et la fin du dernier. Sera adapté si un événement est isOnGoing.
divisionType year | month Requis Type de division.
events Record<string, ZoomServerEvent> Requis Objet avec les événements et leurs coordonnées. La clé est l'id de l'événement pour pouvoir faire le lien avec la liste des événements à la base de l'objet TimelineData.
limits TimelineServerLimit Requis Date de début du premier événement et date de fin du dernier.
screenDivisionNb number Requis Nombre de divisions sur une largeur d'écran.
timelineLimits TimelineServerLimit Requis Limites de la frise. Si la frise est isOnGoing la date de fin sera recalculée côté client.
zoom Zoom Requis Zoom sur lequel on est en train de travailler.

[! note]
Si diffDivision est égal à 50 et divisionType à year alors entre chaque cran de la frise on aura 50ans.

ZoomServerEvent

Paramètre Type Besoin Définition
coordinates ZoomServerEventCoordinates Requis Coordonnées de l'événement au niveau de la frise en fonction du zoom.

ZoomServerEventCoordinates

Paramètre Type Besoin Définition
end number | null Requis Distance relative de la fin de l'événement par rapport au début de la frise en "step".
start number Requis Distance relative du début de l'événement par rapport au début de la frise en "step".

[! note]
Si un zoom a une diffDivision à 10 et un divisionType à year, si start est à un 1.3, alors l'événement commence 13ans après le début de la frise.

TimelineOptions

Paramètre Type Besoin Définition
dark boolean Facultatif Indique si la frise est en dark mode ou non.
eventSelected string Facultatif Permet d'afficher la frise avec un événement directement sélectionné
language en | fr Facultatif Langue de la frise (affichage des mois).

Méthodes

Méthode Définition Description
setDarkMode (dark: boolean) => void Permet de changer le dark/light mode.
setEvents (data: TimelineServerData) => void Permet de modifier les événements affichés.
setLocale (locale: en | fr) => void Permet de mettre à jour la langue de la frise.

Événements JS

Événement Donnée envoyée Description
back-to-start undefined Click sur l'icône en forme de maison. Ne renvoie rien.
event-click TimelineServerEvent Click sur un événement. Renvoie l'événement cliqué.
nav-previous { event: TimelineServerEvent } Click pour aller à l'événement précédent. Renvoie un objet avec l'événement précédent.
nav-next { event: TimelineServerEvent } Click pour aller à l'événement suivant. Renvoie un objet avec l'événement suivant.
zoom Zoom Change de zoom (zoomer ou dézoomer). Renvoie le nouveau niveau de zoom.