Skip to content
This repository has been archived by the owner on Apr 3, 2021. It is now read-only.
/ two-step Public archive

A JavaScript library for best-practice scrollytelling

License

Notifications You must be signed in to change notification settings

WSJ/two-step

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Note: This library has been deprecated and the repo is no longer being maintained. See alternatives for other options.

TwoStep

This is a JavaScript library for scrollytelling, which is dynamically changing charts (or triggering whatever) as text scrolls into view. It implements best practices for scrollytelling, which means built-in keyboard shortcuts, no scrolljacking and reliable "sticky" behaviour.

TwoStep was developed at The Wall Street Journal and has been used in stories such as:

Demos

TwoStep is highly flexible, and can be used in range of designs.

These demos are also meant as starting points for new projects.

Setup

  1. Include jQuery, Waypoints, FixTo and TwoStep on the page.

  2. Set up HTML and CSS as best fits your project. See source code from the demos above for inspiration.

  3. In your JavaScript:

var ts = new TwoStep({
    elements: document.querySelectorAll('.slide-item'),
    onChange: function(event) {
        console.log(event.index);
    }
});

Options

Only elements is required. All others are optional.

  • elements: Array/NodeList of DOM nodes (i.e. your narrative text).
  • narrative: Array of functions corresponding to elements. Each called with event object as argument.
  • onChange: Called when any/every element is activated. Called with event object as argument.
  • stick: DOM node to stick in right rail (i.e. your sticky chart).
  • offset: Object to manually set the offset for both directions. Must include both an up and down key and both values should be strings (i.e. {up:"50%",down:"0"})

Event object

Whenever a narrative function or onChange is called, it’s passed an event object as an argument.

var ts = new TwoStep({
    elements: document.querySelectorAll('.item'),
    onChange: function(event) {
        console.log(event);
    }
});

Here’s what you can find in a typical event object:

{
    index: 0,
    direction: 'up',     // or 'down', or null
    element: < element > // DOM node corresponding to index
}

How to get scroll direction

Check event.direction:

var ts = new TwoStep({
    elements: document.querySelectorAll('.item'),
    onChange: function(event) {
        if (event.direction === 'up') {
            // do something
        } else if (event.direction === 'down') {
            // do something else
        }
    }
});

Public methods

  • .goTo(index, scroll): Activate item at index. If scroll is true, will animate to position. Returns a promise which resolves when scrolling is complete.
  • .disable(): Prevent waypoints from firing and unstick stuck element, if present
  • .enable(): Return to standard behaviour

Compiling from scratch

Make sure you have Node.js installed. Then run:

npm install
npm run start

Running tests

To run tests, open tests.html in your browser and wait a couple of seconds.

Alternatives to TwoStep

For something a bit different, see scrollWatcher, also made by WSJ.

Version history

v1.0.0 (November 27, 2017)

  • Initial public release

License

ISC