Data Visualization with D3 4.x Cookbook - Second Edition

The easiest way to get all the recipe source code that you will need is to clone the Git repository (https://github.com/NickQiZhu/d3-cookbook-v2 ) for this book. If you are not planning to set up a development environment for the recipes, then you can safely skip this section.

First, install a Git client on your computer. You can find a list of Git client software at https://git-scm.com/downloads , and a detailed guide on how to install it on different operating systems at https://git-scm.com/book/en/Getting-Started-Installing-Git .

Once the Git client is installed, simply issuing the following command will download all recipe source code to your computer:

> git clone git@github.com:NickQiZhu/d3-cookbook-v2.git

There are probably more than a dozen different ways to set up an HTTP server on your computer based on the operating system you use and the software package you decide to use to act as an HTTP server. Here, I will attempt to cover some of the most popular setups.

> python -m SimpleHTTPServer 8888

> python -m http.server 8888

> npm install http-server -g

> http-server -p 8888

Functions in JavaScript are objects. Like any other object in JavaScript, function object is just a collection of name and value pair. The only difference between a function object and a regular object is that function can be invoked and additionally associated with the following two hidden properties: function context and function code. This might come as a surprise and seem unnatural, especially if you come from a more procedural programming background. Nevertheless, this is the critical insight most of us need in order to make sense of some of the strange ways that D3 uses functions.

Now, with this insight in mind, let's take a look at the following code snippet again:

  var instance = {}; // <-- A 
 
  var headline, description; // <-- B 
 
  instance.render = function () { 
    var div = d3.select('body').append("div"); 
 
    div.append("h3").text(headline); // <-- C 
 
    div.attr("class", "box") 
      .attr("style", "color:" + spec.color) // <-- D 
      .append("p") 
      .text(description); // <-- E 
 
    return instance; // <-- F 
  }; 

At the lines marked as A, B, and C, we can clearly see that instance, headline, and description are all internal private variables belonging to the SimpleWidget function object. While the render function is a function associated with the instance object which itself is defined as an object literal. Since functions are just objects, they can also be stored in an object/function, referred to by variables, contained in an array, and being passed as function arguments. The result of the execution of the SimpleWidget function is the returning of object instance at line I as follows:

function SimpleWidget(spec) { 
... 
  return instance; // <-- I 
} 

Curious readers will probably be asking by now how the variable scoping is resolved in this example since the render function has seemingly strange access to not only the instance, headline, and description variables but also the spec variable that is passed into the base SimpleWidget function. This seemingly strange variable scoping is actually determined by a simple static scoping rule. This rule can be thought as the following: whenever the runtime searches for a variable reference, the search will be first performed locally. When a variable declaration is not found (as in the case of headline on line C), the search continues toward the parent object (in this case, the SimpleWidget function is its static parent and the headline variable declaration is found at line B). If still not found, then this process will continue recursively to the next static parent, so on and so forth, till it reaches a global variable definition; if it is still not found, then a reference error will be generated for this variable. This scoping behavior is very different from variable resolution rules in some of the most popular languages, such as Java and C#.

It might take some time to get used to; however, don't worry too much about it if you still find it confusing. With more practice and by keeping the static scoping, rule in mind, you will be comfortable with this kind of scoping in no time.

This pattern is usually referred as functional when compared with the more popular prototype-based Pseudo-classical pattern. The advantage of the functional pattern is that it provides a much better mechanism for information hiding and encapsulation since the private variables, in our case, the headline and description variables, are only accessible by nested functions through the static scoping rule; therefore, the object returned by the SimpleWidget function is flexible yet more tamper-proof and durable.

Let's take a look at the following code; something strange has happened on line G:

instance.headline = function (h) { 
  if (!arguments.length) return headline; // <-- G 
  headline = h; 
  return instance; // <-- H 
}; 

You might be asking where this arguments variable on line G came from. It was never defined anywhere in this example. The arguments variable is a built-in hidden parameter that is available to functions when they are invoked. The arguments variable contains all arguments for a function invocation in an array.

This hidden parameter when combined with the ability to omit function argument in JavaScript allows you to write a function such as instance.headline with unspecified number of parameters. In this case, we can either have one argument h or none. Because arguments.length returns 0 when no parameter is passed, the headline function returns headline if no parameter is passed, otherwise it turns into a setter if parameter h is provided. To clarify this explanation, let's take a look at the following code snippet:

var widget = SimpleWidget({color: "#6495ed"}) 
    .headline("Simple Widget"); // set headline 
console.log(widget.headline()); // prints "Simple Widget" 

Here, you can see how the headline function can be used as both setter and getter with different parameters.

The next interesting aspect of this particular example is the capability of chaining functions to each other. This is also the predominant function invocation pattern that the D3 library deploys since most of the D3 functions are designed to be chainable to provide a more concise and contextual programming interface. This is actually quite simple once you understand the variable, parameter function concept. Since a variable-parameter function, such as the headline function, can serve as setter and getter at the same time, returning the instance object when it's acting as a setter allows you to immediately invoke another function on the invocation result, hence the chaining.

Let's take a look at the following code:

var widget = SimpleWidget({color: "#6495ed"}) 
  .headline("Simple Widget") 
  .description("This is ...") 
  .render(); 

In this example, the SimpleWidget function returns the instance object (as on line I).

function SimpleWidget(spec) { 
... 
    instance.headline = function (h) { 
        if (!arguments.length) return headline; // <-- G 
        headline = h; 
       return instance; // <-- H 
    }; 
... 
    return instance; // <-- I 
} 

Then, the headline function is invoked as a setter, which also returns the instance object (as on line H). The description function can then be invoked directly on its return, which again returns the instance object. Finally, the render function can be called.

Now, with the knowledge of functional JavaScript and a working ready-to-go D3 data visualization development environment, we are ready to dive into the rich concepts and techniques that D3 has to offer. However, before we take off, I would like to cover a few more important areas, how to find and share code and how to get help when you are stuck.

One of the great things about D3 when compared with other visualization options is that it offers a wealth of examples and tutorials that you can draw your inspiration from. During the course of creating my own open source visualization charting library and the creation of this book, I had relied heavily on these resources. I will list some of the most popular options available in this aspect. This list is by no means a comprehensive directory, but rather a starting place for you to explore: