Selecting a single element

It is very common that at times you will need to select a single element on a page to perform some visual manipulation. This recipe will show you how to perform a targeted single element selection in D3 using a CSS selector.

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/single-selection.html .

How to do it...

Let's select something (a paragraph element perhaps) and produce the classic hello world on screen.

<p id="target"></p> <!-- A --> 
 
<script type="text/javascript"> 
    d3.select("p#target") // <-- B 
    .text("Hello world!"); // <-- C 
</script> 

This recipe simply produces text Hello world! on your screen.

How it works...

The d3.select command is used to perform a single-element selection in D3. This method accepts a string that represents a valid CSS3 selector or an element object if you already have a reference to the element you want to select. The d3.select command returns a D3 selection object on which you can chain modifier functions to manipulate the attribute, content, or inner HTML of this element.

Note

More than one element can be selected using the selector, provided only the first element is returned in the selection.

In this example, we simply select the paragraph element with target as the value of id at line B, and then set its textual content to Hello world! on line C. All D3 selections support a set of standard modifier functions. The text function we have shown in this particular example is one of them. The following are some of the most common modifier functions you will encounter throughout this book:

• selection.attr: This function allows you to retrieve or modify a given attribute on the selected element(s):

       // set foo attribute to goo on p element 
       d3.select("p").attr("foo", "goo");  
       // get foo attribute on p element 
       d3.select("p").attr("foo"); 
  

• selection.classed: This function allows you to add or remove CSS classes on the selected element(s):

       // test to see if p element has CSS class goo 
       d3.select("p").classed("goo"); 
       // add CSS class goo to p element 
       d3.select("p").classed("goo", true); 
       // remove CSS class goo from p element. classed function 
       // also accepts a function as the value so the decision  
       // of adding and removing can be made dynamically 
       d3.select("p").classed("goo", function(){return false;}); 
  

• selection.style: This function lets you set the CSS style with a specific name to the specific value on the selected element(s):

       // get p element's style for font-size 
       d3.select("p").style("font-size"); 
       // set font-size style for p to 10px 
       d3.select("p").style("font-size", "10px"); 
       // set font-size style for p to the result of some  
       // calculation. style function also accepts a function as  
       // the value can be produced dynamically 
       d3.select("p").style("font-size", function(){  
           return parseFloat(d3.select(this).style('font-size')) + 
               10 + 'px'; 
       }); 
  

• Variable this in the preceding anonymous function is the DOM element object for the selected element <p>; therefore, it needs to be wrapped in d3.select again in order to access its style attribute.
• selection.text: This function allows you to access and set the text content of the selected element(s) as follows:

       // get p element's text content 
       d3.select("p").text(); 
       // set p element's text content to "Hello" 
       d3.select("p").text("Hello"); 
       // text function also accepts a function as the value,  
       // thus allowing setting text content to some dynamically  
       // produced content 
       d3.select("p").text(function(){ 
         return Date(); 
       }); 
  

• selection.html: This function lets you modify the element's inner HTML content as shown in the following:

       // get p element's inner html content 
       d3.select("p").html(); 
       // set p element's inner html content to "<b>Hello</b>" 
       d3.select("p").html("<b>Hello</b>"); 
       // html function also accepts a function as the value,  
       // thus allowing setting html content to some dynamically  
       // produced message 
       d3.select("p").html(function(){ 
         return d3.select(this).text() +  
           " <span style='color: blue;'>D3.js</span>"; 
       }); 
  

These modifier functions work on both single-element and multi-element selection results. When applied to multi-element selections, these modifications will be applied to each and every selected element. We will see them in action in other, more complex  recipes that will be covered later in this chapter.

When a function is used as a value in these modifier functions, there are actually some built-in parameters passed to these functions to enable data-driven calculation. This data-driven approach is what gives D3 its power and its name (Data-Driven Document) and will be discussed in detail in the next chapter.