Function chaining

As we have seen so far, the D3 API is completely designed around the idea of function chaining. Therefore, it forms a DSL for building HTML/SVG elements dynamically. In this code example, we will take a look at how the entire body structure of the previous example can be constructed using D3 alone.

Note

If DSL is a new concept for you, I highly recommend checking out this excellent explanation on DSL by Martin Fowler in the form of an excerpt from his book Domain-Specific Languages. The excerpt can be found at http://www.informit.com/articles/article.aspx?p=1592379 .

Getting ready

Open your local copy of the following file in your web browser:

https://github.com/NickQiZhu/d3-cookbook-v2/blob/master/src/chapter2/function-chain.html .

How to do it...

Let's take a look at how a function chain can be used to produce concise and readable code that produces dynamic visual content:

<script type="text/javascript"> 
  var body = d3.select("body"); // <-- A 
 
  body.append("section") // <-- B 
      .attr("id", "section1") // <-- C 
    .append("p") // <-- D 
      .attr("class", "blue box") // <-- E 
    .append("p") // <-- F 
      .text("dynamic blue box"); // <-- G 
 
  body.append("section") 
      .attr("id", "section2") 
    .append("p") 
      .attr("class", "red box") 
    .append("p") 
      .text("dynamic red box"); 
</script> 

This code generates the following visual output (similar to what we saw in the previous chapter):

Function chain

How it works...

Despite the visual similarity to the previous example, the construction process of the DOM elements is significantly different in this example. As demonstrated by the code example, there is no static HTML element on the page contrary to the previous recipe where both the section and p elements existed.

Let's examine closely how these elements were dynamically created. On line A, a general selection was made to the top-level body element. The body selection result was cached using a local variable called body. Then, at line B, a new element section was appended to the body. Remember that the append function returns a new selection that contains the newly appended element; therefore, on line C, the id attribute can then be set on a newly created section element to section1. Afterward, on line D, a new p element was created and appended to #section1 with its CSS class set to blue box on line E. For the next step, similar to the previous line, on line F, a paragraph element was appended to the p element with its textual content set to dynamic blue box on line G.

As illustrated by this example, this chaining process can continue to create any structure of arbitrary complexity. In fact this is how a typical D3-based data visualization structure is created. Many visualization projects simply contain only a HTML skeleton and rely on D3 to create the rest. Getting comfortable with this way of function chaining is critical if you want to become efficient with the D3 library.

Note

Some of D3's modifier functions return a new selection, such as the select, append, and insert functions. It is a good practice to use different levels of indentation to differentiate the selection your function chain is being applied on.