Help:EasyTimeline syntax

The EasyTimeline feature produces an embedded 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 possibilities.

Graphical timelines can be produced by providing a script between special tags:
<timeline>script
</timeline>

EasyTimeline will then be invoked to render a PNG image and (optionally) a clickable map.

Disclaimer: Even though 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.

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.

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 one of the following forms, depending on the type of command:

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.

Most commands only accept attributes that are specified on the same line.

Data blocks: some commands, like BarData, PlotData, TextData, 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.

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".

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.

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 can be validated against this list, thus preventing typing errors.

bar

defines the bar id. Other commands (notably 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 with 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. 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.

Examples:

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

The following lines produce the same output (only reference in PlotData changes):

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).

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 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 List of popes (graphical)). In short it is a good idea most of the time.

barincrement

Amount in pixels that should be added to the image size for each bar specified (mandatory and only allowed in combination with width:auto or height:auto).

Specify value in absolute or relative measurements. (do not use anymore, see below)

height

Specify value in absolute or relative measurements. (do not use anymore, see below)

left

Margin between left side of image and left side of plot area. Specify value in absolute or relative measurements.

top

Margin between top of image and top of plot area. Specify value in absolute or relative measurements.

right

Margin between right side of image and right 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.

width/height attributes

These 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. Now you can specify all four margins, and are advised to do so, and not use width and height attributes anymore. 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).

Example:

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

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 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:

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 or specify start or end which refers to time frame defined by command Period.

NB: This attribute cannot 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 or specify start which refers to time frame defined by command Period.

NB: This attribute should be used in combination with attribute till and cannot 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 cannot be combined with attribute at.

shift

Specifies a horizontal and vertical displacement in absolute measurements for a text. This allows:

When command BarData has not been used, bars will be drawn in the order in which they occur in any 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.

barset

Restarts the bar display "from the top", allowing multiple bars on the same line. Syntax: barset:name
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.

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. When not specified color black will be assumed.

Absolute measures may be used for specifying sizes, positions and position shifts, measured in pixels.

Example:

PlotArea = width:800 height:600 left:50 bottom:50

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.

1 Only a subset of unicode is allowed for font rendering, but unicode in links should work for all characters. See also 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).

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. //en.wikipedia.org/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).

Special characters:

Blank spaces and underscores in the url should be written as %20.

The tilde character (~) is normally interpreted as line break. When a tilde is part of an url write it as is two tildes.
For example, link to www.site.com/~mysite as:

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

The number sign (#) is normally interpreted as start of comment. When a number sign is part of an url make sure the text is embedded in double quotes as follows:

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

Actually it may be a good idea to always put texts between double quotes.

Timeline has somewhat limited unicode support. It uses FreeSans.ttf font, which supports a subset of all the possible glyphs (it supports Cyrillic alphabet, east-Europe diactrics and kana for instance, but lacks kanji). No other fonts are available at this time.

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