Timeline v1.0.1

Hosted Version Source →

The newseful timeline provides a more structured layout for developing stories. By separating events from reactions, it provides the reader with a clearer understanding of the reporter’s work.

The timeline component is simple enough for reporters to set up themselves, but can be customized for greater flexibility.


The newseful timeline component relies on two external dependencies when using Google Sheets as a data source. These dependencies are the javascript libraries d3.js and tabletop.js. To add the hosted versions of these files, and the newseful timeline file, to your project, copy and paste these lines into your code editor:

<script src=‘http://d3js.org/d3.v3.min.js’></script>
<script src=‘https://raw.githubusercontent.com/jsoma/tabletop/master/src/tabletop.js’></script>
<script src=‘http://nf-components.na1429654158.netdna-cdn.com/components/timeline/1.0/newseful-timeline.js’></script>

You’ll also need a link to the Newseful style sheet, unless you plan on styling the timeline yourself. To include the Newseful style sheet, add this code to the head section of your page.

<link rel=‘stylesheet’ href=‘http://nf-components.na1429654158.netdna-cdn.com/components/styles/1.0/newseful.css’>

With these files added to your project, you’re ready to create a timeline. There are two required options to instantiate the default timeline, the container, which is a reference to the element on the page that will contain the timeline, and the dataURL property, which contains a link to the public version of your Google Sheet. For more information on data sources and setting up your Google Sheet’s public URL, visit the Data Sources section below.

To instantiate your timeline, add the following script to your page, substituting your variables where indicated:

  var sheet = ‘http://YOUR_SHEET_URL’;
  var element = document.querySelector(‘YOUR_ELEMENT_SELECTOR’);

  var timeline = new NFTimelineView({
  	container : element,
  	dataURL : sheet

Data Sources

Newseful’s timeline component provides two options for data sources. The default option is to use Google Sheets as a data source, but properly formatted JSON can also be used.

Google Sheets

To use Google Sheets, you’ll need to set up your spreadsheet in a particular way. For reference on how the columns should be titled and filled, consult this example spreadsheet.

Once your spreadsheet is set up, you’ll need to make it publicly visible. In order to do this, within the google sheets interface navigate to File > Publish to the web. Once you’ve published your sheet, you should see a URL. Copy this URL and use it as the dataURL property when instantiating a new timeline (see above).

Custom Data Source

Newseful’s timeline can also accept a custom data source as JSON. In order to use a custom data source, you will need to format the JSON as follows:

var data = {
	reactions : [{
		time : DATE_AND_TIME,
		source : NAME_OF_SOURCE,
		text : TEXT
	}, ...],
	events : [{
		time : DATE_AND_TIME,
		text : TEXT
	}, ...]

Then, when instantiating the timeline, pass in the data as the data property of the instantiation options, ommitting the dataURL property entirely.


In addition to the option of using custom data sources, the timeline component offers several other configuration options. Custom styles can easily be implemented by overriding the selectors in newseful.css, which uses the BEM convention to style components.

Several configuration options are also available when instantiating the timeline.

var sheet = ‘http://YOUR_SHEET_URL’;
var element = document.querySelector(‘YOUR_ELEMENT_SELECTOR’);

var timeline = new NFTimelineView({
	container : element,
	dataURL : sheet,
	sortOrder : ‘chrono’,
	labelFrequency : 3

Event Order

The default order for events in the Newseful timeline is reverse chronological. To override this and enable chronological sorting, instantiate the timeline with ‘chrono’ as the sortOrder parameter of the instantiation options.

Label Frequency

The frequency of the date labels along the middle axis of the timeline is configurable. The default is to add them every day, but passing an integer x to the instantiation option labelFrequency will adjust it to provide labels every x days.