Tranduit de l'Anglais par Christian Fauré.

Contents

Pour commencer

Voici les quelques étapes, simples, pour créer une Timeline. Ouvrez votre editeur de texte ou votre navigateur favori et commencez par créer un fichier HTML.

Etape 1. Pointer vers l'API

Dans votre code HTML, faites un lien vers le code Javascript de l'API Timeline comme ci-dessous:

<html>
  <head>
    ...
    <script src="http://simile.mit.edu/timeline/api/timeline-api.js" type="text/javascript"></script>
    ...
  </head>
  <body>
    ...
  </body>
</html>

Etape 2. Créer un élement DIV

Créez un élément div dans votre code HMTL ;

<div id="my-timeline" style="height: 150px; border: 1px solid #aaa"></div>

Vous devez lui donner un ID ainsi que fixer sa hauteur. Vous pouvez éventuellement fixer ses bordures -- cela peut améliorer l'apparence de la Timeline.

Etrape 3. Appeler Timeline.create()

Ajoutez deux événements, onload et onresize, à l'élément body:

 <body onload="onLoad();" onresize="onResize();">
   ...
 </body>

Puis écrivez le code suivant dans un bloc de script ou dans un fichier Javascript séparé :

var tl;
function onLoad() {
  var bandInfos = [
    Timeline.createBandInfo({
        width:          "70%", 
        intervalUnit:   Timeline.DateTime.MONTH, 
        intervalPixels: 100
    }),
    Timeline.createBandInfo({
        width:          "30%", 
        intervalUnit:   Timeline.DateTime.YEAR, 
        intervalPixels: 200
    })
  ];
  tl = Timeline.create(document.getElementById("my-timeline"), bandInfos);
}
var resizeTimerID = null;
function onResize() {
    if (resizeTimerID == null) {
        resizeTimerID = window.setTimeout(function() {
            resizeTimerID = null;
            tl.layout();
        }, 500);
    }
}

Remarquez que si l'on demande au code de construire la Timeline dans l'événement onload, c'est pour être sûr que lorsqu'on commence à utiliser l'API de Timeline, tout son code a bien été chargé. Ce code créé une Timeline horizontale composé de deux bandes : dans celle du haut, un mois est composé de 100 pixels (approximativement, puisqu'ici un mois est composé de 30 jours, bien que ce ne soit pas toujours le cas); et dans celle du bas, une année est composée de 200 pixels. La bande du haut représente 70% de la hauteur totale de la Timeline, et celle du bas 30%. Remarquez que les deux bandes défilent de manière indépendante.

Timeline-howto-image1.jpg

Pour que les deux bandes défilent de manière synchrone, afin que la ligne du bas mette en évidence la partie visible de la bande du haut, ajoutez le code suivant (celui souligné):

function onLoad() {
  var bandInfos = [
    Timeline.createBandInfo({
        width:          "70%", 
        intervalUnit:   Timeline.DateTime.MONTH, 
        intervalPixels: 100
    }),
    Timeline.createBandInfo({
        width:          "30%", 
        intervalUnit:   Timeline.DateTime.YEAR, 
        intervalPixels: 200
    })
  ];
  bandInfos[1].syncWith = 0;
  bandInfos[1].highlight = true;
  
  tl = Timeline.create(document.getElementById("my-timeline"), bandInfos);
}

Si vous faites défiler une bande, l'autre defile de la même manière.

Timeline-howto-image2.jpg

Etape 4. Ajouter des Événements

Pour ajouter des événements à la Timeline, créez un event source et chargez les données à partir d'un fichier XML:

function onLoad() {
  var eventSource = new Timeline.DefaultEventSource();
  var bandInfos = [
    Timeline.createBandInfo({
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "70%", 
        intervalUnit:   Timeline.DateTime.MONTH, 
        intervalPixels: 100
    }),
    Timeline.createBandInfo({
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "30%", 
        intervalUnit:   Timeline.DateTime.YEAR, 
        intervalPixels: 200
    })
  ];
  bandInfos[1].syncWith = 0;
  bandInfos[1].highlight = true;
  
  tl = Timeline.create(document.getElementById("my-timeline"), bandInfos);
  Timeline.loadXML("example1.xml", function(xml, url) { eventSource.loadXML(xml, url); });
}

