24,656
edits
Changes
m
no edit summary
{{hh}}
The EasyTimeline feature produces an embedded [[Help:Images and other uploaded files|image]] from wikitext. The image can be a one-dimensional diagram (horizontally or vertically), or a two-dimensional one. The name "EasyTimeline" refers to the possibility to apply the feature with a time scale horizontally or vertically, possibly with another parameter in the other direction, but there are also various other possiblities.
See also [[EasyTimeline]], [[Help:EasyTimeline examples]].
==Introduction==
Graphical timelines can be produced by providing a script between special tags:<br/>
<nowiki><timeline></nowiki><br/>
''script''<br/>
<nowiki></timeline></nowiki>
EasyTimeline will then be invoked to render a PNG image and (optionally) a clickable map.
'''Disclaimer''': Even when EasyTimeline is designed for ease of use, a complicated graphical timeline is a non-trivial affair.
A simple timeline may take half an hour to compose (or even less, when a suitable example is taken as a basis). Large timelines may take a few hours for composition and fine-tuning. However, adding to or correcting a timeline, no matter how complex, should be a relatively straightforward affair,
even for contributors who have no expert knowledge of the syntax described here.
Feel free to ask the [[user:Erik Zachte|author of EasyTimeline]] for advice.
==Available commands==
The script commands define:
*Overall layout: [[#ImageSize|ImageSize]], [[#PlotArea|PlotArea]], [[#Colors|Colors]], [[#BackgroundColors|BackgroundColors]], [[#AlignBars|AlignBars]]
*Interpretation and presentation of dates and periods: [[#DateFormat|DateFormat]], [[#Period|Period]], [[#ScaleMajor|ScaleMajor]], [[#ScaleMinor|ScaleMinor]], [[#TimeAxis|TimeAxis]]
*Events, periods and descriptive texts: [[#PlotData|PlotData]], [[#TextData|TextData]]
*How to order, divide, and name groups of events and periods: [[#BarData|BarData]], [[#Legend|Legend]], [[#DrawLines|DrawLines]]
*Shorthands for pieces of script code that occur multiple times: [[#Define|Define]]
The following commands are mandatory: [[#ImageSize|ImageSize]], [[#PlotArea|PlotArea]], [[#Period|Period]] and [[#TimeAxis|TimeAxis]]. At least one of the following commands is required: [[#PlotData|PlotData]] and/or [[#TextData|TextData]]. Either or both can occur multiple times. All other commands are optional.
'''Case''': Commands and their attributes can be specified in lower, upper or mixed case. Please try to be consistent in applying case as this will further readability, e.g. use mixed case for all commands and lowercase for all attributes.
----
==General syntax rules==
A script can contain commands and comments. Each command is followed by one or more attributes.
===Commands===
Commands should start on the first position of a line.
Some commands can be followed by multiple lines of data and/or options.
These extra lines should start with at least one space or be completely empty
(the latter is useful for visually grouping related data lines).
Commands have the one of the following forms, depending on the type of
command:
'''''Command = attribute(s)'''''
<div style="background-color: #F0F0F0"><pre>
DateFormat = dd/mm/yyyy
</pre></div>
'''''Command name = attribute(s)'''''
<div style="background-color: #F0F0F0"><pre>
Color Jp = value:red legend:Japan
</pre></div>
'''''Command =<br/> attribute(s)<br/> attribute(s)<br/> etc.'''''
<div style="background-color: #F0F0F0"><pre>
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
</pre></div>
===Comments===
Single and multi line comments can be specified:
* Text following the hash sign '''#''' will be regarded as a comment
* Text between '''#>''' and '''<#''' will also be regarded as a comment. Comments can span multiple lines, when tagged this way.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
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 <#
</pre></div>
===Attributes===
When several attributes can be specified for a certain command, they are
notated as 'name:value' pairs. When several values can be specified for
one attribute they have to be enclosed between parentheses.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
AlignBars = justify
Color SB = value:rgb(0.8,0,0.7) legend:Sea_Battles
</pre></div>
====Parameters vs data items====
Most commands only accept attributes that are specified on the same line.
'''Data blocks:''' some commands, like [[#BarData|BarData]], [[#PlotData|PlotData]], [[#TextData|TextData]], [[#Colors|Colors]] expect a ''data block'' consisting of one or more ''data lines''. Data lines should start with one or more spaces. A data block is considered complete when a line
starting with a non-space is encountered (exception: empty lines are
ignored, they may be used to group related data lines within a block).
Attributes in a data block can conceptually be divided into ''parameters'' and ''data items''. Data blocks can contain parameters and data items intermingled.
'''Data items:''' in data lines attributes ''text'', ''from'', ''till'' and ''at'' always apply only to the line in which they occur.
'''Parameters:''' in data lines attributes like ''color'' and ''fontsize'' have different implications depending on the context. If these parameters occur on a line without data items, they set new defaults for the data lines that follow. If they appear on a line mixed with data items they apply only to that line, thus overruling a default that was previously set.
<small>Example:</small>
<!-- all data start with space here to keep source formatting
but in actual usage commands should be at start of line -->
<div style="background-color: #F0F0F0"><pre>
# 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
</pre></div>
===Special characters===
*'''#''', '''#>''', '''<#''' (hash, hash+"greater than", "less than"+hash): see [[#Comments|Comments]]
*'''~''' (tilde) in texts means: line break
*'''^''' (caret) in texts means: tab
*'''_''' (underscore) in texts means: space
*'''$''' (dollar sign) precedes any user defined constant
----
==Command Reference==
For each command the valid attributes are listed. Some commands and/or
attributes are optional (O).
For some commands certain attributes are mutually exclusive (will be
explained where applicable).
===AlignBars===
Bars will always be drawn at equal distances.
This command specifies whether the bars should be spaced as much apart as possible, or some white
space should be reserved between the left/top side of the chart and the
first bar or between the last bar and the right/bottom side of the chart.
;early (default) : The first bar will be placed on the leftmost/topmost position of the chart ('glued' to the axis), leaving space between the last bar and right/bottom side of the chart.
;late : Opposite from ''early'': the last bar will be placed as far to the right/bottom side of the chart as possible, leaving space between the axis line (left/top side of chart) and the first bar.
;justify : The first and last bars will be placed as far apart as possible, leaving no empty space on either side of the chart. When only one bar is present, justify will be interpreted as "centered".
<small>Examples:</small>
{{EasyTimeline_Examples_AlignBars}}
----
===BackgroundColors===
This command allows the specifiction of background colors for various parts of the chart.
Any color ''id''s specified should be defined first using [[#Colors|Colors]].
;canvas (O) : Specify a background color for the whole image.
;bars (O) : Specify a background color for all bars.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
BackgroundColors = bars:darkgrey
BackgroundColors = canvas:lightgrey bars:darkgrey
BackgroundColors = canvas:lightgrey
</pre></div>
----
===BarData===
This is an optional command which if present determines which bars will be drawn on the chart and in which order.
If it is omitted then bars will be drawn in order of their appearance in command [[#PlotData|PlotData]].
For complex timelines with many bars, usage of this command is recommended:
*It will ease reordering of the displayed data.
*Bar names specified in [[#PlotData|PlotData]] can be validated against this list, thus preventing typing errors.
;bar : defines the bar id. Other commands (notably [[#PlotData|PlotData]]) will expect this id for reference. This will also be the label to be shown along the axis, unless attribute ''text'' is present. The bar id should not contain any spaces: use underscores instead, these will be converted to spaces, as wih article titles.
;text (O) : When specified this specifies the text to be presented along the axis, instead of the bar id. See also rules for [[#Text Input|text input]]. The text may include one embedded link (see '''Note 1''').
;link (O) : Specify a web link (see '''Note 1''') (URL). The label along the axis will be shown as a blue clickable link.
'''Notes'''
#Either use attribute ''link'', or an embedded link in attribute ''text'', not both.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
BarData =
bar:Japan
bar:US text:"United States" # refer in PlotData to bar "US" but show "United States"
bar:China text:[[China]] # label China will be shown as blue clickable link to the English Wikipedia article about China
</pre></div>
The following lines produce the same output (only reference in [[#PlotData|PlotData]] changes):
<div style="background-color: #F0F0F0"><pre>
bar:US text:[[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
</pre></div>
----
===Colors===
This command allows colors to be defined and coupled to an id (identification tag).
Other commands will refer to colors with the id specified here.
This command expects one or more color definitions, each on a separate indented line.
;id :Other commands will use this id to specify text, bar or background colors.
;value : Actual color definition. Color values can be either be specified as:
;* predefined color constant, for which 32 predefined color names are recognized (see the Ploticus color page where all these constants are defined).
;* rgb (red,green,blue): specify 3 numbers between 0 (minimal) and 1 (maximal)
;* hsv (hue, saturation, value): specify 3 numbers between 0 and 1
;* gray (value): specify a number between 0 (black) and 1 (white)
;legend (O) : Specifies the text that should be displayed in the legend for this color. If this attribute is omitted no entry will appear in the legend at all. See [[#Text Input|Text Input]] for rules.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
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)
</pre></div>
----
===DateFormat===
This comand defines how dates, specified in other commands, should be
interpreted.
Valid dateformats are:
;dd/mm/yyyy : Dates are interpreted as day/month/year
: '''Note''': this format is only allowed for dates starting from 01/01/1800
;mm/dd/yyyy : Dates are interpreted as month/day/year
: '''Note''': this format is only allowed for dates starting from 01/01/1800
;yyyy : this deals with [[en:integer|integer]]s from -9999 to +9999
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
DateFormat = mm/dd/yyy
</pre></div>
----
===Define===
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).
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
Define $broad = width:30
Define $narrow = width:10
Define $bardefaults = $broad fontsize:S
</pre></div>
----
===DrawLines===
Some timelines extend over several clearly distinct periods.
A line demarcating these periods may serve as a visual aid.
Lines specified here will be drawn over the whole width/length of the chart
(depending on the orientation defined by [[#TimeAxis|TimeAxis]]).
;at : Specify the date/year where the line should be drawn, in compliance with the specified [[#DateFormat|DateFormat]].
;color : Specify the color in which the line should drawn.
:'''Note''': The color id specified should be defined first with command [[#Colors|Colors]].
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
LineData=
at:start color:red
at:end color:red
at:07/12/1941 color:red
</pre></div>
----
===ImageSize (mandatory)===
This command defines the overall size of the final image.
Specify values in [[#Measurements|absolute measurements]].
;width : Width of final image: maximum is 1600 pixels
;height : Height of final image: maximum is 1200 pixels
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
ImageSize = width:800 height:600
</pre></div>
----
===Legend===
A legend will only be shown when this command is present.
There are several ways to define the appearance and position of the legend. Some attributes are mutually exclusive (see below).
;orientation (O) : Specify hor[izontal] or ver[tical] (default).
:'''Restriction''': orientation = 'horizontal' and position = 'right' are mutually exclusive
;position (O) : 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 (O) : 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:<br/>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 (O) : Defines the distance between columns. You can specify an [[#Measurements|absolute distance]] or a relative distance (as percentage of the page width).
:'''Restriction''': this parameter is ignored when columns = 1 is defined or implied.
;left (O) : Defines the distance between the left side of the legend and the left side of the page. You can specify an absolute distance or a relative distance (as percentage of the page width).
;top (O) : Defines the distance between the top of the legend and the bottom of the page. You can specify an absolute distance or a relative distance (as percentage of the page height).
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
Legend = orientation:vertical position:bottom columns:3 columnwidth:140
Legend = orientation:horizontal position:bottom
Legend = left:100 top:120 columns:3
</pre></div>
----
===Period (mandatory)===
Defines the time period that will be displayed in the chart. Both parameters are mandatory. Specify dates in compliance with specified [[#DateFormat|DateFormat]].
;from : Timeline starts here. The specified value can be referenced as start in commands like [[#PlotData|PlotData]] and [[#TextData|TextData]].
;till : Time ends here. The specified value can be referenced as end in other commands.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
Period = from:01/09/1939 till:02/09/1945
</pre></div>
----
===PlotArea (mandatory)===
;width : Specify value in absolute or relative [[#Measurements|measurements]].
;height : Specify value in absolute or relative measurements.
;left : Margin between left side of image and left side of plot area. Specify value in absolute or relative measurements.
;bottom : Margin between bottom of image and bottom of plot area. Specify value in absolute or relative measurements.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
PlotArea = width:640 height:420 left:160 bottom:120
PlotArea = width:80% height:70% left:20% bottom:20%
</pre></div>
----
===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|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 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
====Positional attributes====
;at : Specifies at which date/year a text 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|DateFormat]] or specify ''start'' or ''end'' which refers to time frame defined by command [[#Period|Period]].
:'''NB''': This attribute can not be combined with attributes '''from''' or '''till'''.
;from : Specifies at which date/year a bar should start. Use date/year format as specified in [[#DateFormat|DateFormat]] or specify ''start'' which refers to time frame defined by command Period.
:'''NB''': This attribute should be used in combination with attribute '''till''' and can not be combined with attribute '''at'''.
;till : Specifies at which date/year a bar should end. Use date/year format as specified in DateFormat or specify ''end'' which refers to time frame defined by command Period.
:'''NB''': This attribute should be used in combination with attribute '''from''' and can not be combined with attribute '''at'''.
;shift : Specifies a horizontal and vertical displacement in absolute [[#Measurements|measurements]] for a text. This allows:
:*Texts to be shifted to avoid overlaps
:*Placement of text beside a bar, instead of on top of it.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
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"
</pre></div>
====Bar related attributes====
;bar : Specifies to which bar all other attributes apply.
:When command [[#BarData|BarData]] has not been used, bars will be drawn in the order in which they occur in any [[#PlotData|PlotData]] data block. The id specified here will also be the text presented along the axis, next to the bar.
: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|BarData]].
;color : Specifies the color is which the bar should be drawn.
:The color id specified should be defined first with command [[#Colors|Colors]].
;width : Specifies the width of the bar in absolute or relative [[#Measurements|measurements]].
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
BarData=
id:US text:United States
id: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
</pre></div>
Notes:
#this line establishes a default bar width for the remainder of the data block
#this line specifies a bar to be drawn and a text to placed on it at the same time
#bar US will be drawn before bar SB, even when specified after it, because command [[#BarData|BarData]] determines the sequence
#bar Midway will be rejected because it is not declared with command [[#BarData|BarData]]
#the last line will not result in a bar being plotted, it merely specifies on which bar the text should be placed
====Text attributes====
;text : Defines a text that should be plotted on or near a bar. The anchor position can be defined either explicitly with attribute at, or implicitly with attributes from and till. In the latter case the text will be positioned in the middle of the defined bar segment. See also [[#Text Input|Text Input]] for rules
:The text may include embedded links (see '''Notes 1 & 2''') for use in clickable maps.
;textcolor (O) : Defines the color of the text. The color id specified should be defined first with command [[#Colors|Colors]]. When not specified color black will be assumed.
;fontsize (O) : Specify a point size between 6 and 30, or (preferably) one of tags XS, S (default), M, L or XL. See [[#Font Support|Font Support]] for more details.
;align (O) : Specify center (default), left or right.
;link (O) : Specify a web link (see '''Note 1''') (URL) for use in clickable maps. The text will be shown as a blue clickable link.
'''Notes'''
#Either use attribute link, or an embedded link in attribute text, not both.
#On PNG images only one clickable link will be shown per text segment (text with line breaks (~) constitutes several segments).
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
PlotData=
bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:7/12 [[Pearl Harbour]]
</pre></div>
produces the same result as:
<div style="background-color: #F0F0F0"><pre>
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
</pre></div>
====Marker attribute====
;mark : Places a marker in a bar at the specified position. Specify as mark:(symbol, color). The only value for ''symbol'' supported to date is ''line''. The ''color'' id specified should be defined first with command [[#Colors|Colors]]. When not specified color black will be assumed.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
PlotData=
bar:test width:15 color:red
from:1900 till:2000
at:1990 mark:(line,white)
</pre></div>
will be shown as:
<timeline>
ImageSize = width:140 height:60
PlotArea = width:100 height:30 left:20 bottom:30
TimeAxis = orientation:horizontal
DateFormat = yyyy
Period = from:1900 till:2000
AlignBars = early
ScaleMajor = unit:year increment:50 start:1900
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
PlotData =
width:15 color:red
bar:test from:1900 till:2000
bar:test at:1990 mark:(line,white)
</timeline>
----
===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
'''Note''': the orientation of the lines and/or placement of the stubs depends
on the orientation of the [[#TimeAxis|TimeAxis]].
;gridcolor (O) : Defines the color for the grid lines. When this attribute is omitted no grid lines will be drawn.
:'''Note''': The color id specified should be defined first with command [[#Colors|Colors]].
;unit (O) : Specifies the unit by which the grid spacing is incremented. Specify day, month or year (default).
:'''Note''': When [[#DateFormat|DateFormat]] yyyy is specified, only unit year is allowed.
;increment (O) : Specifies the numbers of units by which the grid spacing is incremented. Default is 1.
;start (O) : Specifies where the first grid line and/or stub should be displayed. Defaults to start of defined [[#Period|Period]].
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
ScaleMajor = gridcolor:red start:1940
ScaleMajor = gridcolor:red unit:month increment:3 start:01/09/1939
</pre></div>
----
===ScaleMinor===
This command defines a further subdivision of the timescale. See ScaleMajor for syntax .
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
ScaleMajor = grid:red unit:year increment:1 start:01/01/1940
ScaleMinor = grid:blue unit:month increment:3 start:01/10/1939
</pre></div>
----
===TextData===
Used to define a text block that can be positioned anywhere on the chart.
;text : The actual text. See also [[#Text Input|Text Input]] for rules. The text may include embedded links (see '''Notes 1 & 2''').
;pos : Defines the top-left corner of the text block in absolute or relative [[#Measurements|measurements]]. Define as ''pos:(x,y)''.
;link (O) : Specify a web link (see '''Note 1''') (URL) for use in clickable maps. The label along the axis will be shown as a blue clickable link.
;textcolor (O) : Defines the color of the text. The color id specified should be defined first using [[#Colors|Colors]]. When not specified, the color is black.
;fontsize (O) : Specify a point size between 6 and 30, or (preferably) one of tags '''XS''', '''S''' (default), '''M''', '''L''' or '''XL''' (see [[#Font Support|Font Support]] for more details).
;tabs (O) : Defines position and alignment for tab character: '''^''' (caret). Specify multiple tab settings as tabs: (''x<sup>1</sup>-a<sup>1</sup>,x<sup>2</sup>-a<sup>2</sup>,x<sup>3</sup>-a<sup>3</sup>'', etc..) where
:*''x<sup>n</sup>'' is the horizontal displacement in absolute measurements from the left side of the text
:*''a<sup>n</sup>'' is the alignment for the text segment (specify ''center'', ''left'' or ''right'')
;lineheight (O) : 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''':
#Either use attribute ''link'', or an embedded link in attribute ''text'', not both.
#On PNG images only one clickable link will be shown per text segment (text with tabs (^) constitutes several segments). <!-- is this strictly relevant here? -->
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
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 [[Tripartite Pact]]
text:^10^1944^1-22/7^Bretton Woods 44 nations establish
text:^^^^^IMF and World Bank
</pre></div>
will be shown as:
<timeline>
ImageSize = width:400 height:70
PlotArea = width:400 height:70 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
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 [[Tripartite Pact]]
text:^10^1944^1-22/7^Bretton Woods 44 nations establish
text:^^^^^IMF and World Bank
</timeline>
----
===TimeAxis===
Defines the orientation of the time axis, and textual representation of stubs along that axis.
;format (O) : Specify in which format dates should be presented along the time axis.
:Currently only format yyyy (default) is supported. More formats may follow.
;orientation (O) : Specify hor[izontal] (default) or ver[tical].
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
TimeAxis = orientation:horizontal format:yyyy
</pre></div>
----
==Presets==
At the moment two presets are available:
*Preset = TimeVertical_OneBar_UnitYear
*Preset = TimeHorizontal_AutoPlaceBars_UnitYear
Not clear if whether there is documentation about them.
==Input rules==
===Scales for size and position===
'''Absolute measures''' may be used for specifying sizes, positions and position shifts, measured in pixels.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
PlotArea = width:800 height:600 left:50 bottom:50
</pre></div>
'''Relative measures''' may be used for specifying sizes and positions. Specify a number between 0 and 100, immediately followed by a %
(percentage) sign. For horizontal measurements the percentage is related to image width, for vertical measurements to image height.
The first coordinate is horizontal from left to right, the second is vertically upward.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
PlotArea = width:80% height:80% left:10% bottom:5%
</pre></div>
===Text Input===
Text input is subject to a few rules:
1 No unicode is allowed yet. See also [[#Font Support|font support]].
2 When text should contain spaces, either specify these by using underscores or place the text between double quotes.
:Exception: when the text attribute is the last attribute on a line, spaces are allowed (no confusion will arise where the text stops and the next attribute starts, that is—to be precise—when no colons occur in the text).
<small>Example: (the following are all equivalent)</small>
<div style="background-color: #F0F0F0"><pre>
BarData =
text:Japanese_mandate_since_1914 bar:Marshalls
BarData =
text:"Japanese mandate since 1914" bar:Marshalls
BarData =
bar:Marshalls text:Japanese mandate since 1914
</pre></div>
3 In data lines following command [[#TextData|TextData]] two characters have special meaning:
:'''~''' (tilde) means ''line break''
:'''^''' (caret) means ''tab''
<small>Example showing line breaks:</small>
<div style="background-color: #F0F0F0"><pre>
TextData =
.. text:Generated for Wikipedia~Version 1.1 - 2 Januari 2004
# will be shown as:
#
# Generated for Wikipedia
# Version 1.1 - 2 Januari 2004
</pre></div>
<small>Example showing tabs:</small>
<div style="background-color: #F0F0F0"><pre>
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
</pre></div>
----
==Clickable maps==
Both output formats available in MediaWiki, i.e. PNG and SVG, can contain clickable links. Texts shown in blue, and bars, may then be clicked, to surf to another web page.
Links can be specified with commands [[#BarData|BarData]], [[#PlotData|PlotData]] and [[#TextData|TextData]],
either with attribute ''link'', or as embedded links, via attribute ''text''.
===Embedded links===
Embedded links are links that are (part of a) displayable text, specified
with attribute ''text''. Their counterpart are explicit links (URL only)
which are defined with attribute ''link''.
Both type of links can be specified with commands [[#BarData|BarData]], [[#PlotData|PlotData]] and [[#TextData|TextData]] and are used for [[#clickable maps|clickable maps]].
In embedded links, internal link style is as usual, interwiki link style does not work, external link style is as usual with single brackets, but here with a pipe instead of a space. Blank spaces and underscores in the url should be written as %20.
Examples:
<div style="background-color: #F0F0F0"><pre>
<nowiki>text:example [[Help:Link]] internal link</nowiki>
</pre></div>
will be shown as:
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"example [[Help:Link]] internal link"
</timeline>
<div style="background-color: #F0F0F0"><pre>
<nowiki>text:[[Help:Link|Link]]</nowiki>
</pre></div>
will be shown as:
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[[Help:Link|Link]]"
</timeline>
<div style="background-color: #F0F0F0"><pre>
<nowiki>text:[http://en.wikipedia.org/wiki/Rembrandt|Rembrandt van Rijn] paints Night Watch</nowiki>
</pre></div>
will be shown as:
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[http://en.wikipedia.org/wiki/Rembrandt|Rembrandt van Rijn] paints Night Watch"
</timeline>
Attempt to use interwiki link style:
<div style="background-color: #F0F0F0"><pre>
<nowiki>text:[[en:Main_Page]]</nowiki>
</pre></div>
and similar with nl: and m: give:
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[[en:Main_Page]]"
</timeline>
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[[nl:Main_Page]]"
</timeline>
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[[m:Main_Page]]"
</timeline>
The third one to Meta-Wikipedia works properly, except from Meta itself, the other links work like [[Main_Page]] (internal page, the prefix is ignored) or e.g. {{SERVER}}/w/Main_Page (gives File not found), depending on the URL of the referring page (e.g. different for a preview page and a diff page).
----
==Font Support==
No unicode is allowed yet. No font type can be specified yet.
Five font tags are predefined which 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
<timeline>
ImageSize = width:130 height:90
PlotArea = width:130 height:90 left:0 bottom:0
TimeAxis = orientation:vertical #dummy
Colors =
id:gray value:gray(0.95)
Backgroundcolors = canvas:gray
Period = from:1 till:2 # dummy
TextData =
pos:(10,70) fontsize:XS text:"fontsize:XS"
pos:(10,58) fontsize:S text:"fontsize:S"
pos:(10,41) fontsize:M text:"fontsize:M"
pos:(10,25) fontsize:L text:"fontsize:L"
pos:(10,7) fontsize:XL text:"fontsize:XL"
</timeline>
This documentation is originally a wikified version of the [http://members.chello.nl/epzachte/Wikipedia/EasyTimeline/Syntax.htm original EasyTimeline documentation].
==EasyTimeline code with a template parameter is not allowed==
{{Template talk:Etl}}
{{hc}}
[[Category:Graphical Timelines]]
The EasyTimeline feature produces an embedded [[Help:Images and other uploaded files|image]] from wikitext. The image can be a one-dimensional diagram (horizontally or vertically), or a two-dimensional one. The name "EasyTimeline" refers to the possibility to apply the feature with a time scale horizontally or vertically, possibly with another parameter in the other direction, but there are also various other possiblities.
See also [[EasyTimeline]], [[Help:EasyTimeline examples]].
==Introduction==
Graphical timelines can be produced by providing a script between special tags:<br/>
<nowiki><timeline></nowiki><br/>
''script''<br/>
<nowiki></timeline></nowiki>
EasyTimeline will then be invoked to render a PNG image and (optionally) a clickable map.
'''Disclaimer''': Even when EasyTimeline is designed for ease of use, a complicated graphical timeline is a non-trivial affair.
A simple timeline may take half an hour to compose (or even less, when a suitable example is taken as a basis). Large timelines may take a few hours for composition and fine-tuning. However, adding to or correcting a timeline, no matter how complex, should be a relatively straightforward affair,
even for contributors who have no expert knowledge of the syntax described here.
Feel free to ask the [[user:Erik Zachte|author of EasyTimeline]] for advice.
==Available commands==
The script commands define:
*Overall layout: [[#ImageSize|ImageSize]], [[#PlotArea|PlotArea]], [[#Colors|Colors]], [[#BackgroundColors|BackgroundColors]], [[#AlignBars|AlignBars]]
*Interpretation and presentation of dates and periods: [[#DateFormat|DateFormat]], [[#Period|Period]], [[#ScaleMajor|ScaleMajor]], [[#ScaleMinor|ScaleMinor]], [[#TimeAxis|TimeAxis]]
*Events, periods and descriptive texts: [[#PlotData|PlotData]], [[#TextData|TextData]]
*How to order, divide, and name groups of events and periods: [[#BarData|BarData]], [[#Legend|Legend]], [[#DrawLines|DrawLines]]
*Shorthands for pieces of script code that occur multiple times: [[#Define|Define]]
The following commands are mandatory: [[#ImageSize|ImageSize]], [[#PlotArea|PlotArea]], [[#Period|Period]] and [[#TimeAxis|TimeAxis]]. At least one of the following commands is required: [[#PlotData|PlotData]] and/or [[#TextData|TextData]]. Either or both can occur multiple times. All other commands are optional.
'''Case''': Commands and their attributes can be specified in lower, upper or mixed case. Please try to be consistent in applying case as this will further readability, e.g. use mixed case for all commands and lowercase for all attributes.
----
==General syntax rules==
A script can contain commands and comments. Each command is followed by one or more attributes.
===Commands===
Commands should start on the first position of a line.
Some commands can be followed by multiple lines of data and/or options.
These extra lines should start with at least one space or be completely empty
(the latter is useful for visually grouping related data lines).
Commands have the one of the following forms, depending on the type of
command:
'''''Command = attribute(s)'''''
<div style="background-color: #F0F0F0"><pre>
DateFormat = dd/mm/yyyy
</pre></div>
'''''Command name = attribute(s)'''''
<div style="background-color: #F0F0F0"><pre>
Color Jp = value:red legend:Japan
</pre></div>
'''''Command =<br/> attribute(s)<br/> attribute(s)<br/> etc.'''''
<div style="background-color: #F0F0F0"><pre>
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
</pre></div>
===Comments===
Single and multi line comments can be specified:
* Text following the hash sign '''#''' will be regarded as a comment
* Text between '''#>''' and '''<#''' will also be regarded as a comment. Comments can span multiple lines, when tagged this way.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
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 <#
</pre></div>
===Attributes===
When several attributes can be specified for a certain command, they are
notated as 'name:value' pairs. When several values can be specified for
one attribute they have to be enclosed between parentheses.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
AlignBars = justify
Color SB = value:rgb(0.8,0,0.7) legend:Sea_Battles
</pre></div>
====Parameters vs data items====
Most commands only accept attributes that are specified on the same line.
'''Data blocks:''' some commands, like [[#BarData|BarData]], [[#PlotData|PlotData]], [[#TextData|TextData]], [[#Colors|Colors]] expect a ''data block'' consisting of one or more ''data lines''. Data lines should start with one or more spaces. A data block is considered complete when a line
starting with a non-space is encountered (exception: empty lines are
ignored, they may be used to group related data lines within a block).
Attributes in a data block can conceptually be divided into ''parameters'' and ''data items''. Data blocks can contain parameters and data items intermingled.
'''Data items:''' in data lines attributes ''text'', ''from'', ''till'' and ''at'' always apply only to the line in which they occur.
'''Parameters:''' in data lines attributes like ''color'' and ''fontsize'' have different implications depending on the context. If these parameters occur on a line without data items, they set new defaults for the data lines that follow. If they appear on a line mixed with data items they apply only to that line, thus overruling a default that was previously set.
<small>Example:</small>
<!-- all data start with space here to keep source formatting
but in actual usage commands should be at start of line -->
<div style="background-color: #F0F0F0"><pre>
# 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
</pre></div>
===Special characters===
*'''#''', '''#>''', '''<#''' (hash, hash+"greater than", "less than"+hash): see [[#Comments|Comments]]
*'''~''' (tilde) in texts means: line break
*'''^''' (caret) in texts means: tab
*'''_''' (underscore) in texts means: space
*'''$''' (dollar sign) precedes any user defined constant
----
==Command Reference==
For each command the valid attributes are listed. Some commands and/or
attributes are optional (O).
For some commands certain attributes are mutually exclusive (will be
explained where applicable).
===AlignBars===
Bars will always be drawn at equal distances.
This command specifies whether the bars should be spaced as much apart as possible, or some white
space should be reserved between the left/top side of the chart and the
first bar or between the last bar and the right/bottom side of the chart.
;early (default) : The first bar will be placed on the leftmost/topmost position of the chart ('glued' to the axis), leaving space between the last bar and right/bottom side of the chart.
;late : Opposite from ''early'': the last bar will be placed as far to the right/bottom side of the chart as possible, leaving space between the axis line (left/top side of chart) and the first bar.
;justify : The first and last bars will be placed as far apart as possible, leaving no empty space on either side of the chart. When only one bar is present, justify will be interpreted as "centered".
<small>Examples:</small>
{{EasyTimeline_Examples_AlignBars}}
----
===BackgroundColors===
This command allows the specifiction of background colors for various parts of the chart.
Any color ''id''s specified should be defined first using [[#Colors|Colors]].
;canvas (O) : Specify a background color for the whole image.
;bars (O) : Specify a background color for all bars.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
BackgroundColors = bars:darkgrey
BackgroundColors = canvas:lightgrey bars:darkgrey
BackgroundColors = canvas:lightgrey
</pre></div>
----
===BarData===
This is an optional command which if present determines which bars will be drawn on the chart and in which order.
If it is omitted then bars will be drawn in order of their appearance in command [[#PlotData|PlotData]].
For complex timelines with many bars, usage of this command is recommended:
*It will ease reordering of the displayed data.
*Bar names specified in [[#PlotData|PlotData]] can be validated against this list, thus preventing typing errors.
;bar : defines the bar id. Other commands (notably [[#PlotData|PlotData]]) will expect this id for reference. This will also be the label to be shown along the axis, unless attribute ''text'' is present. The bar id should not contain any spaces: use underscores instead, these will be converted to spaces, as wih article titles.
;text (O) : When specified this specifies the text to be presented along the axis, instead of the bar id. See also rules for [[#Text Input|text input]]. The text may include one embedded link (see '''Note 1''').
;link (O) : Specify a web link (see '''Note 1''') (URL). The label along the axis will be shown as a blue clickable link.
'''Notes'''
#Either use attribute ''link'', or an embedded link in attribute ''text'', not both.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
BarData =
bar:Japan
bar:US text:"United States" # refer in PlotData to bar "US" but show "United States"
bar:China text:[[China]] # label China will be shown as blue clickable link to the English Wikipedia article about China
</pre></div>
The following lines produce the same output (only reference in [[#PlotData|PlotData]] changes):
<div style="background-color: #F0F0F0"><pre>
bar:US text:[[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
</pre></div>
----
===Colors===
This command allows colors to be defined and coupled to an id (identification tag).
Other commands will refer to colors with the id specified here.
This command expects one or more color definitions, each on a separate indented line.
;id :Other commands will use this id to specify text, bar or background colors.
;value : Actual color definition. Color values can be either be specified as:
;* predefined color constant, for which 32 predefined color names are recognized (see the Ploticus color page where all these constants are defined).
;* rgb (red,green,blue): specify 3 numbers between 0 (minimal) and 1 (maximal)
;* hsv (hue, saturation, value): specify 3 numbers between 0 and 1
;* gray (value): specify a number between 0 (black) and 1 (white)
;legend (O) : Specifies the text that should be displayed in the legend for this color. If this attribute is omitted no entry will appear in the legend at all. See [[#Text Input|Text Input]] for rules.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
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)
</pre></div>
----
===DateFormat===
This comand defines how dates, specified in other commands, should be
interpreted.
Valid dateformats are:
;dd/mm/yyyy : Dates are interpreted as day/month/year
: '''Note''': this format is only allowed for dates starting from 01/01/1800
;mm/dd/yyyy : Dates are interpreted as month/day/year
: '''Note''': this format is only allowed for dates starting from 01/01/1800
;yyyy : this deals with [[en:integer|integer]]s from -9999 to +9999
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
DateFormat = mm/dd/yyy
</pre></div>
----
===Define===
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).
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
Define $broad = width:30
Define $narrow = width:10
Define $bardefaults = $broad fontsize:S
</pre></div>
----
===DrawLines===
Some timelines extend over several clearly distinct periods.
A line demarcating these periods may serve as a visual aid.
Lines specified here will be drawn over the whole width/length of the chart
(depending on the orientation defined by [[#TimeAxis|TimeAxis]]).
;at : Specify the date/year where the line should be drawn, in compliance with the specified [[#DateFormat|DateFormat]].
;color : Specify the color in which the line should drawn.
:'''Note''': The color id specified should be defined first with command [[#Colors|Colors]].
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
LineData=
at:start color:red
at:end color:red
at:07/12/1941 color:red
</pre></div>
----
===ImageSize (mandatory)===
This command defines the overall size of the final image.
Specify values in [[#Measurements|absolute measurements]].
;width : Width of final image: maximum is 1600 pixels
;height : Height of final image: maximum is 1200 pixels
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
ImageSize = width:800 height:600
</pre></div>
----
===Legend===
A legend will only be shown when this command is present.
There are several ways to define the appearance and position of the legend. Some attributes are mutually exclusive (see below).
;orientation (O) : Specify hor[izontal] or ver[tical] (default).
:'''Restriction''': orientation = 'horizontal' and position = 'right' are mutually exclusive
;position (O) : 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 (O) : 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:<br/>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 (O) : Defines the distance between columns. You can specify an [[#Measurements|absolute distance]] or a relative distance (as percentage of the page width).
:'''Restriction''': this parameter is ignored when columns = 1 is defined or implied.
;left (O) : Defines the distance between the left side of the legend and the left side of the page. You can specify an absolute distance or a relative distance (as percentage of the page width).
;top (O) : Defines the distance between the top of the legend and the bottom of the page. You can specify an absolute distance or a relative distance (as percentage of the page height).
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
Legend = orientation:vertical position:bottom columns:3 columnwidth:140
Legend = orientation:horizontal position:bottom
Legend = left:100 top:120 columns:3
</pre></div>
----
===Period (mandatory)===
Defines the time period that will be displayed in the chart. Both parameters are mandatory. Specify dates in compliance with specified [[#DateFormat|DateFormat]].
;from : Timeline starts here. The specified value can be referenced as start in commands like [[#PlotData|PlotData]] and [[#TextData|TextData]].
;till : Time ends here. The specified value can be referenced as end in other commands.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
Period = from:01/09/1939 till:02/09/1945
</pre></div>
----
===PlotArea (mandatory)===
;width : Specify value in absolute or relative [[#Measurements|measurements]].
;height : Specify value in absolute or relative measurements.
;left : Margin between left side of image and left side of plot area. Specify value in absolute or relative measurements.
;bottom : Margin between bottom of image and bottom of plot area. Specify value in absolute or relative measurements.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
PlotArea = width:640 height:420 left:160 bottom:120
PlotArea = width:80% height:70% left:20% bottom:20%
</pre></div>
----
===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|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 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
====Positional attributes====
;at : Specifies at which date/year a text 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|DateFormat]] or specify ''start'' or ''end'' which refers to time frame defined by command [[#Period|Period]].
:'''NB''': This attribute can not be combined with attributes '''from''' or '''till'''.
;from : Specifies at which date/year a bar should start. Use date/year format as specified in [[#DateFormat|DateFormat]] or specify ''start'' which refers to time frame defined by command Period.
:'''NB''': This attribute should be used in combination with attribute '''till''' and can not be combined with attribute '''at'''.
;till : Specifies at which date/year a bar should end. Use date/year format as specified in DateFormat or specify ''end'' which refers to time frame defined by command Period.
:'''NB''': This attribute should be used in combination with attribute '''from''' and can not be combined with attribute '''at'''.
;shift : Specifies a horizontal and vertical displacement in absolute [[#Measurements|measurements]] for a text. This allows:
:*Texts to be shifted to avoid overlaps
:*Placement of text beside a bar, instead of on top of it.
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
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"
</pre></div>
====Bar related attributes====
;bar : Specifies to which bar all other attributes apply.
:When command [[#BarData|BarData]] has not been used, bars will be drawn in the order in which they occur in any [[#PlotData|PlotData]] data block. The id specified here will also be the text presented along the axis, next to the bar.
: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|BarData]].
;color : Specifies the color is which the bar should be drawn.
:The color id specified should be defined first with command [[#Colors|Colors]].
;width : Specifies the width of the bar in absolute or relative [[#Measurements|measurements]].
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
BarData=
id:US text:United States
id: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
</pre></div>
Notes:
#this line establishes a default bar width for the remainder of the data block
#this line specifies a bar to be drawn and a text to placed on it at the same time
#bar US will be drawn before bar SB, even when specified after it, because command [[#BarData|BarData]] determines the sequence
#bar Midway will be rejected because it is not declared with command [[#BarData|BarData]]
#the last line will not result in a bar being plotted, it merely specifies on which bar the text should be placed
====Text attributes====
;text : Defines a text that should be plotted on or near a bar. The anchor position can be defined either explicitly with attribute at, or implicitly with attributes from and till. In the latter case the text will be positioned in the middle of the defined bar segment. See also [[#Text Input|Text Input]] for rules
:The text may include embedded links (see '''Notes 1 & 2''') for use in clickable maps.
;textcolor (O) : Defines the color of the text. The color id specified should be defined first with command [[#Colors|Colors]]. When not specified color black will be assumed.
;fontsize (O) : Specify a point size between 6 and 30, or (preferably) one of tags XS, S (default), M, L or XL. See [[#Font Support|Font Support]] for more details.
;align (O) : Specify center (default), left or right.
;link (O) : Specify a web link (see '''Note 1''') (URL) for use in clickable maps. The text will be shown as a blue clickable link.
'''Notes'''
#Either use attribute link, or an embedded link in attribute text, not both.
#On PNG images only one clickable link will be shown per text segment (text with line breaks (~) constitutes several segments).
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
PlotData=
bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:7/12 [[Pearl Harbour]]
</pre></div>
produces the same result as:
<div style="background-color: #F0F0F0"><pre>
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
</pre></div>
====Marker attribute====
;mark : Places a marker in a bar at the specified position. Specify as mark:(symbol, color). The only value for ''symbol'' supported to date is ''line''. The ''color'' id specified should be defined first with command [[#Colors|Colors]]. When not specified color black will be assumed.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
PlotData=
bar:test width:15 color:red
from:1900 till:2000
at:1990 mark:(line,white)
</pre></div>
will be shown as:
<timeline>
ImageSize = width:140 height:60
PlotArea = width:100 height:30 left:20 bottom:30
TimeAxis = orientation:horizontal
DateFormat = yyyy
Period = from:1900 till:2000
AlignBars = early
ScaleMajor = unit:year increment:50 start:1900
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
PlotData =
width:15 color:red
bar:test from:1900 till:2000
bar:test at:1990 mark:(line,white)
</timeline>
----
===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
'''Note''': the orientation of the lines and/or placement of the stubs depends
on the orientation of the [[#TimeAxis|TimeAxis]].
;gridcolor (O) : Defines the color for the grid lines. When this attribute is omitted no grid lines will be drawn.
:'''Note''': The color id specified should be defined first with command [[#Colors|Colors]].
;unit (O) : Specifies the unit by which the grid spacing is incremented. Specify day, month or year (default).
:'''Note''': When [[#DateFormat|DateFormat]] yyyy is specified, only unit year is allowed.
;increment (O) : Specifies the numbers of units by which the grid spacing is incremented. Default is 1.
;start (O) : Specifies where the first grid line and/or stub should be displayed. Defaults to start of defined [[#Period|Period]].
<small>Examples:</small>
<div style="background-color: #F0F0F0"><pre>
ScaleMajor = gridcolor:red start:1940
ScaleMajor = gridcolor:red unit:month increment:3 start:01/09/1939
</pre></div>
----
===ScaleMinor===
This command defines a further subdivision of the timescale. See ScaleMajor for syntax .
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
ScaleMajor = grid:red unit:year increment:1 start:01/01/1940
ScaleMinor = grid:blue unit:month increment:3 start:01/10/1939
</pre></div>
----
===TextData===
Used to define a text block that can be positioned anywhere on the chart.
;text : The actual text. See also [[#Text Input|Text Input]] for rules. The text may include embedded links (see '''Notes 1 & 2''').
;pos : Defines the top-left corner of the text block in absolute or relative [[#Measurements|measurements]]. Define as ''pos:(x,y)''.
;link (O) : Specify a web link (see '''Note 1''') (URL) for use in clickable maps. The label along the axis will be shown as a blue clickable link.
;textcolor (O) : Defines the color of the text. The color id specified should be defined first using [[#Colors|Colors]]. When not specified, the color is black.
;fontsize (O) : Specify a point size between 6 and 30, or (preferably) one of tags '''XS''', '''S''' (default), '''M''', '''L''' or '''XL''' (see [[#Font Support|Font Support]] for more details).
;tabs (O) : Defines position and alignment for tab character: '''^''' (caret). Specify multiple tab settings as tabs: (''x<sup>1</sup>-a<sup>1</sup>,x<sup>2</sup>-a<sup>2</sup>,x<sup>3</sup>-a<sup>3</sup>'', etc..) where
:*''x<sup>n</sup>'' is the horizontal displacement in absolute measurements from the left side of the text
:*''a<sup>n</sup>'' is the alignment for the text segment (specify ''center'', ''left'' or ''right'')
;lineheight (O) : 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''':
#Either use attribute ''link'', or an embedded link in attribute ''text'', not both.
#On PNG images only one clickable link will be shown per text segment (text with tabs (^) constitutes several segments). <!-- is this strictly relevant here? -->
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
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 [[Tripartite Pact]]
text:^10^1944^1-22/7^Bretton Woods 44 nations establish
text:^^^^^IMF and World Bank
</pre></div>
will be shown as:
<timeline>
ImageSize = width:400 height:70
PlotArea = width:400 height:70 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
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 [[Tripartite Pact]]
text:^10^1944^1-22/7^Bretton Woods 44 nations establish
text:^^^^^IMF and World Bank
</timeline>
----
===TimeAxis===
Defines the orientation of the time axis, and textual representation of stubs along that axis.
;format (O) : Specify in which format dates should be presented along the time axis.
:Currently only format yyyy (default) is supported. More formats may follow.
;orientation (O) : Specify hor[izontal] (default) or ver[tical].
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
TimeAxis = orientation:horizontal format:yyyy
</pre></div>
----
==Presets==
At the moment two presets are available:
*Preset = TimeVertical_OneBar_UnitYear
*Preset = TimeHorizontal_AutoPlaceBars_UnitYear
Not clear if whether there is documentation about them.
==Input rules==
===Scales for size and position===
'''Absolute measures''' may be used for specifying sizes, positions and position shifts, measured in pixels.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
PlotArea = width:800 height:600 left:50 bottom:50
</pre></div>
'''Relative measures''' may be used for specifying sizes and positions. Specify a number between 0 and 100, immediately followed by a %
(percentage) sign. For horizontal measurements the percentage is related to image width, for vertical measurements to image height.
The first coordinate is horizontal from left to right, the second is vertically upward.
<small>Example:</small>
<div style="background-color: #F0F0F0"><pre>
PlotArea = width:80% height:80% left:10% bottom:5%
</pre></div>
===Text Input===
Text input is subject to a few rules:
1 No unicode is allowed yet. See also [[#Font Support|font support]].
2 When text should contain spaces, either specify these by using underscores or place the text between double quotes.
:Exception: when the text attribute is the last attribute on a line, spaces are allowed (no confusion will arise where the text stops and the next attribute starts, that is—to be precise—when no colons occur in the text).
<small>Example: (the following are all equivalent)</small>
<div style="background-color: #F0F0F0"><pre>
BarData =
text:Japanese_mandate_since_1914 bar:Marshalls
BarData =
text:"Japanese mandate since 1914" bar:Marshalls
BarData =
bar:Marshalls text:Japanese mandate since 1914
</pre></div>
3 In data lines following command [[#TextData|TextData]] two characters have special meaning:
:'''~''' (tilde) means ''line break''
:'''^''' (caret) means ''tab''
<small>Example showing line breaks:</small>
<div style="background-color: #F0F0F0"><pre>
TextData =
.. text:Generated for Wikipedia~Version 1.1 - 2 Januari 2004
# will be shown as:
#
# Generated for Wikipedia
# Version 1.1 - 2 Januari 2004
</pre></div>
<small>Example showing tabs:</small>
<div style="background-color: #F0F0F0"><pre>
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
</pre></div>
----
==Clickable maps==
Both output formats available in MediaWiki, i.e. PNG and SVG, can contain clickable links. Texts shown in blue, and bars, may then be clicked, to surf to another web page.
Links can be specified with commands [[#BarData|BarData]], [[#PlotData|PlotData]] and [[#TextData|TextData]],
either with attribute ''link'', or as embedded links, via attribute ''text''.
===Embedded links===
Embedded links are links that are (part of a) displayable text, specified
with attribute ''text''. Their counterpart are explicit links (URL only)
which are defined with attribute ''link''.
Both type of links can be specified with commands [[#BarData|BarData]], [[#PlotData|PlotData]] and [[#TextData|TextData]] and are used for [[#clickable maps|clickable maps]].
In embedded links, internal link style is as usual, interwiki link style does not work, external link style is as usual with single brackets, but here with a pipe instead of a space. Blank spaces and underscores in the url should be written as %20.
Examples:
<div style="background-color: #F0F0F0"><pre>
<nowiki>text:example [[Help:Link]] internal link</nowiki>
</pre></div>
will be shown as:
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"example [[Help:Link]] internal link"
</timeline>
<div style="background-color: #F0F0F0"><pre>
<nowiki>text:[[Help:Link|Link]]</nowiki>
</pre></div>
will be shown as:
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[[Help:Link|Link]]"
</timeline>
<div style="background-color: #F0F0F0"><pre>
<nowiki>text:[http://en.wikipedia.org/wiki/Rembrandt|Rembrandt van Rijn] paints Night Watch</nowiki>
</pre></div>
will be shown as:
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[http://en.wikipedia.org/wiki/Rembrandt|Rembrandt van Rijn] paints Night Watch"
</timeline>
Attempt to use interwiki link style:
<div style="background-color: #F0F0F0"><pre>
<nowiki>text:[[en:Main_Page]]</nowiki>
</pre></div>
and similar with nl: and m: give:
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[[en:Main_Page]]"
</timeline>
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[[nl:Main_Page]]"
</timeline>
<timeline>
ImageSize = width:380 height:25
PlotArea = width:380 height:25 left:0 bottom:0
TimeAxis = orientation:vertical # dummy, required
Period = from:0 till:1 # dummy, required
Colors =
id:canvas value:rgb(1,1,0.85)
BackgroundColors = canvas:canvas
TextData =
pos:(10,10) fontsize:XL text:"[[m:Main_Page]]"
</timeline>
The third one to Meta-Wikipedia works properly, except from Meta itself, the other links work like [[Main_Page]] (internal page, the prefix is ignored) or e.g. {{SERVER}}/w/Main_Page (gives File not found), depending on the URL of the referring page (e.g. different for a preview page and a diff page).
----
==Font Support==
No unicode is allowed yet. No font type can be specified yet.
Five font tags are predefined which 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
<timeline>
ImageSize = width:130 height:90
PlotArea = width:130 height:90 left:0 bottom:0
TimeAxis = orientation:vertical #dummy
Colors =
id:gray value:gray(0.95)
Backgroundcolors = canvas:gray
Period = from:1 till:2 # dummy
TextData =
pos:(10,70) fontsize:XS text:"fontsize:XS"
pos:(10,58) fontsize:S text:"fontsize:S"
pos:(10,41) fontsize:M text:"fontsize:M"
pos:(10,25) fontsize:L text:"fontsize:L"
pos:(10,7) fontsize:XL text:"fontsize:XL"
</timeline>
This documentation is originally a wikified version of the [http://members.chello.nl/epzachte/Wikipedia/EasyTimeline/Syntax.htm original EasyTimeline documentation].
==EasyTimeline code with a template parameter is not allowed==
{{Template talk:Etl}}
{{hc}}
[[Category:Graphical Timelines]]
