Add hover_tooltips, hover_mode, hover_formatters opts to easily modify hover

examples/user_guide/Plotting_with_Bokeh.ipynb

@@ -14,7 +14,6 @@
    "outputs": [],
    "source": [
     "import numpy as np\n",
-    "import pandas as pd\n",
     "import holoviews as hv\n",
     "from holoviews import dim, opts\n",
     "\n",
@@ -626,6 +625,20 @@
     "Some Elements allow revealing additional data by hovering over the data. To enable the hover tool, simply supply ``'hover'`` as a list to the ``tools`` plot option. By default the tool will display information for all the dimensions specified on the element:"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "import holoviews as hv\n",
+    "from holoviews import dim, opts\n",
+    "\n",
+    "hv.extension('bokeh')"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -652,7 +665,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Additionally, you can provide `'vline'`, the equivalent of passing `HoverTool(mode='vline')`, or `'hline'` to set the hit-testing behavior"
+    "Additionally, you can provide `'vline'`, the equivalent of passing `HoverTool(mode='vline')`, or `'hline'` to set the hit-testing behavior."
    ]
   },
   {
@@ -661,20 +674,26 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "error = np.random.rand(100, 3)\n",
-    "heatmap_data = {(chr(65+i), chr(97+j)):i*j for i in range(5) for j in range(5) if i!=j}\n",
-    "data = [np.random.normal() for i in range(10000)]\n",
-    "hist = np.histogram(data, 20)\n",
-    "\n",
-    "points = hv.Points(error)\n",
-    "heatmap = hv.HeatMap(heatmap_data).sort()\n",
-    "histogram = hv.Histogram(hist)\n",
-    "image = hv.Image(np.random.rand(50,50))\n",
-    "\n",
-    "(points + heatmap + histogram + image).opts(\n",
-    "    opts.Points(tools=['hline'], size=5), opts.HeatMap(tools=['hover']),\n",
-    "    opts.Image(tools=['vline']), opts.Histogram(tools=['hover']),\n",
-    "    opts.Layout(shared_axes=False)).cols(2)"
+    "hv.Curve(np.arange(100)).opts(tools=[\"vline\"]) + hv.Curve(np.arange(100)).opts(tools=[\"hline\"])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Equivalently, you may say `tools=[\"hover\"]` alongside `hover_mode`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    hv.Curve(np.arange(100)).opts(tools=[\"hover\"], hover_mode=\"vline\")\n",
+    "    + hv.Curve(np.arange(100)).opts(tools=[\"hover\"], hover_mode=\"hline\")\n",
+    ")"
    ]
   },
   {
@@ -695,7 +714,7 @@
     "\n",
     "points = hv.Points(\n",
     "    elements, ['electronegativity', 'density'],\n",
-    "    ['name', 'symbol', 'metal', 'CPK', 'atomic radius']\n",
+    "    ['name', 'symbol', 'metal', 'CPK', 'atomic radius'],\n",
     ").sort('metal')\n",
     "\n",
     "tooltips = [\n",
@@ -712,6 +731,179 @@
     "    title='Chemical Elements by Type (scaled by atomic radius)')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You may also use `hover_tooltips` to replicate the behavior above."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hover_tooltips = [\n",
+    "    ('Name', '@name'),\n",
+    "    ('Symbol', '@symbol'),\n",
+    "    ('CPK', '$color[hex, swatch]:CPK')\n",
+    "]\n",
+    "\n",
+    "points.clone().opts(\n",
+    "    tools=[\"hover\"], hover_tooltips=hover_tooltips, color='metal', cmap='Category20',\n",
+    "    line_color='black', size=dim('atomic radius')/10,\n",
+    "    width=600, height=400, show_grid=True,\n",
+    "    title='Chemical Elements by Type (scaled by atomic radius)')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `hover_tooltips` feature extends the capabilities of Bokeh's `HoverTool` tooltips by providing additional flexibility and customization options.\n",
+    "\n",
+    "It supports a mix of string and tuple formats for defining tooltips, allowing for both direct references to data columns and customized display options.\n",
+    "\n",
+    "Additionally, you can include as many, or as little, dimension names as desired."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hover_tooltips = [\n",
+    "    \"name\",  # will assume @name\n",
+    "    (\"Symbol\", \"@symbol\"),  # @ still required if tuple\n",
+    "    ('CPK', '$color[hex, swatch]:CPK'),\n",
+    "    \"density\"\n",
+    "]\n",
+    "\n",
+    "points.clone().opts(\n",
+    "    tools=[\"hover\"], hover_tooltips=hover_tooltips, color='metal', cmap='Category20',\n",
+    "    line_color='black', size=dim('atomic radius')/10,\n",
+    "    width=600, height=400, show_grid=True,\n",
+    "    title='Chemical Elements by Type (scaled by atomic radius)')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`hover_tooltips` also support displaying the HoloViews element's `label` and `group`.\n",
+    "\n",
+    "Keep in mind, to reference these special variables that are not based on the data, a prefix of `$` is required!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "a_curve = hv.Curve([0, 1, 2], label=\"A\", group=\"C\")\n",
+    "b_curve = hv.Curve([2, 1, 0], label=\"B\", group=\"C\")\n",
+    "(a_curve * b_curve).opts(\"Curve\", hover_tooltips=[\"$label\", \"$group\", \"@x\", \"y\"])  # $ is required, @ is not needed for string"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If you need special formatting, you may also specify the formats inside `hover_tooltips` alongside `hover_formatters`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def datetime(x):\n",
+    "    return np.array(x, dtype=np.datetime64)\n",
+    "\n",
+    "\n",
+    "df = pd.DataFrame(\n",
+    "    {\n",
+    "        \"date\": [\"2019-01-01\", \"2019-01-02\", \"2019-01-03\"],\n",
+    "        \"adj_close\": [100, 101, 100000],\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "curve = hv.Curve((datetime(df[\"date\"]), df[\"adj_close\"]), \"date\", \"adj close\")\n",
+    "curve.opts(\n",
+    "    hover_tooltips=[\"date\", (\"Close\", \"$@{adj close}{%0.2f}\")],  # use @{ } for dims with spaces\n",
+    "    hover_formatters={\"@{adj close}\": \"printf\"},  # use 'printf' formatter for '@{adj close}' field\n",
+    "    hover_mode=\"vline\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Lastly, you can provide HTML strings too! Just be sure to provide all the used dimensions within the HTML to `vdims`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = pd.DataFrame(\n",
+    "    dict(\n",
+    "        x=[1, 2, 3, 4, 5],\n",
+    "        y=[2, 5, 8, 2, 7],\n",
+    "        desc=[\"A\", \"b\", \"C\", \"d\", \"E\"],\n",
+    "        imgs=[\n",
+    "            \"https://docs.bokeh.org/static/snake.jpg\",\n",
+    "            \"https://docs.bokeh.org/static/snake2.png\",\n",
+    "            \"https://docs.bokeh.org/static/snake3D.png\",\n",
+    "            \"https://docs.bokeh.org/static/snake4_TheRevenge.png\",\n",
+    "            \"https://docs.bokeh.org/static/snakebite.jpg\",\n",
+    "        ],\n",
+    "        fonts=[\n",
+    "            \"<i>italics</i>\",\n",
+    "            \"<pre>pre</pre>\",\n",
+    "            \"<b>bold</b>\",\n",
+    "            \"<small>small</small>\",\n",
+    "            \"<del>del</del>\",\n",
+    "        ],\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "TOOLTIPS = \"\"\"\n",
+    "    <div>\n",
+    "        $label\n",
+    "        <div>\n",
+    "            <img\n",
+    "                src=\"@imgs\" height=\"42\" alt=\"@imgs\" width=\"42\"\n",
+    "                style=\"float: left; margin: 0px 15px 15px 0px;\"\n",
+    "                border=\"2\"\n",
+    "            ></img>\n",
+    "        </div>\n",
+    "        <div>\n",
+    "            <span style=\"font-size: 17px; font-weight: bold;\">@desc</span>\n",
+    "            <span style=\"font-size: 15px; color: #966;\">[$index]</span>\n",
+    "        </div>\n",
+    "        <div>\n",
+    "            <span>@fonts{safe}</span>\n",
+    "        </div>\n",
+    "        <div>\n",
+    "            <span style=\"font-size: 15px;\">Location</span>\n",
+    "            <span style=\"font-size: 10px; color: #696;\">($x, $y)</span>\n",
+    "        </div>\n",
+    "    </div>\n",
+    "\"\"\"\n",
+    "\n",
+    "hv.Scatter(df, kdims=[\"x\"], vdims=[\"y\", \"desc\", \"imgs\", \"fonts\"], label=\"Pictures\").opts(\n",
+    "    hover_tooltips=TOOLTIPS, size=20\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},