# data[].attributes.attachment_link.description
See all the wonderful things Jessica Lawson has made

# data[].attributes.body
Online timeline maker

# data[].attributes.attachment_link.title
Tiki-Toki Timeline Maker: Beautiful web-based timeline software

# data[].attributes.attachment_link.description
Create beautiful interactive timelines that you can share on the web. The perfect timeline maker for company history timelines and school projects.

# data[].attributes.attachment_link.description
This video is part of the Interactive Timelines course on KQED Teach - KQED's online professional learning platform for educators. Sign up at teach.kqed.org to take this course and learn more about making interactive timelines.

# data[].attributes.body
Timelines are visual representations of all our significant events, packaged neatly in chronological order--AKA our history. Humans have been creating timelines as far back as 1077 B.C.E when the Egyptians built an 80-foot obelisk during the reign of Ramses XI with the dates of the reigns of previous pharaohs. Brain scientists tell us that number lines are particularly important for students because the brain holds numbers in a type of number line.

# data[].attributes.headline
Timelines tell something about what the creator thinks is important

# data[].attributes.subject
Timelines tell something about what the creator thinks is important

# data[].attributes.body
A timeline is more than a series of dates. A timeline tells the story of an event or process, stitching together moments, days and years into a cohesive narrative. Dates may appear to be unbiased data points, but choosing which ones to string together on a timeline creates a story that reflects the views of its creator. This link takes you to 2 interactive timelines about the Dakota Access Pipeline, both with very different perspectives.

# data[].attributes.headline
Creating your own timelines - a collaborative process

# data[].attributes.subject
Creating your own timelines - a collaborative process

# data[].attributes.body
Most, if not all, interactive timeline tools start with a spreadsheet. This means that making an interactive timeline is extremely accessible for classrooms because by design, they are collaborative and familiar.

Building an interactive timeline means you get to focus on

Deciding on your narrative (the time scope)

Selecting the significant events (the dates)

Researching and verifying your information and sources

Bolstering your narrative with the right media

# data[].attributes.body
Chart growth or progression in science experiments

Put historical events in context

Show character or plot development throughout the course of a story or novel

Document the development of a trend, idea, social movement, business or product

Analyze relationships among people, places, events or ideas over time

# data[].attributes.body
Aim for something visually engaging! Create catchy titles (no more than 10 words), and summarize descriptions, with wonderful word choice and no more than 5 sentences. Use color to convey a mood or separate or connect different time zones. Finally, keep timelines as short as possible - make strategic choices about curation. See below for an example of color to separate time periods.

# data[].attributes.body
Everything in your timeline should support the story you want to tell. Choose images, links, and videos that bring your audience closer to your story

# data[].attributes.headline
Wow! Check out this interactive timeline of the last 2000 years!!!

# data[].attributes.subject
Wow! Check out this interactive timeline of the last 2000 years!!!

# data[].attributes.body
Each dot represents something from history, and link to a wikipedia page for more info.
This blew my mind. It might be fun to let kids loose on it, and see what they get curious about.

# data[].attributes.attachment_link.description
Histography is an interactive timeline that spans across 14 billion years of history, from the Big Bang to 2015

# data[].attributes.body
An interactive timeline tool

# data[].attributes.attachment_link.readable_text
TimelineSetter creates beautiful timelines.

It is a command-line utility that takes a specially-structured CSV file as input and outputs standards-compliant HTML/CSS/JavaScript. It supports any span of time from minutes to years, and supports multiple parallel event series in a single timeline. It can handle custom descriptions and even arbitrary HTML in each event "card." It creates fluid embeds that will look great at any width.

TimelineSetter "bakes out" timelines, ready for uploading directly into your CMS, Amazon S3, or however you typically serve static files. It requires no server-side processing at all once you've generated a timeline.

TimelineSetter source on Github.

Assorted Docs and Samples

How it Works

The project is broken into two parts: a Ruby package (along with a binary) for generating the assets, and the HTML, CSS and JavaScript for the timeline itself. TimelineSetter will create a unique HTML page that embeds a JSON object with your data. The CSS and JavaScript are identical for every timeline created, so you can host those centrally and simply point to them when you deploy a timeline, or (with the minified option) you can package them up with your HTML and paste it into your CMS all at once. You can customize the CSS to match the look and feel of your site.

Dependencies

TimelineSetter relies on TableFu, as well as the JavaScript libraries Underscore and jQuery. All of these are either installed along with TableSetter, or packaged with the source. It has been tested with jQuery 1.5.1 and Underscore 1.1.5.

Installation

Install TimelineSetter through RubyGems on Unix-like OSes:

gem install timeline_setter

