selection.data method
selection.data binds elements to data.
d3-selection/joining
32 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
selection.join method
selection.join enters, updates or exits elements based on data.
selection.enter method
selection.enter gets the enter selection, which represents data missing elements.
selection.exit method
selection.exit gets the exit selection, which represents elements missing data.
selection.datum method
selection.datum gets or sets element data without joining.
selection.merge method
selection.merge merges this selection with another.
selection.data() signature and behavior
selection.data(data, key) binds an array of data with selected elements, returning the update selection. It also defines enter and exit selections. The data parameter is an array of arbitrary values or a function that returns an array for each group. When data is assigned to an element, it is stored in the __data__ property, making the data sticky and available on re-selection. If data is not specified, the method returns the array of data for the selected elements. This method cannot be used to clear bound data; use selection.datum() instead.
selection.exit() signature and behavior
selection.exit() returns the exit selection: existing DOM elements in the selection for which no new datum was found. The exit selection is empty for selections not returned by selection.data(). The exit selection is typically used to remove superfluous elements corresponding to old data.
selection.data() key function behavior
If no key function is specified, the first datum is assigned to the first element, the second datum to the second element, and so on. If a key function is specified, it controls which datum is assigned to which element. The key function is evaluated for each selected element with parameters: current datum (d), current index (i), and current group (nodes), with this as the current DOM element. It is also evaluated for each new datum with parameters: current datum (d), current index (i), and group's new data, with this as the group's parent DOM element. The datum for a given key is assigned to the element with the matching key. Multiple elements with the same key are put into the exit selection; multiple data with the same key are put into the enter selection.
selection.data() with multiple groups
When data is specified for each group in the selection and the selection has multiple groups, data should typically be specified as a function. This function is evaluated for each group in order, being passed the group's parent datum (d, which may be undefined), the group index (i), and the selection's parent nodes (nodes), with this as the group's parent element.
selection.data() order guarantees
The update and enter selections are returned in data order, while the exit selection preserves the selection order prior to the join. If a key function is specified, the order of elements in the selection may not match their order in the document; use selection.order() or selection.sort() as needed.
selection.data() example: table from matrix
const matrix = [ [11975, 5871, 8916, 2868], [ 1951, 10048, 2060, 6171], [ 8010, 16145, 8090, 8045], [ 1013, 990, 940, 6907] ]; d3.select("body") .append("table") .selectAll("tr") .data(matrix) .join("tr") .selectAll("td") .data(d => d) .join("td") .text(d => d); This example creates an HTML table from a matrix of numbers using nested data joins.
selection.data() example: join by key function
const data = [ {name: "Locke", number: 4}, {name: "Reyes", number: 8}, {name: "Ford", number: 15}, {name: "Jarrah", number: 16}, {name: "Shephard", number: 23}, {name: "Kwon", number: 42} ]; d3.selectAll("div") .data(data, function(d) { return d ? d.name : this.id; }) .text(d => d.number); This example joins data by key using a function that uses the datum name if present, otherwise falls back to the element's id property.
selection.join() signature and behavior
selection.join(enter, update, exit) appends, removes and reorders elements as necessary to match data previously bound by selection.data(), returning the merged enter and update selection. This method is a convenient alternative to the explicit general update pattern, replacing selection.enter(), selection.exit(), selection.append(), selection.remove(), and selection.order().
selection.join() string shorthand
The enter function may be specified as a string shorthand, which is equivalent to selection.append() with the given element name. Optional update and exit functions may be specified; they default to the identity function and calling selection.remove(), respectively.
selection.join() simple example
svg.selectAll("circle") .data(data) .join("circle") .attr("fill", "none") .attr("stroke", "black"); This example shows the string shorthand for selection.join(), which appends circle elements for each data point.
selection.join() function callbacks example
svg.selectAll("circle") .data(data) .join( enter => enter.append("circle"), update => update, exit => exit.remove() ) .attr("fill", "none") .attr("stroke", "black"); This example shows the expanded form of selection.join() with separate functions for enter, update, and exit selections, equivalent to the string shorthand.
selection.join() with different styling for enter and update
svg.selectAll("circle") .data(data) .join( enter => enter.append("circle").attr("fill", "green"), update => update.attr("fill", "blue") ) .attr("stroke", "black"); This example shows how to set different fill colors for enter and update selections while applying common attributes after the join.
selection.join() merge behavior
The selections returned by the enter and update functions are merged and then returned by selection.join. If the enter and update functions return transitions, their underlying selections are merged and then returned by selection.join. The return value of the exit function is not used. You can animate enter, update and exit by creating transitions inside the enter, update and exit functions.
selection.enter() signature and behavior
selection.enter() returns the enter selection: placeholder nodes for each datum that had no corresponding DOM element in the selection. The enter selection is empty for selections not returned by selection.data(). The enter selection is typically used to create missing elements corresponding to new data.
selection.enter() example: create divs from array
const div = d3.select("body") .selectAll("div") .data([4, 8, 15, 16, 23, 42]) .enter().append("div") .text(d => d); This example creates six new DIV elements from an array of numbers, appends them to the body in order, and assigns their text content as the associated number.
selection.enter() placeholders and parent element
Conceptually, the enter selection's placeholders are pointers to the parent element. The enter selection is typically only used transiently to append elements, and is often merged with the update selection after appending, such that modifications can be applied to both entering and updating elements.
selection.exit() example: update and remove elements
div = div.data([1, 2, 4, 8, 16, 32], d => d); div.enter().append("div").text(d => d); div.exit().remove(); This example updates DIV elements with a new array of numbers using a key function. It appends new elements for [1, 2, 32] using the enter selection and removes exiting elements [15, 23, 42] using the exit selection.
selection.exit() order preservation
The order of DOM elements can be reordered if the new data's order differs from the old data's order. Use selection.order() to reorder elements in the DOM when necessary.
selection.datum() signature and behavior
selection.datum(value) gets or sets the bound data for each selected element. Unlike selection.data(), this method does not compute a join and does not affect indexes or the enter and exit selections. If a value is not specified, it returns the bound datum for the first (non-null) element in the selection.
selection.datum() with constant and function values
If a value is specified as a constant, all elements are given the same datum. If the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). A null value will delete the bound data.
selection.datum() example: expose HTML5 custom data attributes
selection.datum(function() { return this.dataset; }) This example exposes HTML5 custom data attributes by setting each element's data as the built-in dataset property. For elements like <li data-username="shawnbot">Shawn Allen</li>, this makes the data-username attribute accessible as bound data.
selection.merge() signature and behavior
selection.merge(other) returns a new selection merging this selection with the specified other selection or transition. The returned selection has the same number of groups and the same parents as this selection. Any missing (null) elements in this selection are filled with the corresponding element, if present (not null), from the specified selection.
selection.merge() index-based merging
Merging is based on element index, so you should use operations that preserve index, such as selection.select() instead of selection.filter(). If both this selection and the specified other selection have (non-null) elements at the same index, this selection's element is returned in the merge and the other selection's element is ignored.
selection.merge() example: merge odd and even selections
const odd = selection.select(function(d, i) { return i & 1 ? this : null; }); const even = selection.select(function(d, i) { return i & 1 ? null : this; }); const merged = odd.merge(even); This example shows how to merge two selections by selecting odd and even indexed elements separately and then merging them back together.
selection.merge() internal use in selection.join()
selection.merge() is used internally by selection.join() to merge the enter and update selections after binding data. It can also be used explicitly for custom merging operations.
selection.merge() not for concatenation
selection.merge() is not intended for concatenating arbitrary selections. If both selections have non-null elements at the same index, this selection's element is returned and the other selection's element is ignored.