So you want to code a data story?
[This article was originally published on our Medium blog—check it out for career tips and best practices in the field!]
How I got to now: A condensed version
It was two years ago, and I was in my final semester of my MSc. Urban Sciences. I stumbled upon Konti’s most-famed baby: the Belt and Road story, which features maps and a seamless scrollytelly experience. That catapulted me into the dataviz rabbit hole which I never came out of.
As a result of religiously poring over works by The Pudding, The Upshot and Reuters Graphics, I’d decided that I, too, wanted to make a data story — dataviz with story text. Recklessly, I’d told my final-year project mentor that my deliverable would be a data story built with D3.js (D3 was all the rage in the dataviz circles). “Reckless” because I was going head-first without any idea of how to write a data story — and make it into a webpage within four months? Good luck, past-Aishah.
It worked out in the end, though; I got an “A” and didn’t become an urban planner.
This is the first story in a series where I take you through how I code a data story at Konti. If you’ve been sitting on that dataviz project, this is your sign to push through! I’m living proof that coding dataviz does get easier! :)
So get a pen and your laptop, and follow my tutorial on making two formats of our datastories: Chronicle and scrollytelling.
Note: I’m assuming that you have a basic understanding of how HTML and CSS work on a webpage.
Chronicle format
The most common format of a Konti data story is the “Chronicle” format (see example): text is interlaced with dataviz, illustrations, and other media types, which creates visual breaks for the reader.
HTML is called a mark-up language because you are literally “marking” the different elements that make up a webpage: paragraphs <p>, images <img>, and blocks that we call <div>. If HTML makes the skeleton of a webpage, then CSS, or cascading styling sheets, provides the style over these bones — typography, colours, and spacing.
Image caption: Left: A code snippet for a paragraph, image, and heading. Right: How this code is rendered in a browser
To speed things up I have a “Chronicle” template ready with some lorem ipsum placeholder text. This is a perfect setup, because now I can sort of have a mental picture about what my story is going to look like.
You can access this template on my Github below, and follow along this tutorial!
Get the Chronicle template here!
I’ve used Bootstrap V4 as a base for my grid system, because it helps to make the webpage responsive. Across medium to extra-large screens, I’m setting the text blocks to span across 7 columns out of 12 justified in the center. On mobile devices, it’s 11 columns, also center-justified, because I like the extra padding on the x-axis.
I’ve also set two classes for headers and two for body text, which can be called with the prefix “text-” (e.g., text-body-1) for some variations.
What about the dataviz? Well, in most of the Konti chronicle stories, we use the plug-and-play tool Flourish to do the heavy lifting of creating the charts that we would otherwise have to code. Every chart that we make in Flourish can be exported into our code.
Flourish provides it in a <div>. An example will look like this:
<div class=”flourish-embed flourish-chart” data-src=”visualisation/[the chart id here]"> <script src=”https://public.flourish.studio/resources/embed.js"></script></div>
Note that you have the <script> that renders the chart according to the chart id, and the <div> comes with pre-defined classes already.
Image caption: Screen grab from building a bar chart in Flourish: plug in the data, view the chart, and export it out as an embed link
It comes with a nifty level of customisation for colour, layout (paddings and margins), and typography. And trust me, selecting the right colour palette and typography pairings is harder than it sounds. But done right, you’ll get a data story in which the visuals are all coherent.
Best of all, Flourish is free to use once you create an account. Check out some of the charts that Flourish provides!
Image caption: A screen grab from Flourish featuring some of the charts that you can build
Commonly used ones would be the humble bar chart, which is straightforward in depicting discrete categories of continuous data, and the line chart for time series data. If you’re feeling a little more experimental, the bubble chart might be up your alley.
To add a Flourish chart into your code:
TLDR: A bare minimum HTML page for a Chronicle format would warrant the following—responsive grids (so it looks good on all devices), typography classes for body and header text, and placeholder images. We use iframes to plonk in charts that are generated with Flourish.
Scrollytelling format
Another popular data storytelling format is called scrollytelling. As the portmanteau suggests, it’s scrolling while telling a story.
It is a powerful visual storytelling technique […] new content appears or changes through transitions as users scroll down or up the web page.
Lorenzo Amabili writes about the different ways of using scrollytelling and I think it’s a great primer for people who wants to make one. My first experience of trying to build one came from Jim Vallandingham’s So You Want to Build a Scroller. It was an ambitious attempt for someone with little to no Javascript knowledge, and I failed miserably ??.
But hang on! I’m going to show you an easier way to build a scrollytelling story by using Scrollama and Flourish. It’s a bit long, so bear with me! You can also skip ahead for the code template at the end.
Scrollama.js
At Konti, I was introduced to Scrollama.js — an amazing scrollytelling library by Russell Goldenberg! He wrote a very succinct and informative write-up on the basics of it — published by none other than The Pudding ??.
A side-by-side setup for a Scrollama section will look like this; I’ve have highlighted the viewport of the device in grey. Each instance comprises “steps” which trigger a function when it crosses a certain threshold — say, a line at the bottom 20 percent mark horizontally across the viewport. The function is responsible for changing the visuals in what Goldernberg calls a sticky graphic pattern. This sticky element stays stuck in its position in the viewport while the user scrolls through the steps, and it unsticks once the user has run through it.
Image caption: Annotated layout of a side-by-side scrollytelling story
For this Medium piece, I relied on Goldernberg’s side-by-side demo code.
Flourish Story
If you’d thought Flourish is efficient for creating charts, Flourish “stories” is going to blow your mind.
Image caption: An example of a Flourish story — automated transitions between charts and annotations available
A Flourish Story closely resembles a deck of Powerpoint slide, in which the slides are populated by visualisations that we’ve created before. Two amazing functions of Flourish Stories are 1) Adding annotations to our charts and 2) Automated transitions between the charts — which look sick!
Can you imagine manually hardcoding the transitions? (I was so stressed when I did it for the first Bicentennial story).
Image caption: Annotated screengrab: How to create a Flourish from existing Flourish data visualisations
Exporting the Flourish Story yields this link; let me break it down for you:
<div class=”flourish-embed” data-src=”story/872914"
<script src=”https://public.flourish.studio/resources/embed.js"></script></div>>
Note that it’s similar to the previous single Flourish chart. Except this time, the data-srcattribute defines it as a story, and we’re missing the class ‘flourish-chart’. The script tag renders the story with id 872914.
We’re going to tweak this a little. Instead of using that <div> to embed the Flourish Story into our code, we’re going to render it by using the following URL:
The URL that we’re using. The suffix of “slide-” will change according to the slide that is being shown.
Instead of using a <div>, we are going to embed our Flourish Story by using an iframe whose src is that URL.
It starts with the first slide at slide-0; this number will change as you progress through the deck. The idea is that "going through" the slides would require the user to initiate a trigger of some sort. It can be a click like the native navigation bar that comes with the Flourish Story.
Flourish Story + Scrollama js
But because we’re going for a scrollytelly, the trigger action would naturally be the user’s scroll. User scrolls -> URL changes -> Flourish slide changes.
I’ve added a scrollytelling section as a continuation from the Chronicle template here on my Github —download the code and let’s put together a Flourish Story-scrollytelly.
Get the ScrollyTelling template here!
We are going to use the “steps” defined by Scrollama.js to trigger the Flourish Story slides to change. To make things simple, let’s do a 1–1 map of step to slide — the first step (paragraph text) triggers the first slide (Flourish slide-0), and so on.
In code, we will use the handleStepEnter() function to do this. Since I'm using D3 to define the parameters needed for Scrollama earlier anyway, I'll just use D3 for this.
What this function does is tell Scrollama that when the “step” element comes to view, we update the source of the iframe. The slide constantly corresponds to the current “step”, so that the correct slide is updated in the Flourish Story.
And voila! We’ve created a scrollytelling section with Flourish Stories!
Examples of Flourish-styled viz in Konti stories
In fact, Konti utilises this method in some of our stories. The most obvious one would be the Bicentennial series (Friendly Societies, Education, and Healthcare).
But you can also click through the Flourish Story slides by adding UI elements such as your own arrow buttons. The Han Chinese names story uses this method, in which we created custom buttons that tie the story text to the Flourish Story slides.
Image caption: Screen grab of the Han Chinese names story by Bella which uses the up/down button to run through the Flourish Stories slides –?see it here: https://kontinentalist.com/stories/a-cultural-history-of-han-chinese-names-for-girls-and-boys-in-china
The flow chart featured in the UNHCR partnership story is my personal favourite, because this Flourish Story, and its use of thematic colours, seamlessly blends into the rest of the hardcoded story. The user can toggle between the two Flourish Story slides using the UI tabs at the bottom of the chart.
Image caption: Screen grab of the UNHCR partnership story by Zafirah; the story uses the up/down button to run through the Flourish Stories slides – see it here: https://v1.kontinentalist.com/stories/the-rohingya-in-myanmar-a-refugee-crisis-at-sea
Is this still coding?
Flourish is a low-code software. Sure, it can't do crazy custom charts like Bella's story on Asian representation. But don't be fooled by the simplicity of this “low-code” or “no-code” software. It’s a pretty nifty way to ease yourself into creating a scrollytelly story before jumping into creating your own transitioning charts with D3!
I hope this pseudo-tutorial brings some benefit to my fellow colleagues who've been telling me that they want to pick up coding!
To recap, here’s a list of resources that I mention throughout this piece:
Template codes and Flourish
More reads for ScrollyTelling
If you were to ask me what my favourite data story is, it would have to be the instant noodles story ?? because it was my first hardcoded story (you never forget your first!), and I had a part to play in wrangling the dataset. The charts were customised to the story (e.g., having noodle strands as the bars in bar charts). I'll talk more about that in my next medium post, so stay tuned! You can also follow me on Twitter in the meantime :)