From 3e666230177ad08ed5ce7a9745a5984d5f70d9fd Mon Sep 17 00:00:00 2001
From: Fabien Lelaquais <86590727+FabienLelaquais@users.noreply.github.com>
Date: Wed, 27 Nov 2024 10:56:17 +0100
Subject: [PATCH] Update Scenario Selector documentation with 4.0 features
(#1215)
- Added Filtering, Sorting and Searching section in the Scenario Selector doc page.
- Added actual MUI icons to be used in the doc body text (added to the table control doc page).
- Tiny doc adjustement in the metric control formatting paragraph.
- Tiny doc change in the toggle control.
- Force UTF-8 encoding in Markdown generation.
- Release Notes updated.
---
.gitignore | 1 +
.../corelements/data_node.md_template | 31 +-
.../data_node_selector.md_template | 78 ++----
.../scenario_selector-create-d.png | Bin 49179 -> 19899 bytes
.../scenario_selector-create-l.png | Bin 49084 -> 19346 bytes
.../scenario_selector-filled-d.png | Bin 53455 -> 0 bytes
.../scenario_selector-filled-l.png | Bin 54142 -> 0 bytes
.../scenario_selector-filter1-d.png | Bin 0 -> 35598 bytes
.../scenario_selector-filter1-l.png | Bin 0 -> 36172 bytes
.../scenario_selector-filter2-d.png | Bin 0 -> 4542 bytes
.../scenario_selector-filter2-l.png | Bin 0 -> 4274 bytes
.../scenario_selector-filter3-d.png | Bin 0 -> 25193 bytes
.../scenario_selector-filter3-l.png | Bin 0 -> 27313 bytes
.../scenario_selector-filter4-d.png | Bin 0 -> 5050 bytes
.../scenario_selector-filter4-l.png | Bin 0 -> 5249 bytes
.../scenario_selector-filter5-d.png | Bin 0 -> 21417 bytes
.../scenario_selector-filter5-l.png | Bin 0 -> 22063 bytes
.../corelements/scenario_selector-init1-d.png | Bin 0 -> 29896 bytes
.../corelements/scenario_selector-init1-l.png | Bin 0 -> 30738 bytes
.../scenario_selector-search1-d.png | Bin 0 -> 27107 bytes
.../scenario_selector-search1-l.png | Bin 0 -> 27758 bytes
.../scenario_selector-search2-d.png | Bin 0 -> 11956 bytes
.../scenario_selector-search2-l.png | Bin 0 -> 12109 bytes
.../corelements/scenario_selector-sort1-d.png | Bin 0 -> 25714 bytes
.../corelements/scenario_selector-sort1-l.png | Bin 0 -> 26858 bytes
.../corelements/scenario_selector-sort2-d.png | Bin 0 -> 3391 bytes
.../corelements/scenario_selector-sort2-l.png | Bin 0 -> 4435 bytes
.../corelements/scenario_selector-sort3-d.png | Bin 0 -> 3833 bytes
.../corelements/scenario_selector-sort3-l.png | Bin 0 -> 3834 bytes
.../corelements/scenario_selector-sort4-d.png | Bin 0 -> 25800 bytes
.../corelements/scenario_selector-sort4-l.png | Bin 0 -> 26426 bytes
.../corelements/scenario_selector.md_template | 265 +++++++++++++++---
.../viselements/generic/metric.md_template | 13 +-
.../gui/viselements/generic/table.md_template | 93 +++---
.../viselements/generic/toggle.md_template | 10 +-
docs/release-notes/index.md | 22 +-
.../dynamic_element/tabular_data_props.md | 109 +++----
docs/userman/gui/extension/extension_data.md | 8 +-
tools/_setup_generation/step_viselements.py | 79 +++++-
tools/postprocess.py | 32 ++-
40 files changed, 507 insertions(+), 234 deletions(-)
delete mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filled-d.png
delete mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filled-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter1-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter1-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter2-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter2-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter3-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter3-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter4-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter4-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter5-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-filter5-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-init1-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-init1-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-search1-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-search1-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-search2-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-search2-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-sort1-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-sort1-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-sort2-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-sort2-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-sort3-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-sort3-l.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-sort4-d.png
create mode 100644 docs/refmans/gui/viselements/corelements/scenario_selector-sort4-l.png
diff --git a/.gitignore b/.gitignore
index bd2bc7aa3..526413b2b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -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
diff --git a/docs/refmans/gui/viselements/corelements/data_node.md_template b/docs/refmans/gui/viselements/corelements/data_node.md_template
index b9503e904..aff98913c 100644
--- a/docs/refmans/gui/viselements/corelements/data_node.md_template
+++ b/docs/refmans/gui/viselements/corelements/data_node.md_template
@@ -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
@@ -59,8 +59,8 @@ top-left corner of the 'Properties' section:
Data representation switch
-In the image above, the switch is set to the 'Table' mode.
-The other option is the 'Chart' mode.
+In the image above, the switch is set to the 'Table' mode ([MUI:TableChartOutlined] icon).
+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).
@@ -123,9 +123,9 @@ From this tab, you can access the attributes of the data node:
The Properties section
-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.)
-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).
+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
@@ -135,20 +135,21 @@ property is set to True (which is its default value), the label of the owning en
The data node is owned by a scenario
-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).
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.).
-The user can cancel the creation of a new property by pressing the 'Cancel' button (with the ⨉
-icon).
-The user can delete a property by selecting it and pressing the *trash* button.
+name and value, and then pressing the [MUI:CheckCircle] icon.
+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
diff --git a/docs/refmans/gui/viselements/corelements/data_node_selector.md_template b/docs/refmans/gui/viselements/corelements/data_node_selector.md_template
index b50b595f0..37e6f430b 100644
--- a/docs/refmans/gui/viselements/corelements/data_node_selector.md_template
+++ b/docs/refmans/gui/viselements/corelements/data_node_selector.md_template
@@ -17,10 +17,8 @@ the selector might appear as follows:
Data nodes are organized in their owning scenario and cycle, when relevant.
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.
-Expanding the 'My scenario' item (by clicking the
-
-- 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
@@ -31,19 +29,17 @@ icons allow users to perform various actions:
- Data node selector toolbar
+ Data Node Selector toolbar
Users can interact with the icons in the toolbar to perform various tasks:
--
- : Opens a filter configuration dialog, allowing users to define filters that apply to the list of
- data nodes.
-- :
- Enables users to specify sorting preferences for organizing the data nodes in the list.
--
- : 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.
Filtering
@@ -52,16 +48,14 @@ criteria.
Opening the Filter dialog
-When the user presses the
-
-icon (Filter), the following dialog appears:
+When the user presses the [MUI:FilterList] icon (Filter), the following dialog appears:
Initialize filters
-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.
Creating a new filter
@@ -87,7 +81,7 @@ 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:
@@ -95,9 +89,7 @@ follows:
Create a new filter
-To add this filter to the filters list, the user must press the
-
-(Check) icon.
+To add this filter to the filters list, the user must press the [MUI:Check] icon (Check).
Multiple filters can be added as needed.
To close the filter configuration dialog, the user must click outside the dialog area.
@@ -109,15 +101,12 @@ Once filters are added, they are applied immediately. The filtered data node lis
Filters applied
-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
-
-(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).
Sorting
-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
@@ -136,9 +125,7 @@ Consider the following initial list of data nodes displayed in the selector:
Initial data nodes list
-When the user presses the
-
-icon (Sort), the sorting configuration dialog appears:
+When the user presses the [MUI:SortByAlpha] icon (Sort), the sorting configuration dialog appears:
@@ -155,10 +142,8 @@ In the following image, the user has selected the 'Label' property, and a descen
Sort criterion configuration
-After the sorting criterion is validated (pressing the
- 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:
@@ -166,9 +151,7 @@ data nodes:
The user can then create additional sorting criteria (which are applied in sequence).
-To remove a sorting rule, the user can select the
- 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.
@@ -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
-
-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:
@@ -194,9 +176,8 @@ labels containing the entered text:
Search active
-To close the search box, the user must press the
-
-icon (Search off) in the toolbar.
+To close the search box, the user must press the [MUI:SearchOffOutlined] icon (Search off) in the
+toolbar.
- 
@@ -95,9 +89,7 @@ follows:
@@ -155,10 +142,8 @@ In the following image, the user has selected the 'Label' property, and a descen
@@ -166,9 +151,7 @@ data nodes:
@@ -194,9 +176,8 @@ labels containing the entered text:
- 
-