This tutorial introduces the basics of Knight Lab ¹‘s Timeline.JS ^{11 2} and StoryMap.JS ^{21 3}, OKFN Labs ⁴‘s TimeMapper ⁵, and ProPublica ^{34 6}‘s TimelineSetter ^{33 7}. There are dozens of timeline creation tools on the web, but these four stand out for their simplicity and elegance. Two of these tools create traditional timelines (Timeline.JS, TimelineSetter), whereas the other two are used to link stories to maps (StoryMap.JS, TimeMapper).

Timeline.JS

• User level: beginner to advanced. Basic Timeline.JS use only requires creating a Google spreadsheet. Advanced users can create timelines from JSON objects.


• Requirements: a Google Drive ^{22 20 9} account for basic use.

Believing that existing timeline creation tools were “almost all either hard on the eyes or hard to use”, Zach Wise ¹⁰ created Timeline.JS ^{11 2} as an easy way to build attractive timelines. The result is one of the simplest and most flexible timeline creation tools on the web. Timeline.JS has been used by Le Monde ¹², Time Magazine ¹³, and many other publications ¹⁴—and you can use it to create professional-looking timelines in a matter of minutes.

As explained on the Timeline.JS website ¹⁵, making a timeline is as easy as following these steps:

1. Create a Google Spreadsheet. Copy the Timeline.JS spreadsheet template ¹⁶ and insert your data, making sure not to remove any columns or column headers or to leave any blank rows.
   
   
   
   
   

   Timeline.JS spreadsheet

   
   
   


2. Publish the spreadsheet. From the File menu, select “Publish to the Web”, and press “Start publishing”. Copy the URL you are given.
   
   
   
   
   

   Publish the spreadsheet

   
   
   


3. Paste the URL into the Timeline.JS generator box. Choose the width and height of your timeline. (Click More options to set other options like language and font.)
   
   
   
   
   

   Paste in the URL

   
   
   


4. Embed the code into your website. Timeline.JS will generate embeddable HTML that you can paste into a website.
   
   
   
   
   

   Timeline.JS timeline

   
   
   

That's it!

Timeline.JS is a powerful piece of software. It includes many customization options ¹⁷, and it also supports loading data in the form of JSON objects ¹⁸. Advanced users who wish to learn about these features can read the Timeline.JS README on GitHub ¹⁹.

StoryMap.JS

• User level: beginner to advanced. Basic storymaps can be created with an easy web interface. Advanced users can create storymaps from JSON objects.


• Requirements: a Google Drive ^{22 20 9} account for basic use.

Whereas Knight Lab's Timeline.JS makes it easy to tell stories that unfold in time, its younger sibling StoryMap.JS ^{21 3} makes it easy to tell stories that extend across space. With StoryMap, you can construct timeline-like sequences of slides and link them to a stylish interactive map.

Much like Timeline.JS, StoryMap.JS includes both easy and advanced creation features. Unlike Timeline.JS, StoryMap.JS provides a handy web interface for creating stories—you don't have to create your own spreadsheet.

To get started, log in to your Google Drive ^{22 20 9} account. Then:

1. Go to the StoryMap.JS website ²³ and click Make a storymap now. The first time you do this, you will need to press the green Authorize button to set up your account.
   
   
   
   
   

   Authorize your account

   
   
   


2. Once you've authorized your account, click New StoryMap. Enter a unique, private name for your new storymap in the popup and click Create. You will see an editor screen like the image below.
   
   
   
   
   

   StoryMap editor

   
   
   


