Creating Dashboards

When creating a workflow in deephaven.ui, components are laid out in a panel and those panels are then laid out in a dashboard.

The dashboard is the top-level component that allows you to create a page layout containing a collection of components. The user can move and resize panels within the dashboard in rows, columns, and stacks.

In the previous section, we went over the important rules of dashboards and the basics of how to lay out panels in a dashboard with ui.row, ui.column, and ui.stack. This section covers more advanced topics.

Layout Hierarchy

Top-Level

Your dashboard must start with a row or column, which is the “top” of the layout tree. Columns should go inside rows, and rows should go inside columns.

Note: Nesting rows within rows or columns within columns will sub-divide the row or column.

Bottom-Level

Stacks and panels are considered the “bottom” of the layout tree. Once added, the layout in that section is considered complete. For layouts within a panel, see tabs, flex, grid, view, and nested dashboards.

Automatic Wrapping

Children are implicitly wrapped when necessary, so the entire layout does not need to be explicitly defined.

End to end example: dashboard([t1, t2]) would become dashboard(column(stack(panel(t1)), stack(panel(t2)))).

Automatic wrapping is applied by the following rules:

Dashboard: wrap in row/column if no single node is the default. For example, [t1, t2] as the child to the dashboard would become row(t1, t2).
Row/Column:
- If there are children that are rows/columns, wrap the non-wrapped children with the same element. For example, row(col(t1), t2) becomes row(col(t1), col(t2)).
- If none of the children are wrapped by rows/columns, they are wrapped in stacks. For example, row(col(t1), col(t2)) from above becomes row(col(stack(t1)), col(stack(t2))).
Stacks: wrap non-panel children in panels. For example, row(col(stack(t1)), col(stack(t2))) becomes row(col(stack(panel(t1))), col(stack(panel(t2)))).

Multiple dashboards

To create multiple dashboards, you can return more than one dashboard from your script.

from deephaven import ui

dash_2x1 = ui.dashboard(ui.row(ui.panel("A", title="A"), ui.panel("B", title="B")))

dash_1x2 = ui.dashboard(ui.column(ui.panel("A", title="A"), ui.panel("B", title="B")))

dash_2x2 = ui.dashboard(
    ui.row(
        ui.column(ui.panel("A", title="A"), ui.panel("C", title="C")),
        ui.column(ui.panel("B", title="B"), ui.panel("D", title="D")),
    )
)

As deephaven.ui components are spread across multiple panels in a dashboard, those components will need to interact and respond to changes in components in different panels. This means sharing state between components.

In the sections on sharing state, we learned to “lift state up” to a common parent in order to share it between multiple components. However, one of the rules of a dashboard is that it must be a child of the root script and not nested inside a @ui.component. This means that state cannot be lifted up into a component that returns a dashboard.

How, then, do we lift state up to share it between panels in a dashboard? A ui.row or a ui.column can be returned from a @ui.component containing state for the dashboard.

In the example, create_dashboard contains the state variables shared across multiple panels. It then returns a ui.row which is used as the root layout for a dashboard. This allows the UI elements in the control_panel component to apply a filter to table and plot located in separate panels.

from deephaven.time import dh_now
from deephaven import time_table, ui
import deephaven.plot.express as dx

# The control panel contain UI elements to set filtering
@ui.component
def control_panel(filter_type, set_filter_type, dates, set_dates, value, set_value):
    return ui.panel(
        ui.radio_group(
            ui.radio("Date"),
            ui.radio("Value"),
            value=filter_type,
            on_change=set_filter_type,
            label="Filter type",
        ),
        ui.date_range_picker(label="Date filter", value=dates, on_change=set_dates),
        ui.picker(
            "A", "B", selected_key=value, on_change=set_value, label="Value filter"
        ),
        title="Controls",
    )


# The create dashboard component contains the state variables and returns the ui.row
@ui.component
def create_dashboard(start_date, end_date, table):
    # State to choose the filter type
    filter_type, set_filter_type = ui.use_state("Date")

    # State variable to filter by Value column
    value, set_value = ui.use_state("A")

    # State variable to filter by Date column
    dates, set_dates = ui.use_state({"start": start_date, "end": end_date})
    start = dates["start"]
    end = dates["end"]

    # handler to filter the table
    def handle_filter(filter_type, start, end, value, table):
        if filter_type == "Date":
            return table.where("Date >= start && Date < end")
        else:
            return table.where("Value=value")

    # memoize table operations and plots
    filtered_table = ui.use_memo(
        lambda start=start, end=end: handle_filter(
            filter_type, start, end, value, table
        ),
        [filter_type, start, end, value, table],
    )
    plot = ui.use_memo(
        lambda: dx.line(filtered_table, x="Date", y="Row"), [filtered_table]
    )

    # This row will be the root layout for the dashboard
    return ui.row(
        control_panel(filter_type, set_filter_type, dates, set_dates, value, set_value),
        ui.column(
            ui.stack(
                ui.panel(filtered_table, title="Filter table"),
                ui.panel(table, title="Original table"),
                active_item_index=0,
            ),
            ui.panel(plot, title="Plot"),
        ),
    )


