The timeline is a very useful way to visualize sequences of events, and they’re especially useful to orient readers within the complex investigative stories we do at ProPublica. But they’re not very easy to make. As far as we know, there are no good open source frameworks that web developers can use to generate timelines quickly without losing design flexibility. So we made our own, which is debuting today.
By way of background, our most recent timeline was part of our story on disability discharges last month. We found some interesting parallels between what the Education Department was doing to reform the program and one borrower’s attempt to navigate the bureaucracy over the same five-year period. To visualize these parallel paths, we designed a timeline that showed both series events on one bar, but differentiated by color and space.
The timeline we created isn’t ideal; it was coded by hand so the space between events is not to scale, and impressionistic at best. There’s some cool code that automatically stacks cards on top of each other, but we ended up scrapping a few events just to avoid too many cards piling on top of each other.
Worst of all, the amount of labor that was required to put it together was, as you might imagine, big enough to discourage doing very many timelines like it. So we sought a better, more scalable way to accurately display timelines.
What we came up with is a tool called TimelineSetter. It takes a spreadsheet of events – or even many series of events — and generates an easy-to-use timeline. You can see a TimelineSetter-generated timeline accompanying today’s story by T. Christian Miller on the outcomes for five U.S. soldiers’ after a rocket attack in Iraq.
TimelineSetter shows six color-coded series of events — one for each soldier in the blast and one “default” group for events that included multiple soldiers. Users can toggle displaying each series using checkboxes. above the bar. Unlike our bespoke timeline, TimelineSetter also automatically figures out when events happen relative to each other and automatically places “notches” on the timeline bar at the right location.
It supports zooming, dragging, mouse scrolling, double-click to zoom, navigating using the left/right arrow on your keyboard, and even iPhone/iPad swiping and double-tapping. It also allows arbitrary HTML in each event “card,” so we’ve included photos, slideshows and even video embeds in the timeline. While our site’s template is fixed-width, TimelineSetter’s markup and style is fluid, and will fit into whatever sized container we throw it into.
TimelineSetter is mostly written in JavaScript, with a Ruby component to convert a CSV spreadsheet into a JSON object, and a command line application to bake out the HTML/CSS/JS assets ready to drop into a CMS or Amazon S3. There isn’t a server component at all.
We have some more code generalization and fixes we need to do before it’s ready to open source, but we plan to do so as soon as we can. If you’re interested in working with us on the open source release, email us at [email protected].
We’d like to thank NYU journalism professor Jay Rosen’s Studio20 class, who helped us think through how timelines provide context and help orient readers in a complex story, as part of their “Build a Better Explainer” project. We’re especially grateful to Chelsea Stark and her fellow students for their work.