Le champ date est là pour s'assurer que la Timeline commence à afficher les événements immédiatement, sans que l'utilateur n'ait à déplacer une bande. Voici la Timeline que l'on obtient avec 3 événements :

Timeline-howto-image3.jpg

Jetez un oeil au fichier example1.xml. Il y a 3 types d'événements : une durée, un événement instantané sans date de début précis, et un événement instantané avec un début précis. Cliquez sur les événements pour voir comment leur bulle sont affichés sur la base des données du fichier XML. Pour en savoir plus sur le format de ces fichiers XML, reportez-vous à la documentation sur les event sources. Remarquez que le seul moyen d'ajouter des événements à une Timeline est de charger des fichiers XML.

Les différences entre les deux bandes

En voyant la précedente Timeline, il est évident que la bande du bas est plus dense que celle du haut, car le temps y est plus concentré, et donc le nombre d'évenements affichés plus importants. Cette bande du bas n'a pas pour vocation d'afficher autant de détails que celle du haut. Aussi peut-on y désactiver l'affichage du texte et condenser plusieurs événements sur un axe vertical :

function onLoad() {
  var eventSource = new Timeline.DefaultEventSource();
  var bandInfos = [
    Timeline.createBandInfo({
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "70%", 
        intervalUnit:   Timeline.DateTime.MONTH, 
        intervalPixels: 100
    }),
    Timeline.createBandInfo({
        showEventText:  false,
        trackHeight:    0.5,
        trackGap:       0.2,
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "30%", 
        intervalUnit:   Timeline.DateTime.YEAR, 
        intervalPixels: 200
    })
  ];
  bandInfos[1].syncWith = 0;
  bandInfos[1].highlight = true;
  
  tl = Timeline.create(document.getElementById("my-timeline"), bandInfos);
  Timeline.loadXML("example1.xml", function(xml, url) { eventSource.loadXML(xml, url); });
}

La bande du bas de la Timeline ci dessous n'affiche pas de texte, et les marqueurs d'événements sont également plus petits que ceux de la bande du haut. Remarquez toutefois que le troisième événement est aligné avec le premier dans la bande du bas, ce qui n'est pas le cas dans la bande du haut. Nous adresserons ce problème plus tard.

Timeline-howto-image4.jpg

Comprendre l'initialisation des paramètres

Vous avez certainement compris que Timeline.createBandInfo() contient les informations de paramètrage qui peuvent être modifiées pour réaliser une bande dans une Timeline. Ce que fait Timeline.createBandInfo() peut être décrit de la manière suivante (dans un pseudo-code):

Timeline.createBandInfo = function(params) {
  return {
    width:          params.width,
    eventSource:    params.eventSource (or null by default),
    timeZone:       params.timeZone (or 0 by default),
    ether:          new Timeline.LinearEther({
                      interval:          the number of milliseconds in params.intervalUnit,
                      pixelsPerInterval: params.intervalPixels,
                      centersOn:         params.date (or the current date by default)
                    }),
    etherPainter:   new Timeline.GregorianEtherPainter({
                      unit:              params.intervalUnit,
                      theme:             params.theme (or the default theme)
                    }),
    eventPainter:   new Timeline.DurationEventPainter({
                      showText:          params.showEventText (or true by default),
                      theme:             the same theme above,
                      trackHeight:       params.trackHeight (or the default track height in the theme),
                      trackGap:          params.trackHeight (or the default track gap in the theme),
                      layout:            new Timeline.StaticTrackBasedLayout({
                                           eventSource: the same eventSource above,
                                           ether:       the same ether above,
                                           showText:    the same showText value above,
                                           theme:       the same theme above
                                         })
                    })
  }
};

