Callbacks¶

Callbacks define how buttons, containers, auto-refresh, and row actions respond to user interactions. All executable callbacks must be async functions.

Callback Types¶

Type	Decorator / Class	Purpose	Returns
Standard Event	`@standard_event_callback`	Toast notification	`str`
Page Update	`@page_update_callback`	Modify page elements	`None`
Drilldown	`@drilldown_callback(type, size)`	Open modal/popover	`None`
Auto Refresh	`@auto_refresh_callback(rate)`	Periodic page update	`None`
Row Action	`@row_action_callback(title)`	Table row interaction	`None`
Container Toggle	`ContainerToggleCallback(...)`	Show/hide container	N/A
Asset Download	`AssetDownloadCallback(...)`	Trigger file download	N/A

Standard Event Callback¶

Returns a message string displayed as a toast notification. The page is not re-rendered.

StandardEventCallback ¶

Protocol/Type Hint for the CallbackType.STANDARD typed callback.

The callback must be an async function with the following signature::

async def example_callback(store_interface: StoreInterface,
                           **step_clients: dict[str, Any] | None) -> str:
    return "success message"

from virtualitics_sdk.types.callbacks import standard_event_callback
from virtualitics_sdk.store.store_interface import StoreInterface

@standard_event_callback
async def on_click(store_interface: StoreInterface) -> str:
    # Perform an action
    return "Operation completed successfully!"

button = Button(
    title="Run",
    on_click=on_click,
    show_confirmation=False
)

Page Update Callback¶

Modifies the current page in place. Changed elements re-render automatically without a full page refresh.

PageUpdateCallback ¶

Protocol/Type Hint for the CallbackType.PAGE_UPDATE typed callback.

The callback must be an async function with the following signature::

async def example_callback(store_interface: StoreInterface,
                           **step_clients: dict[str, Any] | None) -> None:

from virtualitics_sdk.types.callbacks import page_update_callback

@page_update_callback
async def refresh_data(store_interface: StoreInterface) -> None:
    page = await store_interface.get_page()
    table = page.get_element_by_id("data_table")
    table.data = fetch_new_data()

button = Button(
    title="Refresh",
    on_click=refresh_data,
    show_confirmation=False
)

Drilldown Callback¶

Opens a modal or popover overlay with custom content.

DrilldownCallback ¶

Protocol defining the required callback signature. Any callable matching this signature can be used as a drilldown callback.

from virtualitics_sdk.types.callbacks import drilldown_callback
from virtualitics_sdk.page.drilldown import DrilldownType, DrilldownSize
from virtualitics_sdk.store.drilldown_store_interface import DrilldownStoreInterface

@drilldown_callback(
    drilldown_type=DrilldownType.FAST_MODAL,
    drilldown_size=DrilldownSize.LARGE
)
async def show_details(
    card: Card,
    input_data: dict[str, str | float | int],
    store_interface: DrilldownStoreInterface
) -> None:
    detail_df = await store_interface.get_data("details")
    card.add_content([
        RichText("## Details"),
        Table(data=detail_df)
    ])

Drilldown Types¶

DrilldownType ¶

Drilldown Sizes¶

DrilldownSize ¶

Auto Refresh Callback¶

Periodically updates the page at a specified interval. Useful for live dashboards.

from virtualitics_sdk.types.callbacks import auto_refresh_callback

@auto_refresh_callback(refresh_rate_seconds=5)
async def refresh_dashboard(store_interface: StoreInterface) -> None:
    page = await store_interface.get_page()
    metrics = page.get_element_by_id("live_metrics")
    metrics.data = fetch_latest_metrics()

Row Action Callback¶

Handles interactions with table row actions. Receives the row data in input_data.

from virtualitics_sdk.types.callbacks import row_action_callback

@row_action_callback(title="View Details")
async def view_row(store_interface: StoreInterface, input_data: dict) -> None:
    page = await store_interface.get_page()
    detail_text = page.get_element_by_id("row_detail")
    detail_text.content = f"Selected row: {input_data}"

Container Toggle Callback¶

Toggles the visibility of a Container element. This is a class, not a decorator — pass it directly as on_click.

ContainerToggleCallback ¶

ContainerToggleCallback(visible: bool, container_id: str)

from virtualitics_sdk.types.callbacks import ContainerToggleCallback

# Show a container
show_btn = Button(
    title="Show",
    on_click=ContainerToggleCallback(visible=True, container_id="my_container")
)

# Hide a container
hide_btn = Button(
    title="Hide",
    on_click=ContainerToggleCallback(visible=False, container_id="my_container")
)

The container_id accepts the ID with or without the card/ prefix.

Asset Download Callback¶

Triggers a file download when clicked. Requires an Asset object.

AssetDownloadCallback ¶

AssetDownloadCallback(asset: Asset, extension: str = 'csv', mime_type: str | None = None, label: str | None = None)

Configure the asset to be downloaded.

Parameters:

asset (Asset) –

Object with id, type, label, name, time_created.
extension (str, default: 'csv' ) –

File extension for the download.
mime_type (str | None, default: None ) –

Mime type of the download.
label (str | None, default: None ) –

Optional override for the download label (defaults to asset.label).

from virtualitics_sdk.types.callbacks import AssetDownloadCallback

button = Button(
    title="Download",
    on_click=AssetDownloadCallback(
        asset=my_asset,
        extension=".csv",
        mime_type="text/csv"
    )
)

Callback Validation¶

All executable callbacks (standard_event, page_update, drilldown, row_action) are validated at decoration time:

Must be async functions
Must have the required parameters (store_interface, and input_data for drilldown/row_action)
standard_event_callback must have a -> str return annotation

Invalid callbacks raise TypeError at import time with a descriptive message.

Importing All Callbacks¶

from virtualitics_sdk.types.callbacks import (
    # Decorators
    standard_event_callback,
    page_update_callback,
    drilldown_callback,
    auto_refresh_callback,
    row_action_callback,
    # Classes
    ContainerToggleCallback,
    AssetDownloadCallback,
)