Timeline JS (original) (raw)
If you just want to dive in, you can probably copy from one of our examples (like the one about Whitney Houston). Otherwise, complete documentation is below.
After you have worked out how to create JSON data for a Timeline, you'll also need to put it on the page.
The TimelineJS JSON format consists of a single JSON object with the following properties:
events
Yes
A JSON list of "slide" objects (see below)
title
No
A "slide" object (see below)
eras
No
A JSON list of "era" objects (see below)
scale
No
Either human or cosmological. If no scale is specified, the default is human. The cosmological scale is required to handle dates in the very distant past or future. (Before Tuesday, April 20th, 271,821 BCE after Saturday, September 13 275,760 CE) For the cosmological scale, only the year is considered, but it's OK to have a cosmological timeline with years between 271,821 BCE and 275,760 CE.
Slide objects are JSON objects with the following properties:
start_date
Yes, except for title slides
A "date" object (see below)
end_date
No
A "date" object (see below)
text
No, but recommended
A "text" object (see below)
media
No
A "media" object (see below)
group
No
Any text. If present, Timeline will organize events with the same value for group to be in the same row or adjacent rows, separate from events in other groups. The common value for the group will be shown as a label at the left edge of the navigation.
display_date
No
A string which will be used when Timeline displays the date for this. If used, override's display_date values set on the start or end date for this event, which is useful if you want to control how the two dates relate to each other.
background
No
A Javascript object. The object can have these properties:url: the fully-qualified URL pointing to an image which will be used as the backgroundalt: alternative text that describes the image provided by the url propertycolor: a CSS color, in hexadecimal (e.g. #0f9bd1) or a valid CSS color keyword.
autolink
No
A boolean value (true or false). Defaults to true, which means that Timeline will scan text fields and automatically add<a> tags so that links and email addresses are "clickable." If set to false, you may still manually apply the tags in the appropriate fields when you want links. Autolinking applies to the text field in a [text](#json-text) object and the caption and credit fields in a [media](#json-media) object.
unique_id
No
A string value which is unique among all slides in your timeline. If not specified, TimelineJS will construct an ID based on the headline, but if you later edit your headline, the ID will change. Unique IDs are used when the [hash_bookmark](/docs/options.html#hash%5Fbookmark) option is used, and can also be used with the timeline.goToId() method to programmatically move the timeline to a specific slide.
Era objects are JSON objects which are used to label a span of time on the timeline navigation component. In structure, they are essentially very restricted "slide" objects.
start_date
Yes
A "date" object (see below)
end_date
Yes
A "date" object (see below)
text
No, but recommended
A "text" object (see below)
Date objects are JSON objects with the following properties:
year
Yes
A number. Don't use commas. BCE years should be negative numbers. Don't use the letters "BC", "BCE" or any others.
month
No
A number from 1-12 (Javascript experts don't outsmart yourselves: Timeline corrects for Javascript's strange use of "0" for "January", etc.)
day
No
A number
hour
No
A number from 0-23
minute
No
A number from 0-59
second
No
A number from 0-59
millisecond
No
A number
display_date
No
A string for presenting the date. This value will be presented exactly as specified, overriding TimelineJS's default date formatting. Note that the year property, at a minimum, must still be provided so that TimelineJS can properly position the event on the actual timeline.
format
No
A formatting string which will be used to render the date parts, if you wish to override TimelineJS's default formatting. Note that in general you can achieve the same with display_date (above), without needing to master the complexity of the date format strings.
Text objects are JSON objects with the following properties. For each slide, text objects are optional.
headline
No
Any text. HTML markup is OK. Blank is also OK.
text
No
Any text. HTML markup is OK. Blank is OK. Not used for era objects.
Media objects are JSON objects with the following properties. For each slide, media objects are optional.
url
Yes
caption
No
Any text. HTML markup is OK.
credit
No
Any text. HTML markup is OK.
thumbnail
No
A URL for an image to use in the timenav marker for this event. If omitted, Timeline will use an icon based on the type of media. Not relevant for title slides, because they do not have a marker.
alt
No
An alt tag for your image. If none is provided, the caption, if any, will be used.
title
No
A title for your image. If none is provided, the caption, if any, will be used.
link
No
Optional URL to use as the href for wrapping the media with an tag.
link_target
No
Optional target to be associated with link if used.