scenario_selector

Select scenarios from the list of all scenario entities.

The Scenario Selector shows all the scenario entities handled by Taipy and lets the user select a scenario from a list, create new scenarios or edit existing scenarios.

Properties¶

Name	Type	Default	Description
`value`^(★)	`Union[Scenario, list[Scenario]]` dynamic		Bound to the selected `Scenario`, or None if there is none.
`scenarios`	`list[Union[Scenario,Cycle]]` dynamic	None	The list of `Cycle` or `Scenario` objects to show. If this is None, all Cycles and Scenarios are listed.
`multiple`	`bool`	False	If True, the user can select multiple scenarios, therefore the value property can hold a list of `Scenario` objects.
`filter`	`Union[bool,str,taipy.gui_core.filters.ScenarioFilter,list[Union[str,taipy.gui_core.filters.ScenarioFilter]]]`	"*"	One or multiple `Scenario` property names to filter on. If False, do not allow filter.
`show_search`	`bool`	True	If False, prevents users from searching for scenarios by label.
`sort`	`Union[bool,str,taipy.gui_core.filters.ScenarioFilter,list[Union[str,taipy.gui_core.filters.ScenarioFilter]]]`	"*"	A list of `Scenario` property names to sort on. If False, do not allow sort.
`show_add_button`	`bool`	True	If False, the button to create a new scenario is not displayed.
`display_cycles`	`bool`	True	If False, the cycles are not shown.
`show_primary_flag`	`bool`	True	If False, the primary scenarios are not identified with specific visual hint.
`show_pins`	`bool`	False	If True, a pin is shown on each item of the selector and allows to restrict the number of displayed items.
`on_change`	`Union[str, Callable]`		A function or the name of a function that is triggered when the value is updated. The parameters of that function are all optional: state (`State`): the state instance. var_name (str): the variable name. value (`Scenario`): the selected scenario.
`show_dialog`	`bool`	True	If True, a dialog is shown when the user click on the 'Add scenario' button.
`on_creation`	`Union[str, Callable]`		A function or the name of a function that is triggered when a scenario is about to be created. All the parameters of that function are optional: state (`State`): the state instance. id (str): the identifier of this scenario selector. payload (dict): the details on this callback's invocation. This dictionary has the following keys: config (str): the name of the selected scenario configuration. date (datetime): the creation date for the new scenario. label (str): the user-specified label. properties (dict): a dictionary containing all the user-defined custom properties. The callback function can return a scenario, a string containing an error message (a scenario will not be created), or None (then a new scenario is created with the user parameters).
`height`	`str`	"50vh"	The maximum height, in CSS units, of the control.
`id`	`str`		The identifier that will be assigned to the rendered HTML component.
`class_name`	`str` dynamic		The list of CSS class names associated with the generated HTML Element. These class names will be added to the default `taipy_gui_core-scenario_selector`.

^(★)value is the default property for this visual element.

Details¶

The Scenario Selector is a visual control that displays a tree structure where scenarios are grouped by their respective cycles (provided the display_cycles property is not set to False).

Here is an example of a populated Scenario Selector:

In the example above, we observe several created scenarios, including some organized within a cycle, as indicated by the icon.

Additionally, because the show_primary_flag property is enabled by default (not explicitly set to False), the primary scenario within each cycle is marked with a icon, allowing users to identify it at a glance.

At the top of the control, a toolbar provides a few icons that let users perform various tasks:

: Opens a filter configuration dialog, allowing users to define filters that apply to the list of scenarios. This is described in the Filtering section.
: Enables users to specify sorting preferences for organizing the scenarios in the list. This is described in the Sorting section.
: Toggles the visibility of a text search box, which helps users locate specific scenarios quickly. This is described in the Searching section.

Creating new scenarios¶

If no scenarios have been created yet, the tree selector will appear empty.
By default, a button for creating new scenarios is displayed, controlled by the show_add_button property:

