Use an Observable Notebook in a News Story

15 May, 20192 Min Read — In Tools, Observable, Visualisation, Article Technology

I adapted a bar-chart race in an Observable Notebook and deployed it within a New Zealand Herald article — and the whole process is surprisingly easy.

Observable Notebooks are great for getting started with visualisation, collaborating and sharing, and for prototyping ideas. Observable’s extensive collection of other people’s notebooks are an excellent source of inspiration — both for ideas and techniques.

When I saw John Burn-Murdoch’s observable implementation of a bar-chart race, https://observablehq.com/@johnburnmurdoch/bar-chart-race-the-most-populous-cities-in-the-world, I decided it was time for me join the bar-chart race band-wagon.

I grabbed the data for the most capped international rugby players each year from 1900 until now and adapted John’s code — resulting in https://observablehq.com/@vizowl/international-rugby-caps

I showed this to the sports team at the New Zealand Herald and they wanted to use it.

Observable notebooks can be downloaded and embedded so I decided to see whether I could use this approach within an article. But I didn’t want to rely on any of Observable’s infrastructure — Everything to be on either CDNs or Herald infrastructure.

There is quite a bit of detail in the downloading and embedding notebook — so here I’ll just note down what was needed to roll an observable notebook into the Herald’s workflow.

These instructions are targeted at people that are already building and deploying javascript based apps.

My rugby players bar-chart race notebook is here. At the Herald we use a webpack based workflow for deploying interactive articles. So the steps needed to use an Observable notebook are basically just:

  • Install the notebook into the article’s javascript app

  • Import the notebook

  • Display only the relevant parts of the notebook with the article

Downloading and installing a notebook

This was just a matter of using npm to download and include the notebook as part of our package.json

  • First install the Observable runtime
npm i --save-dev @observablehq/runtime
  • Then install the notebook
npm i --save-dev https://api.observablehq.com/@vizowl/international-rugby-caps.tgz

It is also possible to pin specific versions of the notebook — but I just re-ran the install whenever I had changed the notebook.

Importing the notebook

We use ES6 style imports

  • Load the Observable runtime and inspector.
import {Runtime, Inspector} from "@observablehq/runtime"
  • and then load the notebook
import notebook from "international-rugby-caps"

Using the notebook

The Herald template relies on being provided with a div with the id nzh-datavis-root — and that is where we attach the notebook element we are using.

const root = document.getElementById('nzh-datavis-root')
Runtime.load(notebook, (cell) => {
if (cell.name === "chart") {
return {
fulfilled: (value) => { root.appendChild(value); }
}
}
});

And that’s it — it would have been nice to add a pause button to control the bar-chart animation — but deadlines. The (paywalled) article is here.

Extras

  • It is possible to include more than one element — just modify the if condition.

  • A little more work is required to embed notebooks that render to canvas — see the breakout demo.

  • The full Herald datavis workflow uses webpack to build and bundle all the assets. Then these are uploaded to an S3 bucket and served via Amazon’s CloudFront cdn.

  • I created a template the is already setup to use an observable notebook using Mike Bostock’s H1B notebook as a starting point.