495 lines
11 KiB
Markdown
495 lines
11 KiB
Markdown
# Selections & Data Joins
|
|
|
|
## Why Data Joins Matter
|
|
|
|
**The Problem**: Manually creating, updating, and removing DOM elements for dynamic data is error-prone. You must track which elements correspond to which data items, handle array length changes, and avoid orphaned elements.
|
|
|
|
**D3's Solution**: Data joins establish declarative one-to-one correspondence between data arrays and DOM elements. Specify desired end state; D3 handles lifecycle automatically.
|
|
|
|
**Key Principle**: "Join data to elements, then manipulate elements using data." Changes to data propagate to visuals through re-joining.
|
|
|
|
---
|
|
|
|
## Selections Fundamentals
|
|
|
|
### Creating Selections
|
|
|
|
```javascript
|
|
// Select first matching element
|
|
const svg = d3.select('svg');
|
|
const firstCircle = d3.select('circle');
|
|
|
|
// Select all matching elements
|
|
const allCircles = d3.selectAll('circle');
|
|
const allRects = d3.selectAll('rect');
|
|
|
|
// CSS selectors supported
|
|
const blueCircles = d3.selectAll('circle.blue');
|
|
const chartGroup = d3.select('#chart');
|
|
```
|
|
|
|
**Key Methods**:
|
|
- `select(selector)`: Returns selection with first match
|
|
- `selectAll(selector)`: Returns selection with all matches
|
|
- Empty selection if no matches (not null)
|
|
|
|
---
|
|
|
|
### Modifying Elements
|
|
|
|
```javascript
|
|
// Set attributes
|
|
selection.attr('r', 10); // Set radius to 10
|
|
selection.attr('fill', 'steelblue'); // Set fill color
|
|
|
|
// Set styles
|
|
selection.style('opacity', 0.7);
|
|
selection.style('stroke-width', '2px');
|
|
|
|
// Set classes
|
|
selection.classed('active', true); // Add class
|
|
selection.classed('hidden', false); // Remove class
|
|
|
|
// Set text
|
|
selection.text('Label');
|
|
|
|
// Set HTML
|
|
selection.html('<strong>Bold</strong>');
|
|
|
|
// Set properties (DOM properties, not attributes)
|
|
selection.property('checked', true); // For checkboxes, etc.
|
|
```
|
|
|
|
**Attribute vs Style**:
|
|
- Use `.attr()` for SVG attributes: `x`, `y`, `r`, `fill`, `stroke`
|
|
- Use `.style()` for CSS properties: `opacity`, `font-size`, `color`
|
|
|
|
---
|
|
|
|
### Creating and Removing Elements
|
|
|
|
```javascript
|
|
// Append child element
|
|
const g = svg.append('g'); // Returns new selection
|
|
g.attr('transform', 'translate(50, 50)');
|
|
|
|
// Insert before sibling
|
|
svg.insert('rect', 'circle'); // Insert rect before first circle
|
|
|
|
// Remove elements
|
|
selection.remove(); // Delete from DOM
|
|
```
|
|
|
|
---
|
|
|
|
### Method Chaining
|
|
|
|
All modification methods return the selection, enabling chains:
|
|
|
|
```javascript
|
|
d3.select('svg')
|
|
.append('circle')
|
|
.attr('cx', 100)
|
|
.attr('cy', 100)
|
|
.attr('r', 50)
|
|
.attr('fill', 'steelblue')
|
|
.style('opacity', 0.7)
|
|
.on('click', handleClick);
|
|
```
|
|
|
|
**Why Chaining Works**: Methods mutate selection and return it.
|
|
|
|
---
|
|
|
|
## Data Join Pattern
|
|
|
|
### Basic Join
|
|
|
|
```javascript
|
|
const data = [10, 20, 30, 40, 50];
|
|
|
|
svg.selectAll('circle') // Select all circles (may be empty)
|
|
.data(data) // Bind data array
|
|
.join('circle') // Create/update/remove to match data
|
|
.attr('r', d => d); // Set attributes using data
|
|
```
|
|
|
|
**What `.join()` Does**:
|
|
1. **Enter**: Creates `<circle>` elements for data items without elements (5 circles created if none exist)
|
|
2. **Update**: Updates existing circles if some already exist
|
|
3. **Exit**: Removes circles if data shrinks (e.g., data becomes `[10, 20]`, 3 circles removed)
|
|
|
|
---
|
|
|
|
### Accessor Functions
|
|
|
|
Pass functions to `.attr()` and `.style()` receiving `(datum, index)` parameters:
|
|
|
|
```javascript
|
|
.attr('cx', (d, i) => i * 50 + 25) // d = data value, i = index
|
|
.attr('cy', 100) // Static value
|
|
.attr('r', d => d) // Radius = data value
|
|
```
|
|
|
|
**Pattern**: `(d, i) => expression`
|
|
- `d`: Datum (current array element)
|
|
- `i`: Index in array (0-based)
|
|
|
|
---
|
|
|
|
### Data with Objects
|
|
|
|
```javascript
|
|
const data = [
|
|
{name: 'A', value: 30, color: 'red'},
|
|
{name: 'B', value: 80, color: 'blue'},
|
|
{name: 'C', value: 45, color: 'green'}
|
|
];
|
|
|
|
svg.selectAll('circle')
|
|
.data(data)
|
|
.join('circle')
|
|
.attr('r', d => d.value) // Access object properties
|
|
.attr('fill', d => d.color);
|
|
```
|
|
|
|
---
|
|
|
|
## Enter, Exit, Update Pattern
|
|
|
|
For fine-grained control (especially with custom transitions):
|
|
|
|
```javascript
|
|
svg.selectAll('circle')
|
|
.data(data)
|
|
.join(
|
|
// Enter: new elements
|
|
enter => enter.append('circle')
|
|
.attr('r', 0) // Start small
|
|
.call(enter => enter.transition().attr('r', d => d.value)),
|
|
|
|
// Update: existing elements
|
|
update => update
|
|
.call(update => update.transition().attr('r', d => d.value)),
|
|
|
|
// Exit: removing elements
|
|
exit => exit
|
|
.call(exit => exit.transition().attr('r', 0).remove())
|
|
);
|
|
```
|
|
|
|
**When to Use**:
|
|
- Custom enter animations (fade in, slide in)
|
|
- Custom exit animations (fade out, fall down)
|
|
- Different behavior for enter vs update
|
|
|
|
**When NOT Needed**: Simple updates use `.join('circle').transition()...` after join.
|
|
|
|
---
|
|
|
|
## Key Functions (Object Constancy)
|
|
|
|
**Problem**: By default, data join matches by index. If data reorders, elements don't track items correctly.
|
|
|
|
```javascript
|
|
// Without key function
|
|
const data1 = [{id: 'A', value: 30}, {id: 'B', value: 80}];
|
|
const data2 = [{id: 'B', value: 90}, {id: 'A', value: 40}]; // Reordered!
|
|
|
|
// Element 0 bound to A (30), then B (90) - wrong!
|
|
// Element 1 bound to B (80), then A (40) - wrong!
|
|
```
|
|
|
|
**Solution**: Key function returns unique identifier:
|
|
|
|
```javascript
|
|
svg.selectAll('circle')
|
|
.data(data, d => d.id) // Key function
|
|
.join('circle')
|
|
.attr('r', d => d.value);
|
|
|
|
// Now element tracks data item by ID, not position
|
|
```
|
|
|
|
**Key Function Signature**: `(datum) => uniqueIdentifier`
|
|
|
|
**When to Use**:
|
|
- Data array reorders
|
|
- Data array filters (items removed/added)
|
|
- Transitions where element identity matters
|
|
|
|
---
|
|
|
|
## Updating Scales
|
|
|
|
When data changes, update scale domains:
|
|
|
|
```javascript
|
|
function update(newData) {
|
|
// Recalculate domain
|
|
yScale.domain([0, d3.max(newData, d => d.value)]);
|
|
|
|
// Update axis
|
|
svg.select('.y-axis')
|
|
.transition()
|
|
.duration(500)
|
|
.call(d3.axisLeft(yScale));
|
|
|
|
// Update bars
|
|
svg.selectAll('rect')
|
|
.data(newData, d => d.id) // Key function
|
|
.join('rect')
|
|
.transition()
|
|
.duration(500)
|
|
.attr('y', d => yScale(d.value))
|
|
.attr('height', d => height - yScale(d.value));
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Event Handling
|
|
|
|
```javascript
|
|
selection.on('click', function(event, d) {
|
|
// `this` = DOM element
|
|
// `event` = mouse event object
|
|
// `d` = bound datum
|
|
|
|
console.log('Clicked', d);
|
|
d3.select(this).attr('fill', 'red');
|
|
});
|
|
```
|
|
|
|
**Common Events**:
|
|
- Mouse: `click`, `mouseover`, `mouseout`, `mousemove`
|
|
- Touch: `touchstart`, `touchend`, `touchmove`
|
|
- Drag: Use `d3.drag()` behavior instead
|
|
- Zoom: Use `d3.zoom()` behavior instead
|
|
|
|
**Event Object Properties**:
|
|
- `event.pageX`, `event.pageY`: Mouse position
|
|
- `event.target`: DOM element
|
|
- `event.preventDefault()`: Prevent default behavior
|
|
|
|
---
|
|
|
|
## Selection Iteration
|
|
|
|
```javascript
|
|
// Apply function to each element
|
|
selection.each(function(d, i) {
|
|
// `this` = DOM element
|
|
// `d` = datum
|
|
// `i` = index
|
|
console.log(d);
|
|
});
|
|
|
|
// Call function with selection
|
|
function styleCircles(selection) {
|
|
selection
|
|
.attr('stroke', 'black')
|
|
.attr('stroke-width', 2);
|
|
}
|
|
|
|
svg.selectAll('circle').call(styleCircles);
|
|
```
|
|
|
|
**Use `.call()` for**: Reusable functions, axes, behaviors (drag, zoom).
|
|
|
|
---
|
|
|
|
## Filtering and Sorting
|
|
|
|
```javascript
|
|
// Filter selection
|
|
const largeCircles = svg.selectAll('circle')
|
|
.filter(d => d.value > 50);
|
|
|
|
largeCircles.attr('fill', 'red');
|
|
|
|
// Sort elements in DOM
|
|
svg.selectAll('circle')
|
|
.sort((a, b) => a.value - b.value); // Ascending order
|
|
```
|
|
|
|
**Note**: `.sort()` reorders DOM elements, affecting document flow and rendering order.
|
|
|
|
---
|
|
|
|
## Nested Selections
|
|
|
|
```javascript
|
|
// Parent selection
|
|
const groups = svg.selectAll('g')
|
|
.data(data)
|
|
.join('g');
|
|
|
|
// Child selection within each group
|
|
groups.selectAll('circle')
|
|
.data(d => [d, d, d]) // 3 circles per group
|
|
.join('circle')
|
|
.attr('r', 5);
|
|
```
|
|
|
|
**Pattern**: Each parent element gets its own child selection.
|
|
|
|
---
|
|
|
|
## Selection vs Element
|
|
|
|
```javascript
|
|
// Selection (D3 wrapper)
|
|
const selection = d3.select('circle');
|
|
selection.attr('r', 10); // D3 methods
|
|
|
|
// Raw DOM element
|
|
const element = selection.node();
|
|
element.setAttribute('r', 10); // Native DOM methods
|
|
```
|
|
|
|
**Use `.node()` to**:
|
|
- Access native DOM properties
|
|
- Use with non-D3 libraries
|
|
- Perform operations D3 doesn't support
|
|
|
|
---
|
|
|
|
## Common Patterns
|
|
|
|
### Pattern 1: Update Function
|
|
|
|
```javascript
|
|
function update(newData) {
|
|
const circles = svg.selectAll('circle')
|
|
.data(newData, d => d.id);
|
|
|
|
circles.join('circle')
|
|
.attr('cx', d => xScale(d.x))
|
|
.attr('cy', d => yScale(d.y))
|
|
.attr('r', 5);
|
|
}
|
|
|
|
// Call on data change
|
|
update(data);
|
|
```
|
|
|
|
---
|
|
|
|
### Pattern 2: Conditional Styling
|
|
|
|
```javascript
|
|
svg.selectAll('circle')
|
|
.data(data)
|
|
.join('circle')
|
|
.attr('r', 5)
|
|
.attr('fill', d => d.value > 50 ? 'red' : 'steelblue');
|
|
```
|
|
|
|
---
|
|
|
|
### Pattern 3: Data-Driven Classes
|
|
|
|
```javascript
|
|
svg.selectAll('rect')
|
|
.data(data)
|
|
.join('rect')
|
|
.classed('high', d => d.value > 80)
|
|
.classed('medium', d => d.value > 40 && d.value <= 80)
|
|
.classed('low', d => d.value <= 40);
|
|
```
|
|
|
|
---
|
|
|
|
### Pattern 4: Multiple Attributes
|
|
|
|
```javascript
|
|
selection.attr('stroke', 'black').attr('stroke-width', 2).attr('fill', 'none');
|
|
```
|
|
|
|
---
|
|
|
|
## Debugging
|
|
|
|
```javascript
|
|
console.log(selection.size()); // Number of elements
|
|
console.log(selection.nodes()); // Array of DOM elements
|
|
console.log(selection.data()); // Array of bound data
|
|
```
|
|
|
|
---
|
|
|
|
## Common Pitfalls
|
|
|
|
### Pitfall 1: Forgetting to Return Accessor Value
|
|
|
|
```javascript
|
|
// WRONG - undefined attribute
|
|
.attr('r', d => { console.log(d); })
|
|
|
|
// CORRECT
|
|
.attr('r', d => {
|
|
console.log(d);
|
|
return d.value; // Explicit return
|
|
})
|
|
|
|
// Or use arrow function implicit return
|
|
.attr('r', d => d.value)
|
|
```
|
|
|
|
---
|
|
|
|
### Pitfall 2: Not Using Key Function for Dynamic Data
|
|
|
|
```javascript
|
|
// WRONG - elements don't track items
|
|
.data(dynamicData)
|
|
|
|
// CORRECT
|
|
.data(dynamicData, d => d.id)
|
|
```
|
|
|
|
---
|
|
|
|
### Pitfall 3: Selecting Before Elements Exist
|
|
|
|
```javascript
|
|
// WRONG - circles don't exist yet
|
|
const circles = d3.selectAll('circle');
|
|
svg.append('circle'); // This circle not in `circles` selection
|
|
|
|
// CORRECT - select after creating
|
|
svg.append('circle');
|
|
const circles = d3.selectAll('circle');
|
|
|
|
// Or use enter selection
|
|
const circles = svg.selectAll('circle')
|
|
.data(data)
|
|
.join('circle'); // Creates circles, returns selection
|
|
```
|
|
|
|
---
|
|
|
|
### Pitfall 4: Modifying Selection Doesn't Update Variable
|
|
|
|
```javascript
|
|
const circles = svg.selectAll('circle');
|
|
circles.attr('fill', 'red'); // OK - modifies elements
|
|
|
|
circles.data(newData).join('circle'); // Returns NEW selection
|
|
// `circles` variable still references OLD selection
|
|
|
|
// CORRECT - reassign
|
|
circles = svg.selectAll('circle')
|
|
.data(newData)
|
|
.join('circle');
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- Learn scale functions: [Scales & Axes](scales-axes.md)
|
|
- See data join in action: [Workflows](workflows.md)
|
|
- Add transitions: [Transitions & Interactions](transitions-interactions.md)
|