Page¶

Pages define the user interface for each step in your app.

Page Class¶

Page ¶

Page(title: str, sections: List[Section], on_auto_refresh: Optional[PageUpdateCallback] = None, last_updated: Optional[datetime] = None, on_last_updated_click: Optional[DrilldownCallback] = None)

The Page for a Step.

Parameters:

title (str) –

The title of the Page.
sections (List[Section]) –

The sections contained inside the Page.
on_auto_refresh (Optional[PageUpdateCallback], default: None ) –

a callback of type PageUpdateCallback to be called when the page is automatically refreshed. Use the @auto_refresh_callback decorator to instantiate the function. EXAMPLE: .. code-block:: python # Imports from virtualitics_sdk import Page, Section . . . # Example usage class ExStep(Step): def run(self, flow_metadata): . . . ex_step_page = Page(title="Example Page", sections=[Section("", [])]) ex_step = ExStep(title="Example", description="", parent="Data & Visualizations", type=StepType.RESULTS, page=ex_step_page)

sections `property` ¶

sections: List[Section]

Return the sections of a Page.

Returns:

List[Section] –

The sections on a given Page.

get_element_by_id ¶

get_element_by_id(elem_id: str, quiet: bool = False) -> Element

Returns the Element on a Page with a specified ID.

Parameters:

elem_id (str) –

The ID of the element.
quiet (bool, default: False ) –

If True, return None if element is not found. Defaults to False

Raises:

ValueError –

if no element exists with the specified title.

Section Class¶

Section ¶

Section(title: str, content: List[Card], subtitle: str = '', description: str = '', _id: str = None, show_title: bool = True, show_description: bool = True)

A divider of the Page. A container for cards. A Page can have multiple Sections.

Parameters:

title (str) –

The title of the Section.
content (List[Card]) –

The cards inside of this Section.
subtitle (str, default: '' ) –

The subtitle of the Section, defaults to "".
description (str, default: '' ) –

The description for the Section, defaults to "".

_id (str, default: None ) –

EXAMPLE:

