Appendix B. What’s New in 4.0
A lot changed in version 4.0 of D3! In case you were just getting comfortable with version 3.x, you may feel as though 4.0 pulled the rug out from under you. Here I’ve summarized the changes most likely to affect beginner users of D3; this appendix addresses only the changes that impact what you would have learned from the first edition of this book.
For the rest, see Mike Bostock’s exhaustive list of “Changes in D3 4.0”. Also see Mike Bostock’s essay “What Makes Software Good?” for context and the rationale behind these changes.
The good news is that the fundamental principles baked into D3 (such as that of the data join) are unchanged. But 4.0 was rewritten from the ground up, and there are several significant structural and syntactical changes. 4.0 is decidedly not backward compatible.
Modularity
No longer one giant, hulking library, D3 is now modular, meaning it’s made up of many tiny libraries, each focused on a specific domain. Unless your project is super fancy, you can probably just use the default bundle, which includes the following D3 microlibraries or modules (each repository for which also contains its own documentation):
For more advanced use, you can generate custom bundles in order to, say, exclude all the bits you don’t need (to make your custom D3 bundle as tiny as possible) or add other bits you do need. See the changes doc for details and ideas on how to generate your own custom D3 bundles.
Namespace and camelCase
As part of this change, the namespace has been flattened, meaning that most methods are now top-level. For example, d3.svg.line is now simply d3.line. For clarity, however, most method names have been condensed and are now written in camelCase. For example, d3.scale.linear is now d3.scaleLinear. See Appendix E for a listing of the new method names used in this book.
Selections
Selection-related methods now return brand-new selections, as opposed to modifying the current selection. So, once a selection is created, you can never modify it (though you could generate a new selection, and then store that in the same variable, effectively overwriting the original selection).
In 3.x, using append() with enter() (such as after a data join) would add the element it had just created back into the update selection—effectively “auto-merging” new elements into the existing selection. Now that selections are immutable, we have to use the new merge() method to explicitly create a new selection of, say, an update selection and an enter selection. See Chapter 9 for an explanation on using merge() with data joins.
Multivalue Maps
In 3.x, if you got tired of typing attr() over and over again, you could use a multivalue map to set multiple attribute values with a single attr(). This feature is no longer included in the D3 core, but can be added with the d3-selection-multi module. Note that the multivalue methods have pluralized names: attrs() and styles() (as opposed to attr() and style()).
For example, we could collapse these three attr() statements:
svg.select("circle").attr("cx",0).attr("cy",0).attr("fill","red");
…into one by defining all three attribute values within a single object:
svg.select("circle").attrs({cx:0,cy:0,fill:red});
Transitions
In 3.x, you had to jump through some hoops to schedule transitions in sequence, or to synchronize transitions that would run concurrently. It’s easier to chain transitions now: just follow an initial transition() with a second transition():
svg.selectAll("circle").transition()// <-- Transition #1.duration(500).attr("cx",…)// Reposition circles first.attr("cy",…).transition()// <-- Transition #2.delay(1000)// Wait 1 second.duration(500).attr("fill","black");// Change fill value
Note that the second transition’s delay() kicks in only after the first transition has finished, so we’d see the circles change position, then a 1-second pause, then the fills would change to black.
Also, you can now cancel in-progress or scheduled transitions by calling interrupt() on any selection. For example, to interrupt the transitioning circles, use d3.selectAll("circle").interrupt().
Finally, when you’re specifying easings, ease() no longer accepts strings; pass in symbol names instead. For example, "linear" is replaced with d3.easeLinear. Reference the changes doc for the complete list of easing symbols.
See Chapter 9 for an introduction to transitions, and Chapter 16 for more complex examples of chained transitions.
Ordinal Scales
The old d3.scale.ordinal() supported rangeBands() and rangePoints(). These have been superseded by band scales, created with d3.scaleBand(). See Chapter 9 for a detailed explanation of band scales.
Axes
Axes created with d3.svg.axis() were oriented with orient(), as in orient("top"), orient("right"), orient("bottom"), or orient("left"). Now the axis orientation is baked into the name of whatever axis generator method you use: either d3.axisTop, d3.axisRight, d3.axisBottom, or d3.axisLeft.
The axis generators now also generate their own CSS styling. (In 3.x, you had to remember to include your own CSS.) These styles, of course, can always be overridden with your own style rules. See Chapter 8 for an introduction to axes and an example of overriding CSS styles.
Stack Layout
This has been completely rewritten and functions quite differently than in 3.x. See Chapter 13 for a detailed explanation of the stack layout, and Chapter 16 for additional examples.
Zooming
The old d3.behavior.zoom is now simply d3.zoom. More importantly, the zoom state (the “active zoom transform”) is no longer stored in the zoom behavior, but is stored on any elements to which it is applied (much as bound data is stored in memory “on” individual elements). This is an improvement because then each element can keep track of its own zoom state, and the same zoom behavior can be applied to multiple elements. d3.zoom also includes the new convenience methods translateBy(), scaleBy(), and scaleTo(). See Chapter 14 for an introduction to zooming in the context of geographic maps.