Another Big TimelineJS Update That You Shouldn’t Even Notice

But we wanted to warn you ahead of time

There’s another big but invisible change coming to TimelineJS.

In July, we announced a big update to TimelineJS on the day of the release. With some minor exceptions, we were right that most people didn’t notice.

Next week, we’ll be making another big update, which, again, we hope you won’t notice. This time, we thought we should announce it ahead of time, because timelines created before January, 2015 will probably stop working unless steps are taken. Timelines which are published through non-standard methods may stop working. We’re pretty sure that most people’s timelines will work, but we want to give people time to check and prepare. We plan to make these updates on the morning (Chicago time) of September 23rd. We’ll send a tweet from @KnightLab when they’re done.

The root issue is a change to how Google makes Sheets data available. This change goes into effect on September 30th, 2020June 8, 2021. Timelines created before January, 2015 are not set up to “pick up” the updates we’re releasing. Relatedly, timelines running off of a copy of our code, instead of the “official” source, won’t pick up the changes. This includes users of the TimelineJS plugin for Wordpress, which includes a copy of the TimelineJS code in the plugin.

Google has delayed the shutdown date again, now to June 8, 2021. We have already deployed the changes described in this post, so most TimelineJS users are already seeing them. However, timelines created before January, 2015 should continue to work without any changes until this new date.

Am I affected by this change?

Detail of the lower-left corner of a current timeline. (The logo only turns orange if you move your mouse cursor over it.) If your timeline doesn't have the logo/Timeline JS in this area, it will stop working on September 30th, 2020June 8, 2021.

You can recognize timelines made with the newer version of TimelineJS by the Knight Lab logo and “Timeline JS” in the bottom. (The logo only turns orange if you move your mouse cursor over it.) Timelines based on Google Sheets which don’t have this will definitely stop working on September 30th, 2020June 8, 2021, when Google’s change becomes effective.

For timelines which have the logo, you are probably fine. If you want to make sure, look at the embed code you use to put them on your site. If the code has https://cdn.knightlab.com/libs/timeline3/latest/embed/index.html… (specifically timeline3/latest) then you’ll pick up our changes. Otherwise, you are probably using an older version of the TimelineJS code, and will need to update your timelines.

In general, updating those pre-2015 timelines is easy: the newer version of TimelineJS uses a new spreadsheet format, but reads the old format as well, so you should simply be able to paste the Google Sheets URL into the “Google Spreadsheet URL” field in step 3 of the Timeline authoring tool. Of course, you should also set any font and language choices, as appropriate. Then, use the updated embed code to replace the current TimelineJS embed code on your website.  (You may even be able to just change timeline/latest to timeline3/latest in your embed code!) You can do this at any time between now and when Google turns off the legacy Sheets data API on September 30th, 2020June 8, 2021.

TimelineJS WordPress plugin users

If you use the TimelineJS WordPress plugin, you will need to update it using WordPress’s standard update mechanism before September 30th, 2020June 8, 2021. Again, this update is scheduled to go live on September 23rd. The plugin will be version 3.8.0.0 (or higher). You may also need to modify existing timelines on your WordPress site.

In 2015, when we updated the WordPress plugin to work with the new version of TimelineJS, we set it to create new timelines using the new code, but we chose not to automatically change existing timelines to use the new code.

As part of this update, we are changing the default behavior of the WordPress plugin to use the new TimelineJS code. For almost all users with very old timelines, this should simply work. However, there is a slight chance that old timelines will look a little different, so we recommend checking them out. If you want to test them before we change the TimelineJS WordPress plugin on September 23rd, you can edit the shortcode which embeds your timeline. Just add version="timeline3" right after the opening part of the shortcode, resulting in something which looks a little like this:

[timeline version="timeline3" src="https://docs.google.com/spreadsheets/..."]

This will tell the plugin to use the newer version of TimelineJS to show your timeline, and it will probably “just work,” but you should double-check it. You can do this at any time, and if you don’t do anything, it will effectively happen when you update to version 3.8.0.0 or higher of the TimelineJS WordPress plugin.

Also, if there happen to be any TimelineJS/WordPress users who are using JSON to configure their timelines AND are using the old version of TimelineJS, this change to the default behavior will cause their timelines to stop working. The easiest fix will be to go in to posts using the older version of timeline with a JSON file, and add version="timeline2" to the shortcode, getting something that looks like this:

[timeline version="timeline2" src="/timeline2.json"]

The new version information can go anywhere in the shortcode after the beginning [timeline…] part. You must do this before you update to version 3.8.0.0 or newer of the TimelineJS WordPress plugin. Generally, we’d recommend updating to use TimelineJS3, but that will require changing your JSON file to use the TimelineJS3 JSON format. If you choose to do that before you update to version 3.8.0.0 of the plugin, be sure to add  version="timeline3" to your shortcode.

Need Help?

We’re trying very hard to make this change seamless. Hopefully you don’t need to do anything, or you can use the above to do what needs to be done. However, if you get into a jam, you can submit a support request. Please be sure to include links to your Google Sheets data and the page on your website where the problem is happening.

This also affects StorylineJS

The changes that Google is making also affect StorylineJS. Since StorylineJS is newer and has a smaller community, we don’t expect as many unusual circumstances, so we are planning on releasing the update to StorylineJS on Monday, September 21. If you see something strange happening with your storyline after that date, submit a support request and let us know what is happening. As with TimelineJS, please be sure to include links to your Google Sheets data and the page on your website where the problem is happening.

About the author

Joe Germuska

Chief Nerd

Joe runs Knight Lab’s technology, professional staff and student fellows. Before joining us, Joe was on the Chicago Tribune News Apps team. He's the project lead for CensusReporter.org and a board member of City Bureau.

Latest Posts

Storytelling Tools

We build easy-to-use tools that can help you tell better stories.

View More