support template string on hover #3126

antoinerg · 2018-10-18T19:49:38Z

See this #3126 (comment) for understanding how to add support for hovertemplate to new traces.

However, there are several caveats:

1 - In the process of making that PR, I realized that there are a lot of computed values on hover that are not emitted in hover events. Because we are passing the hover event data to the template, only a limited subset of the total information is currently available. Enriching the event data for each trace is probably outside the scope of the current PR since it should benefit BOTH hovertemplate and plotly_hover events. However, it is something that can be done fairly easily and separately (some traces already have an event_data.js file in place where such code would go)!

2 - Some traces have many hover labels. For example, in box traces, there are six labels when hovering on a box. As of right now, the numerical value for each of those is assigned to variable y regardless of what it represents (q(1|3), min, max, etc.). We should certainly add a label variable alongside in order for template '%{label}: %{y}' to exactly reproduce the current hover labels while enabling number formatting. All traces with several different hover labels would have to implement this change.

In the future, to support different templates for each hover labels, we could either allow hovertemplate to be an object with a key for each label ({q1: 'templatestring', min: 'templatestring', ...}) OR we can move everything in nested attributes : {q1: {hovertemplate: '...'}, min: {hovertemplate: '...'}, ...}. The latter has the advantages of allowing further customization for each label (think color or hiding) since each of them could have a nested hoverinfo and hoverlabel. We need to think carefully about this one. The latter approach is what @alexcjohnson and I decided to do in our latest work for sankey traces (see PR #3096).

3 - Right now, hovertemplate doesn't control the content of the secondary labels. As @alexcjohnson pointed out, this could be supported by a special tag <extra>Secondary box content here</extra>.

Please chime in :)

antoinerg · 2018-10-18T19:52:54Z

src/components/fx/hover.js

