Input Elements¶
Input elements collect user-provided data like text, numbers, and date ranges.
TextInput¶
TextInput(value: str = '', description: str = '', title: str = '', show_title: bool = True, show_description: bool = True, required: bool = False, label: str = '', placeholder: str = '', page_update: Optional[PageUpdateCallback] = None, reference_id: Optional[str] = '')
A Text Input element.
Parameters:
-
value(str, default:'') –The inputted text, defaults to ''.
-
description(str, default:'') –The element's description, defaults to ''.
-
title(str, default:'') –The title of the element, defaults to ''.
-
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.
-
required(bool, default:False) –If true, mark the field as required to require user input before the step may continue. Defaults to false.
-
label(str, default:'') –The label of the element, defaults to ''.
-
placeholder(str, default:'') –The placeholder of the text input shown on first view of the input. Defaults to ''.
-
page_update(Optional[PageUpdateCallback], default:None) –Updater function. Allows for handling dynamic page update on a page. Takes a StoreInterface and optionally client runners as arguments. This update is triggered when the user blurs the input or presses the Enter key. Defaults to None (no update function).
-
reference_id(Optional[str], default:'') –EXAMPLE:
# Imports from virtualitics_sdk import TextInput... # Example usage class ExampleStep(Step): def run(self, flow_metadata):... text_input = TextInput("Initial values can be set", title="Text Input", label="Some Text", description="Of course we also allow <em>open ended</em> text input such as this.", placeholder='Type Something') The above TextInput will be displayed as: .. image:: ../images/text_input_ex.png :align: center How to use page_update .. code-block:: python # Imports from virtualitics_sdk import TextInput, StoreInterface, Card, Step... ... # Example page update function def textinput_updater(store_interface: StoreInterface): page = store_interface.get_page() text_element = page.get_element_by_reference_id('My Updatable Text Input') new_value = store_interface.get_element_value( store_interface.step_name, "My Updatable Text Input" ) text_element.description = f'You updated the text field! New value: {new_value}' 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()... text_input = TextInput( "Initial value", title="Title Text Input", description="This text input is updatable.", reference_id="My Updatable Text Input", page_update=textinput_updater ) card = Card(title="Example Card", content=[text_input]) page.add_card_to_section(card, "Ex Section")
from virtualitics_sdk import TextInput
text_input = TextInput(
id="search_query",
title="Search",
placeholder="Enter search term...",
default=""
)
# Get value in action()
def action(self, flow_metadata):
query = self.page.get_element_by_id("search_query").value
results = search_data(query)
return Page(...)
Numeric Inputs¶
NumericSlider¶
NumericRange(min_range: Union[int, float], max_range: Union[int, float], min_selection: Optional[Union[int, float]] = None, max_selection: Optional[Union[int, float]] = None, include_nulls_visible: bool = True, include_nulls_value: bool = False, title: str = '', description: str = '', single: bool = False, show_title: bool = True, show_description: bool = True, label: str = '', placeholder: str = '', step_size: Optional[Union[float, int]] = None, page_update: Optional[PageUpdateCallback] = None, reference_id: Optional[str] = '')
A Numeric Range Input Element.
:meta private:
Parameters:
-
min_range(Union[int, float]) –The minimum value for the range.
-
max_range(Union[int, float]) –The maximum value for the range.
-
min_selection(Optional[Union[int, float]], default:None) –The minimum selected value. Defaults to min_range value, defaults to None.
-
max_selection(Optional[Union[int, float]], default:None) –The maximum selected value. Defaults to max_range value, defaults to None. For single sided sliders, this is the value to change to set defaults.
-
include_nulls_visible(bool, default:True) –whether null values will be visible, defaults to True.
-
include_nulls_value(bool, default:False) –whether to include null values, defaults to False.
-
title(str, default:'') –The title of the element, defaults to ''.
-
description(str, default:'') –The element's description, defaults to ''.
-
single(bool, default:False) –whether this range element is for a single sided slider, defaults to False.
-
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.
-
label(str, default:'') –The label of the element, defaults to ''.
-
placeholder(str, default:'') –The placeholder of the element, defaults to ''.
-
step_size(Optional[Union[float, int]], default:None) –The size of default intervals between the min and max, defaults to None to automatically determine step size.
-
page_update(Optional[PageUpdateCallback], default:None) –A callable that will be executed to update the page when the value of this element changes. The callable should not take any arguments.
-
reference_id(Optional[str], default:'') –EXAMPLE:
# Imports from virtualitics_sdk import NumericRange... # Example usage class ExampleStep(Step): def run(self, flow_metadata):... num_range = NumericRange(0, 50, max_selection=10, single=True, label="Slider Value", title="Single Numeric Range", description="This is a single sided slider.", placeholder='Type a Number', step_size=10) The above NumericRange will be displayed as: .. image:: ../images/numeric_range_ex.png :align: center :scale: 75% <strong>EXAMPLE with page_update:</strong> .. code-block:: python # Imports from virtualitics_sdk import NumericRange, Text... # Example usage class ExampleStep(Step): def <strong>init</strong>(self): self.text_display = Text("Current value: 10") def update_text(self): # This function will be called when the slider value changes new_value = self.num_range.get_value() self.text_display.content = f"Current value: {new_value}" def run(self, flow_metadata): self.num_range = NumericRange(0, 50, max_selection=10, single=True, title="Interactive Slider", page_update=self.update_text) return [self.num_range, self.text_display]
Get the value of an element. If the user has interacted with the value, the default will be updated.
from virtualitics_sdk import NumericSlider
slider = NumericSlider(
id="threshold",
title="Confidence Threshold",
min_value=0.0,
max_value=1.0,
step=0.01,
default=0.5
)
NumericRange¶
NumericRange(min_range: Union[int, float], max_range: Union[int, float], min_selection: Optional[Union[int, float]] = None, max_selection: Optional[Union[int, float]] = None, include_nulls_visible: bool = True, include_nulls_value: bool = False, title: str = '', description: str = '', single: bool = False, show_title: bool = True, show_description: bool = True, label: str = '', placeholder: str = '', step_size: Optional[Union[float, int]] = None, page_update: Optional[PageUpdateCallback] = None, reference_id: Optional[str] = '')
A Numeric Range Input Element.
:meta private:
Parameters:
-
min_range(Union[int, float]) –The minimum value for the range.
-
max_range(Union[int, float]) –The maximum value for the range.
-
min_selection(Optional[Union[int, float]], default:None) –The minimum selected value. Defaults to min_range value, defaults to None.
-
max_selection(Optional[Union[int, float]], default:None) –The maximum selected value. Defaults to max_range value, defaults to None. For single sided sliders, this is the value to change to set defaults.
-
include_nulls_visible(bool, default:True) –whether null values will be visible, defaults to True.
-
include_nulls_value(bool, default:False) –whether to include null values, defaults to False.
-
title(str, default:'') –The title of the element, defaults to ''.
-
description(str, default:'') –The element's description, defaults to ''.
-
single(bool, default:False) –whether this range element is for a single sided slider, defaults to False.
-
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.
-
label(str, default:'') –The label of the element, defaults to ''.
-
placeholder(str, default:'') –The placeholder of the element, defaults to ''.
-
step_size(Optional[Union[float, int]], default:None) –The size of default intervals between the min and max, defaults to None to automatically determine step size.
-
page_update(Optional[PageUpdateCallback], default:None) –A callable that will be executed to update the page when the value of this element changes. The callable should not take any arguments.
-
reference_id(Optional[str], default:'') –EXAMPLE:
# Imports from virtualitics_sdk import NumericRange... # Example usage class ExampleStep(Step): def run(self, flow_metadata):... num_range = NumericRange(0, 50, max_selection=10, single=True, label="Slider Value", title="Single Numeric Range", description="This is a single sided slider.", placeholder='Type a Number', step_size=10) The above NumericRange will be displayed as: .. image:: ../images/numeric_range_ex.png :align: center :scale: 75% <strong>EXAMPLE with page_update:</strong> .. code-block:: python # Imports from virtualitics_sdk import NumericRange, Text... # Example usage class ExampleStep(Step): def <strong>init</strong>(self): self.text_display = Text("Current value: 10") def update_text(self): # This function will be called when the slider value changes new_value = self.num_range.get_value() self.text_display.content = f"Current value: {new_value}" def run(self, flow_metadata): self.num_range = NumericRange(0, 50, max_selection=10, single=True, title="Interactive Slider", page_update=self.update_text) return [self.num_range, self.text_display]
from virtualitics_sdk import NumericRange
range_input = NumericRange(
id="price_range",
title="Price Range",
min_value=0,
max_value=1000,
step=10,
default_min=100,
default_max=500
)
# Get values in action()
def action(self, flow_metadata):
range_elem = self.page.get_element_by_id("price_range")
min_price = range_elem.min_value
max_price = range_elem.max_value
filtered = df[(df['price'] >= min_price) & (df['price'] <= max_price)]
return Page(...)
NumericRangeSlider¶
A Numeric Range Input Element.
:meta private:
Parameters:
-
min_range(Union[int, float]) –The minimum value for the range.
-
max_range(Union[int, float]) –The maximum value for the range.
-
min_selection(Optional[Union[int, float]], default:None) –The minimum selected value. Defaults to min_range value, defaults to None.
-
max_selection(Optional[Union[int, float]], default:None) –The maximum selected value. Defaults to max_range value, defaults to None. For single sided sliders, this is the value to change to set defaults.
-
include_nulls_visible(bool, default:True) –whether null values will be visible, defaults to True.
-
include_nulls_value(bool, default:False) –whether to include null values, defaults to False.
-
title(str, default:'') –The title of the element, defaults to ''.
-
description(str, default:'') –The element's description, defaults to ''.
-
single(bool, default:False) –whether this range element is for a single sided slider, defaults to False.
-
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.
-
label(str, default:'') –The label of the element, defaults to ''.
-
placeholder(str, default:'') –The placeholder of the element, defaults to ''.
-
step_size(Optional[Union[float, int]], default:None) –The size of default intervals between the min and max, defaults to None to automatically determine step size.
-
page_update(Optional[PageUpdateCallback], default:None) –A callable that will be executed to update the page when the value of this element changes. The callable should not take any arguments.
-
reference_id(Optional[str], default:'') –EXAMPLE:
# Imports from virtualitics_sdk import NumericRange... # Example usage class ExampleStep(Step): def run(self, flow_metadata):... num_range = NumericRange(0, 50, max_selection=10, single=True, label="Slider Value", title="Single Numeric Range", description="This is a single sided slider.", placeholder='Type a Number', step_size=10) The above NumericRange will be displayed as: .. image:: ../images/numeric_range_ex.png :align: center :scale: 75% <strong>EXAMPLE with page_update:</strong> .. code-block:: python # Imports from virtualitics_sdk import NumericRange, Text... # Example usage class ExampleStep(Step): def <strong>init</strong>(self): self.text_display = Text("Current value: 10") def update_text(self): # This function will be called when the slider value changes new_value = self.num_range.get_value() self.text_display.content = f"Current value: {new_value}" def run(self, flow_metadata): self.num_range = NumericRange(0, 50, max_selection=10, single=True, title="Interactive Slider", page_update=self.update_text) return [self.num_range, self.text_display]
Get the value of an element. If the user has interacted with the value, the default will be updated.
from virtualitics_sdk import NumericRangeSlider
range_slider = NumericRangeSlider(
id="age_range",
title="Age Range",
min_value=0,
max_value=100,
step=1,
default_min=25,
default_max=65
)
Date/Time Inputs¶
DateTimeRange¶
DateTimeRange(min_range: datetime, max_range: datetime, min_selection: Optional[datetime] = None, max_selection: Optional[datetime] = None, include_nulls_visible: bool = True, include_nulls_value: bool = False, show_date: bool = True, show_time: bool = True, show_timezone: bool = True, is_range: bool = True, title: str = '', description: str = '', show_title: bool = True, show_description: bool = True, label: str = '', placeholder: str = '', timezone: str = 'UTC', page_update: Optional[PageUpdateCallback] = None, reference_id: Optional[str] = '')
A DateTimeRange Input element.
Parameters:
-
min_range(datetime) –The minimum date in the range.
-
max_range(datetime) –The maximum date in the range.
-
min_selection(Optional[datetime], default:None) –The mimumum selected date. Defaults to the min_range value.
-
max_selection(Optional[datetime], default:None) –The maximum selected date. Defaults to max_range value.
-
include_nulls_visible(bool, default:True) –whether null values will be visible, defaults to True.
-
include_nulls_value(bool, default:False) –whether to include null values, defaults to False.
-
show_date(bool, default:True) –whether to show the date selector, defaults to True.
-
show_time(bool, default:True) –whether to show the time selector, defaults to True.
-
show_timezone(bool, default:True) –whether to show the timezone selector, defaults to True.
-
is_range(bool, default:True) –whether to show both start and end date/time (True) or just a single date/time (False), defaults to True.
-
title(str, default:'') –The title of the element, defaults to ''.
-
description(str, default:'') –The element's description, defaults to ''.
-
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.
-
label(str, default:'') –The label of the element, defaults to ''.
-
placeholder(str, default:'') –The placeholder of the element, defaults to ''.
-
timezone(str, default:'UTC') –The timezone for the element, defaults to 'UTC'.
-
page_update(Optional[PageUpdateCallback], default:None) –Updater function. Allows for handling dynamic page update on a page. Takes a StoreInterface and optionally client runners as arguments. This update is triggered when the user blurs the input and the value has changed. Defaults to None (no update function).
-
reference_id(Optional[str], default:'') –EXAMPLE:
# Imports from virtualitics_sdk import DateTimeRange... # Example usage class LandingStep(Step): def run(self, flow_metadata):... date_range = DateTimeRange(datetime.today().replace(year=2000), datetime.today(). replace(year=2020), title="Date Time Range", description= "Here's a datetime range from the beginning of the month to now.") The above DateTimeRange example will be displayed as: .. image:: ../images/date_time_range_ex.png :align: center How to use page_update .. code-block:: python # Imports from virtualitics_sdk import DateTimeRange, StoreInterface, Card, Step from datetime import datetime... ... # Example page update function def datetime_range_updater(store_interface: StoreInterface): page = store_interface.get_page() datetime_element = page.get_element_by_reference_id('My Updatable Datetime Range') new_value = store_interface.get_element_value( store_interface.step_name, "My Updatable Datetime Range" ) datetime_element.description = f'You updated the date range! New value: {new_value}' 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()... datetime_range = DateTimeRange( min_range=datetime(2020, 1, 1), max_range=datetime(2021, 1, 1), title="Title Datetime Range", description="This datetime range is updatable.", reference_id="My Updatable Datetime Range", page_update=datetime_range_updater ) card = Card(title="Example Card", content=[datetime_range]) page.add_card_to_section(card, "Ex Section")
Get the value of an element. If the user has interacted with the value, the default will be updated.
Returns: If is_range is True: dict with 'min' and 'max' keys If is_range is False: string representing the selected date/time
Update the min/max range values for the DateTimeRange element.
Parameters:
-
min_date(Optional[datetime], default:None) –The new minimum date in the range. If None, current min value is preserved.
-
max_date(Optional[datetime], default:None) –The new maximum date in the range. If None, current max value is preserved.
Raises:
-
ValueError–If both min_date and max_date are provided and min_date > max_date.
Reset the selection values to the original min_selection and max_selection provided during initialization.
update_selection(min_value: Optional[datetime] = None, max_value: Optional[datetime] = None, value: Optional[datetime] = None) -> None
Update the selected value(s) for the DateTimeRange element.
Parameters:
-
min_value(Optional[datetime], default:None) –The minimum selected date (for range selections).
-
max_value(Optional[datetime], default:None) –The maximum selected date (for range selections).
-
value(Optional[datetime], default:None) –The selected date (for single date selections when is_range=False).
Raises:
-
ValueError–If mixing value with min_value/max_value, or using value when is_range=True.
from virtualitics_sdk import DateTimeRange
from datetime import datetime, timedelta
# Default to last 30 days
end_date = datetime.now()
start_date = end_date - timedelta(days=30)
date_range = DateTimeRange(
id="date_filter",
title="Date Range",
default_start=start_date,
default_end=end_date
)
# Get values in action()
def action(self, flow_metadata):
date_elem = self.page.get_element_by_id("date_filter")
start = date_elem.start_value
end = date_elem.end_value
filtered = df[(df['date'] >= start) & (df['date'] <= end)]
return Page(...)
Form Validation¶
Validate user inputs:
def action(self, flow_metadata):
text_input = self.page.get_element_by_id("email").value
# Validate email format
if not is_valid_email(text_input):
return Page(
title="Error",
sections=[
Section(
title="Validation Error",
cards=[
Card(
title="Invalid Input",
content=[
RichText("❌ Please enter a valid email address")
]
)
]
)
]
)
# Process valid input
process_email(text_input)
return Page(...)
Combined Input Form¶
Create multi-field forms:
def run(self, flow_metadata):
form_section = Section(
title="User Information",
cards=[
Card(
title="Enter Details",
content=[
TextInput(
id="username",
title="Username",
placeholder="Enter username"
),
TextInput(
id="email",
title="Email",
placeholder="user@example.com"
),
NumericSlider(
id="age",
title="Age",
min_value=18,
max_value=100,
default=25
),
SingleDropdown(
id="country",
title="Country",
options=countries,
default=countries[0]
)
]
)
]
)
return Page(title="Registration", sections=[form_section])
def action(self, flow_metadata):
# Collect all form values
username = self.page.get_element_by_id("username").value
email = self.page.get_element_by_id("email").value
age = self.page.get_element_by_id("age").value
country = self.page.get_element_by_id("country").value
# Validate and process
if not all([username, email, age, country]):
return error_page("All fields are required")
# Save and continue
self._outLink.user_data = {
"username": username,
"email": email,
"age": age,
"country": country
}
return success_page()
Best Practices¶
- Clear Labels: Use descriptive titles for all inputs
- Placeholders: Provide helpful placeholder text
- Defaults: Set sensible default values
- Validation: Validate inputs before processing
- Error Messages: Show clear error messages for invalid inputs
- Required Fields: Indicate which fields are required
- Limits: Set appropriate min/max bounds for numeric inputs
See Also¶
- Dropdowns - Selection inputs
- Elements Overview
- Step Actions