3. The first slide (the one that's open when the editor starts) is the title slide. To add more slides, click Add Slide. For each, fill in whatever text, media, links, etc. you wish. You can also Search the map to choose a location for the slide.


4. When you've finished adding slides, press Save to save the storymap, then pressPublishto get a snippet of HTML you can use to embed your storymap in a web page.
   
   
   
   
   

   Embed the storymap

   
   
   

StoryMap.JS includes many advanced features for power users. Visit the “technical details ²⁴” page to learn more about this high-powered functionality.

TimeMapper

• User level: beginner to intermediate. TimeMapper creates timelines from Google Spreadsheets. Taking advantage of TimeMapper's mapping features requires some understanding of geocoding.


• Requirements: a Google Drive account.

TimeMapper ²⁵ is the newest timeline creation tool introduced in this lesson. It is OKFN Labs ²⁶‘s invention, built on top of Timeline.JS and adding new features. TimeMapper's most useful addition to Timeline.JS is its built-in support for timemaps, timelines which link events to an interactive map display.

Using TimeMapper is very similar to using Timeline.JS. You can watch a YouTube tutorial ²⁷explaining how to create a timemap, or follow these steps:

1. Create a Google Spreadsheet. Copy the TimeMapper template ²⁸ and insert your data.For more information on adding geographical information to create a full-fledged timemap, see beneath these steps.


2. Publish the spreadsheet. From the File menu, select “Publish to the Web”, and press “Start publishing”. Important: close the publishing window, click Share, and copy the “Link to share” box. (This is different from Timeline.JS.)
   
   
   
   
   

   Sharing settings link

   
   
   


3. Paste the URL into the TimeMapper “create” page ²⁹ and click Publish. You will be redirected to your newly created timemap, where you will be able to click Embed to get HTML code that you can insert into your own websites.
   
   
   
   
   

   TimeMapper timemap

   
   
   

To take advantage of TimeMapper's mapping feature, you need to add geographical information to your data in the Location column. Two types of geodata are supported: latitude-longitude coordinates and GeoJSON objects.

Coordinates must be in the format lat, long (e.g. 37.5, -122). The spreadsheet template includes a formula which automatically looks up coordinates corresponding to human-readable place names in the Place column. This formula is explained in a School of Data blog post ³⁰.

Advanced users who want to go beyond simple coordinates can use GeoJSON feature objects. For an example of how to generate GeoJSON objects, see this blog post on adding GeoJSON country boundaries to Google spreadsheets ³¹.

TimelineSetter

• User level: intermediate to advanced. To use TimelineSetter, you must know what a CSV is and be comfortable using a command line. TimelineSetter has advanced features for users who know HTML, CSS, and JavaScript.


• Requirements: a Unix-like operating system (Linux or Mac OS X) and RubyGems ^{37 32}.

TimelineSetter ^{33 7} is a command-line timeline creation tool built by ProPublica ^{34 6} for the newsroom. Newspapers like the LA Times ³⁵ and Huffington Post ³⁶ have used TimelineSetter to create beautiful interactive timelines.

TimelineSetter converts specially formatted CSV files to web content that you can load directly onto your server or content management system. TimelineSetter's timelines can be customized by editing the command's CSS and JavaScript output.

If you have RubyGems ^{37 32} installed, you can install TimelineSetter with the following command:

gem install timeline_setter

To get started with TimelineSetter, turn your data into a CSV in the TimelineSetter format. Each row in the CSV should represent a single event associated with a date and/or time. The CSV must also have a specific set of columns, all of which are required to be there—but individual rows may leave some columns blank. The required columns are:

• date: the date of the event. This can be specific down to the second. The TimelineSetter generator can parse dates in a variety of formats.


• display_date (optional): the date to display on the timeline.


• description: A description of the event.


• link: A URL used to generate a “read more” link, pointing to more details.


• series (optional): A name for the series of events this event belongs to. If not specified, defaults to “default”. TimelineSetter groups together events with the same series and formats them in the same color.


• html (optional): HTML to insert above description. Can be anything except <script>elements.

See the sample CSV ³⁸ for an example.

Once your CSV is formatted properly, you can generate a timeline with this command, which will create the timeline in your current directory:

timeline-setter -c data.csv

The output will appear in the same directory as your data file.

If you want to put it in a new directory called (for example) output-directory, use this command:

timeline-setter -c data.csv -o output-directory

You can copy the output directly to your web server (or customize stylesheets/timeline-setter.css to style the timeline first).

To learn more about TimelineSetter and its advanced features, read the documentation onthe TimelineSetter website ³⁹.