[9/15/14: REPAIRED!  This tutorial was broken because a file used (tabletop.js) needed to be updated to the newest version.  It works now.  Enjoy! — LW]

Gay marriage became legal today in Rhode Island, making marriage equality the law of the land in all of New England.

The Providence Journal published a detailed timeline of GLBT history in the state — but it’s text-only.  On this happy day, what could we do to spiff things up a little?  I decided to give the Projo’s timeline a little celebratory finery by creating a vertical, interactive timeline using Timeline.js.  Check it out.

Now I will show you how to do it!

Timeline, like Tabletop.js, is a creation of Balance Media and the brainchild of WNYC’s John Keefe (here’s John talking about the thinking behind the vertical timeline).  In print, most of us are used to seeing timelines presented horizontally, but that’s probably not an ideal format for the up-and-down scrolling that web browsers encourage.

Putting together a Timeline.js timeline is easy — I was able to do it on my first try in under an hour.  Let me show you how:

1. Download Timeline.js from Github.   (Remember, you can view any image on this blog full size by clicking on it.  I leave helpful annotations on the images, so if you can’t read ’em, click ’em!)



2. Unzip Timeline-Master.zip.  Inside you will find three files: css, img, and js, and a number of assorted files.



3. Open index.html in a browser. If you click on index.html to open it in a browser, you will see an example timeline. The data displayed on a Timeline.js timeline is kept in a Google spreadsheet.  Here’s the example spreadsheet that index.html is linked to:



4. Make a new Google Docs/Drive spreadsheet. You will need your own Google spreadsheet for your timeline.  Log into Google Docs/Drive and create a new spreadsheet.



5. Grab the right format for your spreadsheet. Your spreadsheet has to be formatted in a particular way for Timeline.js to work.  Visit this Google Spreadsheet template.  Select and copy the first three rows, and paste them into your blank spreadsheet.



6. Find the formula that formats the dates for your timeline. Notice column C.  Click on “Oct 27” and look in the formula bar:



Column C has a formula in it — it takes what you put in column B — dates like “October 27, 2011” and turns them into “Oct 27,” which is the format that Timeline wants.

7. Get rid of the extra row. Delete row 2 — the row with the instructions in them.  We don’t need it now, and Timeline won’t work if we leave it the way it is.



8. Start building your spreadsheet.  putting your own data into the form.  If you want, you can cut and paste the data I used to make the GLBT history timeline above.  You’ll notice that column C isn’t translating your month/date/year dates into Mon-date format.  You have to copy the formula into those blank cells in column C to make it work.

First, find the cell in column C that is translating your month/date/year date into a Mon-date format and copy it by pressing Command-C (Mac, the cloverleaf key to the left of the spacebar) or Ctrl-C (Windows).

Here’s the data in Excel format: GLBTMarriageEqualityTimeline

Screen Shot 2013-05-07 at 11.25.00 AM


Next, paste the formula into one of the empty cells in column C.



Once you’ve pasted the formula into the empty cell, you’ll notice that the formula now takes the Month, Date, Year data from the cell in Column B to the left and puts it into the Mon-Date formula that Timeline is looking for:



You can paste the formula into more than one cell at a time by selecting several cells and pasting the formula into it.  Or you can do it one by one at first.  I often like to do things slowly and manually the first time around even if it’s repetitive — I feel like I “get it” better, and I tend to remember it better when I’m done.

Next, change the name of the sheet in your spreadsheet to “Posts.”  That’s what Timeline.js expects it to be named.   Note!  We are NOT talking about the name of your spreadsheet, but the name of the individual worksheet WITHIN your spreadsheet file.  Individual worksheets are denoted by tabs at the bottom of the spreadsheet.  Check out the screenshot below — notice the tab at the bottom?  That’s what I’m talking about.  That tab should read “posts.”  If you just opened a fresh spreadsheet and pasted data in and didn’t change it, it probably still says “Sheet1,” which is the default.  Here’s how you change the name to “posts,” which you have to do for this to work:


9. Make your spreadsheet public and publish it. Make your document public and publish it to the web.  First, click Share in the upper right.



Make your spreadsheet public.




Just making your spreadsheet public isn’t enough, however.  You have to publish it to the web.  Click File >> Publish To The Web.  You’ll see this:




Click “Start Publishing.”  Once you do, you will get a public URL for your spreadsheet.  Copy it.


10. Let Timeline.js know where your data is.  In your Timeline Master folder, you will find a folder named “js.”  Inside that, you’ll find a file called script.js.  Open that with a programmer’s text editor.  (If you don’t know what a programmer’s editor is, see this Journalist’s Learn-to-Code Resource Guide and scroll down to “Text Editors.”  There are suggestions for good free ones for all platforms.  You do need one, so download that stat, k?)



The key is a portion of the public URL of your spreadsheet.  For this URL:



the key is the portion between key= and the ampersand (&) 0– that is:


Take the public URL from your spreadsheet, copy the key, and paste it on line 3 to replace the one that’s there now.  Be sure not to disturb the single quote marks on either side.

11. Check out your timeline. Open up your timeline in a browser — go to your Timeline-master file and click on “index.html.”  (If this doesn’t automatically open the file in a web browser, open a web browser, click File >> Open and open the file that way).  You will see a timeline!



12. Change the title.  You may notice that the title and header of the timeline are not what you want them to be.  Let’s change that.

Open index.html in a programmer’s editor.   On or around line 21, you’ll see some text wrapped in <H1> tags.  That’s the title.  It will look like this:


Change it to whatever you want.  Write some lines below if you wish.  Save the file and reload index.html in your web browser.  Voila!  The title has changed.

13.  Mess with it. Try changing some data in your spreadsheet and then reloading the page to see what happens.  Add the URL of an image to the photo_url column or something. Like this one:





I know, right?!  I can’t even.

14.  Enjoy being a badass.  *fistbump*


But wait!  How do I get it on the Internet?!  Well, you need server space — but once you have it, you put up the same files — preserving the order of the folders!  — on your server?  Boom.  You got this.

If you liked this, you’ll probably like The Insanely Illustrated Guide To Your First Data-Driven TileMill Map. And here’s a Github repository with the code for this tutorial, if that’s how you roll.


Category : Uncategorized

21 thoughts on “The Absurdly Illustrated Guide To Your First Dynamic, Data Driven Timeline

    Timeline everything!

  2. lisawilliams says:

    Indeed. All the things that can’t be timelined should be mapped and all the stuff that can’t be mapped should be graphed. The revolution will be scatterplotted 🙂

  3. Andrew Duffy says:

    Great tutorial. To avoid confusion, international readers should remember that they have to work with dates formatted the US way.

    In Australia we naturally write Oct 26 2011 as 26/10/11 not 10/26/11. Obviously, the formula doesn’t work if you forget to work to the US-format.

    1. lisawilliams says:

      Andrew — excellent catch! Thank you for the helpful note on date formats for Timeline.js.

Leave a Reply

Your email address will not be published. Required fields are marked *