Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Scenario Selector documentation with 4.0 features #1215

Merged
merged 4 commits into from
Nov 27, 2024
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ mkdocs.yml
/docs/gallery/other/index.md

/docs/refmans/gui/viselements/index.md
/docs/refmans/gui/viselements/mui-icons.svg
/docs/refmans/gui/viselements/generic/*.md
!/docs/refmans/gui/viselements/generic/index.md
/docs/refmans/gui/viselements/generic/charts/*.md
Expand Down
31 changes: 16 additions & 15 deletions docs/refmans/gui/viselements/corelements/data_node.md_template
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@ To edit the data node, the user can click the line where the value is displayed:
Note that a 'Comment' field allows the user to explain why this value is changed. This information
is part of the history of the data node.

When the new value is entered, the user presses the 'Apply' (✓) or the 'Cancel' (⨉) button to
apply or cancel the change, respectively.
When the new value is entered, the user presses the [MUI:CheckCircle] icon or the [MUI:Cancel] icon
to apply or cancel the change, respectively.

### Tabular data

Expand All @@ -59,8 +59,8 @@ top-left corner of the 'Properties' section:
<figcaption>Data representation switch</figcaption>
</figure>

In the image above, the switch is set to the 'Table' mode.<br/>
The other option is the 'Chart' mode.
In the image above, the switch is set to the 'Table' mode ([MUI:TableChartOutlined] icon).<br/>
The other option is the 'Chart' mode ([MUI:BarChartOutlined] icon).

Tabular data can be edited only in the 'Table' mode, as described in
[this section](#editing-tabular-data).
Expand Down Expand Up @@ -123,9 +123,9 @@ From this tab, you can access the attributes of the data node:
<figcaption>The Properties section</figcaption>
</figure>

The label of the data node can be changed using the 'Label' field: click in the value area, change
the content, then press the 'Apply' button (with the ✓ icon.)<br/>
To cancel the change, press the 'Cancel' button (with the ⨉ icon).
The label of the data node can be changed using the 'Label' field: the user clicks in the value
area, change the content, then presses the [MUI:CheckCircle] icon (Apply).<br/>
The [MUI:Cancel] icon (Cancel) is used to cancel the change.

If the data node has has an owner (a scenario or a cycle) and if the [*show_owner*](#p-show_owner)
property is set to True (which is its default value), the label of the owning entity appears in the
Expand All @@ -135,20 +135,21 @@ property is set to True (which is its default value), the label of the owning en
<img src="../data_node-properties-owner-l.png" class="visible-light" width="70%"/>
<figcaption>The data node is owned by a scenario</figcaption>
</figure>
When the selected data node is owned by a scenario, a button is visible next to the scenario's
label. This button can be pressed to display the list of the owning scenarios so the user can
select one from there. As a result, any variable bound to the [*scenario*](#p-scenario) is set to
the selected scenario entity: the application can use that to update other parts of the page from
When the selected data node is owned by a scenario, the [MUI:Launch] icon is visible next to the
scenario's label. This icon can be clicked to display the list of the owning scenarios so the user
can select one from there. As a result, any variable bound to the [*scenario*](#p-scenario) is set
to the selected scenario entity: the application can use that to update other parts of the page from
an `on_change` callback.

The section at the bottom lists the custom properties for the selected data node. This is visible
only if the [*show_properties*](#p-show_properties) property is set to True (which is its default
value).<br/>
The user can create new properties by clicking the 'New Property Key' line, providing a property
name and value, and then pressing the 'Apply' button (with the ✓ icon.).<br/>
The user can cancel the creation of a new property by pressing the 'Cancel' button (with the ⨉
icon).<br/>
The user can delete a property by selecting it and pressing the *trash* button.
name and value, and then pressing the [MUI:CheckCircle] icon.<br/>
The user can cancel the creation of a new property by pressing the [MUI:Cancel] icon.

The user can delete a property by selecting it and then pressing the [MUI:DeleteOutline] icon
(Delete).

## The 'History' tab

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,8 @@ the selector might appear as follows:
Data nodes are organized in their owning scenario and cycle, when relevant.<br/>
In this example, *cleaned_dataset* and *initial_dataset* are scoped at the
[`Scope.GLOBAL`](../../../reference/pkg_taipy/pkg_common/pkg_config/Scope/index.md) level.<br/>
Expanding the 'My scenario' item (by clicking the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#collapse"/></svg>
- Expand - icon) reveals data nodes scoped at
[`Scope.SCENARIO`](../../../reference/pkg_taipy/pkg_common/pkg_config/Scope/index.md).
Expanding the 'My scenario' item (by clicking the [MUI:ChevronRight] icon) reveals data nodes scoped
at [`Scope.SCENARIO`](../../../reference/pkg_taipy/pkg_common/pkg_config/Scope/index.md).

When the user selects a data node, the [*on_change*](#p-on_change) callback is triggered allowing
the application to respond to the user's selection. The selected node's value is reflected in the
Expand All @@ -31,19 +29,17 @@ icons allow users to perform various actions:
<figure class="tp-center">
<img src="../data_node_selector-toolbar-d.png" class="visible-dark" width="120%"/>
<img src="../data_node_selector-toolbar-l.png" class="visible-light" width="120%"/>
<figcaption>Data node selector toolbar</figcaption>
<figcaption>Data Node Selector toolbar</figcaption>
</figure>

Users can interact with the icons in the toolbar to perform various tasks:

- <svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#filter_list"/></svg>
: Opens a filter configuration dialog, allowing users to define filters that apply to the list of
data nodes.
- <svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#sort_by_alpha"/></svg>:
Enables users to specify sorting preferences for organizing the data nodes in the list.
- <svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#search_outlined"/></svg>
: Toggles the visibility of a text search box, which helps users locate specific data nodes
quickly.
- [MUI:FilterList]: Opens a filter configuration dialog, allowing users to define filters that apply
to the list of data nodes.
- [MUI:SortByAlpha]: Enables users to specify sorting preferences for organizing the data nodes in
the list.
- [MUI:SearchOutlined]: Toggles the visibility of a text search box, which helps users locate
specific data nodes quickly.

<h3 id="filtering">Filtering</h3>

Expand All @@ -52,16 +48,14 @@ criteria.

<h4>Opening the Filter dialog</h4>

When the user presses the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#filter_list"/></svg>
icon (Filter), the following dialog appears:
When the user presses the [MUI:FilterList] icon (Filter), the following dialog appears:
<figure class="tp-center">
<img src="../data_node_selector-filter1-d.png" class="visible-dark" width="80%"/>
<img src="../data_node_selector-filter1-l.png" class="visible-light" width="80%"/>
<figcaption>Initialize filters</figcaption>
</figure>

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

<h4>Creating a new filter</h4>
Expand All @@ -87,17 +81,15 @@ The available comparisons depend on the type of the selected field:
- 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 "eva", the user would configue a filter as
To list all data nodes with labels containing the string "eva", the user would configure a filter as
follows:
<figure class="tp-center">
<img src="../data_node_selector-filter3-d.png" class="visible-dark" width="80%"/>
<img src="../data_node_selector-filter3-l.png" class="visible-light" width="80%"/>
<figcaption>Create a new filter</figcaption>
</figure>

To add this filter to the filters list, the user must press the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#check"/></svg>
(Check) icon.<br/>
To add this filter to the filters list, the user must press the [MUI:Check] icon (Check).<br/>
Multiple filters can be added as needed.

To close the filter configuration dialog, the user must click outside the dialog area.
Expand All @@ -109,15 +101,12 @@ Once filters are added, they are applied immediately. The filtered data node lis
<figcaption>Filters applied</figcaption>
</figure>

To remove a filter from the list, the user would open the filters dialog
(<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#filter_list"/></svg>
icon), locate the criterion that must be removed and delete it pressing the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#delete"/></svg>
(Delete) icon.
To remove a filter from the list, the user would open the filters dialog ([MUI:FilterList] icon),
locate the criterion that must be removed and delete it pressing the [MUI:Delete] icon (Delete).

<h3 id="sorting">Sorting</h3>

The data node selector sorts data nodes by default in alphabetically ascending order based on their
The Data Node Selector sorts data nodes by default in alphabetically ascending order based on their
labels. Grouping is applied according to their respective Cycle or Scenario, if applicable

Users can define custom sorting criteria to modify how data nodes are ordered. This process is
Expand All @@ -136,9 +125,7 @@ Consider the following initial list of data nodes displayed in the selector:
<figcaption>Initial data nodes list</figcaption>
</figure>

When the user presses the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#sort_by_alpha"/></svg>
icon (Sort), the sorting configuration dialog appears:
When the user presses the [MUI:SortByAlpha] icon (Sort), the sorting configuration dialog appears:
<figure class="tp-center">
<img src="../data_node_selector-sort2-d.png" class="visible-dark" width="80%"/>
<img src="../data_node_selector-sort2-l.png" class="visible-light" width="80%"/>
Expand All @@ -155,20 +142,16 @@ In the following image, the user has selected the 'Label' property, and a descen
<figcaption>Sort criterion configuration</figcaption>
</figure>

After the sorting criterion is validated (pressing the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#check"/></svg> icon),
it is added to the sorting criteria list and the criterion is immediately applied to reorder the
data nodes:
After the sorting criterion is validated (pressing the [MUI:Check] icon), it is added to the sorting
criteria list and the criterion is immediately applied to reorder the data nodes:
<figure class="tp-center">
<img src="../data_node_selector-sort4-d.png" class="visible-dark" width="80%"/>
<img src="../data_node_selector-sort4-l.png" class="visible-light" width="80%"/>
<figcaption>Data nodes sorted by their label</figcaption>
</figure>

The user can then create additional sorting criteria (which are applied in sequence).<br/>
To remove a sorting rule, the user can select the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#delete"/></svg> button
next to the criterion.
To remove a sorting rule, the user can select the [MUI:Delete] button next to the criterion.

To exit the sorting dialog, click anywhere outside the dialog window.

Expand All @@ -177,9 +160,8 @@ To exit the sorting dialog, click anywhere outside the dialog window.
The Search feature allows users to quickly locate data nodes by filtering the list based on text
input.

When the user presses the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#search_outlined"/></svg>
icon (Search), a search box appears within the data node selector interface:
When the user presses the [MUI:SearchOutlined] icon (Search), a search box appears within the Data
Node Selector interface:
<figure class="tp-center">
<img src="../data_node_selector-search1-d.png" class="visible-dark" width="80%"/>
<img src="../data_node_selector-search1-l.png" class="visible-light" width="80%"/>
Expand All @@ -194,9 +176,8 @@ labels containing the entered text:
<figcaption>Search active</figcaption>
</figure>

To close the search box, the user must press the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#search_off_outlined"/></svg>
icon (Search off) in the toolbar.
To close the search box, the user must press the [MUI:SearchOffOutlined] icon (Search off) in the
toolbar.

<h3 id="pinning">Pinning</h3>

Expand All @@ -208,17 +189,16 @@ Assuming we are in the following situation:
<figure class="tp-center">
<img src="../data_node_selector-pin1-d.png" class="visible-dark" width="80%"/>
<img src="../data_node_selector-pin1-l.png" class="visible-light" width="80%"/>
<figcaption>Crowded data node selector</figcaption>
<figcaption>Crowded Data Node Selector</figcaption>
</figure>

If the user wants to focus only on the data node called *initial_dataset* and the data nodes from
the scenario called 'Peter's', she can click the
<svg class="mui-icon" viewBox="0 0 24 24"><use href="../../mui-icons.svg#push_pin_outlined"/></svg>
icon (Pin) next to these two items. Here is what the display would look like:
the scenario called 'Peter's', she can click the [MUI:PushPinOutlined] icon (Pin) next to these two
items. Here is what the display would look like:
<figure class="tp-center">
<img src="../data_node_selector-pin2-d.png" class="visible-dark" width="80%"/>
<img src="../data_node_selector-pin2-l.png" class="visible-light" width="80%"/>
<figcaption>Data node selector with pinned items</figcaption>
<figcaption>Data Node Selector with pinned items</figcaption>
</figure>

Here is what the control looks like after the 'Pinned only' switch was set and the scenario item
Expand All @@ -239,6 +219,6 @@ Note that the cycle item is not pinned because the other scenarios it contains a
- *Pinning* a scenario item pins all its data nodes.</br>
*Unpinning* a scenario item unpins all its data nodes.
- *Pinning* a cycle item pins all the data nodes across all its scenarios.</br>
*Unpinning* a cycle item unpins all the data nodes across all its scenarios.
*Unpinning* a cycle item unpins all the data nodes across all its scenarios.

Turn off the 'Pinned Only' switch to view the complete list of data nodes again.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading