Building visualizations with D3.js can be a haphazard process. In this article I’ll talk about different ways to start new projects, and some of the challenges that are likely to crop up along the way.
How do you start a new project in D3?
There is a wealth of tutorials available for D3. These are good learning tools and worthwhile reading for anyone learning the fundamentals of D3. However, once you’re more experienced with D3, a tutorial won’t be of much value unless you find one that closely matches the project you have in mind.
As an experienced D3-er, you’ll probably have the API reference handy. But do you code everything from scratch?
I—and most programmers I’ve asked—use an example or a previous project as a starting point. Even a simple-looking visualization has a lot of moving parts, and examples can provide many things:
A shortcut around spending a bunch of time skimming the D3 API docs, revisiting syntax and arguments. (If you don’t work with layout and drawing functions frequently, it can take awhile to refamiliarize yourself with the nuances.)
An initial pattern for code organization, declarative style, and D3’s selections.
A place to play with inputs and outputs to explore how the whole visualization fits together.
Because examples are often instrumental in getting a new project up and running, the abundance of freely usable examples is one of D3’s greatest strengths.
Anatomy of a project
A visualization built with D3 uses the basic elements of the web: a sprinkling of HTML and CSS, and a significant chunk of JS to tie it all together.
If you’re lucky, you can grab some example code, change a few labels and colors, and drop in your own data. Presto, you just made a working visualization!
But maybe you need data in another format, or with additional variables. Or you want to reorganize a chart, or render things differently, or add some new interactivity or animation.
The situation can get out of control quickly. Most examples don’t provide much in the way of documentation or comments, and D3 code—even well-crafted code—is typically a tangle of terse, vaguely-named functions and closures. (I’ll explore this claim in a future article about refactoring well-known D3 examples.)
If an example proves to be difficult to adapt, you’re no longer building a shiny new visualization; instead, you’re elbows-deep in an autopsy of someone else’s code.
One way to avoid the pitfalls of inscrutable example code is to adopt a charting library.
With minimal coding, you should be able to create standard charts (bars, lines, pies, that sort of thing). You can pile on extra visual flair and annotations, and enable complex (but again, standard) interactions. And all this probably comes with decent documentation as well.
If a particular library meets all your needs, it can be a quick out-of-the-box solution, and you can focus on higher level issues in your project.
Despite all this convenience, I rarely reach for a JS charting library. This is because my needs are either so minimal that a whole library would be overkill, or I need to customize my visualization to a degree where the library ultimately hinders progress more than it helps.
Also, in programs with complex structures and many moving parts, I vastly prefer code over configuration.
Although I don’t tend to use them myself, I think JS charting libraries are great examples of usability for developers. Wouldn’t it be nice if more D3 examples had thorough documentation, or were designed for adaptation and customization?
Whether I’m working on a D3 project, configuring a ready-made chart, or otherwise drawing something with SVG or Canvas, I always look for an example first. But where are all the good ones? Where to look first?
Root around on D3’s Gallery for anything that sounds promising.
Keep digging, but settle on a more generic starting point: anything simple that will get you up and running.
This process leaves me feeling lost and a little bit crazy: I can’t possibly be the first person to attempt a particular visualization, but searches can be fruitless. I often find only scraps of an answer in the form of undocumented example code, static images, and sometimes academic papers.
Are people not sharing their visualizations?
Why are the visualizations that do get shared so difficult to discover?
Is there any way to encourage quality comments or documentation alongside examples?
Why is there no online market (that I’m aware of) for unique JS visualizations? Is that market owned by charting libraries?
What is a good boilerplate for new projects? Is the new standard for plugins useful for creating self-contained projects?
Beyond packaging, what coding standards should a project follow for things like user interaction?
So I’m still trying to figure it out: how do you start a new project in D3?