# Imports  from virtualitics_sdk import Card, Section...
# Example usage  class ExStep(Step): def run(self, flow_metadata):...
ex_card = Card(title="Example Card", content=[example_content]) ex_section = Section(Here's the card!", [ex_card])

add_card_w_content ¶

add_card_w_content(elems: Union[Element, List[Element], List[Row]], card_title: str = '', card_subtitle: str = '', card_description: str = '', card_id='', show_card_title: bool = True, show_card_description: bool = True, page_update: Optional[Callable] = None, filter_update: Optional[Callable] = None, filters: Optional[List[InputElement]] = None, updater_text: Optional[str] = None, index: Optional[int] = None)

Adds a new card containing the content specified. It's recommended you use the method in the :class:~virtualitics_sdk.page.page.Page class instead when writing apps.

Parameters:

elems (Union[Element, List[Element], List[Row]]) –

The elements to be added. Can be a list or single element.
card_title (str, default: '' ) –

The title of the new card, defaults to ''.
card_subtitle (str, default: '' ) –

The subtitle for the new card, defaults to ''.
card_description (str, default: '' ) –

The description for the new card, defaults to ''.
card_id –

The ID of the card to add, defaults to "".
show_card_title (bool, default: True ) –

whether to show the title of the card on the page when rendered, defaults to True.
show_card_description (bool, default: True ) –

whether to show the description of the card to the page when rendered, defaults to True.
page_update (Optional[Callable], default: None ) –

The page update function for the new card, defaults to None.
filter_update (Optional[Callable], default: None ) –

The filter update function for the new card, defaults to None.
filters (Optional[List[InputElement]], default: None ) –

A list of input elements that can be used as input to the card’s filter function, defaults to previous filter options given for this card.
updater_text (Optional[str], default: None ) –

The text to show on the card’s update button. If this value is not set, the frontend will default to showing previous text set for the updater.

Card Class¶

Card ¶

Card(title: str, content: List[Union[Element, Row]], subtitle: str = '', description: str = '', _id: Optional[str] = None, show_title: bool = True, show_description: bool = True, page_update: Optional[PageUpdateCallback] = None, disable_next: bool = False, updater_text: Optional[str] = None, filters: Optional[List[InputElement]] = None, filter_update: Optional[Callable] = None, show_comments: bool = False, show_export: bool = False, show_share: bool = False, info_content: Optional[str] = None)

A container for elements on a Page. A Section is made up of Cards.

Parameters:

title (str) –

The title for this Card.
content (List[Union[Element, Row]]) –

The elements contained in this Card.
subtitle (str, default: '' ) –

The subtitle for this Card, defaults to "".
description (str, default: '' ) –

The description for this Card, defaults to "".
_id (Optional[str], default: None ) –

ID of the card. Defaults to autogenerated UUID.
show_title (bool, default: True ) –

Whether to show the title on the page when rendered, defaults to True.
show_description (bool, default: True ) –

Whether to show the description to the page when rendered, defaults to True.
page_update (Optional[PageUpdateCallback], default: None ) –

Page update callback. Allows for handling dynamic page updating. Must be decorated using the @page_update_callback decorator. Takes a StoreInterface and optionally client runners as arguments, defaults to None.
disable_next (bool, default: False ) –

If initialized to True, disables the next button for the current step. Must be updated using a page update to allow users to continue to the next step.
updater_text (Optional[str], default: None ) –

The text to show on the update button. If this value is not set, the frontend will default to showing the text, "Update"
filters (Optional[List[InputElement]], default: None ) –

A list of input elements that can be used as input to the card's filter function, defaults to None.
filter_update (Optional[Callable], default: None ) –

Another updater function to call in combination with filter inputs
show_comments (bool, default: False ) –

Whether to share the comments icon on this card. Defaults to False for non-Dashboard Steps This value always be True with Dashboard Steps.
show_export (bool, default: False ) –

Whether to share the export icon on this card. Defaults to False for non-Dashboard Steps This value always be True with Dashboard Steps.
show_share (bool, default: False ) –

Whether to share the share icon on this card. Defaults to False for non-Dashboard Steps This value always be True with Dashboard Steps.

info_content (Optional[str], default: None ) –

EXAMPLE:

# Imports from virtualitics_sdk import Card...
# Example usage class ExStep(Step): def run(self, flow_metadata): store_interface = StoreInterface(**flow_metadata) page = store_interface.get_page()...
card = Card(title="Example Card", content=[example_element]) page.add_card_to_section(card, "")  How to use page_update and updater_text  .. code-block:: python # Imports from virtualitics_sdk import Card...
...
# Example page update function def updater(store_interface: StoreInterface): current_page = store_interface.get_page() updated_example_element = modify(example_element) # modify element(s) in the card current_page.replace_content_in_section( elems=[updated_example_element], section_title="Ex Section", card_title="Example Card" ) store_interface.update_page(current_page)  # Example usage of page updater class ExStep(Step): def run(self, flow_metadata): store_interface = StoreInterface(**flow_metadata) page = store_interface.get_page()...
card = Card(title="Example Card", content=[example_element], page_update=updater, updater_text="Example Text") page.add_card_to_section(card, "Ex Section")  Using a page_update with disable_next=True in order to run validation. You MUST specify card.disable_next = False at some branch of your updater logic to enable the next button.  .. code-block:: python def updater(store_interface: StoreInterface): value_one = store_interface.get_element_value(step_name="StepOne", elem_title="Value One") value_two = store_interface.get_element_value(step_name="StepOne", elem_title="Value Two") current_page = store_interface.get_page() card = current_page.get_card_by_title("Card One") try: result = RichText(f'Result is : {float(value_one) + float(value_two)}! You can now continue to the next step with this valid input.') card.disable_next = False # Next button will be enabled (barring other elements being required) except ValueError as _: result = RichText(f'Could not add together {value_one} and {value_two}. Try again to continue step.') card.disable_next = True # Next button will be disabled still, user will need to re try inputs...
. # add elements and feedback to user. store_interface.update_page(current_page)  How to use filters and filter_update  .. code-block:: python # Imports from virtualitics_sdk import Card...
...
# Example page update function @page_update_callback def updater(store_interface: StoreInterface): page = store_interface.get_page() card = page.get_card_by_title("Card Title")  dropdown = store_interface.get_element_value( store_interface.step_name, "Single Selection Dropdown" ) date_range = store_interface.get_element_value( store_interface.step_name, "Date Range Title" )  store_interface.update_page(page) ...   # Example usage of page updater class ExStep(Step): def run(self, flow_metadata): store_interface = StoreInterface(**flow_metadata) page = store_interface.get_page()...
min_range = datetime(2020, 6, 27, 12) max_range = datetime(2025, 1, 27, 12) date_range =  DateTimeRange(min_range=min_range, max_range=max_range, title="Date Range Title", description= "date-description")  dropdown_options = ['a', 'b', 'c'] dropdown = Dropdown(options=dropdown_options, multiselect=False, title="Single Selection Dropdown", selected=['a'])  card = Card(title="Card Title", content=[example_element], filters=[dropdown, date_range], filter_update=updater) page.add_card_to_section(card, "Ex Section")

add_content ¶

add_content(content: Union[Row, List[Element], Element], ratio: Optional[List[Union[int, float]]] = None, index: Optional[int] = None)

Add content to a Card.

Parameters:

content (Union[Row, List[Element], Element]) –

The element(s) to add to the Card.
ratio (Optional[List[Union[int, float]]], default: None ) –

The relative widths of the elements inside the :class:~virtualitics_sdk.elements.dashboard.Row,
index (Optional[int], default: None ) –

The index to add the content to. If None, it will default to appending the content to the end of the card defaults to all elements having the same width.

update_item ¶

update_item(element_title: str, new_element: Element)

This function updates an element in a dashboard, which can be used in conjunction with the card's updater or filter_update function to provide dynamic page updates.

Parameters:

element_title (str) –

The title of the element to be updated.
new_element (Element) –

The new element that will replace currently existing element.

remove_item ¶

remove_item(element_title: str, quiet: bool = False)

This function removes an element in a dashboard, which can be used in conjunction with the card's updater of filter_update function to provide dynamic page updates.

Parameters:

element_title (str) –

The title of the element to be updated.
quiet (bool, default: False ) –

If True, do not return an error if there is no element with that title found on the page. Defaults to False

force_update ¶

force_update()

Mark page as edited to force an update.

Usage Example¶

from virtualitics_sdk import Page, Section, Card, Table, RichText

# Create a page with multiple sections
page = Page(
    title="Analysis Results",
    sections=[
        Section(
            title="Data Overview",
            cards=[
                Card(
                    title="Summary Statistics",
                    content=[Table(data=stats_df)]
                )
            ]
        ),
        Section(
            title="Visualizations",
            cards=[
                Card(
                    title="Distribution Plot",
                    content=[PlotlyPlot(figure=fig)]
                )
            ]
        )
    ]
)

Page Structure¶

Pages follow a hierarchical structure:

Page
└── Section (1 or more)
    └── Card (1 or more)
        └── Element (1 or more)

Working with Sections¶

Sections organize related content on a page:

section = Section(
    title="Data Analysis",
    cards=[card1, card2, card3],
    description="Analysis results and visualizations"
)

Working with Cards¶

Cards are containers for UI elements:

# Simple card with single element
card = Card(
    title="Sales Table",
    content=[Table(data=sales_df)]
)

# Card with multiple elements
card = Card(
    title="Multi-Element Card",
    content=[
        RichText("## Overview"),
        Table(data=df),
        PlotlyPlot(figure=fig)
    ]
)

Dynamic Updates¶

Getting Elements¶

Retrieve elements by ID to check their values:

def action(self, flow_metadata):
    # Get dropdown value
    selected_region = self.page.get_element_by_id("region_dropdown").value

    # Get text input
    user_input = self.page.get_element_by_id("search_box").value

    # Process and return new page
    return Page(...)

Updating Elements¶

Update elements dynamically:

# Update element and get new page
new_page = self.page.update_element(
    element_id="status_text",
    new_value="Processing complete"
)

Auto-Refresh¶

Pages can auto-refresh at intervals:

from virtualitics_sdk import Page, auto_refresh_callback

@auto_refresh_callback(refresh_rate_seconds=5)
async def refresh_page(page, link, flow_metadata):
    # Update page content
    new_data = fetch_latest_data()
    # Return updated page elements
    return {"data_table": Table(data=new_data)}

page = Page(
    title="Live Dashboard",
    sections=[...],
    on_auto_refresh=refresh_page
)

Card Types¶

Container¶

Container extends Card with show/hide toggling. See Container for details.

Segment¶

Segment extends Card and is used inside a SegmentedControl. See Segmented Control for details.

CardType ¶

AccordionDetail¶

AccordionDetail extends Card and is used inside a Accordion. See Accordion for details.

CardType ¶

Comment¶

Comments can be attached to cards for collaboration:

Comment ¶

Comment(commenter: str, message: str)

from virtualitics_sdk.page.comment import Comment

# Add a comment to a card
comment = Comment(commenter="user@example.com", message="This looks good!")
card.add_comment(comment)

Cards expose show_comments=True to display the comments icon in Dashboard steps.

Drilldowns¶

Drilldowns open modal overlays or popovers when triggered by a button callback.

DrilldownType¶

DrilldownType ¶

DrilldownSize¶

See Callbacks Reference for the full enum values.

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

@drilldown_callback(
    drilldown_type=DrilldownType.FAST_MODAL,
    drilldown_size=DrilldownSize.LARGE
)
async def show_detail(card, input_data, store_interface):
    card.add_content([RichText("## Modal Content")])

See the Callbacks Reference for the full drilldown callback API.

Best Practices¶

Logical Grouping: Group related content in sections
Clear Titles: Use descriptive section and card titles
Unique IDs: Ensure all elements have unique IDs within a page
Responsive Layout: Cards automatically layout responsively
Limit Elements: Don't overcrowd pages, use multiple steps instead

Page¶

Page Class¶

Page ¶

sections property ¶

get_element_by_id ¶

Section Class¶

Section ¶

add_card_w_content ¶

Card Class¶

Card ¶

add_content ¶

update_item ¶

remove_item ¶

force_update ¶

Usage Example¶

Page Structure¶

Working with Sections¶

Working with Cards¶

Dynamic Updates¶

Getting Elements¶

Updating Elements¶

Auto-Refresh¶

Card Types¶

Container¶

Segment¶

CardType ¶

AccordionDetail¶

CardType ¶

Comment¶

Comment ¶

Drilldowns¶

DrilldownType¶

DrilldownType ¶

DrilldownSize¶

Best Practices¶

See Also¶

sections `property` ¶