Extension:EasyTimeline/syntaxe

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page Extension:EasyTimeline/syntax and the translation is 54% complete.
Other languages:
English • ‎Türkçe • ‎français • ‎svenska • ‎čeština • ‎日本語

La fonction EasyTimeline produit une image intégrée à partir de wikitext. L'image peut être un diagramme unidimensionnel (horizontalement ou verticalement), ou un diagramme bidimensionnel. Le nom "EasyTimeline" fait référence à la possibilité d'appliquer la fonction avec une échelle de temps horizontalement ou verticalement, éventuellement avec un autre paramètre dans l'autre sens, mais il existe également diverses autres possibilités.

Introduction

Des chronologies graphiques peuvent être produites en fournissant un script entre des balises spéciales :

<timeline>
script
</timeline>

EasyTimeline sera alors invoqué pour rendre une image PNG et (éventuellement) une carte cliquable.

Clause de non-responsabilité : Même si EasyTimeline est conçu pour être facile à utiliser, une chronologie graphique compliquée est une affaire non triviale. Une simple chronologie peut prendre une demi-heure à composer (ou même plus, lorsqu'un exemple approprié est pris comme base). Des délais longs peuvent prendre quelques heures pour la composition et la mise au point. Cependant, l'ajout ou la correction d'une chronologie, aussi complexe soit-il, devrait être une affaire relativement simple, même pour les contributeurs qui n'ont aucune connaissance approfondie de la syntaxe décrite ici.

N'hésitez pas à demander conseil au auteur d'EasyTimeline.

Commandes disponibles

Les commandes de script définissent :

Règles générales de codage

Un script peut contenir des commandes et des commentaires. Chaque commande est suivie d'un ou plusieurs attributs.

Cas des lettres : les commandes et leurs attributs peuvent être écrits en minuscules, majuscules ou en casse mixte. Veuillez essayer d'être cohérent dans l'application du cas car cela améliorera la lisibilité, par exemple utilisez une casse mixte pour toutes les commandes et des minuscules pour tous les attributs.

Les commandes suivantes sont obligatoires :

  • ImageSize, détermine la taille globale de la chronologie
  • PlotArea, détermine les marges
  • Period, détermine la période qui sera affichée dans le graphique
  • TimeAxis, l'orientation (horizontale/verticale) de l'axe du temps

Au moins une des commandes suivantes est requise (l'une ou les deux peuvent se produire plusieurs fois) :

Tous les autres paramètres sont optionnels.

Commentaires

Des commentaires sur une ou plusieurs lignes peuvent être spécifiés :

  • Le texte suivant le signe dièse # sera considéré comme un commentaire
  • Le texte entre #> et <# sera également considéré comme un commentaire. Les commentaires peuvent s'étendre sur plusieurs lignes lorsqu'ils sont étiquetés de cette façon.

Exemples :

DateFormat = dd/mm/yyyy # European date format

Period = from:01/09/1939 till:02/09/1945 #> this chart will show
  the complete duration of World War II <#

Commandes

Les commandes doivent commencer sur la première position d'une ligne.

Certaines commandes peuvent être suivies de plusieurs lignes de données et/ou d'options.

Ces lignes supplémentaires doivent commencer par au moins un espace ou être complètement vides (ce dernier est utile pour regrouper visuellement les lignes de données associées).

Les commandes ont l'une des formes suivantes, selon le type de commande :

Command = attribute(s)

DateFormat = dd/mm/yyyy

Command name = attribute(s)

Define $US = text:"United States"

Command =

attribute(s)
attribute(s)
etc.
PlotData =
  fontsize:XS width:20
  bar:Japan from:start till:19/02/1945 color:JT
  bar:Japan from:19/02/1945 till:14/03/1945 color:AI

Attributs

Lorsque plusieurs attributs peuvent être spécifiés pour une certaine commande, ils sont notés comme des paires 'nom:valeur'. Lorsque plusieurs valeurs peuvent être spécifiées pour un attribut, elles doivent être placées entre parenthèses. Quelques commandes, comme Color, utilisent d'autres formats.

Exemples :

BackgroundColors = bars:darkgrey
PlotData = at:5 shift:(10, -7) text:Foo
Color SB = value:rgb(0.8,0,0.7) legend:Sea_Battles

Paramètres vs éléments de données

La plupart des commandes n'acceptent que les attributs spécifiés sur la même ligne.

Blocs de données
Certaines commandes, comme BarData, PlotData, TextData, Colors attendent un bloc de données (data block) composé d'une ou plusieurs lignes de données (data lines). Les lignes de données doivent commencer par un ou plusieurs espaces. Un bloc de données est considéré comme complet lorsqu'une ligne commençant par un non-espace est rencontrée (exception: les lignes vides sont ignorées, elles peuvent être utilisées pour regrouper des lignes de données liées dans un bloc).
Les attributs d'un bloc de données peuvent être divisés conceptuellement en paramètres (parameters) et éléments de données (data items). Les blocs de données peuvent contenir des paramètres et des éléments de données entremêlés.
Éléments de données
Dans les lignes de données, les attributs text, from, till et at s'appliquent toujours uniquement à la ligne dans laquelle ils apparaissent.
Paramètres
Dans les lignes de données, les attributs tels que color et fontsize ont des implications différentes selon le contexte. Si ces paramètres apparaissent sur une ligne sans éléments de données, ils définissent de nouvelles valeurs par défaut pour les lignes de données qui suivent. S'ils apparaissent sur une ligne mélangée avec des éléments de données, ils s'appliquent uniquement à cette ligne, remplaçant ainsi une valeur par défaut précédemment définie.

Exemple :

# In this example two sets of bars are drawn, in red and blue respectively,
# but in each set one bar (marking war periods) will be drawn in green.

PlotData =
  color:red fontsize:S                               # set defaults
  bar:USSR from:1919 till:1922 text:Lenin            # red bar
  bar:USSR from:1922 till:1953 text:Stalin           # red bar
  bar:USSR from:1939 till:1945 text:WWII color:green # green bar
  bar:USSR from:1953 till:1964 text:Krushchev        # red bar
   
  color:blue                                         # change default color
  bar:US from:1913 till:1921 text:Wilson             # blue bar
  bar:US from:1917 till:1918 text:WWI color:green    # green bar
  bar:US from:1921 till:1923 text:Harding            # blue bar

#> this multiline comment does not end command PlotData,
   even when the previous line does not start with a space<#

   bar:US from:1923 till:1929 text:Coolidge           # blue bar

TextData =                                            # now PlotData is considered complete
   tabs:...etc

Règles d'entrée des données d'attribut

Mesures

Les mesures peuvent être absolues ou relatives à la taille de l'image en fonction de l'unité spécifiée dans les attributs.

Dans les attributs qui prennent des paires de coordonnées, la première coordonnée est horizontale de gauche à droite, la seconde est verticalement vers le haut.

Mesures absolues

Ils peuvent être utilisés pour spécifier les tailles totales de l'image, les positions et les décalages de position. La valeur peut être spécifiée en pixels (px), en pouces (in) ou en centimètres (cm) en ajoutant une unité postfixée à la valeur. Les valeurs peuvent avoir des décimales fractionables.

Exemple :

PlotArea = left:50 bottom:50 right:50 top:90

Les mesures absolues suivantes sont équivalentes :

  • 800px
  • 800 (l'unité par défaut est le pixel)
  • 8 pouces (en supposant une résolution d'affichage de 100 pixels par pouce)
  • 3,15cm (en supposant la même résolution d'affichage, convertie en centimètres)

Mesures relatives

Ils peuvent être utilisés pour spécifier des tailles et des positions en fonction des tailles totales d'image ; ils ne peuvent pas être utilisés pour spécifier les tailles totales d'image (voir ImageSize) mais peuvent être utilisés pour définir le PlotArea.

Pour les mesures horizontales, le pourcentage est lié à la largeur de l'image, pour les mesures verticales à la hauteur de l'image.

Spécifiez un nombre compris entre 0 et 100, immédiatement suivi d'un signe % (pourcentage).

Exemple :

PlotArea = left:10% bottom:5% right:5% top:15%

Saisie de texte

La saisie de texte est soumise à quelques règles :

  1. Seul un sous-ensemble d'unicode est autorisé pour le rendu des polices, mais l'unicode dans les liens devrait fonctionner pour tous les caractères. Voir aussi Font support.
  2. Lorsque le texte doit contenir des espaces, spécifiez-les en utilisant des traits de soulignement (_) ou placez le texte entre "guillemets doubles".
    Exception : lorsque l'attribut text est le dernier attribut d'une ligne, les espaces sont autorisés (aucune confusion ne se produira là où le texte s'arrête et l'attribut suivant commence, c'est-à-dire & mdash; pour être précis & mdash; quand aucun virgule n'apparaît dans le texte).
  3. Dans les lignes de données suivant la commande TextData, deux caractères ont une signification particulière
    ^ (caret) signifie tab
    ~ (tilde) signifie nouvelle ligne

Exemple : (les éléments suivants sont tous équivalents)

BarData =
  text:Japanese_mandate_since_1914 bar:Marshalls

BarData =
  text:"Japanese mandate since 1914" bar:Marshalls

BarData =
  bar:Marshalls text:Japanese mandate since 1914

Exemple montrant des onglets :

TextData =
  tabs:(4-right,12-right,14-left,34-left)
  text:^1^1940^27/9^Berlin Ger,It,Jap sign Tripartite Pact
  text:^10^1944^1-22/7^Bretton Woods 44 nations establish
  text:^^^^^IMF and World Bank

# will be shown as:
#
#      1    27/9 Berlin Ger,It,Jap sign Tripartite Pact
#     10  1-22/7 Bretton Woods 44 nations establish
#                                    IMF and World Bank

Cartes cliquables

Les deux formats de sortie disponibles dans MediaWiki, à savoir PNG et SVG, peuvent contenir des liens cliquables. Les textes affichés en bleu et les barres peuvent ensuite être cliqués pour naviguer vers une autre page Web.

Les liens peuvent être spécifiés avec les commandes BarData, PlotData et TextData, soit avec l'attribut link, soit en tant que liens incorporés, via l'attribut text.

Liens intégrés

Les liens incorporés sont des liens qui font (partie d'un) texte affichable, spécifié avec l'attribut text. Leur contrepartie sont des liens explicites (URL uniquement) qui sont définis avec l'attribut link.

Les deux types de liens peuvent être spécifiés avec les commandes BarData, PlotData et TextData et sont utilisés pour clickable maps.

Dans les liens incorporés, le style de lien interne est comme d'habitude, le style de lien interwiki ne fonctionne pas, le style de lien externe est comme d'habitude avec des crochets simples, mais ici avec un pipe au lieu d'un espace.

Exemples :

  text:example [[Help:Link|Help:Link]] internal link

sera affiché comme :

Help:Link
  text:[[Special:MyLanguage/Help:Link|Link]]

sera affiché comme :

Special:MyLanguage/Help:Link
  text:[http://en.wikipedia.org/wiki/Rembrandt|Rembrandt van Rijn] paints Night Watch

sera affiché comme :

Utilisation interwikis

Une tentative d'utilisation du style de lien interwiki :

  text:[[en:Main Page|en:Main Page]]

et similaire avec nl: et m: donne :

m:Main Page

Le troisième vers Meta-Wikipedia fonctionne correctement, sauf à partir de Meta lui-même, les autres liens fonctionnent comme MainPage (page interne, le préfixe est ignoré) ou par ex.//www.mediawiki.org/w/Main_Page (donne File not found), en fonction de l'URL de la page de référence (par exemple différente pour une page d'aperçu et une page de diff).

Caractères spéciaux

  • #, #>, <# (hash, hash + "supérieur à", "inférieur à" + hash): voir Commentaires
  • ~ (tilde) dans les textes signifie : saut de ligne
  • ^ (caret) dans les textes signifie : tabulation
  • _ (trait de soulignement) dans les textes signifie : espace
  • $ (signe dollar) précède toute constante définie par l'utilisateur

Les espaces vides et les traits de soulignement dans une URL doivent être écrits sous la forme %20.

Le caractère tilde (~) est normalement interprété comme un saut de ligne. Lorsqu'un tilde fait partie d'une URL, écrivez-le comme deux tildes.
Par exemple, créez un lien vers www.site.com/~mysite comme suit :

  text:[www.site.com/~~mysite|My site]

Le signe dièse (#) est normalement interprété comme le début du commentaire. Lorsqu'un signe dièse fait partie d'une URL, assurez-vous que le texte est incorporé entre guillemets doubles comme suit :

  text:"More at [www.site.com/~~mysite#section2|My site]"

En fait, il peut être judicieux de toujours mettre les textes entre guillemets.

Référence de commande

Pour chaque commande, les attributs valides sont répertoriés. Certaines commandes sont obligatoires et certains attributs des commandes sont facultatifs.

Pour certaines commandes, certains attributs sont mutuellement exclusifs (seront expliqués le cas échéant).

AlignBars

Les barres seront toujours dessinées à des distances égales. Cette commande spécifie si les barres doivent être espacées autant que possible, ou si un espace blanc doit être réservé entre le côté gauche/supérieur du graphique et la première barre ou entre la dernière barre et le côté droit/inférieur du graphique.

early (par défaut)
La première barre sera placée sur la position la plus à gauche/la plus haute du graphique ('collée' à l'axe), laissant un espace entre la dernière barre et le côté droit/inférieur du graphique.
late
À l'opposé de early : la dernière barre sera placée aussi loin que possible du côté droit/inférieur du graphique, laissant un espace entre la ligne de l'axe (côté gauche/supérieur du graphique) et la première barre.
justify
Les première et dernière barres seront placées aussi loin que possible, ne laissant aucun espace vide de chaque côté du graphique. Lorsqu'une seule mesure est présente, la justification sera interprétée comme "centrée".

L'alignement exact dépend du paramètre d'orientation dans la commande obligatoire TimeAxis.

Exemples :

Alignbars = early late justify (default)
TimeAxis = orientation:horizontal
TimeAxis = orientation:vertical

BackgroundColors

Cette commande permet de spécifier les couleurs d'arrière-plan pour différentes parties du graphique. Tout « color-id » spécifié doit être défini en premier en utilisant Colors.

canvas : color-id (facultatif)

Spécifie une couleur d'arrière-plan pour toute l'image.
bars: color-id (facultatif)
Spécifie une couleur d'arrière-plan pour toutes les barres.

Exemples :

BackgroundColors = bars:darkgrey

BackgroundColors = canvas:lightgrey bars:darkgrey

BackgroundColors = canvas:lightgrey

BarData

Il s'agit d'une commande facultative qui, si elle est présente, détermine quelles barres seront dessinées sur le graphique et dans quel ordre. S'il est omis, les barres seront dessinées dans l'ordre de leur apparition dans la commande PlotData.

Pour les chronologies complexes avec de nombreuses barres, l'utilisation de cette commande est recommandée :

  • Cela facilitera la réorganisation des données affichées.
  • Les noms de barres spécifiés dans PlotData peuvent être validés par rapport à cette liste, évitant ainsi les erreurs de frappe.
bar : bar-id
Définit l'identifiant de la barre. D'autres commandes (notamment PlotData) attendront cet identifiant pour référence. Ce sera également l'étiquette à afficher le long de l'axe, à moins que l'attribut « texte » ne soit présent. L'identifiant de la barre ne doit contenir aucun espace : utilisez plutôt des traits de soulignement (_), ceux-ci seront convertis en espaces, comme pour les titres d'articles.
text : some_text (facultatif)
Lorsque spécifié, cela indique le texte à présenter le long de l'axe, au lieu de l'ID de la barre. Voir aussi les règles pour saisie de texte. Le texte peut inclure un lien intégré (voir Note 1).
link (lien) : URL-local (facultatif)
Spécifier un lien Web (voir Note 1) (URL). L'étiquette le long de l'axe sera affichée sous la forme d'un lien cliquable bleu.

Notes

  1. Utilisez l'attribut « link », ou un lien incorporé dans l'attribut « text », pas les deux.

Exemples :

BarData =
  bar:Japan
  bar:US       text:"United States"  # refer in PlotData to bar "US" but show "United States"
  bar:China    text:[[Special:MyLanguage/China|China]]        # label China will be shown as blue clickable link to the English Wikipedia article about China

Les lignes suivantes produisent le même résultat (référence uniquement dans les modifications PlotData) :

bar:US            text:[[Special:MyLanguage/United_States|United_States]]

bar:US            text:"United States" link:http://www.wikipedia.org/wiki/United_States

bar:United_States                      link:http://www.wikipedia.org/wiki/United_States

Colors

Cette commande permet de définir des couleurs et de les coupler à un identifiant (étiquette d'identification). D'autres commandes feront référence aux couleurs avec l'identifiant spécifié ici. Cette commande attend une ou plusieurs définitions de couleur, chacune sur une ligne en retrait distincte.

id : color-id
D'autres commandes utiliseront cet identifiant pour spécifier les couleurs du texte, de la barre ou de l'arrière-plan.
value (valeur) : color-space ( coordonnées )
Définition de la couleur réelle. Les valeurs de couleur peuvent être spécifiées comme suit:
* predefined-color-name : 32 constantes de couleur sont prédéfinies et reconnues (voir la page de couleurs Ploticus où toutes ces constantes sont définies).
  • rgb(red,green,blue): spécifiez 3 nombres entre 0 (minimal) et 1 (maximal)
  • hsb(hue,saturation,brightness): spécifiez 3 nombres entre 0 et 1.
  • gray(value): spécifiez 3 nombres entre 0 et 1. (noir) et 1 (blanc).
Notes
# Les coordonnées de l'espace de couleurs 0 et 1 doivent être spécifiées sous forme d'entiers uniquement, les coordonnées intermédiaires nécessitent un point comme séparateur décimal après 0.
# Pour créer des couleurs RVB ou HSV, veuillez consulter Convertisseur de couleurs RVB / HSB
Hexadécimal à rgb ()
Pour convertir de l'hexadécimal (# D09916) en RGB (rgb (0.816,0.600,0.086)):
# Visitez ColorHexa et recherchez votre couleur hexadécimale.
# Lire la ligne de texte au début le long des lignes de "Dans un espace colorimétrique RVB, hex ... est composé de RR.R% rouge, GG.G% vert et BB.B% bleu".
# Divisez les trois nombres (RR.R, GG.G et BB.B) par 100, et utilisez le nombre résultant (entre 0 et 1) comme valeurs pour rgb ().
légende : texte à saisir (facultatif)
Spécifie le texte qui doit être affiché dans la legend pour cette couleur. Si cet attribut est omis, aucune entrée n'apparaîtra dans la légende.
Notes:
# Voir Saisie de texte pour les règles.
# Les liens incorporés sont pris en charge dans les textes de légende, voir Clickable maps.

Exemple :

Colors =
  id:war       value:red   legend:War_Period
  id:peace     value:blue  legend:Peace_Time
  id:treaty    value:rgb(0.6,0,0.6)
  id:lightgrey value:gray(0.9)
  id:darkgrey  value:gray(0.1)

Predefined colors

Référence aux couleurs en HTML

#000000 #b29999 #e5d3c9 #ffffff      
#ffcccc #ff9999 #ff4c7f #b24c4c #ff0000    
#ff7f00 #ff9e23 #ffcc99 #ffd800 #eaea00 #ffff00 #ffe599
#00ff00 #00b200 #4c994c #007f33 #99cc99 #99e599 #ccffb2
#b2ccff #007fcc #0066cc #0000ff      
#770077 #aa4caa #9999ff #b2b2ff #ccb2cc    

DateFormat

Cette commande définit la façon dont les dates, spécifiées dans d'autres commandes, doivent être interprétées.

Les formats de date valides sont :

dd/mm/yyyy (dates dans la plupart des pays anglophones)
Les dates sont interprétées comme jour / mois / année
Remarque: ce format n'est autorisé que pour les dates à partir du 01/01/1800
mm/dd/yyyy (dates aux États-Unis)
Les dates sont interprétées comme mois / jour / année
'Remarque' : ce format n'est autorisé que pour les dates à partir du 01/01/1800
yyyy (c'est le format par défaut)
Cela concerne les integers de -9999 à 9999 sans zéros non significatifs

Notes the following formats are still not supported:

  • the ISO 8601 standard format: yyyy-mm-dd (standard in Canada).
  • the alternate Central-European standard format: yyyy.mm.dd.
  • the date formats with month but without day: mm/yyyy or ISO 8601 yyyy-mm.
  • the date formats with quarters: qq/yyyy or ISO 8601 yyyy-Qq.
  • other date element separators, multilingual abbreviated month names...

Exemple :

DateFormat = mm/dd/yyyy

Définir

This command allows definition of text constants, i.e. shorthands for pieces of script code that occur multiple times. Text constants should always start with a $ (dollar sign).

Example:

Define $broad       = width:30
Define $narrow      = width:10
Define $bardefaults = $broad fontsize:S

ImageSize (mandatory)

This command defines the overall size of the final image. Specify values in absolute measurements.

width:pixels/auto
Width of final image in pixels: maximum is 1600 pixels, minimum is 25
(can also be set to auto if the TimeAxis direction is set to vertical).
height:pixels/auto
Height of final image in pixels: maximum is 1200 pixels, minimum is 25
(can also be set to auto if the TimeAxis direction is set to horizontal).
barincrement:pixels
Amount in pixels that should be added to the image size for each bar specified
(only allowed in combination with width:auto or height:auto, and then mandatory).

For maximum flexibility you can let the script calculate the height or width of the image, based on the number of bars and the amount in pixels to add per bar. Specify height:auto (for horizontal time axis) or width:auto (for vertical time axis).

This is especially helpful when the number of bars in a timeline is likely to change over time again and again. Or to ensure equal distances between bars in images with many narrow bars where differences in amount of white space would soon be noticed (see for a real example :en:Template:Vocal and instrumental pitch ranges). Or to make sure several related timelines always use the same distance between bars, no matter how many bars each contains (see for a real example :en:List of popes (graphical). In short it is a good idea most of the time.

Exemples :

ImageSize = width:800 height:600

ImageSize = width:800 height:auto barincrement:30

Légende

A legend will only be shown when this command is present, and at least one of the colors has the legend: attribute specified. There are several ways to define the appearance and position of the legend. Some attributes are mutually exclusive (see below).

orientation:hor/ver (optional)
Specify hor[izontal] or ver[tical] (default).
restriction: orientation = 'horizontal' and position = 'right' are mutually exclusive
position:top/bottom/right (optional)
Defines placement of the legend relative to the chart area. Specify top, bottom (default) or right.
restriction: orientation = 'horizontal' and position = 'right' are mutually exclusive
columns:integer (optional)
Specify 1, 2, 3 or 4.
When this attribute is omitted the number of columns is determined as follows:
  • orientation horizontal: Attribute columns does not apply here. All entries will be on the same line.
  • orientation vertical:
    • position right: All entries will be in one column
    • position top or bottom: The number of columns depends on the number of entries to be shown:
      1-5 entries: 1 column, 6-10 entries: 2 columns, 11 or more entries: 3 columns.

Tip: you may consider omitting the following parameters at first, and only add them when defaults settings are not satisfactory.

columnwidth:distance (optional)
Defines the distance between columns. You can specify an absolute distance or a relative distance (as percentage of the image width).
restriction: this parameter is ignored when columns = 1 is defined or implied.
left:distance (optional)
Defines the distance between the left side of the legend and the left side of the image. You can specify an absolute distance or a relative distance (as percentage of the page width).
top:distance (optional)
Defines the distance between the top of the legend and the bottom of the image. You can specify an absolute distance or a relative distance (as percentage of the page height).

Exemples :

Legend = orientation:vertical position:bottom columns:3 columnwidth:140

Legend = orientation:horizontal position:bottom

Legend = left:100 top:120 columns:3

LineData

Some timelines extend over several clearly distinct periods. A line demarcating these periods may serve as a visual aid.

at:time
Draws a line perpendicular to the time axis (between minimum and maximal positions, see also below).
Specify the date/year where the line should be drawn, in compliance with the specified DateFormat.
color:color-id (optional)
Specify the color in which the line should drawn.
Note: The color id specified should be defined first with command Colors.
layer:front/back (optional)
Specify front or back (default). Defines whether the line should appear in front of or behind all time segment bars.
width:distance (optional)
Specify value between 0.1 (very thin) and 10 (very thick); the default value is 1

Advanced positioning options

You can draw lines in any direction. Only in rare cases the following extra attributes may be needed for full flexibility:

  1. Parallel to the time axis with arbitrary start and stop times:
    atpos:position
    from:time (optional)
    till:time (optional)
    Specify the absolute or relative position on the axis orthogonal to the TimeAxis.
    Specify the dates/years between which the line should be drawn, in compliance with the specified DateFormat (default is the full range of time as set in the mandatory Period command, see also below).
  2. Orthogonal to the time axis with arbitrary start and stop positions:
    at:time
    frompos:position (optional)
    tillpos:position (optional)
    Specify the date/year where the line should be drawn, in compliance with the specified DateFormat.
    Specify the start and stop absolute or relative positions on the axis orthogonal to the TimeAxis (default is the full length of the DrawArea).
    Draws a line orthogonal to the time axis (default at full range of time as set in the mandatory Period command, see also below).
  3. In any direction with arbitrary start and stop points:
    points:(x1,y1)(x2,y2)
    Specify the absolute or relative positions as coordinates, independantly of the direction of the time axis.

Exemple :

LineData =
  layer:front                                            # all lines in front of bars unless stated otherwise
  at:1                         color:yellow              # perpendicular to time axis full length
  at:2                         color:orange  layer:back  # perpendicular to time axis full length but behind bars
  at:4  frompos:50 tillpos:105 color:green               # perpendicular to time axis, with specified start and stop points
  from:5 till:8 atpos:50       color:red                 # parallel to time axis
  points:(100,20)(170,105)     color:blue    width:3     # from one arbitrary absolute position to another, extra thick

Period (mandatory)

Defines the time period that will be displayed in the chart. Both parameters are mandatory. Specify dates in compliance with specified DateFormat.

from:time
Timeline starts here. The specified value can be referenced as start in commands like PlotData and TextData.
till:time
Time ends here. The specified value can be referenced as end in other commands.

Example:

Period = from:01/09/1939 till:02/09/1945

PlotArea (obligatoire)

left:distance
Margin between left side of image and left side of plot area. Specify value in absolute or relative measurements.
top:distance
Margin between top of image and top of plot area. Specify value in absolute or relative measurements.
right:distance (recommended)
Margin between right side of image and right side of plot area. Specify value in absolute or relative measurements.
This attribute and the deprecated width attribute are mutually exclusive.
bottom:distance (recommended)
Margin between bottom of image and bottom of plot area. Specify value in absolute or relative measurements.
This attribute and the deprecated height attribute are mutually exclusive.
The minimum value for this attribute is 20 pixels if you have specified legend labels (see Legend).
width:distance (deprecated)
Specify value in absolute or relative measurements.
do not use anymore, see the right attribute above.
height:distance (deprecated)
Specify value in absolute or relative measurements.
do not use anymore, see the bottom attribute above.

Notes:

  1. The width and height attributes are only retained for downward compatibility. Earlier a plot area could only be defined by its total width and height, and left and bottom margins.
  2. Now you can specify all four margins, and are advised to do so, and not use width and height attributes anymore.
  3. The advantage is added flexibility: when you change the overall image size, you do not need to adjust the plotarea definition as well. This is even more important when the image size is calculated automatically (see ImageSize).

Exemple :

PlotArea = left:40 bottom:60 top:10 right:10 # e.g. extra space to the left and below the plot area for axis labels and legend

PlotData

Used to define bars (symbolizing a time period), and add text next to these bars on a specific position.

For texts which are not related to a certain period or date/year or which require extensive formatting use command TextData.

Attributes text, at, from and till always apply only to the line on which they occur. All other attributes, when not combined with one of these four, act as default for the remainder of the command block or until a new default is specified, and may be overruled for a single line. See Parameters vs data items for more info and an example.

PlotData accepts a lot of attributes, some of which are mutually exclusive. These attributes can be grouped as follows:

  • Positional attributes
  • Bar related attributes
  • Text attributes
  • Marker attribute

Attributs positionnels

at:time (applies only to current line in data block)
Specifies at which date/year a text or marker should be positioned. Depending on attribute align the text either starts, ends or is centered at this position. Use date/year format as specified in DateFormat or specify start or end which refers to time frame defined by command Period.
Note: This attribute can not be combined with attributes from and till.
from:time (applies only to current line in data block)
till:time (applies only to current line in data block)
Specifies at which date/year a bar should start and end. Use date/year format as specified in DateFormat or specify start which refers to time frame defined by command Period.
Note: These two attributes should be used in combination and can not be combined with attribute at.
shift:(x,y) (optional)
Specifies a horizontal and vertical displacement in absolute measurements for a text. This allows:
  • Texts to be shifted to avoid overlaps between successive bars;
  • Placement of text beside a bar, instead of on top of it.

Exemples :

PlotData=
  bar:Japan from:start      till:19/02/1945 color:JT
  bar:Japan from:19/02/1945 till:14/03/1945 color:AI
  bar:Japan from:02/09/1945 till:end        color:AO

  at:07/12/1941 shift:(0,-15) text:"<-- WW2 reaches Asia"

Bar related attributes

bar:bar-id
Specifies to which bar all other attributes apply (including the optional marker attributes and text attributes).
The bar-id specified here will also be the text presented along the axis, next to the bar.
  • When command BarData has not been used, bars will be drawn in the order in which they occur in any PlotData data block.
  • When command BarData has been used, bars will presented in the order specified there, also the bar-id specified here will be validated against that list. Also the text presented along the axis will depend on the definition in BarData.
barset:barset-id (optional)
Restarts the bar display "from the top", allowing multiple bars on the same line.
The specified bar-id must have been declared in BarData.
The default barset is anonymous and needs not be specified if there's no BarData.
Blank lines may be added to skip over lines that you do not wish to add to with declarations such as at:1234 with no further attributes. Multiple bars may then be specified on after this attribute.
color:color-id (optional)
Specifies the color is which the bar should be drawn.
The color id specified should be defined first with command Colors.
The default value will be the same color as the previously specified bar.
width:distance (optional)
Specifies the width of the bar in absolute or relative measurements.
The default value will be computed according to the total size of the PlotArea, and the maximum number of bars in all barsets (including the default anonymous barset).

Exemple :

BarData=
  bar:US text:United States
  bar:SB text:Sea Battles

Colors=
  id:US value:blue legend:United_States
  id:SB value:rgb(0.8,0,0.7) legend:Sea_Battles

PlotData=
  width:0.3                                                            # see note 1
  bar:SB     from:07/08/1942 till:09/02/1943 text:Guadalcanal color:SB # see note 2
  bar:US     from:start      till:end color:US                         # see note 3
  bar:Midway from:start      till:end color:US                         # see note 4
  bar:US     at:07/12/1941   text:7/12 Pearl Harbour                   # see note 5

Notes:

  1. this line establishes a default bar width for the remainder of the data block
  2. this line specifies a bar to be drawn and a text to placed on it at the same time
  3. bar US will be drawn before bar SB, even when specified after it, because command BarData determines the sequence
  4. bar Midway will be rejected because it is not declared with command BarData
  5. the last line will not result in a bar being plotted, it merely specifies on which bar the text should be placed

Attributs de texte (facultatif)

text:some_text (applies only to current line in data block)
Defines a text that should be plotted on or near a bar.
Notes
  1. See also Text Input for rules.
  2. The text may include embedded links (see Notes 1 & 2) for use in clickable maps.
  3. See Clickable maps for information about texts with embedded links and limitations.
textcolor:color-id (optional)
Defines the color of the text. The color id specified should be defined first with command Colors. When not specified color black will be assumed.
fontsize:integer/tag (optional)
Specify a point size between 6 and 30, or (preferably) one of tags XS, S (default), M, L or XL. See Font support for more details.
anchor:middle/from/till (optional)
Specify the anchor position. If not defined, the anchor position is either explicitly set with the attribute at, or implicitly with the attributes from and till. In the latter case the text will be positioned in the middle of the defined bar segment.
align:center/left/right (optional)
Specify center (default), left or right.
link:URL (optional, applies only to current line in data block)
Specify a web link (see Note 1) (URL) for use in clickable maps. The text will be shown as a blue clickable link.
Notes
  1. This attribute can only be used with the text attribute.
  2. Either use attribute link, or an embedded link in attribute text, not both.
  3. On PNG images rendered as clickable maps, only one clickable link will be shown per text segment: text with line breaks (~) constitutes several segments.
  4. See Clickable maps for information about texts with embedded links and limitations.

Example:

PlotData=
   bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:7/12 [[Special:MyLanguage/Pearl Harbour|Pearl Harbour]]

produces the same result as:

PlotData=
   bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:"7/12 Pearl Harbour" link:http://www.wikipedia.org/wiki/Pearl_Harbour

Marker attribute (optional)

mark:(symbol,color-id)
Places a marker in a bar at the specified position.
  • The only value for symbol supported to date is line.
  • The color-id specified should be defined first with command Colors. When not specified color black will be assumed.

Example:

PlotData=
  bar:test width:15 color:red
  from:1900 till:2000
  at:1990 mark:(line,white)

will be shown as:

ScaleMajor

This command divides the timeline into smaller periods, either

  • Graphically, through thin vertical or horizontal lines in the chart
  • Textually, through stubs in the time axis, below or to the left of the chart
  • Both graphically and textually
gridcolor:color-id (optional)
Defines the color for the grid lines.
When this attribute is omitted no grid lines will be drawn.
The color-id specified should be defined first with command Colors.
unit:time-unit (optional)
Specifies the time unit by which the grid spacing is incremented.
Specify day, month or year (default).
When DateFormat = yyyy is specified, only unit year is allowed.
increment:integer (optional)
Specifies the (non zero) number of units by which the grid spacing is incremented.
The default increment is 1.
start:time (optional)
Specifies where the first grid line and/or stub should be displayed.
Defaults to start of defined Period.

Note: the orientation of the lines and/or placement of the stubs depends on the orientation of the TimeAxis.

Examples:

ScaleMajor = gridcolor:red start:1940

ScaleMajor = gridcolor:red unit:month increment:3 start:01/09/1939

ScaleMinor

This command defines a further subdivision of the timescale (see ScaleMajor for attributes syntax).

Example:

ScaleMajor = grid:red  unit:year  increment:1 start:01/01/1940
ScaleMinor = grid:blue unit:month increment:3 start:01/10/1939

TextData

Used to define a text block that can be positioned anywhere on the chart.

text:some_text
The actual text.
See also Text Input for rules.
The text may include embedded links (see also Notes 1 & 2).
pos:(x,y)
Defines the top-left corner of the text block in absolute or relative measurements.
link:URL (optional)
Specify a web link (see Note 1) for use in clickable maps.
The label along the axis will be shown as a blue clickable link.
textcolor:color-id (optional)
Defines the color of the text to draw.
The color-id specified should be defined first using Colors.
When not specified, the color is black.
fontsize:integer/tag (optional)
Specify a point size between 6 and 30, or (preferably) one of tags XS, S (default), M, L or XL (see Font support for more details).
tabs:(x1-alignment1,x2-alignment2...) (optional)
Defines position and alignment for tab character: ^ (caret).
Specify multiple tab settings as a comma-separated list of xn-alignn where
  • xn is the horizontal displacement in absolute measurements from the left side of the text;
  • alignmentn is the alignment for the text segment (specify center, left or right).
lineheight:distance (optional)
Defines spacing between consecutive lines in absolute measurements.
Specify a value up to 40 pixels (or 0.4in).
When not specified a default lineheight will be based on the font size currently in use.

Notes:

  1. Either use attribute link, or an embedded link in attribute text, not both.
  2. On PNG images only one clickable link will be shown per text segment (text with tabs (^) constitutes several segments).

Example:

TextData =
  pos:(20,67) textcolor:black fontsize:S
  tabs:(10-right,14-left,50-left,90-left,230-left)
  text:"^1^1940^27/9^Germany,Italy and Japan sign [[Special:MyLanguage/Tripartite Pact|Tripartite Pact]]"
  text:^10^1944^1-22/7^Bretton Woods 44 nations establish
  text:^^^^^IMF and World Bank

will be shown as:

Special:MyLanguage/Tripartite Pact

TimeAxis (mandatory)

Defines the orientation of the time axis, and textual representation of stubs along that axis.

format:time-format (optional)
Specify in which format dates should be presented along the time axis.
Currently only format yyyy (default) is supported. This means that if a the unit: attribute for ScaleMajor is set to anything other than year, the major grid lines will not be in sync with the axis labels. For instance, setting unit:month and increment:6 will result in major gridlines every 6 months, but axis labels every 6 years. Support for more formats may follow.
orientation:hor/ver
Specify hor[izontal] or ver[tical].
The default time axis orientation is horizontal.
order:reverse (optional)
Specify reverse as the option to reverse the time flow.
The default is the forward time flow.

Example:

TimeAxis = orientation:horizontal format:yyyy

Presets

Presets are a shorthand for often used settings. They save a few code lines and promote standardisation, but may be confusing, as the timeline script become less self documenting.

At the moment two presets are available:

  • Preset = TimeVertical_OneBar_UnitYear, which expands to
PlotArea   = left:45 right:10 top:10 bottom:10
TimeAxis   = orientation:vertical format:yyyy
DateFormat = yyyy
AlignBars  = early
ScaleMajor = unit:year
ScaleMinor = unit:year
PlotData   =
   mark:(line,white) align:left fontsize:S width:20 shift:(20,0)
  • Preset = TimeHorizontal_AutoPlaceBars_UnitYear, which expands to
ImageSize  = height:auto barincrement:20
PlotArea   = left:25 right:25 top:15 bottom:30
TimeAxis   = orientation:horizontal format:yyyy
Colors = 
  id:canvas value:gray(0.7)
  id:grid1  value:gray(0.4)
  id:grid2  value:gray(0.2)
BackgroundColors = canvas:canvas
DateFormat = yyyy
AlignBars  = justify
ScaleMajor = unit:year grid:grid1
ScaleMinor = unit:year
Legend = orientation:vertical left:35 top:130
PlotData =
   align:left anchor:from fontsize:M width:15 shift:(4,-6) textcolor:black

Implementation and integration limitations

Font support

Timeline has somewhat limited Unicode support:

  • it uses the FreeSans.ttf font, which supports a subset of all the possible glyphs ;
  • for instance, it supports the West- and East-European diacritics for the Latin alphabet, as well as the Cyrillic, Greek and Armenian alphabets, the Hebrew abjad (but without visual reordering), the Devanagari, Bengali, Gurmukhi, Gujarati, Tamil and Kannara abugidas for Indian languages, the Kanas alphasyllabaries (for basic Japanese only), and a good subset of extended general punctuation, currency unit symbols, subscript/superscript digits, letterlike symbols, fractions and Roman numbers, some arrows and mathematical operators;
  • but it lacks the Georgian alphabets, the Arabic abjad, the Hangul alphabet and syllables, the Oriya, Telugu Thai, Lao and Tibetan abugidas, the Kanji and Han ideographs (so Chinese, Korean, Georgian, Arabic and Thai are not supported, and Japanese must still be transliterated to basic Kanas or to Latin);
  • also it does not support Dingbats, as well as non linguistic symbols like box drawing characters that should be drawn using the supported line drawing commands.
  • Different fonts can be set in LocalSettings.php which may have better unicode support. For example, the Malayalam Wikipedia uses a different font which has better Malayalam language support.

As a legacy of bitmap font usage, only five font tags are predefined. They will render at slightly different sizes in PNG and SVG images to produce optimal readability for both platforms. It is advised to use these tags instead of numbers whenever possible. They are: XS=eXtra Small, S=Small (default), M=Medium, L=Large, XL=eXtra Large

EasyTimeline code with template parameter or magic words

If you want to use easy timeline with template parameters or things like {{CURRENTDAY2}} you can use #tag syntax:

{{#tag:timeline|
Timeline code here
}}

However, one must replace all |'s with {{!}} (which should be a template containing just |). See the section on #tag at Help:Magic words for details

Known bugs and limitations in embedded links

  • You can currently specify only one link per text segment.
  • Link trailers are not recognized, you must put the full text that is part of the link within "MyLanguage/".
  • Links that are not specified at the begining of the text (or the begining of a new line after a line break specified by a tilde) are incorrectly positioned (the normal text color is used at the correct position, and the text with the blue link color is overdrawn on top of it with the wrong horizontal position). See the first example tryig to show "Help:Link" above in this section.
  • If the displayed text in bar legends of a PlotData contains newlines (represented by a ~), the targer URL is broken, keeping only the first word in it.

    For example the following code in bar data:

  •   from:1935 till:2004 text:"[[Special:MyLanguage/Françoise Sagan|Françoise Quoirez,~alias Françoise Sagan]]" color:writer
    

    currently renders as

    where the target links to Françoise instead of Françoise Sagan, and shows the incorrect tooltip text "Françoise Sagan/.." with extra characters. This bug does not occur if the target link contains a single word. Surrounding the full text (with the link itself) with quotes does not solve the problem. Additionally, this requently causes the timeline to fail without showing the error during its rendering (no image rendered on the browser).

  • In addition the target is assumed as belonging to the same parent page as the current subpage even though the target link does not start with a "/" (with the wiki syntax), so timelines containing links are not usable in subpages (like this one).