Creating Selections

You typically obtain an initial selection instance by using one of the selection functions that operate on the global d3 object (see Table 3-1). You can then create subsets of this initial selection using member functions that operate on a Selection instance (see Table 3-2).

Selection methods accept a CSS selector string (see “CSS Selectors”) and return a collection of matching DOM elements in document order. The select(selector) functions return only the first matching element, while the selectAll(selector) methods return all matching elements. Both functions return an empty collection if no matching elements are found or if the selector is null or undefined. (Using CSS selector strings as selection criterion is the common case; we will discuss some additional options later in this chapter.)

As already indicated, selection methods nest when chained: any subsequent selection action will only act on the results of the previous one. (Technically, the previous action returns a new selection object, which becomes the target for the next action, and so on.) For example, the following code (taken straight from the D3 Reference Documentation) will select the first bold element in all paragraphs in the document:

bs = d3.selectAll( "p" ).select( "b" );

whereas the following snippet will select all <circle> elements inside the element with the ID id123:

cs = d3.select( "#id123" ).selectAll( "circle" );

You can obtain an initial selection by querying the global d3 object, which amounts to searching the entire document. Of course, Selection objects can be assigned to variables (as in the snippets just shown), passed to functions (as in Example 2-6), and so on.

Three types of selectors can be used with the select() and selectAll() functions:

• A CSS selector string (see “CSS Selectors”). This is the common case.

• The selection functions on the global d3 object accept either a node (for select()) or a collection of nodes (for selectAll()).

• When selection functions are invoked on a Selection object, they can accept an accessor function as the selector. For select(), this function must return a DOM Element instance or null if there is no match; for selectAll(), it must return an array of elements, possibly empty if there are no matches; for filter(), it must return a Boolean value indicating whether the current element should be retained.

Using a node as the selector may seem strange: why call select() if I already have a node in hand? If this is the case, then you call select() not to select a node, but as a convenient way to wrap the node in a Selection object, to make the Selection API available for it. This is commonly done inside of event handlers, when you want to bring the Selection API to work on the current node that has received the event. (You already saw an example of this in Example 2-8; further examples can be found in Figures 4-2 and 4-4.)

Understanding Selections

Most D3 programming begins with making a selection of elements from a document; this selection will then be modified. Selections are therefore the base material when working with D3. Two questions present themselves at this point:

• What actually is a selection?

• What can I do with a selection?

Technically, a Selection is a JavaScript wrapper around an ordered collection of DOM elements together with a set of methods to manipulate this collection. The API is declarative and supports method chaining, hence it is generally unnecessary to handle the elements of the collection explicitly.

Conceptually, a selection is a handle on (all or part of) the DOM tree, together with a set of operations that constitute the three activities listed earlier: selecting elements, binding data, and modifying appearance and behavior.

It is probably best to think of selections as opaque abstraction and operate on them only through the provided API. Besides functions to create selections based on specified criteria, most operations in the Selection API can be grouped into two sets: those that operate on the elements of a selection (for example, by changing the attributes of an element), and those that operate on the entire selection itself (for example, by adding or removing elements). Last, but not least, there is a small set of operations to manage the association between a data set and the elements of a selection. We will turn to that topic next.

Unmatched Items: The Enter and Exit Selections

If the number of data points and DOM elements is not equal, there will be a surplus of unmatched items, either of data points or DOM elements, but not both. Because items are matched starting at the beginning, the unmatched items will always be the trailing items in their respective collections. If items are joined on a key (see the next section), matching can fail in additional ways.

After a call to data(data), collections of any unmatched items are accessible through the enter() and exit() methods (see Figure 3-2).¹ Without a preceding call to data(), these methods return empty collections. The exit() method actually returns a Selection of DOM elements, but the enter() method only returns a collection of placeholder elements (by construction, there can be no actual nodes for surplus data points).

Figure 3-2. Binding data to a selection when the number of data points does not agree with the number of elements in the selection

The collections of surplus items can be used to create or remove items as necessary to make the graph match up with the data set. Given a set of surplus data items (as returned by enter()), you can create the needed DOM elements:

