Merge branch 'main' into bug/components_range_slider_mark_step_bugfix

.pre-commit-config.yaml

@@ -22,6 +22,11 @@ repos:
         entry: tools/find_forbidden_words_in_repo.sh
         language: script
         pass_filenames: false
+      - id: check-branch-name
+        name: check-branch-name
+        entry: tools/check_branch_name.sh
+        language: script
+        pass_filenames: false
 
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6

pyproject.toml

@@ -14,7 +14,6 @@ target-version = ["py38"]
 
 [tool.codespell]
 builtin = "clear,rare,en-GB_to_en-US"
-dictionary = "tools/forbidden_words.txt"
 ignore-words-list = "grey"
 
 [tool.mypy]

tools/check_branch_name.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+BRANCH_LOCAL=$(git symbolic-ref --short HEAD)
+BRANCH_CI=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}
+REGEX="^(main|(release|feat|bug|docs|qa|dev|demo|ci|tidy)\/[^/]+(/[^/]+)*)$"
+
+if ! [[ $BRANCH_LOCAL =~ $REGEX ]]  && [[ $BRANCH_CI =~ $REGEX ]]; then
+  echo "Branch name is invalid - please rename your branch following this regex syntax: $REGEX"
+  exit 1
+fi

vizro-core/changelog.d/20231012_205313_huong_li_nguyen_update_guides_custom.md

@@ -0,0 +1,42 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Removed
+
+- A bullet item for the Removed category.
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category.
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category.
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category.
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category.
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category.
+
+-->

vizro-core/changelog.d/20231014_171921_huong_li_nguyen_provide_id_to_outer_containers.md

