{% extends "base.html" %} {% block content %}

## TimelineJS JSON data format

Every timeline needs data about the events it is to show. Most people are happy to just use a Google spreadsheet to configure their Timeline, but if you want to write code to dynamically create or update your timeline, you'll need to understand how to format the data.

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:

Name
Required?
Notes
`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:

Name
Required?
Notes
`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 background
`alt`: alternative text that describes the image provided by the `url` property
`color`: 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` object and the `caption` and `credit` fields in a `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` 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.

Name
Required?
Notes
`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:

Name
Required?
Notes
`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.

Name
Required?
Notes
`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.

Name
Required?
Notes
`url`
Yes
In most cases, a URL (see media type documentation for complete details).
`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 <a> tag.
`link_target`
No
Optional target to be associated with link if used.
{% endblock %} {% block scripts %}
{% endblock %}