When the 'Add Scenario' button is clicked, a dialog appears, allowing users to configure the new scenario's settings:

In the dialog, users must specify:

The scenario configuration to use,
The scenario creation date,
The label for the new scenario.

Additionally, custom properties can be added to the scenario by clicking the button (Add) located to the right of the property key and value fields.

After configuring the necessary details:

Clicking the 'Create' button will create the scenario and add it to the Scenario Selector list.
Clicking the 'Cancel' button will close the dialog without saving any changes.

Editing a scenario¶

To edit an existing scenario, users can click the icon (Edit) located next to the scenario item in the tree. This action opens a dialog box similar to the scenario creation dialog, allowing users to modify scenario settings.

Here is how this dialog box looks like:

In the dialog, users can:

Modify the Scenario Label,
Add custom properties by filling in the 'Key' and 'Value' fields in the 'Custom Properties' section then pressing the icon (Add),
Remove custom properties by clicking the icon (Delete) next to an existing custom property.

Note that the scenario configuration and creation date cannot be modified.

The 'Apply' button saves and propagates changes to the scenario.
The 'Cancel' button closes the dialog without making any changes.
The 'Delete' button permanently deletes the scenario.

Selecting a scenario¶

When the user selects a scenario in the tree selector, the value property is set to the selected entity and the on_change callback is invoked. The application can then use the selected value.

If no scenario is selected, value is set no None.

Filtering¶

The Filter functionality allows users to refine the list of scenarios by applying one or more criteria.

Here is the Scenario Selector list that we will work with to demonstrate this functionality.

Opening the Filter dialog

When the user presses the icon (Filter), the following dialog appears:

All the filters that are currently applied to the list of scenarios are shown. So far, the list is empty.

Creating a new filter criteria

To create a new filter, the user must select a filtering criterion from the dropdown menu in the first field:

After selecting a criterion, the 'Action' dropdown updates with comparison options specific to the selected criterion.
The available comparisons depend on the type of the selected field:

Boolean: Options include "is" and "is not." The value field accepts True or False.
String: Options include "is," "is not," and "contains." The value field accepts a text value.
Number: Options include "equals," "does not equal," "is less than," "is less than or equal to," "is greater than or equal to" and "is greater than." The value field accepts a numerical value.
Date: Options include "is on," "is not on," "is before," "is on or before," "is on or after" and "is after." The value field accepts a date value.

To list all data nodes with labels containing the string "ina", the user would configure a filter as follows:

To add this filter to the filters list, the user must press the (Check) icon.
Multiple filters can be added as needed.

To close the filter configuration dialog, the user must click outside the dialog area.

Once filters are added, they are applied immediately. The filtered scenario list appears as shown:

You can see that only scenarios with matching label now appear in the list.
The icon (Filter) in the control's tool bar has an overlay icon indicating that a filter with one criterion is currently applied.

Removing a filter criteria

To remove a filter from the list, the user would open the filters dialog ( icon), locate the criterion that must be removed and delete it pressing the icon (Delete).

Sorting¶

By default, the Scenario Selector sorts scenarios in ascending order by their creation date. When applicable, scenarios are grouped by their respective Cycle.

Users can customize the sorting order by defining custom sorting criteria, similar to the process of filtering. This allows users to create a prioritized sequence of sorting rules.

Each sorting criterion specifies:

The scenario property to sort by (e.g., label, creation date).
The sorting direction, either ascending ("asc") or descending ("desc").

Consider the following initial list of scenarios displayed in the selector:

Users can click the icon (Sort) to open the sorting configuration dialog:

Users can select a property from the dropdown and specify the sorting order: 'asc' (Ascending) or 'desc' (Descending).

In the following image, the user has selected the 'Label' property with a descending sort:

After the sorting criterion is validated (pressing the icon), it is added to the sorting rules. The scenarios are immediately reordered according to the applied criteria:

Note the overlay indicator on top of the icon, indicating that a sorting criterion is currently applied.

