New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: forceLink seems to replace string IDs with links to objects, but this is not documented #103

Closed
safinaskar opened this Issue Aug 26, 2017 · 1 comment

Comments

2 participants
@safinaskar

safinaskar commented Aug 26, 2017

forceLink seems to replace string IDs with links to objects, but this is not documented. I. e. https://github.com/d3/d3-force/blob/master/README.md#forceLink doesn't say anything about this. I discovered this only by experimenting with code

@mbostock

This comment has been minimized.

Show comment
Hide comment
@mbostock

mbostock Aug 27, 2017

Member

It’s implied in two places, but I agree it should be clearer. In link.links:

Each link is an object with the following properties:

  • source - the link’s source node; see simulation.nodes
  • target - the link’s target node; see simulation.nodes
  • index - the zero-based index into links, assigned by this method

For convenience, a link’s source and target properties may be initialized using numeric or string identifiers rather than object references; see link.id.

And in link.id:

The id accessor is invoked for each node whenever the force is initialized, as when the nodes or links change, being passed the node and its zero-based index.

So the implication is that if you don’t specify link objects whose link.source and link.target properties are objects, they will be replaced by object references whenever the link force is initialized. See the implementation here:

d3-force/src/link.js

Lines 60 to 61 in c7d165a

if (typeof link.source !== "object") link.source = find(nodeById, link.source);
if (typeof link.target !== "object") link.target = find(nodeById, link.target);

This applies not just to string identifiers but the default numeric indexes, too (when you haven’t specified a custom link.id accessor).

Forces are initialized when they are attached to simulations and when the simulation’s nodes change. Related, simulation.force and simulation.nodes should explicitly mention that they (re-)initialize forces; this is currently only documented by force.initialize.

Member

mbostock commented Aug 27, 2017

It’s implied in two places, but I agree it should be clearer. In link.links:

Each link is an object with the following properties:

  • source - the link’s source node; see simulation.nodes
  • target - the link’s target node; see simulation.nodes
  • index - the zero-based index into links, assigned by this method

For convenience, a link’s source and target properties may be initialized using numeric or string identifiers rather than object references; see link.id.

And in link.id:

The id accessor is invoked for each node whenever the force is initialized, as when the nodes or links change, being passed the node and its zero-based index.

So the implication is that if you don’t specify link objects whose link.source and link.target properties are objects, they will be replaced by object references whenever the link force is initialized. See the implementation here:

d3-force/src/link.js

Lines 60 to 61 in c7d165a

if (typeof link.source !== "object") link.source = find(nodeById, link.source);
if (typeof link.target !== "object") link.target = find(nodeById, link.target);

This applies not just to string identifiers but the default numeric indexes, too (when you haven’t specified a custom link.id accessor).

Forces are initialized when they are attached to simulations and when the simulation’s nodes change. Related, simulation.force and simulation.nodes should explicitly mention that they (re-)initialize forces; this is currently only documented by force.initialize.

@mbostock mbostock closed this in b20fa13 Sep 23, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment