Building a TimelineJS Feature

Knight Lab’s TimelineJS is a popular open source tool to create interactive timelines based on spreadsheet data. CollectionBuilder can use your collection metadata to generate JSON for TimelineJS, making it easy to add the feature integrated directly to your site.

The default CollectionBuilder TimelineJS feature will create a timeline based on your entire collection metadata, but can be edited to only show items you’ve curated. Below you’ll find instructions split into two steps: Step 1 shows how to add TimelineJS to your site, while Step 2 has instructions on how to edit the content of your TimelineJS instance after it’s been added.

Step 1: Including TimelineJS on a Page

There are three basic options for including a TimelineJS feature in your CollectionBuilder site. They are:

Insert the TimelineJS feature into the Home Page;
replace the current timeline page with a TimelineJS page; or
create a new TimelineJS page.

The instructions below detail each of these options.

Inserting TimelineJS Into the Home Page

Open the “home-infographic.html” file in the “_layouts” directory.
You may want to edit the column sizes or arrangement of the “home-infographic.html” file (follow the instructions in the Home Page documentation to rearrange the Home page layout). The TimelineJS feature will work decently in a smaller section, but it looks best in a wider format (for example, consider replacing the carousel with TimelineJS).
Add the following code to the section of the “home-infographic.html” file in which you’d like the feature to appear:
```
{% include feature/timelinejs.html %}
```
Save the file.

Replacing the Current Timeline Page

Navigate to the “pages” directory, and open the “timeline.md” file.
Locate the yaml front matter at the top of the file (the front matter is the key: value pairs between two lines of dashes (---)).
Edit the value for “layout” to look like this:
```
layout: page-full-width
```
Locate the ## Collection Timeline line of text, below the yaml front matter.
Replace ## Collection Timeline with the following _include command:
```
{% include feature/timelinejs.html %}
```
Save the file.

Navigate to the “pages” directory, and open the “timeline.md” file.
Copy the contents of “timeline.md”.
Create a new markdown file in the “pages” directory called “timelinejs.md”.
Paste the contents copied from “timeline.md” into “timelinejs.md”.
Locate the yaml front matter at the top of the file (the front matter is the key: value pairs between two lines of dashes (---)).
Edit the front matter to look like this:
```
title: TimelineJS
layout: page-full-width
permalink: /timelinejs.html
```
Note that the title and permalink values don’t have to be TimelineJS and timelinejs.html; you can call them whatever you want. They just need to be anything other than Timeline and /timeline.html (since those are used for the collection’s built-in timeline page). Just make sure to include the title and permalink you create in your “_data/config-nav.csv” file, as described below.
Locate the ## Collection Timeline line of text, below the yaml front matter.
Replace ## Collection Timeline with the following _include command:
```
{% include feature/timelinejs.html %}
```
Save the file.
Navigate to the “_data” directory, and open the “config-nav.csv” file.
Edit the “config-nav.csv” file so that it includes the following three rows:
```
Timelines,,
Full Timeline,/timeline.html,Timelines
TimelineJS,/timelinejs.html,Timelines
```
This will create a dropdown menu that links to both timeline pages (the CollectionBuilder timeline and TimelineJS).

Step 2: Curating Your TimelineJS Feature

Using the methods above, you’ve incorporated a TimelineJS feature on your site that uses the entire collection metadata file by default. This will likely be too large for the timeline to work well. Below we detail ways to further customize and curate your timeline.

Note that the following instructions assume that you’ve already added the TimelineJS feature to your site using the instructions in Step 1 above.

Limiting the Items Included

Navigate to the “/assets/data/” directory, and open the “timelinejs.json” file.
You will need to edit the first line of code (below the front matter) so that it limits the collection:
- limit the timeline to only include those items that are images:
```
{%- assign items = site.data[site.metadata] | where_exp: 'item','item.format contains "image"' -%}
```
- limit the timeline to only include those items that occur during a certain year:
```
{%- assign items = site.data[site.metadata] | where_exp: 'item','item.date contains "1935"' -%}
```
There are other ways to limit the timeline as well. See below for limiting it through the creation of a curated spreadsheet.

Creating a New Data Spreadsheet (With New TimelineJS Headlines)

This method will use a new CSV to create a curated timeline by only listing those items that contain information in a newly created field (“headline”).

Make a copy of your current metadata file using a spreadsheet software application like Google Sheets.
Add a column called “headline” right before the “title” column.
Add new headline values to those items you’d like included on a timeline (or simply copy and paste the current title into the new cell).
Save the file as a CSV and rename it “timelinejs.csv”.
Add this CSV to your “_data” directory.
Navigate to the “/assets/data/” directory, and open the “timelinejs.json” file.

Edit the first line so that it reads:

{%- assign items = site.data.timelinejs | where_exp: "item","item.headline" -%}

This will generate a timeline that only includes items that have a headline.

CollectionBuilder