Merge branch 'main' of github.com:mckinsey/vizro into feat/4o_mini

vizro-core/changelog.d/20240808_160555_huong_li_nguyen_extensions_and_customisations_summary.md

@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->

vizro-core/docs/pages/user-guides/extensions.md

@@ -0,0 +1,101 @@
+# How to extend and customize Vizro dashboards
+
+At its simplest, Vizro enables low-code configuration, but you can also customize it to go beyond its default capabilities by incorporating any Dash component, Dash callback, or Plotly chart.
+
+* **[Vizro customizations](#vizro-customizations)**. You can customize Vizro to extend the default functionality of Vizro and create Python functions as customized Plotly charts, tables, dashboard components, actions, or reactive HTML components, and then plug them directly into the existing Vizro dashboard configuration (as explained below).
+
+
+* **[Dash customizations](#dash-customizations)**. You can add custom Dash callbacks directly to any Vizro dashboard, enabling you to code beneath the Vizro layer and control Dash directly.
+
+
+* **[React.js customizations](#reactjs-customizations)**. You can add custom React.js components directly to any Vizro dashboard, enabling users to go beneath both the Vizro and Dash layers and control React.js directly
+
+
+Vizro offers the ability to combine ease of use of low-code configuration, with the flexibility of a range of high-code extensions to expand your dashboard's functionality.
+
+
+## Vizro customizations
+
+### [Custom charts](custom-charts.md)
+
+You can create custom chart functions in Vizro by wrapping Plotly chart code inside a
+Vizro chart function wrapper, and then use the functions directly inside the Vizro dashboard configuration. This enables the creation of `plotly.graph_objects` charts with multiple traces, or `plotly_express` charts with post update customizations
+
+
+### [Custom tables](custom-tables.md)
+
+If the available arguments for the [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] models are insufficient, you can create a custom Dash AG Grid or Dash DataTable.
+
+
+### [Custom components](custom-components.md)
+
+You can create a custom component based on any dash-compatible component (for example, [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)).
+
+All Vizro's components are based on `Dash` and ship with a set of defaults that can be modified. If you would like to overwrite one of those defaults, or if you would like to use extra `args` or `kwargs` of those components, then this is the correct way to include those. You can use any existing attribute of any underlying [Dash component](https://dash.plotly.com/#open-source-component-libraries) with this method.
+
+
+### [Custom actions](custom-actions.md)
+
+If you want to use the [`Action`][vizro.models.Action] model to perform functions that are not available in the [pre-defined action functions][vizro.actions], you can create your own custom action.
+Like other [actions](actions.md), custom actions can also be added as an element inside the [actions chain](actions.md#chain-actions), and triggered with one of dashboard components.
+
+
+### [Custom figures](custom-figures.md)
+
+Custom figures are useful when you need a component that reacts to
+[filter](filters.md) and [parameter](parameters.md) controls.
+
+Vizro's [`Figure`][vizro.models.Figure] model accepts the `figure` argument, where you can enter _any_ custom figure function
+as described in the [how-to guide for figures](figure.md).
+
+
+## Dash customizations
+
+Since Vizro is built using Dash, it is possible to use [Dash callbacks](https://dash.plotly.com/basic-callbacks) directly in any Vizro dashboard. This enables you to code beneath the Vizro layer and control Dash directly,
+which is especially useful when working with callbacks
+
+Here is an example showing a Dash callback within Vizro,
+enabling an interaction between data points in a scatter plot and the content of a text card:
+
+!!! example "Dash callback example"
+
+    === "app.py"
+        ```{.python pycafe-link}
+        from dash import callback, Input, Output
+        import vizro.models as vm
+        import vizro.plotly.express as px
+        from vizro import Vizro
+
+        @callback(
+            Output("card_id", "children"),
+            Input("source_chart", "clickData")
+        )
+        def update_card(click_data):
+            if click_data is None:
+                return "Click on the graph to select a data point."
+            return f"Clicked species: '{click_data['points'][0]['customdata'][0]}'"
+
+        page = vm.Page(
+            title="Example: Dash callback within Vizro",
+            components=[
+                vm.Graph(id="source_chart",
+                         figure=px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species", custom_data=["species"])),
+                vm.Card(id="card_id",
+                        text="Click on the graph to apply filter interaction."),
+            ]
+        )
+
+        dashboard = vm.Dashboard(pages=[page])
+
+        Vizro().build(dashboard).run()
+        ```
+
+
+
+## React.js customizations
+
+It is possible to create custom React.js components and add them
+directly to any Vizro dashboard so enabling you to code beneath both the Vizro and Dash layers and control React.js directly
+
+For more information, see the documentation on [using React.js components with Dash](https://dash.plotly.com/plugins)

vizro-core/mkdocs.yml

@@ -35,6 +35,7 @@ nav:
           - Data: pages/user-guides/data.md
           - Kedro Data Catalog: pages/user-guides/kedro-data-catalog.md
       - EXTENSIONS:
+          - Overview: pages/user-guides/extensions.md
           - Custom charts: pages/user-guides/custom-charts.md
           - Custom tables: pages/user-guides/custom-tables.md
           - Custom components: pages/user-guides/custom-components.md