Legend events

[etpinard]

This PR adds legend two events plotly_legendclick and plotly_legenddoubleclick. Note that, as per @alexcjohnson 's recommendation in #65 (comment), these new events are emitted using Events.triggerHandlers which allows users to cancel the default click/doubleclick behavior via the (last) handler's return value. This PR chose this strategy despite this note:

plotly.js/src/lib/events.js

Lines 93 to 96 in 4ed586a

	* Note: triggerHandler has been recommended for deprecation in v2.0.0,
	* so the additional behavior of triggerHandler triggering internal events
	* is deliberate excluded in order to avoid reinforcing more usage.
	*/

Is it fair to say Events.triggerHandlers is a good idea afterall or is there a better solution?

---

Tagging this PR discussion needed as there are as few debatable things here:

• should we really use Events.triggerHandlers? One drawback of using it: the custom handlers must be called before the default handlers, meaning the users won't have access to the to-be-updated visible trace attribute values - which could be confusing for users that want to augment the default behavior (but maybe listening to plotly_restyle is good enough for that use case?)
• should plotly_legendclick and plotly_legenddoubleclick be the same event? For example, maybe both click and doubleclick could trigger plotly_legendclick where the click/doubleclick distinction would be made using addition event data field (e.g numClick: 1 || 2). This would allows users to define their own click-vs-doubleclick timeouts.
• can anyone think of any other useful field to include in the event data?

---

Referencing numerous related legend feature requests:

• click/hover events for labels/legends hover events for labels/legends #65 (this PR would close the click part)
• Add ability to disable legend trace toggling Add ability to disable legend trace toggling #665 (this PR adds a way, but it might be nice to add attributes for this so that the behavior can be exported)
• [Enhancement] Legend and traces toggling #674, [Enhancement] Legend and traces three-way toggling #1462 are more specific requests. They would all be possible in user-land through the events added in this PR.

cc @jackparmer @willdurand

[alexcjohnson]

should we really use Events.triggerHandlers? One drawback of using it: the custom handlers must be called before the default handlers, meaning the users won't have access to the to-be-updated visible trace attribute values - which could be confusing for users that want to augment the default behavior (but maybe listening to plotly_restyle is good enough for that use case?)

Not sure what that deprecation comment is about (@bpostlethwaite ?) but this seems like a clean solution to me. I don't see ^^ as a downside, in fact it's really the only option if you want to be able to avoid the default behavior in the first place right? I suppose we could make even more events (plotly_legendclicked?) but unless someone is really bothered by it I'd just leave it at plotly_restyle.

should plotly_legendclick and plotly_legenddoubleclick be the same event? For example, maybe both click and doubleclick could trigger plotly_legendclick where the click/doubleclick distinction would be made using addition event data field (e.g numClick: 1 || 2). This would allows users to define their own click-vs-doubleclick timeouts.

referencing #1546 - if we're ever going to add plotly_singleclick then perhaps for consistency we should have three events here - or at least ensure that the two we're introducing match names <-> behaviors with two of the (eventually) three data click events (so if this one behaves like plotly_singleclick perhaps name it plotly_legendsingleclick?)

can anyone think of any other useful field to include in the event data?

For use with our favorite transform, groupby, it would be nice to include _expandedIndex and maybe _group if it exists.

[bpostlethwaite]

I think JQuery deprecated certain behaviours with triggerHandler for versions >2 but I can't find any reference to this with a quick search. IMO if this function has useful functionality or more importantly an intuitive and useful API then we can delete that comment.

[etpinard]

Currently (i.e. excluding the new events in this PR), Events.triggerHandler is used for plotly_beforeplot and plotly_beforehover. These two events are likely to get 🔪 in v2: I can't think of a good use case for plotly_beforeplot outside the old workspace and there are now better ways to disable hover than plotly_beforehover.

So, I suspect when that comment about 🔪 Events.triggerHandler got 🖊️ we were already planning on 🔪 plotly_beforeplot and plotly_beforehover meaning Events.triggerHandler would be w/o a callee in our codebase. Now, looks like Events.triggerHandler is here to stay.

[etpinard]

Tagging this as reviewable:

• 76b4b10 🔪'ed the now obsolete deprecation warning for Events.triggerHandler.
• I chose to keep plotly_legendclick and plotly_legenddoubleclick as is. I'm not 100% convinced about adding singleclick variants, so I'll defer this to plotly_doubleclick also triggers plotly_click #1546
• about _expandedIndex: users already have access to it through eventData.fullData[i]._expandedIndex. I don't see the need to add another event data field.

[etpinard]

For use with our favorite transform, groupby, it would be nice to include _expandedIndex and maybe _group if it exists.

done in 02a85bf

[etpinard]

Oh maybe we wanted to deprecate Events.triggerHandlers because it doesn't work properly with gd.once spitting out

[etpinard]

@alexcjohnson

• so Legend events #2581 (comment) turned out to be fixable (see 9a7cc14) albeit in a bit of hacky way
• from our private convo, I made plotly_legendclick get triggered on mousedown in fde209f
• and I added label to the event data for pie traces in 05e1b6b

[alexcjohnson]

Very nice. 💃

[jacobq]

Are these new events in the docs somewhere? (I don't see them where I expected them to be.)

[etpinard]

@jacobq you can subscribe to plotly/documentation#937