+        // hovertemplate
+        var trace = d.trace, hovertemplate = opts.hovertemplate || trace.hovertemplate || false;
+        if(hovertemplate) {
+            text = Lib.templateString(hovertemplate, gd._hoverdata[curveNumber], trace);


We can pass additional objects as argument to Lib.templateString so the sky is the limit in terms of the number of values we can make available here!

However, as mentioned in point 1, we should probably put useful data into _hoverdata to begin with since it's emitted on hover.

mojoaxel · 2018-10-28T13:32:38Z

@antoinerg You should consider adding a bunch of examples to plotly/documentation to demonstrate the new possibilities with this.

etpinard · 2018-10-30T20:31:41Z

Enriching the event data for each trace is probably outside the scope of the current PR since it should benefit BOTH hovertemplate and plotly_hover events

Matching event data points keys with the upcoming hovertemplate %{} strings is a fantastic idea. The points keys are documented here. The list isn't complete, but garanting that keys emitted during hover/click events work in hovertemplate will be a big plus in terms of user-discoverability and maintainability.

We'll need to handle traces that support a hoveron attribute (e.g. scatter traces that can "hover-on" points and fills) which don't always emit the same event data keys (see #2504 for more info). Perhaps we could have nested hovertemplate for each case e.g. fills.hovertemplate and points.hovertemplate?

Some traces have many hover labels. For example, in box traces, there are six labels when hovering on a box.
In the future, to support different templates for each hover labels, we could either allow hovertemplate to be an object with a key for each label

Thanks writing down thoughts about traces that can generate multiple hover labels. I agree, we'll need to implement per-label templating and styling as some point.

In the case of box traces, I'm not a fan of the {q1: {hovertemplate: '...'}, min: {hovertemplate: '...'}, ...} proposal as it would conflict with #1059. I think it's important to make a distinction between cases where:

one part of a trace can generate multiple hover labels (e.g. 'boxes' hover) and
traces with multiple "parts" each with their own hover labels (e.g. sankey, but also parcats).

this could be supported by a special tag Secondary box content here

Maybe these special tags could help us out. Consider:

boxes.hovertemplate: `
  <mean><span style="color:blue">MEAN: %{y}</span><name>%{data.name}</name></mean>
  <q1>Q1: %{y}</q1>
  <q3>q3: %{y}</q3>
`

would show three labels: one for the mean, q1 and q3 when hovering on a box. The mean hover label would have the trace "name" attach to it in a secondary label and its text would drawn in blue.

Now, those <--> will conflict with other pseudo-html tags we support (e.g. <b> as b is an attribute for scatterternary traces), so we should use some other escape sequence. But all in all, this could be a nice way to support all the per-label customizations our users can think of.

Let me write down a few less-important comments here about the implementation:

What happens when template keys don't exist e.g. show this: %{cow}. How should this render out? e.g. show this: undefined or show this: or something else.
As hovertemplate overrides hoverinfo, we should not coerce hoverinfo if one provides a hovertemplate.
What should %{y} in a template w/o : format mean. Does it mean: print the y event data value using the default plotly formatting or print the raw y value?
At some point, we should implement hoverinfo as a arrayOk attribute to allow user to set different templates for each point.
To close out configurable hoverinfo-x placement #3145, maybe we should add layout.xaxis.hovertemplate and layout.yaxis.hovertemplate

nicolaskruchten · 2018-11-01T14:15:54Z

I'm curious to talk about the interaction between hoverinfo and hovertemplate. I was thinking that hovertemplate could accept %{hoverinfo} key and then that could be the default value, so we could always use the two together.

alexcjohnson · 2018-11-01T16:29:51Z

one part of a trace can generate multiple hover labels (e.g. 'boxes' hover) and

The box-like case (incl. violin, ohlc, candlestick) seems like the toughest nut to crack. There's also the issue of whether you make one or many labels, ie hoverlabel.split #2959. As mentioned this morning I think we should not enable hovertemplate for these types in this PR. I can see a variety of ways to go with the API but none of them would be affected by the API for the simple case of a single label for hovering on a single class of objects. Let's make a new issue to discuss this, including enabling/disabling individual labels, independent styling (not just of the font as in <mean><span style="color:blue"> but also the bgcolor etc that wouldn't work with the mega-template idea).

traces with multiple "parts" each with their own hover labels (e.g. sankey, but also parcats).

Again as I mentioned earlier, I like the plan of describing each class of hover label within its own container. The difficult case for this currently is scatter hoveron: 'fills', which currently seems to be broken for the simple case of just one trace anyway. In the short term we should just fix this to ignore hoverinfo and always display the trace name since that's the only thing it can display, longer term we should make a new container (fills?) and put its config in there, like we do for sankey.

etpinard · 2018-11-01T16:35:26Z

In the short term we should just fix this to ignore hoverinfo and always display the trace name since that's the only thing it can display,

👍

longer term we should make a new container (fills?)

Good plan. Related: #420 (comment)

etpinard · 2018-11-01T16:42:15Z

which currently seems to be broken for the simple case of just one trace anyway

now in -> #3203

alexcjohnson · 2018-11-01T16:53:59Z

What happens when template keys don't exist e.g. show this: %{cow}. How should this render out? e.g. show this: undefined or show this: or something else.

Is there ever a case where this is not simply a mistake the user will want to know about and fix? If not, I'd say leave it show this: %{cow} in the output and maybe Lib.warn about it.

As hovertemplate overrides hoverinfo, we should not coerce hoverinfo if one provides a hovertemplate.

👍 I do think there's a possibility of having hoverinfo create the default hovertemplate, but it's fairly complicated and connected to a bunch of other things like hovermode and the existence of other traces. Probably ignore this for now but perhaps explore it later.

What should %{y} in a template w/o : format mean. Does it mean: print the y event data value using the default plotly formatting or print the raw y value?

I like the idea of this being the default plotly formatting. That way we don't need to augment the d3 format spec at all. I don't see a benefit to raw.

At some point, we should implement hoverinfo as a arrayOk attribute to allow user to set different templates for each point.

👍

To close out configurable hoverinfo-x placement #3145, maybe we should add layout.xaxis.hovertemplate and layout.yaxis.hovertemplate

interesting... sure, perhaps in conjunction with the effort to have hoverinfo create hovertemplate?

etpinard · 2018-11-01T17:08:46Z

Great - thanks @alexcjohnson I think all my concerns have been resolved (at least for this first iteration).

@antoinerg should be all set now 🎉

etpinard · 2018-11-12T21:55:51Z

test/jasmine/tests/pie_test.js

+                    'hovertemplate %{percent}'
+                );
+
+                return Plotly.restyle(gd, 'hovertemplate', '%{label}<extra></extra>');


Could we add one arrayOk hovertemplate test for pies?

Absolutely! There it is 1e4bd33

etpinard · 2018-11-12T21:57:20Z

src/traces/bar/attributes.js

@@ -59,6 +60,7 @@ module.exports = {

    text: scatterAttrs.text,
    hovertext: scatterAttrs.hovertext,
+    hovertemplate: hovertemplateAttrs(),


We should append the hovertemplate descriptions with a list of flags (i.e. event data keys) available.

On a related note: I like that for some traces, like pie, we test that event data has the correct keys:

plotly.js/test/jasmine/tests/pie_test.js

Lines 824 to 856 in ad937d2

it('should contain the correct fields', function() {

var hoverData,

unhoverData;

gd.on('plotly_hover', function(data) {

hoverData = data;

});

gd.on('plotly_unhover', function(data) {

unhoverData = data;

});

mouseEvent('mouseover', width / 2 - 7, height / 2 - 7);

mouseEvent('mouseout', width / 2 - 7, height / 2 - 7);

expect(hoverData.points.length).toEqual(1);

expect(unhoverData.points.length).toEqual(1);

var fields = [

'curveNumber', 'pointNumber', 'pointNumbers',

'data', 'fullData',

'label', 'color', 'value',

'i', 'v'

];

expect(Object.keys(hoverData.points[0]).sort()).toEqual(fields.sort());

expect(hoverData.points[0].pointNumber).toEqual(3);

expect(Object.keys(unhoverData.points[0]).sort()).toEqual(fields.sort());

expect(unhoverData.points[0].pointNumber).toEqual(3);

});

We could potentially use the same array of field names for the test and for the description making sure we have one source of truth 🤔. This improvement could be done in another PR.

We could potentially use the same array of field names for the test and for the description making sure we have one source of truth

Yeah, good call. We usually put things like that in "constants" files like this one:

https://github.com/plotly/plotly.js/blob/master/src/traces/scatter/constants.js

This improvement could be done in another PR.

That's up to you!

I created a new function to check that event data contains a given list of keys: https://github.com/plotly/plotly.js/pull/3126/files#diff-4ddfa80f2c61e112d5587c91a961ab47

If it looks OK, I will dry up the code by listing the extra keys of a given trace into its constants.js file and then use that list to generate the description of hovertemplate attribute 🎉 !

Let me know if that route looks fine to you.

etpinard · 2018-11-12T21:58:12Z

Getting close, once:

are ✅ , I believe we'll be in 💃 land.

etpinard · 2018-11-14T15:14:50Z

src/traces/scatter/attributes.js

@@ -205,7 +205,7 @@ module.exports = {
        ].join(' ')
    },
    hovertemplate: hovertemplateAttrs({}, {
-        keys: ['marker.size', 'marker.color']
+        keys: ['marker.size']


Why is marker.color gone? In fact, all arrayOk attributes should be part of this list. They get added to the event data via

plotly.js/src/components/fx/helpers.js

Lines 161 to 186 in 2ceb5c3

/** Appends values inside array attributes corresponding to given point number

*

* @param {object} pointData : point data object (gets mutated here)

* @param {object} trace : full trace object

* @param {number|Array(number)} pointNumber : point number. May be a length-2 array

* [row, col] to dig into 2D arrays

*/

exports.appendArrayPointValue = function(pointData, trace, pointNumber) {

var arrayAttrs = trace._arrayAttrs;

if(!arrayAttrs) {

return;

}

for(var i = 0; i < arrayAttrs.length; i++) {

var astr = arrayAttrs[i];

var key = getPointKey(astr);

if(pointData[key] === undefined) {

var val = Lib.nestedProperty(trace, astr).get();

var pointVal = getPointData(val, pointNumber);

if(pointVal !== undefined) pointData[key] = pointVal;

}

}

};

Now, maybe we don't need to hardcode all the arrayOk attributes into keys here, maybe we could just mention that all "per-point" values are available for hovertemplate.

marker.color is gone because it is not emitted in the event data. It used to work because hovertemplateString would be called with the full trace object as one of its argument but I removed this in 43a4cd9 to make sure everything is on par with event data. Therefore, if we want marker.color, I need to add it to the event data for scatter.

marker.color is gone because it is not emitted in the event data

Try

Plotly.newPlot(gd, [{ y: [1, 2, 3], marker: {color: [1, 2, 3]} }]) gd.on('plotly_hover', console.log)

It works if it's an array but not if it isn't? 🤔

Plotly.newPlot(gd, [{ y: [1, 2, 3], marker: {color: 'blue'} }]) gd.on('plotly_hover', console.log)

That's why the test was failing: the mock I was using doesn't specify marker.color as an array.

I think it should be available in both cases.

t works if it's an array but not if it isn't?

yes, that's the expected behaviour.

Ok so I added it and now run the test with a mock that specifies marker size and color as arrays. And it now passes.

Now for extra points, I just need to add those extra event data keys in constants.js.

Done in 7be804e

I just realized I didn't read your comment properly. I am sorry about that @etpinard.

Commit 14ac99f should be more satisfactory. I now list the different marker attributes that are arrayOk except for the nested line and gradient. Should I add those as well?

From that same #3126 (comment)

Now, maybe we don't need to hardcode all the arrayOk attributes into keys here,

I think it might be best to NOT hardcoded all arrayOk attributes into that keys list, as it will be hard to remember to append it everytime we add another arrayOk attribute. We should keep that keys list only for keys that have no corresponding schema attributes e.g binNumber in histogram traces, and we should mention that all arrayOk (aka per-point) attribute are available to hovertemplate in the components/fx/hovertemplate_attributes' description.

Sorry for not been clearer.

etpinard · 2018-11-15T18:04:14Z

Beautifully done. 💃

chriddyp · 2018-12-05T13:09:11Z

Nice example of this new hovertemplate string (courtesy @nicolaskruchten )

hovertemplate:
       "<b>%{text}</b><br><br>" +
       "%{yaxis.title}: %{y:$,.0f}<br>" +
       "%{xaxis.title}: %{x:.0%}<br>" +
       "Number Employed: %{marker.size:,}"

Codepen: https://codepen.io/nicolaskruchten/pen/QJgbxo?editors=0010

Braintelligence · 2019-01-22T12:36:30Z

Maybe stupid question: Is it possible to style the hovertemplate more? Like having a table structure?

etpinard · 2019-01-22T15:24:45Z

s it possible to style the hovertemplate more? Like having a table structure?

No. That'll be in #3010

antoinerg added 7 commits October 15, 2018 18:11

rough first implementation for hovertemplate

4c197e8

supply hover's eventData inot hovertemplate

613c8f5

delete unrelated file from branch

edf4795

update description for hovertemplate

dd62855

fix hovertemplate test not being run

a86327a

for now, only offer hoverdata and trace objects to hovertemplate

1fde3aa

templateString evaluates attributes with a dot in their name

d263cce

antoinerg self-assigned this Oct 18, 2018

antoinerg added feature something new status: reviewable labels Oct 18, 2018

antoinerg commented Oct 18, 2018

View reviewed changes

This was referenced Oct 24, 2018

implement hoverinfo 'none' and 'skip' in sankey #3096

Merged

configurable hoverinfo-x placement #3145

Closed

vvch mentioned this pull request Oct 27, 2018

Axis title could also change the labels in the hovering popup #2618

Closed

alexcjohnson mentioned this pull request Oct 30, 2018

Inconsistent datetime hoverinfo with Scattergl and datetime axis #3181

Closed

etpinard removed the status: discussion needed label Nov 5, 2018

etpinard added this to the v1.43.0 milestone Nov 5, 2018

antoinerg added 4 commits November 5, 2018 12:15

do not coerce hoverinfo if hovertemplate is defined

040208f

replace templateString with the more specific hovertemplateString

3eaa3b9

hovertemplate: add warning if variable can't be found

0084efb

coerce hovertemplate at trace-level, starting with scatter(gl)

046d367

axis information is already included in hovertemplate

8d95f05

etpinard removed the status: discussion needed label Nov 12, 2018

etpinard reviewed Nov 12, 2018

View reviewed changes

antoinerg added 9 commits November 13, 2018 10:29

pie: test that hovertemplate supports array

1e4bd33

list available variables in pie's hovertemplate description

61a2da7

hovertemplate: do not look into trace object, use fullData instead

43a4cd9

describe hovertemplate variables for scatter(gl)

70befe3

describe hovertemplate variables for histogram

b6822e8

fix lint

59bc981

scatter: test hover event data

f75f2e0

test that event data has correct fields in bar, scatter, histogram

0654245

bar test: fix hover position to trigger hover events

0ecd1c1

etpinard reviewed Nov 14, 2018

View reviewed changes

antoinerg added 6 commits November 14, 2018 11:38

scatter: add marker.color to hovertemplate available variables

6f86522

one source of truth for event data keys used for doc and test

7be804e

fix lint

583eb97

scatter: list additionnal variables available in eventData

14ac99f

hovertemplate: update desc, do no list attributes that are arrayOK

1caf321

fix syntax

a78600a

antoinerg merged commit 3a32ac0 into master Nov 15, 2018

antoinerg deleted the 3007-hovertemplate branch November 15, 2018 18:06

antoinerg mentioned this pull request Nov 20, 2018

implement hovertemplate for Sankey traces #3269

Closed

nicolaskruchten mentioned this pull request Jan 4, 2019

adding hovertemplates to polar bar and scatter and ternary scatter #3398

Merged

etpinard mentioned this pull request Jan 14, 2019

Implement hovertemplate for all traces that support hover #3437

Closed

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

support template string on hover #3126

support template string on hover #3126

antoinerg commented Oct 18, 2018 •

edited

Loading

antoinerg Oct 18, 2018 •

edited

Loading

mojoaxel commented Oct 28, 2018

etpinard commented Oct 30, 2018

nicolaskruchten commented Nov 1, 2018 •

edited

Loading

alexcjohnson commented Nov 1, 2018

etpinard commented Nov 1, 2018

etpinard commented Nov 1, 2018

alexcjohnson commented Nov 1, 2018

etpinard commented Nov 1, 2018

etpinard Nov 12, 2018

antoinerg Nov 13, 2018

etpinard Nov 12, 2018

antoinerg Nov 13, 2018

etpinard Nov 13, 2018

antoinerg Nov 13, 2018 •

edited

Loading

etpinard commented Nov 12, 2018

etpinard Nov 14, 2018

antoinerg Nov 14, 2018

etpinard Nov 14, 2018

antoinerg Nov 14, 2018 •

edited

Loading

etpinard Nov 14, 2018

antoinerg Nov 14, 2018

antoinerg Nov 14, 2018 •

edited

Loading

antoinerg Nov 14, 2018

etpinard Nov 15, 2018

etpinard commented Nov 15, 2018

chriddyp commented Dec 5, 2018 •

edited

Loading

Braintelligence commented Jan 22, 2019

etpinard commented Jan 22, 2019

	it('should contain the correct fields', function() {

	var hoverData,
	unhoverData;


	gd.on('plotly_hover', function(data) {
	hoverData = data;
	});

	gd.on('plotly_unhover', function(data) {
	unhoverData = data;
	});

	mouseEvent('mouseover', width / 2 - 7, height / 2 - 7);
	mouseEvent('mouseout', width / 2 - 7, height / 2 - 7);

	expect(hoverData.points.length).toEqual(1);
	expect(unhoverData.points.length).toEqual(1);

	var fields = [
	'curveNumber', 'pointNumber', 'pointNumbers',
	'data', 'fullData',
	'label', 'color', 'value',
	'i', 'v'
	];

	expect(Object.keys(hoverData.points[0]).sort()).toEqual(fields.sort());
	expect(hoverData.points[0].pointNumber).toEqual(3);

	expect(Object.keys(unhoverData.points[0]).sort()).toEqual(fields.sort());
	expect(unhoverData.points[0].pointNumber).toEqual(3);
	});

	/** Appends values inside array attributes corresponding to given point number
	*
	* @param {object} pointData : point data object (gets mutated here)
	* @param {object} trace : full trace object
	* @param {number\|Array(number)} pointNumber : point number. May be a length-2 array
	* [row, col] to dig into 2D arrays
	*/
	exports.appendArrayPointValue = function(pointData, trace, pointNumber) {
	var arrayAttrs = trace._arrayAttrs;

	if(!arrayAttrs) {
	return;
	}

	for(var i = 0; i < arrayAttrs.length; i++) {
	var astr = arrayAttrs[i];
	var key = getPointKey(astr);

	if(pointData[key] === undefined) {
	var val = Lib.nestedProperty(trace, astr).get();
	var pointVal = getPointData(val, pointNumber);

	if(pointVal !== undefined) pointData[key] = pointVal;
	}
	}
	};

support template string on hover #3126

support template string on hover #3126

Conversation

antoinerg commented Oct 18, 2018 • edited Loading

antoinerg Oct 18, 2018 • edited Loading

Choose a reason for hiding this comment

mojoaxel commented Oct 28, 2018

etpinard commented Oct 30, 2018

nicolaskruchten commented Nov 1, 2018 • edited Loading

alexcjohnson commented Nov 1, 2018

etpinard commented Nov 1, 2018

etpinard commented Nov 1, 2018

alexcjohnson commented Nov 1, 2018

etpinard commented Nov 1, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

antoinerg Nov 13, 2018 • edited Loading

Choose a reason for hiding this comment

etpinard commented Nov 12, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

antoinerg Nov 14, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

antoinerg Nov 14, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

etpinard commented Nov 15, 2018

chriddyp commented Dec 5, 2018 • edited Loading

Braintelligence commented Jan 22, 2019

etpinard commented Jan 22, 2019

antoinerg commented Oct 18, 2018 •

edited

Loading

antoinerg Oct 18, 2018 •

edited

Loading

nicolaskruchten commented Nov 1, 2018 •

edited

Loading

antoinerg Nov 13, 2018 •

edited

Loading

antoinerg Nov 14, 2018 •

edited

Loading

antoinerg Nov 14, 2018 •

edited

Loading

chriddyp commented Dec 5, 2018 •

edited

Loading