d3.select( "svg" ).selectAll( "circle" )
    .data( data ).enter()
    .append( "circle" ).attr( "fill", "red );

Similarly, given a selection of surplus DOM elements (as returned by exit()), you can remove these items as follows:

d3.select( "svg" ).selectAll( "circle" )
    .data( data ).exit()
    .remove();

The data() method itself returns the Selection of DOM elements that were successfully bound to data points; it can be used to update the appearance of these DOM elements. All three activities are used together in the General Update Pattern that will be discussed later in this chapter.

Joining on a Key

Sometimes joining data and nodes by simply aligning them in order is not enough. In particular when updating an existing set of nodes with new data, it may matter that the correct DOM elements receive new values.

Figure 3-3 shows an example: when the user clicks into the graph, the positions of the circles are updated with new data. Because the graph uses a smooth, animated transition to move the circles from their old positions to new ones, it is important that each circle receives the new data associated with it. Example 3-1 shows the commands to create Figure 3-3.

Figure 3-3. Updating a graph with new data: the appearance of the graph before the update (left) and after (right) (see Example 3-1)

function makeKeys() {
    var ds1 = [["Mary", 1], ["Jane", 4], ["Anne", 2]];            
    var ds2 = [["Anne", 5], ["Jane", 3]];                         

    var scX = d3.scaleLinear().domain([0, 6]).range([50, 300]),
        scY = d3.scaleLinear().domain([0, 3]).range([50, 150]);

    var j = -1, k = -1;                                           

    var svg = d3.select( "#key" );                                

    svg.selectAll( "text" )                                       
        .data(ds1).enter().append( "text" )
        .attr( "x", 20 ).attr( "y", d=>scY(++j) ).text( d=>d[0] );

    svg.selectAll("circle").data(ds1).enter().append( "circle" )  
        .attr( "r", 5 ).attr( "fill", "red" )
        .attr( "cx", d=>scX(d[1]) ).attr( "cy", d=>scY(++k)-5 );

    svg.on( "click", function() {
        var cs = svg.selectAll( "circle" ).data( ds2, d=>d[0] );  

        cs.transition().duration(1000).attr("cx", d=>scX(d[1]) ); 
        cs.exit().attr( "fill", "blue" );                         
    } );
}

The original data set.

The new data set. Note that it is incomplete: only two out of the three items will be updated with new data. Furthermore, the order of the items that are present is different than in the original data set.

Integers to track the vertical position of the text label and circle.

The active <svg> element as Selection, assigned to a variable for future reference.

Create the text labels…

… and the circles at their initial positions.

Inside the click event handler, the new data set is bound to the selection of circle elements. Notice the second argument to the data() function: this function defines the key on which data items will be joined.

A smooth, animated transition from the old positions to the new ones.

The exit() selection is now populated with Mary’s node, since in the last call to data(), no data point was bound to this node. We give this circle a different color to make it stand out.

This example shows how joining on a key is accomplished: you simply supply a second argument to the data(data, key) function. This additional argument must be an accessor function, which returns the desired key value as a string for each node or data point. This function will be evaluated for all items in the data set and for the data points bound to all nodes in the current selection, and items with matching keys will be bound to each other. Nonmatching items, either in the data set or the selection, populate the enter() and exit() selections as usual. If there are duplicate keys, either in the data set or the selection, only the first occurrence of the key (in collection order) is bound. Duplicates in the data set are placed in the enter() selection, duplicates in the current selection end up in the exit() selection. (See Figure 3-4.)

Figure 3-4. Binding data on a nontrivial key. All three of the data(), enter(), and exit() selections may be populated (left). If there are duplicate keys, either in the data set or selection, the corresponding items are placed in the enter() or exit() selections, respectively (right).

The General Update Pattern

A particular situation arises when an existing graph must be updated repeatedly with new data—for example, because data is only becoming available over time or because the graph must respond to user input. In this case, it is not enough to simply create additional graph elements corresponding to new inputs; the new elements must also be merged back with the existing elements to get the whole graph ready for the next iteration. The complete sequence of steps is therefore:

1. Bind new data to an existing selection of elements.

2. Remove any surplus items that do not have matching data associated anymore (the exit() selection).

3. Create and configure all items associated with data points that did not exist before (the enter() selection).

4. Merge the remaining items from the original selection with the newly created items from the enter() selection.

5. Update all items in the combined selection based on the current values of the bound data set.

The example in Example 3-2 defines two data sets; clicking into the graph area replaces the current data set with the other one and updates the graph accordingly.

Figure 3-5. The General Update Pattern: the appearance of the graph before the click (left) and after (right) (see Example 3-2)

function makeUpdate() {
    var ds1 = [ [2, 3, "green"], [1, 2, "red"], [2, 1, "blue"],   
                [3, 2, "yellow"] ];
    var ds2 = [ [1, 1, "red"], [3, 3, "black"], [1, 3, "lime"],
                [3, 1, "blue"]];

    var scX = d3.scaleLinear().domain([1, 3]).range([100, 200]),  
        scY = d3.scaleLinear().domain([1, 3]).range([50, 100]);

    var svg = d3.select( "#update" );                             

    svg.on( "click", function() {                                 
        [ ds1, ds2 ] = [ ds2, ds1 ];                              

        var cs = svg.selectAll( "circle" ).data( ds1, d=>d[2] );  

        cs.exit().remove();                                       

        cs = cs.enter().append( "circle" )                        
            .attr( "r", 5 ).attr( "fill", d=>d[2] )
            .merge( cs );                                         

        cs.attr( "cx", d=>scX(d[0]) ).attr( "cy", d=>scY(d[1]) ); 
    } );

    svg.dispatch( "click" );                                      
}

The two data sets. Each entry consists of the x and y coordinates, followed by the color. We will also use this color string as key when binding the data.

Scales to map the data values to screen coordinates.

Obtain a convenient handle on the <svg> element.

Register a click event handler for this <svg> element. All relevant action will take place inside this event handler.

In response to a user click, swap the data sets, replacing the current one with its alternate.

Bind the new data set to the (existing) <circle> elements in the graph, using the color name as key.

Remove those elements that are no longer bound to data (the exit() selection).

Create new elements for those data points that are new in this data set (the enter() selection).

Merge the existing elements retained from the earlier selection into the selection of newly created elements, and treat the combination as the “current” selection going forward.

Update all the elements in the combined selection using the bound data values.

This statement generates a synthetic click event. This triggers the event handler and therefore populates the graph when the page is first loaded. (We will revisit events in Chapter 4.)

The purpose of the merge() function may not be immediately apparent. But keep in mind that the enter and update selections (as returned by enter() and data(), respectively) are separate selections. If we want to operate on their elements without duplicating code, then we must combine them first. Moreover, a plain concatenation of the enter and update selections would not be appropriate; the merge() operation is designed to operate on the particular data representation of these two selections.²

Operating on Elements of a Selection

The Selection abstraction provides several methods to manipulate aspects of the individual DOM elements contained in the selection (see Table 3-4).

All function arguments are optional (as always in JavaScript). The functions in Table 3-4 can be used to set, get, or clear an attribute (or property,⁵ or style, …), depending on the value argument:

• If no value is supplied, the function returns the current value for the first nonnull element in the selection.

• If a null value is supplied, the attribute (or property) is removed from the element.

• If a constant value is supplied and not null, the attribute (or property) is set to the supplied value.

• If a function is supplied, it is evaluated for every element in the selection and its return value is used to modify the current element.

With the exception of the last two entries, the functions in Table 3-4 are thin wrappers around the equivalent functionality in the DOM API; you may want to compare the appropriate reference documentation for the precise semantics of some of the terms. (See, for example, the MDN Node Reference and the MDN Element Reference.)

Operating on Selections Themselves

The Selection abstraction provides several functions to operate on the entire selection, for example, to add, remove, or reorder elements (see Table 3-5).

The node() and nodes() functions are a way to obtain a reference to the actual DOM Node instances in the selection. This is occasionally useful; we will see examples in Chapter 4.⁶

We have seen the append() function in action several times before. The next example will demonstrate how to use insert() and sort(). Initially, an unordered list is populated from a static data set. If you mouse over the list, two more items are inserted into it. If you then mouse click into the list, the items are sorted, in descending order, according to their text content (see Example 3-3).

function makeSort() {
    var data = [ "Jane", "Anne", "Mary" ];

    var ul = d3.select( "#sort" );
    ul.selectAll( "li" ).data( data ).enter().append( "li" )      
        .text( d=>d );

    // insert on mouse enter
    var once;                                                     
    ul.on( "mouseenter", function() {                             
        if( once ) { return; }
        once = 1;
        ul.insert( "li", ":nth-child(2)" )                        
            .datum( "Lucy" ).text( "Lucy" );
        ul.insert( "li", ":first-child" )                         
            .datum( "Lisa" ).text( "Lisa" );
    } );

    // sort on click
    ul.on( "click", function() {                                  
        ul.selectAll( "li" ).sort( (a,b)=>( a<b?1:b<a?-1:0 ) );   
    } );
}

An unordered list is populated from the data set.

The variable once makes sure that the new items are only added to the list once.

Register the first of two event handlers for the list: if the mouse pointer enters the area occupied by the list, the callback is invoked.

The position where the new list items are to be inserted is specified through pseudo-classes. The :nth-child() pseudo-class starts counting at 1 (so that :nth-child(1) equals :first-child). Observe that we need to both set the data bound to each element (using datum()) and the visible text (using text()) separately when using insert().

Another element is added in front of the entire list, pushing the previously added element from the second to the third position. (Positions in pseudo-classes are evaluated at the time the pseudo-class is applied.)

A click event handler is registered as the second event handler on the list.

Upon a mouse click, the list elements are sorted, in descending order, based on the value of the data bound to them.

Remember that insert() does not bind data; an explicit call to datum() is required to add data to elements added using insert().

As a rule, methods that operate on individual elements of a selection (Table 3-4) return the current selection, whereas methods that operate on the entire selection (Table 3-5) return a new selection—but there are some exceptions. For reference, here are the functions that return new selections:

• select(), selectAll()

• data(), enter(), exit()

• append(), insert(), remove()

• merge(), filter(), sort()

• create()