SECONDS_IN_DAY = 86400
today = dh_now()
_table = time_table("PT1s").update_view(
    ["Date=today.plusSeconds(SECONDS_IN_DAY*i)", "Value=i%2==0 ? `A` : `B`", "Row=i"]
)
example_dashboard = ui.dashboard(
    create_dashboard(today, today.plusSeconds(SECONDS_IN_DAY * 10), _table)
)

Nested Dashboards

Dashboards can be nested inside panels to create complex layouts with isolated drag-and-drop regions. Each nested dashboard has its own independent layout that users can rearrange without affecting the parent dashboard.

Unlike root-level dashboards, nested dashboards can be returned from @ui.component functions, making them ideal for creating reusable dashboard components with encapsulated state.

Basic nested dashboard

A nested dashboard is created by placing a ui.dashboard inside a ui.panel:

from deephaven import ui

nested_example = ui.dashboard(
    ui.row(
        ui.panel(
            ui.dashboard(
                ui.row(
                    ui.panel("Nested A", title="A"),
                    ui.panel("Nested B", title="B"),
                )
            ),
            title="Nested Dashboard",
        ),
        ui.panel("Main Content", title="Main"),
    )
)

Nested dashboard component with state

Nested dashboards are particularly effective when combined with @ui.component to create stateful, reusable dashboard sections

from deephaven import ui


@ui.component
def data_viewer(initial_filter):
    """A reusable dashboard component for viewing filtered data."""
    filter_text, set_filter_text = ui.use_state(initial_filter)
    view_mode, set_view_mode = ui.use_state("table")

    return ui.panel(
        ui.dashboard(
            ui.column(
                ui.panel(
                    ui.flex(
                        ui.text_field(
                            label="Filter",
                            value=filter_text,
                            on_change=set_filter_text,
                        ),
                        ui.picker(
                            "table",
                            "chart",
                            label="View",
                            selected_key=view_mode,
                            on_change=set_view_mode,
                        ),
                        direction="row",
                        gap="size-100",
                    ),
                    title="Controls",
                ),
                ui.panel(
                    f"Showing {view_mode} with filter: {filter_text}",
                    title="Data View",
                ),
            )
        ),
        title="Data Viewer",
    )


multi_viewer_dashboard = ui.dashboard(
    ui.row(
        data_viewer("Region = 'North'"),
        data_viewer("Region = 'South'"),
    )
)

State can be shared between nested dashboards by lifting state up to a common parent component. This allows multiple nested dashboards to react to the same state changes:

from deephaven import ui


@ui.component
def filter_dashboard(filter_text, on_filter_change):
    """A nested dashboard that displays and can modify a shared filter."""
    return ui.panel(
        ui.dashboard(
            ui.column(
                ui.panel(
                    ui.text_field(
                        label="Filter",
                        value=filter_text,
                        on_change=on_filter_change,
                    ),
                    title="Filter Input",
                ),
                ui.panel(f"Current filter: {filter_text}", title="Filter Display"),
            )
        ),
        title="Filter Dashboard",
    )


@ui.component
def results_dashboard(filter_text):
    """A nested dashboard that displays results based on the shared filter."""
    return ui.panel(
        ui.dashboard(
            ui.row(
                ui.panel(f"Results for: {filter_text}", title="Results"),
                ui.panel(f"Count for: {filter_text}", title="Count"),
            )
        ),
        title="Results Dashboard",
    )


@ui.component
def connected_dashboards():
    """Parent component that shares state between nested dashboards."""
    filter_text, set_filter_text = ui.use_state("initial filter")

    return ui.row(
        filter_dashboard(filter_text, set_filter_text),
        results_dashboard(filter_text),
    )


shared_state_dashboard = ui.dashboard(connected_dashboards())

In this example, connected_dashboards holds the shared filter_text state. Both filter_dashboard and results_dashboard receive this state as props. When the user types in the filter input, both nested dashboards update to reflect the new filter value.

Key considerations for nested dashboards

Isolation: Panels within a nested dashboard can only be dragged within that nested dashboard. Cross-dashboard drag-and-drop is not supported.
State persistence: Each nested dashboard maintains its own layout state. When the page is reloaded, the arrangement of panels within nested dashboards is preserved.
Performance: Each nested dashboard creates its own layout instance. For most use cases this has negligible impact, but consider the complexity when creating many nested dashboards.