Additional sorting rules can be created, applied sequentially in the specified order of priority.
To remove a sorting rule, the user can click the button next to the criterion.

To exit the sorting configuration window, users must click anywhere outside the dialog window.

Searching¶

The Search feature allows users to quickly locate scenarios by filtering the list based on text input.

When the user presses the icon (Search), a search box appears within the Scenario Selector interface:

If text is entered in the search box, the list dynamically updates to display only scenarios with labels containing the entered text:

To close the search box, the user must press the icon (Search off) in the toolbar.

Usage¶

Customizing the creation¶

You can set the on_creation property to a callback function that lets you customize how a new scenario is created when pressing the 'Add Scenario' button.

This callback function expects three parameters:

state: the State of the user;
id: the identifier of the control, if any;
payload: a dictionary that contains the following keys:
- action: the name of the callback function;
- config: the ScenarioConfig that was selected in the dialog;
- date: a datetime.datetime object representing the date and time when the creation was requested;
- label: the scenario label as specified in the dialog. This string is used as the scenario name;
- properties: a dictionary that contains all the custom properties that the user has defined in the creation dialog.

The payload parameter contains all the information that is needed to create a new scenario. In the callback function, you can use these parameters to customize the new scenario creation further.

If all those parameters look just fine in terms of what needs to be achieved, the callback function can simply return None. That will get Taipy to carry on with the scenario creation with no customization whatsoever.
That is the default behavior of a scenario_selector control that has no value in its on_creation.
If the parameters (typically the custom property keys or values) are invalid in the application's context, you may want to refuse the creation of the scenario. In this case, the callback function should return a string that provides visual feedback to the user (or an empty string if this is not needed).
You can also create the scenario in the function callback and return it. This is the opportunity to change the scenario creation parameters to fit the application's needs.

Here is an example of a creation callback function that deals with these three situations.

Imagine that the application, if the user has added the "index" custom property to a scenario, needs to check that the property value is valid and transform it before the scenario is actually created.
In our example, we expect the user to set a positive integer value to the property "index". The code will check that the value is valid and replace it with a string representation of this value minus one, prefixed with the sharp ('#') sign.
Here is the code for the creation callback function:

def check_index(state, id, payload):
  # Retrieve the custom properties
    properties = payload.get("properties", None)
    if not properties or not "index" in properties:
        # No custom 'index' property
        # Create a regular scenario
        return None
    # Read the 'index' property
    index = None
    try:
        index = int(properties["index"])
        # Invalid value: must be greater than 1
        if index < 1:
            return "'index' must be strictly positive"
        # Replace the property value
        properties["index"] = f"#{index-1}"
    except: # Invalid value: not an integer
        return "'index' property is not a valid integer"
    # Create a new scenario with the same configuration, label, and date
    scenario = tp.create_scenario(payload["config"], payload["date"], payload["label"])
    # Set the scenario properties
    scenario.properties.update(properties)
    return scenario

When the user requests the creation of a new scenario, the creation dialog pops up. When fields are properly set (only the label is mandatory), the user will press the 'Create' button to confirm the scenario creation.
At this time, the application will invoke the creation callback to customize the scenario parameters.

Lines 4-7 deal with the case where the index custom property was not set. In this case, we want to do nothing special and carry on with the regular creation of the control, returning None from the callback function.

Line 9-18 verify that the index custom property is a valid integer greater than one. If this is not the case, an error message is returned to the user for correction.

Finally, lines 20-22 take care of creating the scenario with the new settings.
This scenario is returned by the callback function to let Taipy know it was created properly.

The Scenario Selector control definition needs to have the on_creation property set to the function:

Definition

MarkdownHTMLPython

<|{scenario}|scenario_selector|on_creation=check_index|>

<taipy:scenario_selector on_creation="check_index">{scenario}</taipy:scenario_selector>

import taipy.gui.builder as tgb
...
tgb.scenario_selector("{scenario}", on_creation=check_index)