En d'autres termes, Timeline.createBandInfo() prend un objet dont les champs contiennent les paramètres d'initialisation pour renvoyer un autre objet dont les champs des paramètres d'initialisation seront compris par Timeline.create(). Timeline.createBandInfo() a pour fonction de rediriger l'ensemble des paramètres que vous avez donné à leur bonne place. Par exemple, params.intervalUnit est utilisé deux fois : une première fois pour construire un ether et une deuxième fois pour construire un ether painter. Les paramètres par défaut qui ne sont pas fournis par Timeline.createBandInfo() le seront par le theme.

Le ether d'une bande indique la correspondance entre le temps et son affichage sous forme de pixels : de combien de pixels une période de temps est composée. Le ether painter rend cette correspondance visible pour l'utilisateur en affichant différentes unités temporelles à l'arrière plan d'une bande. Par exemple : "Juin", "Juillet", "2005", "2006". Le ether painter affiche naturellement les événements qui sont alimentés, et fournis, par le ether source. Le Timeline.DurationEventPainter utilise un layout pour déterminer comment distribuer les événements sur plusieurs lignes, afin que les événements ne se chevauchent pas.

L'objet retourné par le Timeline.createBandInfo() peut être fixé avant d'alimenter le Timeline.create(). Nous l'avons déjà fait pour synchroniser les deux bandes. Cette fois-ci, nous allons prendre la disposition graphique (layout) de la bande du dessus et la caler avec celle du dessous afin que chaque événement soit positionné sur la même ligne dans les deux bandes :

function onLoad() {
  var eventSource = new Timeline.DefaultEventSource();
  var bandInfos = [
    Timeline.createBandInfo({
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "70%", 
        intervalUnit:   Timeline.DateTime.MONTH, 
        intervalPixels: 100
    }),
    Timeline.createBandInfo({
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "30%", 
        intervalUnit:   Timeline.DateTime.YEAR, 
        intervalPixels: 200
    })
  ];
  bandInfos[1].syncWith = 0;
  bandInfos[1].highlight = true;
  bandInfos[1].eventPainter.setLayout(bandInfos[0].eventPainter.getLayout());
  
  tl = Timeline.create(document.getElementById("my-timeline"), bandInfos);
  Timeline.loadXML("example1.xml", function(xml, url) { eventSource.loadXML(xml, url); });
}

Remarquez maintenant que le dernier événement est sur sa propre ligne (tout comme comme dans la bande du dessus), et cela bien qu'il puisse rester sur la même ligne que le premier élément dans la bande du dessus, sans pour autant qu'il n'y ait de chevauchement.

Timeline-howto-image5.jpg

Zones Denses (Hot Zones)

Maintenant chargeons le fichier example2.xml qui contient de nouveaux détails sur le "Trip to Beijing" ("Voyage à Pékin"). Nous pouvons voir que les événements à partir de la journée du 2 Août 2006 sont un peu "à l'étroit", voire écrasés sur une seule ligne verticale :

Timeline-howto-image6.jpg

