D3: using * name * argument in transition.tween ()

Question

According to the documentation for transition.tween() ,

calling transition.tween(name, factory) ...

Registers custom animation for the specified name. When the transition begins, the specified factory function will be called for each selected element in the transition, passing the data of the element (d) and index (i) as arguments, and the element as the context ( this ).

What is the purpose of the named tween? Since .tween needs a reference to the transition used, it seems unlikely that it would be useful to reuse the same animation on different transitions. As far as I can tell, this name has no purpose.

To illustrate my point, I recently used a custom transition.tween() to transition the text and path elements into a group at the same time. HERE is a link to an example. Relevant Code:

 function groupTween(transition, newAngle) { transition.tween("thisNameMeansNothing", function() { var d = d3.select(this).datum(); var interpolate = d3.interpolate(d.endAngle, newAngle); return function(t) { d.endAngle = interpolate(t); d3.select(this).select("path") .attr("d", arc); d3.select(this).select("text") .attr("transform", function(d) { return "translate(" + arc.centroid(d) + ")"; }) .text(function(d) {return formatLabel(d.endAngle);}); }; }); } 

The name is never used except for registering the twin function, but must be specified, since it is the required first argument to .tween() .

Question

Can this name be referenced later? If so, how? Where is such a link stored? In addition, any examples of this use in the wild would be very helpful.

Answer 1

This is a great question.

I suspect that the quick answer about why the name parameter exists at all is that all other transient twins are associated with some name (for example, an attribute or style), and it was convenient for them to work the same way for everyone.

The name is used in the background, in the animation objects that are set for each element. If you create a transition long enough, you can use your DOM inspector to see the changing DOM properties for each element. There will be something called __transition__ , which stores an array with information about the active transition of the element and any planned sub-transitions.

This transition information object does not match the transition selection that you create in your code. Instead, it contains the specific data needed to calculate the transition for this particular element: the start time, duration, and the specific function of the twin factory that will be used to generate the animation for this element. For your custom tween, this is your function(d,i) , which will return function(t) , but there are similar functions created by all standard transition methods.

These twin functions are stored in this transition information object by name, and your custom twist is stored using the name you give it. This means that the one real effect of setting the name is that if you use the same name twice in the same transition, you will rewrite the first version:

http://fiddle.jshell.net/9gPrY/

 pTrans .style("color", "red") .style("color", "green") .tween("countdown", function(d,i){ var check; return function(t){ this.textContent = percent(t); if (!check && t > 0.1) { console.log("That wasn't supposed to happen"); check = true; } }; }) .tween("countdown", function(d,i){ var check; return function(t){ this.textContent = percent(t); if (!check && t > 0.1) { printTweens(); check = true; } }; }); 

The second color transition transition cancels the previous one, and the second countdown twing also cancels the first. Only two tween functions print, one called style.color and one called countdown .

Now I have not conducted exhaustive testing, but it seems that this is so.

So, in a way, perhaps this is a poor design, some internal library guts scrambling into the API. But I believe that there may be times when you would like to be able to rewrite the function of the twin side through a part, and have a useful name. As Lars noted (see comments), the only practical use, besides debugging, seems to be the ability to overwrite the twin factory function during the delay before the transition starts (approximately 17 ms if you did not specify a longer delay).

It could be designed as an optional parameter (for example, .tween(function, [name]) ), but this would not be compatible with the template used for all other API functions.

So, in general, just use the name to make your code more readable by describing what your twin function does. If you are not obsessed with minimization, then use a random single character.