inverted iteration for nested data binds
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src update for d3 v4 Sep 12, 2016
test update for d3 v4 Sep 12, 2016
LICENSE update for d3 v4 Sep 12, 2016
README.md
eslintrc.json
index.js update for d3 v4 Sep 12, 2016
package.json update uglify Nov 29, 2017

README.md

d3-parent

An inversion of d3.select which searches up through the DOM hierarchy instead of down, like a D3 equivalent of the .parents() method from jQuery. Provides a more stable and robust API around parentNode, simplifies traversal of deeply nested hierarchical data joins, and allows inverted manipulation of data binds.

demonstration

Setup

Load this script after D3.js but before your project code.

<html>
  <head>
    <script type="text/javascript" charset="utf-8" src="./d3.v3.js"></script>
    <script type="text/javascript" charset="utf-8" src="./d3-parent.js"></script>
    <script type="text/javascript" charset="utf-8" src="./project.js"></script>
  </head>

Usage

Call the .parent() method on any selection to return a selection of the parent nodes for each item:

  // probably returns a list node such as <ul> or <ol>
  // depending on the markup
  var list_items = d3.select('li');
  var list = list_items.parent();

Optionally provide a selector string to iterate upward through the DOM until a match is found:

  var list_items_links = d3.selectAll('a');
  var list = list_items.parent('ul');

Method calls can be chained together to traverse upward in steps:

  var list_items_links = d3.selectAll('a');
  var list = list_items.parent().parent();

Redundant node references are allowed in the results, and will be returned if you request them:

  var divs = d3.selectAll('div');
  // multiple references to the root node
  var parents = divs.parent('html');

To remove redundant node references, use selection.filter():

  var divs = d3.selectAll('div');
  // multiple references to the root node
  var parents = divs.parent('html');
  var nodes = [];
  // single reference to the root node
  var unique = parents.filter(function(d, i) {
    if (nodes.indexOf(this) === -1) {
      nodes.push(this);
      return true;
    } else {
      return false;
    }
  });

Notes

  • d3-parent can be thought of as a more robust API for parentNode, which is usually necessary for traversing upward in the DOM hierarchy, but is extremely fragile since it must be precisely matched to the document structure.
  • The group index argument is available in nested data joins to traverse upward in the bound data models, but it only moves up by one level. For deeply nested data join hierarchies, d3.parent will usually be a much simpler way to jump to a different level of data binding.
  • The parent() method provides an inverted equivalent to d3.select, but there is no equivalent method for d3.selectAll() which matches multiple parent nodes, because that would break grouping.
  • Existing group and item indices remain intact after DOM traversal, which allows you to programmatically operate on parent nodes using data bound to child nodes.