D3 Selections

Tutorial

D3 has the ability to manipulate webpages. Before we can manipulate a page we have to select a section of it. D3 provides the d3.select function for this purpose. d3.select takes a string argument that is a CSS selector (we covered CSS selectors in SVG CSS). Below are some examples of using d3.select. 

// Select the first body element (if there are multiple, it returns the first)
var bodyElem = d3.select("body");

// Select the first element with id="carlos"
var carlosElem = d3.select("#carlos"); 

// Select the first element with class="rendon"
var rendonClass = d3.select(".rendon");

Selecting ALL THE THINGS

Often we will want to select all elements that match a CSS selector. In this case we use d3.selectAll which returns all elements that match selector instead of the first match like d3.select.

Manipulating Things

D3 has many methods that operate on a "selection" which is what is returned by both d3.select and d3.selectAll. To get started, let's explore two simple but useful methods you can call on a selection.

All together, we can now add a headline to the bottom of our document. This is the "Hello World" of D3. 

var bodySelection = d3.select("body"); 
var appendedH1 = bodySelection.append("h1"); 
appendedH1.text("Hi there");

In this example, I select the body and add a new "h1" to the bottom of it. I then set the text of the "h1" to "Hi there".

Selection Theory

You may have noticed that I talked about the select function without saying what it or the selectAll function actually return. All you know is that you can call append on them to add a new element to the document. The select and selectAll functions return D3 objects called selections. Before we define a selection, we need to talk about the document object model (DOM).

If you are unfamiliar with manipulating webpages with Javascript, DOM allows Javascript to access and manipulate webpage. In simpler words, the DOM is an API to modify a webpage. Each element of the page has an object corresponding to it that allows you to manipulate it. Because HTML pages are made up of a heirarchy of elements, the same is true for the DOM, which is a hierarchy of objects. A lot of the core of D3 is DOM manipulation and the special case of "joining" data to it, which will be covered in a later lab. 

var bodyElem = d3.select("body");

A D3 selection is a wrapper around DOM objects that has D3 methods like append, text, and others we will cover in future labs. If you inspect bodyElem you will see that it looks like an array of arrays that contain DOM elments. These arrays are not standard Javascript arrays because they have D3 methods implemented, such as append. If you are familar with DOM, the following is true:

d3.select("body")[0][0] === document.getElementsByTagName("body")[0]

On the left we can see how the DOM body object is wrapped in two special arrays. On the right we can see how we would access the DOM body object using DOM methods. If we only cared about getting access to the body DOM element to manipulate it, we could have used DOM methods. After all, the DOM exists for exactly this purpose. Unfortunately the DOM API is clunky, which is why wrapper libraries such as D3.js and even more famous jQuery exist. D3.js has a particular focus on enabling data driven documents to power documents, whereas jQuery makes it easy to select and manipulate documents with Javascript than it would be to use the DOM. In fact, it is possible and not uncommon to use jQuery and D3 together. This is especially true for projects that already use jQuery and are introducing D3.

Below we can see why people choose libraries like D3 and jQuery over using DOM directly. The code below adds a new H1 element with the text "Hello".

// Using DOM
var h1 = document.createElement("h1");
h1.innerText = "Hello";
document.getElementsByTagName("body")[0].appendChild(h1);

// Using D3
var body = d3.select("body")
var h1 = body.append("h1")
h1.text("Hello");

// Using D3 with method chaining (covered in next lab)
d3.select("body")
  .append("h1")
  .text("Hello");

Quiz

Match the description of the selection to the selection

"#barChart"      - elements with the id barChart
".barChart"      - elements with the class barChart
"barChart"       - elements with the tag barChart

With D3.js you need a selection to manipulate anything. True/False

Calling append on a selection adds a new element as the last child of the selection. True/False

Things to do

  1. Use d3.select() and text() to change the first list item's text "Topic 1" to the text "d3.select()". Note that list item one has the id "topic1".
  2. Use d3.selectAll() to select all elements of the class "selection". Use append() to add a new "p" element with the text "(about selection)".
  3. Use d3.select(), append() and text() to add a new list item with the text "d3.append()".

Extra Credit

Change the code on the left. Once you've made a change, the page will render on the right.