hovertool tooltips interpretation could be more flexible

[jasonsross]

Currently the Hovertool tooltips accepts some special fields and allows datetime formatting but I'm finding the flexibility a little lacking.

Let's say I have a HoverTool like below that I want to define once and reuse for multiple figures by using the special fields as much as possible so it can display the correct names and values for data in a ColumnDataSource.

hovertool = HoverTool(
    tooltips=[
        ("date", "$x{%F %T}"),
        ("name", "$name"),
        ("value", "$y"),
    ],
    formatters={
        '$x': 'datetime',
    })

Some issues I have with the current form:

1. The special fields are only interpreted in the second item of the 2-item tooltip tuples. In my above example, I had to use two tool tips to display the name of the plotted column and its value. These are nicely flexible, but it makes more sense for them to be done in a single tooltip like: ("$name","$y")
2. The $name special field (which btw is listed twice in the guide here) could use a little adjusting or possibly new special fields and glyph arguments should be implemented. Here's what I mean:
   1. The $name tooltip displays the glyphs name property, but most graphs have at least two axes so one might want to be able to pass multiple names to the hovertool.
   2. For this I propose adding the "x_name" and "y_name" properties to glyphs which the tooltip could display via new special fields $xname and $yname.
   3. These should default to the x and y column names automatically if the glyph was called using a ColumnDataSource and strings for the x and y.
   4. This will allow a single HoverTool object to be reused for several graphs of various x and y columns which I think will provide a nice simplicity to ones code.
3. A default datetime formatting should be automatically applied when the figure has axis_type set to datetime without even specifying this in the HoverTool (lower priority but I think the average user would expect this).

So putting all this together, I am picturing being able to do the following:

hovertool = HoverTool(
    tooltips=[
        ("$xname", "$x{%F %T}"),  
        ("$yname", "$y"),
    ],
    formatters={
        '$x': 'datetime',
    })
p = figure(x_axis_type="datetime", x_axis_label='Datetime', y_axis_label='Value')
p.line('date','column1',source=source)
p.line('date','column2',source=source)
p.line('date','column3',source=source)
p.add_tools(hovertool)
show(p)

p2 = figure(x_axis_type="datetime", x_axis_label='Datetime', y_axis_label='Value')
p2.line('other_date','column4',source=source)
p2.add_tools(hovertool)
show(p2)

I assume adding properties to glyphs is quite the ask so I would say the xname/yname is less serious request here. Perhaps in the short term it's possible to just grab the x and y glyph property here (only if they are strings when using a source) even though the formatting of those might not be what you would prefer shows up in the tooltip.

But I hope getting special field interpretations working on the first tooltip tuple item could be easily done as well as automatic datetime formatting.

I'm happy to try to work on this issue myself but would need a little direction on where these special fields are being interpreted and passed to the plot.

[bryevdv]

1. I think this is already addressable without any new work. The tuple format is an optional convenience for when you want simple fixed labels. It's not mandatory, though. Tooltips can also be given as a custom HTML snippet, e.g. tooltips="$name @fruits: @$name" as seen in this example

2. It must be stated up front that hover tools cannot be shared between plots, and this isn't going to change. Tools are owned by the (one) plot they are added to. At best, you could hope to share the tooltip/formatter specifications.

   I don't really understand the proposal, name is for naming the glyph itself, it's not related to axes. Are you proposing a special variable that simply outputs axis labels? I don't see how that's related to glyphs. Axis labels are what they are, independent of any glyph, or how any glyph is configured. But an $xaxis_label that just outputs the current x-axis name seems like it would be simple enough.

   Alternately, it seems like maybe you could be proposing a special variable that expands to the name of whatever column names are configured for a glyphs x coordinate? That's not sensible in general, since not all glyphs have an x coordinate at all, and even for the ones that do, it's always possible to configure it with a fixed value, instead of a column name, so what would be displayed then?

   A more generic approach would be necessary, e.g $property:foo where that expands to the foo property value on whatever glyph is being hit.

3. Would be great, but CDS columns are not associated with axes in any way, except indirectly that some glyph or other happens to use a column name for a coordinate, so I can't think of a reliable way to infer either that @foo contains datetime date, or that it is driving a position on a datetime axis.

I don't mean to seem overly down on these ideas, but the logic for hit testing and hover formatting is already one of the single most complicated parts of BokehJS, adding even more complexity will need a serious justification. (And sharing tools, one of the proposed justifications is simply not possible at all) TLDR, things I think are do-able:

• a special variable to expand axis labels
• a special variable "syntax" for expanding any arbitrary property on a glyph

[jasonsross]

Ok I've tried using a single string instead of a list of tuples and I can get it to work closer to how I want but now I cannot force newlines within the hovertool box:

hovertool = HoverTool(
    tooltips=
        "date: $x{%F %T} \n $name: $y",
    formatters={
        '$x': 'datetime',  # use 'datetime' formatter for 'date' field
    })

So I hope we can either get the tuple method to parse the special fields of the first element of the 2-element tuple or get the string parsing to handle newline characters. I think the former will be more intuitive and allow cleaner code. What do you think?

As for my other requests, after reading your details I'm ok to drop them and work the just the glyph name attribute as the x_axis_name should usually be the same for all glyphs in a plot. And I'm fine to make new hover tools or tooltips for each plot if we can satisfy my request above.

[bryevdv]

@jasonsross you can supply a more sophisticated HTML template to get any number of lines:

https://bokeh.pydata.org/en/latest/docs/user_guide/tools.html#custom-tooltip

[jasonsross]

@bryevdv deleted my recent comment cause I realized it was the difference between $y and @$name that I was describing.

Thanks for all the discussions and helping me understand the hover tool tips better. I think it's functional enough as is and we can close this issue.