Prepend node? Append existing? Insert at given location?

[mbostock]

Rename add to append, and introduce a similar method prepend for adding to the front.

[mbostock]

Also, it might be nice for these methods to allow references to existing nodes, via the W3C DOM API (e.g., document.getElementById("foo")). But then it seems like you'd want to support the argument being a function, and not just a string... in which case, perhaps the function could return the node to insert (or return a string for the name of the node to create?).

If we allowed a function, perhaps that would allow the function to use a selector internally, especially if apply returned the array of matched nodes.

[mbostock]

I like the idea of a prepend method for adding to the front. For inserting at a given location, a simple way to implement that is an insertAfter method, which creates a new node that is inserted after the context node, rather than as a child of the context node. This makes it easy to chain siblings together, as well:

d3.select("div")
  .append("span").attr("class", "sibling-1")
  .insertAfter("span").attr("class", "sibling-2")
  .insertAfter("span").attr("class", "sibling-3");

The alternative would be require capturing a reference to the selected div:

var div = d3.select("div");
div.append("span").attr("class", "sibling-1");
div.append("span").attr("class", "sibling-2");
div.append("span").attr("class", "sibling-3");

Or a way to select the parent. But you get the idea.

[mbostock]

I guess we could name it insert for brevity, though I like the idea of doing before and after. And I think after should be the default, since insert-before is a bit awkward.

[mbostock]

Added insert(tagName, referenceSelector). For example, insert("div", ":first-child") prepends child nodes.

[drarmstr]

Note a difference is that (at least with Chrome 37 and D3 3.4.6) JQuery's prepend() will insert before any text node content while D3's insert(...,':first-child') will only insert before normal nodes, not text nodes.