Pour résoudre ce problème, nous allons dilater le temps pour les journées comprenant plusieurs événéments, produisant ainsi un effet de grossissement. Parce que nous voulons que la densité du temps soit ici différente qu'ailleurs - nous voulons que cette période de temps corresponde aux pixels de manière différente, nous avons besoin d'un ether différent (et donc d'un autre ether painter qui va avec):

function onLoad() {
  var eventSource = new Timeline.DefaultEventSource();
  var bandInfos = [
    Timeline.createHotZoneBandInfo({
        zones: [
            {   start:    "Aug 01 2006 00:00:00 GMT-0500",
                end:      "Sep 01 2006 00:00:00 GMT-0500",
                magnify:  10,
                unit:     Timeline.DateTime.WEEK
            },
            {   start:    "Aug 02 2006 00:00:00 GMT-0500",
                end:      "Aug 04 2006 00:00:00 GMT-0500",
                magnify:  7,
                unit:     Timeline.DateTime.DAY
            },
            {   start:    "Aug 02 2006 06:00:00 GMT-0500",
                end:      "Aug 02 2006 12:00:00 GMT-0500",
                magnify:  5,
                unit:     Timeline.DateTime.HOUR
            }
        ],
        timeZone:       -5,
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "70%", 
        intervalUnit:   Timeline.DateTime.MONTH, 
        intervalPixels: 100
    }),
    Timeline.createBandInfo({
        timeZone:       -5,
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "30%", 
        intervalUnit:   Timeline.DateTime.YEAR, 
        intervalPixels: 200
    })
  ];
  bandInfos[1].syncWith = 0;
  bandInfos[1].highlight = true;
  bandInfos[1].eventPainter.setLayout(bandInfos[0].eventPainter.getLayout());
  
  tl = Timeline.create(document.getElementById("my-timeline"), bandInfos);
  Timeline.loadXML("example1.xml", function(xml, url) { eventSource.loadXML(xml, url); });
}

Dans la Timeline que l'on obtient alors (ci-dessous), tout le mois d'Août 2006 est dilaté 10 fois, en montrant des intervalles hebdomadaires ; les deux jours du 2 et du 3 Août sont dilatés 7 fois; puis le temps entre 6 heures du matin et midi le 2 Août est dilaté encore 5 fois, montrant alors des intervalles horaires. Toutes ces dilatations sont faites uniquement dans la bande du dessus ; si vous bougez cette bande, observez comment celle du dessous grossie et diminue dans le même temps.

Timeline-howto-image7.jpg

Bien sûr, en faisant défiler la bande du dessous sur les zones denses (hot zones), l'affichage de la bande du dessus a tendance à faire des "sauts". Pour réduire cet effet, nous pouvons assouplir le défilement de la bande du dessous :

function onLoad() {
  var eventSource = new Timeline.DefaultEventSource();
  var bandInfos = [
    Timeline.createHotZoneBandInfo({
        zones: [
            {   start:    "Aug 01 2006 00:00:00 GMT-0500",
                end:      "Sep 01 2006 00:00:00 GMT-0500",
                magnify:  10,
                unit:     Timeline.DateTime.WEEK
            },
            {   start:    "Aug 02 2006 00:00:00 GMT-0500",
                end:      "Aug 04 2006 00:00:00 GMT-0500",
                magnify:  7,
                unit:     Timeline.DateTime.DAY
            },
            {   start:    "Aug 02 2006 06:00:00 GMT-0500",
                end:      "Aug 02 2006 12:00:00 GMT-0500",
                magnify:  5,
                unit:     Timeline.DateTime.HOUR
            }
        ],
        timeZone:       -5,
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "70%", 
        intervalUnit:   Timeline.DateTime.MONTH, 
        intervalPixels: 100
    }),
    Timeline.createHotZoneBandInfo({
        zones: [
            {   start:    "Aug 01 2006 00:00:00 GMT-0500",
                end:      "Sep 01 2006 00:00:00 GMT-0500",
                magnify:  20,
                unit:     Timeline.DateTime.WEEK
            }
        ],
        timeZone:       -5,
        eventSource:    eventSource,
        date:           "Jun 28 2006 00:00:00 GMT",
        width:          "30%", 
        intervalUnit:   Timeline.DateTime.YEAR, 
        intervalPixels: 200
    })
  ];
  bandInfos[1].syncWith = 0;
  bandInfos[1].highlight = true;
  bandInfos[1].eventPainter.setLayout(bandInfos[0].eventPainter.getLayout());
  
  tl = Timeline.create(document.getElementById("my-timeline"), bandInfos);
  Timeline.loadXML("example1.xml", function(xml, url) { eventSource.loadXML(xml, url); });
}

La Timeline que l'on obtient alors aurait peut-être besoin d'être peaufinée pour être plus souple. Mais j'espère que cela aura été un bon point de départ pour vous.

Timeline-howto-image8.jpg