(Note: We haven't tested using the TimelineSetter tools on Windows even once, though the timelines themselves have been tested in modern browsers on Windows, Mac and Linux.)

The `timeline-setter` command

After TimelineSetter is installed, the timeline-setter command should be available in your shell. The command looks for a CSV file to parse and outputs static assets. At any point, you can find help by running timeline-setter without any arguments, or by adding the-h flag. Run the command like so:

timeline-setter -c /path/to/data.csv -o /path/to/output/directory

Running timeline-setter with no -o option will generate the timeline (and supporting assets if applicable) within the current directory.

Full list of options:

-c CSV Path to your CSV file.

-o OUTPUT_PATH Path to output timeline and assets. If absent, timeline will be created in current directory.

-a Do not output supporting assets such as CSS and JavaScript. This is useful if you're customizing those and don't want your versions clobbered.

-m Create a minified one-page version of your timeline with all supporting assets inline.

-O Open a browser to your new timeline after it is generated (currently Mac OS only).

-i Add a custom interval for background "interval notches." These take the format of JavaScript date getter methods. For example, year would be FullYear. All the options are available below. If absent, TimelineSetter will attempt to automatically create interval notches based on the first and last dates in your timeline.

-h Print help to standard output.

Setting Up Your CSV File

TimelineSetter looks for certain column names in your CSV file in order to generate a timeline. All columns are required, though as you'll see, some of them can be left blank (see a sample CSV). Here's a summary of each column and its significance:

date

The date the event happened. Right now, TimelineSetter only supports single-date events, but this can be specific down to the second. The generator will try its best to parse out human dates. Try "March 20, 2010," "3/20/2010," "Mar. 20, 2010 11:59 PM" etc.

display_date

The date displayed on the event's card in the timeline. If this is blank, it will fall back to date

description

A description of the event.

link

A URL to send users to more details about an event. This will generate a "read more" button at the bottom of the card pointing to the URL.

series

A string representing the name of the series of events this particular event is a part of. TimelineSetter will find all the unique series among events in the spreadsheet and assign both colors and checkboxes for them at the top of the spreadsheet. Events not assigned to a series will be part of the "default" series, which have their timeline notches colored charcoal, and have no associated checkbox. Note: As a corollary, if you only have one series, it is best not to assign a name.

html

Any arbitrary HTML that will be inserted above description. This field may contain image tags, YouTube tags, etc. - nearly everything except<script> tags. If you choose to use JavaScript, you must do it inside an iframe and call that iframe inside this field. Note: If you put an image or iframe in this field, make sure to set height and width attributes, or the card may not extend around the image.

Folder structure and deployment

After you've generated a timeline with the timeline-setter command, you should see a structure much like this where you've specified your output:

 |-output |---timeline.html |---javascripts |-----timeline-setter.js |-----vendor |-------underscore-min.js |-------jquery-min.js |---stylesheets |-----timeline-setter.css

Dropping the whole folder onto your server or an asset host like S3 will allow the app to run self-contained. It requires no server-side processing at all. To drop into your CMS, simply copy the relevant bits of timeline.html and paste into your site's template. Then, adjust the<link> and <script> tags to point to their appropriate destinations.

Definitions

The timeline is made up of non-clickable interval notches used to denote periods of time, and event notches, which, when clicked, reveal their associated event cards.

Configuring the Timeline JavaScript Embed

Although the timeline-setter command generates a JavaScript embed that prepopulates your data, you can also create this yourself by calling TimelineSetter.timeline.boot with an array of card objects, and a config object.

var myTimeline = TimelineSetter.Timeline.boot([{card}...], {config})

The config object looks for interval, container, and formatter options.

The interval option takes an interval in the form of a JavaScript date getter. The container option allows you to inject the entire timeline into an element with the given selector. (By default this is #timeline). Finally, formatter is a way to format dates on the timeline's interval notches. Write a formatter like so:

formatter : function(d, defaults) { var months = ['enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio', 'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre']; defaults.month = months[d.getMonth()]; return defaults; }

Styling Your Timeline

TimelineSetter timelines are fully style-able. The default "ProPublica theme" stylesheet is packaged alongside each generated asset bundle, and is available in stylesheets/timeline-setter.css. You can alter this stylesheet, or replace it completely. Here's a guide to do that.

Overview and Styling the Container and Top Matter

All TimelineSetter CSS is scoped within a namespace starting with TS except for the outermost container (by default #timeline.) The container is configurable with the container argument in the TimelineSetter boot function's config object.

Upon first glance, it may not seem like there is much markup at all. That's because we make extensive use of JavaScript (ERB-style) templating via Underscore.js - templates for each part of the timeline reside in a JST object at the end of timeline-setter.js.

Currently, series colors are hard coded in the JavaScript. We support a maximum of nine series colors (assigned in this order: #065718, #EDC047, #91ADD1, #929E5E, #9E5E23, #C44846, #465363, #EDD4A5, #CECECE, they can be overridden in the "color priority" section of timeline-setter.css). Technically you can create an unlimited number of series, but they will eventually fall back to the default charcoal notch color.

Styling the bar, notches and cards

The position of interval notches is based on the interval of time between events as automatically determined by the JavaScript. Here's a sampling of what you might see in interval notches:

year => 2001 month => June, 2004 day => May 1, 2005 hour/minute => 11:59 second => 11:59:22

The interval notches date spans themselves can be customized by using the -i flag when generating a timeline. The available parameters are

Decade Lustrum FullYear Month Week Date Hours Minutes Seconds

The JavaScript API

As of version 0.3.0, TimelineSetter has a JavaScript API that allows programmatic access to certain events, and the ability to activate cards. To use the API, assign the TimelineSetter.Timeline.boot() function to a variable, and then use methods in the api object like so:

var currentTimeline = TimelineSetter.Timeline.boot(options); currentTimeline.api.onLoad(function() { console.log("I'm ready") });

Here are the API methods:

onLoad

Register a callback for when the timeline is loaded.

onCardAdd

Register a callback for when a card is added to the timeline. This method has access to the event name and the card object.

currentTimeline.api.onCardAdd(function(evtName, obj, card) { console.log(obj); console.log(card); });

If you want to customize the card's template, set card.template to an undescore template function.

onCardActivate

Register a callback for when a card is activated (i.e. shown). This method has access to the event name and the card object.

onBarMove

Register a callback for when the bar is moved or zoomed. Be careful with this one: Bar move events can be fast and furious, especially with scroll wheels in Safari.

activateCard

Show the card matching a given timestamp. Right now, timelines only support one card per timestamp.

Roadmap

On the client side, there are a number of features we plan to add, including:

Smoother zooming

Deactivating series checkboxes if none of its events are within the zoomed viewport

Auto-zooming the timeline if embedded into smaller containers

More iOS gestures such as "pinching"

Zooming to fit a series when the series is activated

Ranges of events (e.g. Elizabeth Taylor was married to Michael Wilding between Feb. 21, 1952 and Jan. 26, 1957, as shown here)

Embed code

JavaScript tests

Media Organizations Using TimelineSetter

Credits

Al Shaw, Jeff Larson, ProPublica, Ben Welsh, Los Angeles Times

Contact

For issues with TimelineSetter, use the Issue Tracker. General questions should go to opensource@propublica.org.

Change Log

0.3.2

Fix reliance on jQuery's .toggle(handler, handler) which was deprecated in 1.8

0.3.1

Fix position bug that was preventing card flipping in IE <= 8

Add noscript fallback

Add Century, HalfCentury, Quincenenary, HalfHour, QuarterHour, Millenium intervals

Fix CLI in cases where output directory already exists

0.3.0

Add JavaScript API

Scope timeline to a given element to support multiple timelines on a page

Add date formatter config option. Thanks @omega

0.2.0

New feature adds support for custom interval notch ranges.

Change command line to output supporting assets by default unless -a is specified

0.1.2

Support for decade and lustrum (five year period) interval notches. Thanks, Ben Welsh

0.1.1

Made JavaScript smarter about image widths, so now images can be used without specifying height and width attributes

Fixed "read more" buttons so they can be clicked everywhere, not just on the text

Fixed a CLI bug where timeline was being put in the wrong place when output directory is specified without a trailing slash

Fixed duplicate colors in CSS

Fixed layout rendering problems when a card was more than half the size of the timeline

Fixed an issue where JSON couldn't be generated in Ruby 1.9

Thanks to Ben Welsh for pointing out most of these issues
0.1.0

Initial release

License

Copyright © 2011 ProPublica

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

# data[].attributes.body
Interactive timeline that brings the legacy of segregation into the present day with 'de facto' segregation examples

# data[].attributes.attachment_link.title
Timeline: From Brown v. Board to Segregation Now

# data[].attributes.attachment_link.description
Charting the fight for educational equality to the resegregation of U.S. schools.

# data[].attributes.body
A different way of visualizing change over time

# data[].attributes.attachment_link.title
A Month of Citi Bike: A New Yorker Interactive

# data[].attributes.attachment_link.description
It's been nearly two months since New York City rolled out its bike-sharing program. To see how it's faring, we used live data, provided by Citi Bike, to map where people rode for one month. As the month progresses, the circles on the map grow or shrink according to the number of available bikes at each station.

# data[].attributes.body
A third interactive timeline tool

# data[].attributes.attachment_link.title
How to create a truly Interactive Timeline with Google Sheets

# data[].attributes.attachment_link.description
Looking to 'Flip' your classroom? Want more engaging content and interactive timelines for your teaching and VLE(Virtual Learning environment) or Blog? Look no further. Using Google Sheets and TimelineJS you can create stunning and truly interactive Timelines, using information, images, video, audio and so much more. Find out all about it in this video!

# data[].attributes.attachment_link.description
This is a step-by-step video tutorial on how to use TimelineJS.

# data[].attributes.body
Another interactive timeline tool

# data[].attributes.attachment_link.title
Home - TimeMapper - Make Timelines and TimeMaps fast! - from the Open Knowledge Foundation Labs

# data[].attributes.attachment_link.description
TimeMapper - Make Timelines and TimeMaps fast! - from the Open Knowledge Foundation Labs