Merge pull request #531 from facultyai/popover-triggers

Popover triggers

Author: tcbegley

docs/components_page/components/popover.md

@@ -5,9 +5,20 @@ lead: Use the Popover component to add Bootstrap popovers to any component in yo
 
 ## Simple example
 
-To use `Popover`, add it to your layout, and set the `target` argument to the `id` of the component you would like to attach the popover to. Then define a callback that toggles the `is_open` property of the `Popover`. In the below example we use a simple callback to toggle the popover when a button is clicked. In this case the target of the popover is the button itself, but in general there is no requirement that the components used in the callback need to be related to the target.
+To use `Popover`, add it to your layout, and set the `target` argument to the `id` of the component you would like to attach the popover to. The easiest way to trigger the popover is to specify the `trigger` property. This should be a string containing any of the following 4 values (space separated)
 
-{{example:components/popover/popover.py:popover}}
+*  `"click"`: toggles the popover when the target is clicked.
+*  `"focus"`: toggles the popover when the target receives focus
+*  `"hover"`: toggles the popover when the target is hovered over with the cursor.
+*  `"legacy"`: toggles the popover when the target is clicked, but will also dismiss the popover when the user clicks outside of the popover.
+
+{{example:components/popover/popover.py:popovers}}
+
+## Toggling the Popover with callbacks
+
+Alternatively, you can manually control the appearance of the popover using callbacks by setting the `is_open` property of the `Popover`. This can be useful for example when you want to make the popover appear after the user interacts with something other than the target component as demonstrated in the below example.
+
+{{example:components/popover/popover_callback.py:popover}}
 
 ## Placement
 

docs/components_page/components/popover/popover.py

@@ -1,31 +1,46 @@
 import dash_bootstrap_components as dbc
 import dash_html_components as html
-from dash.dependencies import Input, Output, State
 
-popover = html.Div(
+popover_children = [
+    dbc.PopoverHeader("Popover header"),
+    dbc.PopoverBody("And here's some amazing content. Cool!"),
+]
+
+popovers = html.Div(
     [
         dbc.Button(
-            "Click to toggle popover", id="popover-target", color="danger"
+            "Click", id="click-target", color="danger", className="mr-1"
+        ),
+        dbc.Popover(
+            popover_children,
+            id="click",
+            target="click-target",
+            trigger="click",
+        ),
+        dbc.Button(
+            "Focus", id="focus-target", color="danger", className="mr-1"
+        ),
+        dbc.Popover(
+            popover_children,
+            id="focus",
+            target="focus-target",
+            trigger="focus",
+        ),
+        dbc.Button(
+            "Hover", id="hover-target", color="danger", className="mr-1"
+        ),
+        dbc.Popover(
+            popover_children,
+            id="hover",
+            target="hover-target",
+            trigger="hover",
         ),
+        dbc.Button("Legacy", id="legacy-target", color="danger"),
         dbc.Popover(
-            [
-                dbc.PopoverHeader("Popover header"),
-                dbc.PopoverBody("And here's some amazing content. Cool!"),
-            ],
-            id="popover",
-            is_open=False,
-            target="popover-target",
+            popover_children,
+            id="legacy",
+            target="legacy-target",
+            trigger="legacy",
         ),
     ]
 )
-
-
-@app.callback(
-    Output("popover", "is_open"),
-    [Input("popover-target", "n_clicks")],
-    [State("popover", "is_open")],
-)
-def toggle_popover(n, is_open):
-    if n:
-        return not is_open
-    return is_open

docs/components_page/components/popover/popover_callback.py

@@ -0,0 +1,30 @@
+import dash_bootstrap_components as dbc
+import dash_html_components as html
+from dash.dependencies import Input, Output, State
+
+popover = html.Div(
+    [
+        dbc.Button("Toggle", id="toggle", color="success", className="mr-4"),
+        dbc.Button("Target", id="target", color="danger"),
+        dbc.Popover(
+            [
+                dbc.PopoverHeader("Popover header"),
+                dbc.PopoverBody("And here's some amazing content. Cool!"),
+            ],
+            id="popover",
+            is_open=False,
+            target="target",
+        ),
+    ]
+)
+
+
+@app.callback(
+    Output("popover", "is_open"),
+    [Input("toggle", "n_clicks")],
+    [State("popover", "is_open")],
+)
+def toggle_popover(n, is_open):
+    if n:
+        return not is_open
+    return is_open

setup.cfg

@@ -27,7 +27,7 @@ exclude =
     docs/components_page/components/nav/navlink.py,
     docs/components_page/components/navbar/navbar.py,
     docs/components_page/components/popover/direction.py,
-    docs/components_page/components/popover/popover.py,
+    docs/components_page/components/popover/popover_callback.py,
     docs/components_page/components/progress/animated.py,
     docs/components_page/components/progress/interval.py,
     docs/components_page/components/spinner/loading.py,

src/components/popover/Popover.js

@@ -12,11 +12,28 @@ import {Popover as RSPopover} from 'reactstrap';
  * of the children.
  */
 const Popover = props => {
-  const {children, is_open, hide_arrow, loading_state, ...otherProps} = props;
+  const {
+    children,
+    is_open,
+    hide_arrow,
+    loading_state,
+    setProps,
+    trigger,
+    ...otherProps
+  } = props;
+
+  const toggle = () => {
+    setProps({is_open: !is_open});
+  };
+
   return (
     <RSPopover
       isOpen={is_open}
       hideArrow={hide_arrow}
+      // to ensure proper backwards compatibility, the toggle function is only
+      // passed to the popover if `trigger` is not specified
+      toggle={trigger ? toggle : null}
+      trigger={trigger}
       {...omit(['setProps'], otherProps)}
       data-dash-is-loading={
         (loading_state && loading_state.is_loading) || undefined
@@ -87,6 +104,20 @@ Popover.propTypes = {
    */
   container: PropTypes.string,
 
+  /**
+   * Space separated list of triggers (e.g. "click hover focus legacy"). These
+   * specify ways in which the target component can toggle the popover. If not
+   * specified you must toggle the popover yourself using callbacks. Options
+   * are:
+   * - "click": toggles the popover when the target is clicked.
+   * - "hover": toggles the popover when the target is hovered over with the
+   * cursor.
+   * - "focus": toggles the popover when the target receives focus
+   * - "legacy": toggles the popover when the target is clicked, but will also
+   * dismiss the popover when the user clicks outside of the popover.
+   */
+  trigger: PropTypes.string,
+
   /**
    * Whether the Popover is open or not.
    */