@@ -0,0 +1,41 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Removed
+
+- A bullet item for the Removed category.
+
+-->
+
+### Added
+
+- Provide ID to unique outer HTML divs on page ([#111](https://github.com/mckinsey/vizro/pull/111))
+
+<!--
+### Changed
+
+- A bullet item for the Changed category.
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category.
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category.
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category.
+
+-->

vizro-core/docs/pages/user_guides/custom_charts.md

@@ -1,16 +1,23 @@
 # How to create custom charts
 
 This guide shows you how to create custom charts and how to add them to your dashboard.
-
 The [`Graph`][vizro.models.Graph] model accepts the `figure` argument, where you can enter _any_ [`plotly.express`](https://plotly.com/python/plotly-express/) chart as explained in the user guide on [components][graph].
 
-We always recommend starting with [`plotly.express`](https://plotly.com/python/plotly-express/) charts first, but in case that none of the available charts fulfill your requirements, you can also use any custom created [`plotly.graph_objects.Figure()`](https://plotly.com/python/graph-objects/) object (in short `go.Figure()`). It is equally possible to _enhance_ the resulting `go.Figure()` of a `plotly.express` function call. In general, custom/customized charts need to obey the following conditions:
+## Overview of custom charts
+
+In general, the usage of the custom chart decorator `@capture("graph")` is required if your plotly chart requires any post-update calls or customization.
+
+### When to use a custom chart
+
+- If you want to use any of the post figure update calls by `plotly` e.g., `update_layout`, `update_xaxes`, `update_traces`, etc. (for more details, see the docs on [plotly's update calls](https://plotly.com/python/creating-and-updating-figures/#other-update-methods))
+- If you want to use a custom-created [`plotly.graph_objects.Figure()`](https://plotly.com/python/graph-objects/) object (in short, `go.Figure()`) and add traces yourself via [`add_trace`](https://plotly.com/python/creating-and-updating-figures/#adding-traces)
+
+### Requirements of a custom chart function
 
-!!! note "Conditions for using any `go.Figure()` in [`Graph`][vizro.models.Graph]"
-    - a `go.Figure()` object is returned by a function
-    - this function must be decorated with the `@capture("graph")` decorator
-    - this function accepts a `data_frame` argument (of type `pandas.DataFrame`)
-    - the visualization is derived from and requires only one `pandas.DataFrame` (e.g. any further dataframes added through other arguments will not react to dashboard components such as `Filter`)
+- a `go.Figure()` object is returned by the function
+- the function must be decorated with the `@capture("graph")` decorator
+- the function accepts a `data_frame` argument (of type `pandas.DataFrame`)
+- the visualization is derived from and requires only one `pandas.DataFrame` (e.g. any further dataframes added through other arguments will not react to dashboard components such as `Filter`)
 
 The below minimal example can be used as a base to build more sophisticated charts.
 

vizro-core/docs/pages/user_guides/custom_components.md

@@ -1,9 +1,14 @@
 # How to create custom components
 
-This guide shows you how to create custom components or enhance existing ones. What is a component? A component in this context would be any of the currently existing models such as e.g. [`Filter`][vizro.models.Filter], [`Parameter`][vizro.models.Parameter], etc.
+If you can't find a component that you would like to have in the code basis, you can easily create your own custom component.
+This guide shows you how to create custom components or enhance existing ones.
+
+In general, you can create a custom component based on any dash-compatible component (e.g. [dash-core-components](https://dash.plotly.com/dash-core-components),
+[dash-bootstrap-components](https://dash-bootstrap-components.opensource.faculty.ai/), [dash-html-components](https://github.com/plotly/dash/tree/dev/components/dash-html-components), etc.).
+
 
 !!!warning
-    When creating your own custom components, you are responsible for the security of your creation. Vizro cannot guarantee
+    When creating your own custom components, you are responsible for the security of your component (e.g. prevent setting HTML from code which might expose users to cross-site scripting). Vizro cannot guarantee
     the security of custom created components, so make sure you keep this in mind when publicly deploying your dashboard.
 
 

vizro-core/docs/pages/user_guides/run.md

@@ -88,3 +88,16 @@ Run it via
 gunicorn app:server --workers 3
 ```
 in the cmd. For more gunicorn configuration, please refer to [gunicorn docs](https://docs.gunicorn.org/en/stable/configure.html)
+
+
+## Deployment of Vizro app
+In general, Vizro is returning a Dash app. So if you want to deploy a Vizro app, similar steps apply as if you were to deploy a Dash app.
+For more details, see the docs on [Dash for deployment](https://dash.plotly.com/deployment#heroku-for-sharing-public-dash-apps).
+
+For reference (where app is a Dash app):
+
+| Vizro                          | Dash                            |
+|:-------------------------------|:--------------------------------|
+| Vizro()                        | app                             |
+| Vizro().build(dashboard)       | app (after creating app.layout) |
+| Vizro().build(dashboard).run() | app.run()                       |

vizro-core/src/vizro/models/_dashboard.py

@@ -103,7 +103,7 @@ def build(self):
         self._update_theme()
 
         return dbc.Container(
-            id="dashboard_container",
+            id="dashboard_container_outer",
             children=[
                 html.Div(id=f"vizro_version_{vizro.__version__}"),
                 ActionLoop._create_app_callbacks(),
@@ -117,7 +117,7 @@ def build(self):
     def _update_theme():
         clientside_callback(
             ClientsideFunction(namespace="clientside", function_name="update_dashboard_theme"),
-            Output("dashboard_container", "className"),
+            Output("dashboard_container_outer", "className"),
             Input("theme_selector", "on"),
         )
 

vizro-core/src/vizro/models/_navigation/_accordion.py

@@ -76,7 +76,7 @@ def _get_accordion_container(self, accordion_items, accordion_buttons):
                 html.Hr(),
             ],
             className="nav_panel",
-            id=f"{self.id}_outer",
+            id="nav_panel_outer",
         )
 
     def _create_accordion(self, active_page_id):

vizro-core/src/vizro/models/_page.py

@@ -161,8 +161,7 @@ def _create_theme_switch():
     @staticmethod
     def _create_control_panel(controls_content):
         control_panel = html.Div(
-            children=[*controls_content, html.Hr()],
-            className="control_panel",
+            children=[*controls_content, html.Hr()], className="control_panel", id="control_panel_outer"
         )
         return control_panel if controls_content else None
 
@@ -185,6 +184,7 @@ def _create_component_container(self, components_content):
                 className="component_container_grid",
             ),
             className="component_container",
+            id="component_container_outer",
         )
         return component_container
 
@@ -196,23 +196,23 @@ def _arrange_containers(page_title, theme_switch, nav_panel, control_panel, comp
         """
         _, dashboard = next(model_manager._items_with_type(Dashboard))
         dashboard_title = (
-            html.Div(children=[html.H2(dashboard.title), html.Hr()], className="dashboard_title_outer")
+            html.Div(
+                children=[html.H2(dashboard.title), html.Hr()], className="dashboard_title", id="dashboard_title_outer"
+            )
             if dashboard.title
             else None
         )
 
         header_elements = [page_title, theme_switch]
         left_side_elements = [dashboard_title, nav_panel, control_panel]
-        header = html.Div(
-            children=header_elements,
-            className="header",
+        header = html.Div(children=header_elements, className="header", id="header_outer")
+        left_side = (
+            html.Div(children=left_side_elements, className="left_side", id="left_side_outer")
+            if any(left_side_elements)
+            else None
         )
-        left_side = html.Div(children=left_side_elements, className="left_side") if any(left_side_elements) else None
         right_side_elements = [header, component_container]
-        right_side = html.Div(
-            children=right_side_elements,
-            className="right_side",
-        )
+        right_side = html.Div(children=right_side_elements, className="right_side", id="right_side_outer")
         return left_side, right_side
 
     def _make_page_layout(self, controls_content, components_content):

vizro-core/src/vizro/static/css/layout.css

@@ -86,7 +86,7 @@
   width: 336px;
 }
 
-.dashboard_title_outer {
+.dashboard_title {
   display: flex;
   flex-direction: column;
   width: 100%;

vizro-core/tests/unit/vizro/models/_navigation/conftest.py

@@ -55,7 +55,7 @@ def accordion_from_page_as_list():
             html.Hr(),
         ],
         className="nav_panel",
-        id="accordion_list_outer",
+        id="nav_panel_outer",
     )
     return accordion
 
@@ -93,6 +93,6 @@ def accordion_from_pages_as_dict():
             html.Hr(),
         ],
         className="nav_panel",
-        id="accordion_dict_outer",
+        id="nav_panel_outer",
     )
     return accordion

vizro-core/tests/unit/vizro/models/test_dashboard.py

@@ -17,7 +17,7 @@
 @pytest.fixture()
 def dashboard_container():
     return dbc.Container(
-        id="dashboard_container",
+        id="dashboard_container_outer",
         children=[
             html.Div(id=f"vizro_version_{vizro.__version__}"),
             ActionLoop._create_app_callbacks(),