From b6172973b6f007c7c844790837a920636aa3c400 Mon Sep 17 00:00:00 2001 From: joseph_perkins Date: Mon, 5 Aug 2024 10:58:42 +0100 Subject: [PATCH 01/15] first draft of extensions summary --- .../docs/pages/user-guides/extensions.md | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 vizro-core/docs/pages/user-guides/extensions.md diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md new file mode 100644 index 000000000..f5513f78e --- /dev/null +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -0,0 +1,81 @@ +# How to create custom functionality + +Vizro provides the ability to extensively customise a wide range of functioanlity, +and go far beyond the default Vizro capabilities + +1) **Vizro custom functions** - can be used to seamlessly extend the default functionality of Vizro +by allowing users to quickly create Python functions for customising charts, tables, dashboard components +callbacks in the form of actions, and reactive HTML components - then easily plug them directly +into the existing Vizro dashboard configuration + + +2) **Dash custom functions** - it is easy to create custom Dash callbacks and add them +directly to any Vizro dashboard - allowing users to go beneath the Vizro layer to control Dash directly + + +3) **React custom components** - it is possible to create custom Reach components and add them +directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control Reach directly + +## 1) Vizro custom functions + +Vizro custom functions can be used to seamlessly extend the default functionality of Vizro +by allowing users to quickly create Python functions for customising charts, tables, dashboard components +callbacks in the form of actions, and reactive HTML components - then easily plug them directly +into the existing Vizro dashboard configuration + +- ### Custom charts + +blurb + +[link](custom-charts.md) + +- ### Custom tables + +In cases where the available arguments for the [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] models are not sufficient, +you can create a custom Dash AG Grid or Dash DataTable. + +[link](custom-tables.md) + +- ### Custom components + +In general, 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 our components are based on `Dash`, and they are shipped with a set of sensible 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. + + +[link](custom-components.md) + +- ### Custom actions + +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 could also be added as an element inside the [actions chain](actions.md#chain-actions), and it can be triggered with one of many dashboard components. + + +[link](custom-actions.md) + +- ### Custom figures + +Custom figures are useful when you need a component that reacts to +[filter](filters.md) and [parameter](parameters.md) controls. + +The [`Figure`][vizro.models.Figure] model accepts the `figure` argument, where you can enter _any_ custom figure function +as explained in the [user guide on figures](figure.md). + + +[link](custom-figures.md) + +## 2) Dash custom functions + +It is easy to create custom Dash callbacks and add them +directly to any Vizro dashboard - allowing users to go beneath the Vizro layer to control Dash directly + +[link]() + +## 3) React custom components + +It is possible to create custom Reach components and add them +directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control Reach directly + +https://dash.plotly.com/plugins \ No newline at end of file From 7a765708c59a0ad4f7ed48cb19c907894cbb9c6f Mon Sep 17 00:00:00 2001 From: joseph_perkins Date: Mon, 5 Aug 2024 12:26:11 +0100 Subject: [PATCH 02/15] filling in the missing content (except for Dash customizations) fixing spelling --- .../docs/pages/user-guides/extensions.md | 98 ++++++++++--------- 1 file changed, 51 insertions(+), 47 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index f5513f78e..3016b3049 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -1,81 +1,85 @@ -# How to create custom functionality +# How to extend and customise Vizro dashboards -Vizro provides the ability to extensively customise a wide range of functioanlity, -and go far beyond the default Vizro capabilities +Vizro provides the ability to extensively customize a wide range of functioanlity, +and go far beyond the default Vizro capabilities - to avoid beining limited by any low-code configuration: -1) **Vizro custom functions** - can be used to seamlessly extend the default functionality of Vizro -by allowing users to quickly create Python functions for customising charts, tables, dashboard components +1) **Vizro customizations** - can be used to seamlessly extend the default functionality of Vizro +by allowing users to quickly create Python functions for customizing charts, tables, dashboard components callbacks in the form of actions, and reactive HTML components - then easily plug them directly into the existing Vizro dashboard configuration -2) **Dash custom functions** - it is easy to create custom Dash callbacks and add them +2) **Dash customizations** - it is possible to create custom Dash callbacks and add them directly to any Vizro dashboard - allowing users to go beneath the Vizro layer to control Dash directly -3) **React custom components** - it is possible to create custom Reach components and add them -directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control Reach directly +3) **React.js customizations** - it is possible to create custom React.js components and add them +directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control React.js directly -## 1) Vizro custom functions -Vizro custom functions can be used to seamlessly extend the default functionality of Vizro -by allowing users to quickly create Python functions for customising charts, tables, dashboard components -callbacks in the form of actions, and reactive HTML components - then easily plug them directly -into the existing Vizro dashboard configuration - -- ### Custom charts - -blurb - -[link](custom-charts.md) +This ability for extensive customization combines the ease and simplicity of Vizro configurations, +with the power go beyond that configuration and extend the dashboard functionality almost infinitely - +combining low-code and high-code approaches to provide the best of both worlds -- ### Custom tables -In cases where the available arguments for the [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] models are not sufficient, -you can create a custom Dash AG Grid or Dash DataTable. +## 1) Vizro customizations -[link](custom-tables.md) +Vizro custom functions can be used to seamlessly extend the default functionality of Vizro +by allowing users to quickly create Python functions for customizing charts, tables, dashboard components +callbacks in the form of actions, and reactive HTML components - then easily plug them directly +into the existing Vizro dashboard configuration -- ### Custom components +- ### [Custom charts](custom-charts.md) -In general, 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)). + It is possible to create custom chart functions in Vizro by wrapping Plotly chart code inside a + Vizro chart function wrapper, and then use them easily directly inside Vizro dashboard configuration. + This allows the creation of things like plotly.graph_objects charts with multiple traces, or plotly_express + charts with update_layout customizations -All our components are based on `Dash`, and they are shipped with a set of sensible 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 tables](custom-tables.md) + In cases where the available arguments for the [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] models are not sufficient, + you can create a custom Dash AG Grid or Dash DataTable. -[link](custom-components.md) -- ### Custom actions +- ### [Custom components](custom-components.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 could also be added as an element inside the [actions chain](actions.md#chain-actions), and it can be triggered with one of many dashboard components. + In general, 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 our components are based on `Dash`, and they are shipped with a set of sensible 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) -[link](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 could also be added as an element inside the [actions chain](actions.md#chain-actions), and it can be triggered with one of many dashboard components. + -- ### Custom figures +- ### [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. + Custom figures are useful when you need a component that reacts to + [filter](filters.md) and [parameter](parameters.md) controls. + + The [`Figure`][vizro.models.Figure] model accepts the `figure` argument, where you can enter _any_ custom figure function + as explained in the [user guide on figures](figure.md). -The [`Figure`][vizro.models.Figure] model accepts the `figure` argument, where you can enter _any_ custom figure function -as explained in the [user guide on figures](figure.md). +## 2) Dash customizations -[link](custom-figures.md) +Since Vizro is built with Dash, it is possible to use Dash callbacks directly in any Vizro dashboard - +allowing users to go beneath the Vizro layer to control Dash directly, +which is especially useful when working with callbacks -## 2) Dash custom functions +[link]() -It is easy to create custom Dash callbacks and add them -directly to any Vizro dashboard - allowing users to go beneath the Vizro layer to control Dash directly -[link]() +## 3) React.js customizations -## 3) React custom components +It is possible to create custom React.js components and add them +directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control React.js directly -It is possible to create custom Reach components and add them -directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control Reach directly +For more information view the documentation on [using React.js components with Dash](https://dash.plotly.com/plugins) -https://dash.plotly.com/plugins \ No newline at end of file From bd069907b916b2ecb4eaf136c94ae919949bbeeb Mon Sep 17 00:00:00 2001 From: joseph_perkins Date: Mon, 5 Aug 2024 12:27:01 +0100 Subject: [PATCH 03/15] fix spelling of title --- vizro-core/docs/pages/user-guides/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index 3016b3049..113d1a55a 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -1,4 +1,4 @@ -# How to extend and customise Vizro dashboards +# How to extend and customize Vizro dashboards Vizro provides the ability to extensively customize a wide range of functioanlity, and go far beyond the default Vizro capabilities - to avoid beining limited by any low-code configuration: From d65e0cbd94d4fbd768e95f0527681c0d314830e5 Mon Sep 17 00:00:00 2001 From: joseph_perkins Date: Wed, 7 Aug 2024 23:07:01 +0100 Subject: [PATCH 04/15] word refinement --- vizro-core/docs/pages/user-guides/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index 113d1a55a..0c4a64e75 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -69,7 +69,7 @@ into the existing Vizro dashboard configuration ## 2) Dash customizations -Since Vizro is built with Dash, it is possible to use Dash callbacks directly in any Vizro dashboard - +Since Vizro is built using Dash, it is possible to use Dash callbacks directly in any Vizro dashboard - allowing users to go beneath the Vizro layer to control Dash directly, which is especially useful when working with callbacks From 9ab098f61b89e804208068f190f19aecded3347b Mon Sep 17 00:00:00 2001 From: joseph_perkins Date: Thu, 8 Aug 2024 10:51:32 +0100 Subject: [PATCH 05/15] add dash callback example --- .../docs/pages/user-guides/extensions.md | 39 +++++++++++++++++-- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index 0c4a64e75..07cd18b32 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -73,13 +73,44 @@ Since Vizro is built using Dash, it is possible to use Dash callbacks directly i allowing users to go beneath the Vizro layer to control Dash directly, which is especially useful when working with callbacks -[link]() - +Here is a very simple 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" + ```py + 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() + ``` ## 3) React.js customizations It is possible to create custom React.js components and add them directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control React.js directly -For more information view the documentation on [using React.js components with Dash](https://dash.plotly.com/plugins) - +For more information view the documentation on [using React.js components with Dash](https://dash.plotly.com/plugins) \ No newline at end of file From 2713d6a84bbb341b00839289be61abc7628c8ef2 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 8 Aug 2024 10:18:56 +0000 Subject: [PATCH 06/15] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .../docs/pages/user-guides/extensions.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index 07cd18b32..1f9c7e64b 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -8,7 +8,7 @@ by allowing users to quickly create Python functions for customizing charts, tab callbacks in the form of actions, and reactive HTML components - then easily plug them directly into the existing Vizro dashboard configuration - + 2) **Dash customizations** - it is possible to create custom Dash callbacks and add them directly to any Vizro dashboard - allowing users to go beneath the Vizro layer to control Dash directly @@ -18,7 +18,7 @@ directly to any Vizro dashboard - allowing users to go beneath both the Vizro an This ability for extensive customization combines the ease and simplicity of Vizro configurations, -with the power go beyond that configuration and extend the dashboard functionality almost infinitely - +with the power go beyond that configuration and extend the dashboard functionality almost infinitely - combining low-code and high-code approaches to provide the best of both worlds @@ -32,11 +32,11 @@ into the existing Vizro dashboard configuration - ### [Custom charts](custom-charts.md) It is possible to create custom chart functions in Vizro by wrapping Plotly chart code inside a - Vizro chart function wrapper, and then use them easily directly inside Vizro dashboard configuration. + Vizro chart function wrapper, and then use them easily directly inside Vizro dashboard configuration. This allows the creation of things like plotly.graph_objects charts with multiple traces, or plotly_express charts with update_layout customizations - + - ### [Custom tables](custom-tables.md) In cases where the available arguments for the [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] models are not sufficient, @@ -47,33 +47,33 @@ into the existing Vizro dashboard configuration In general, 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 our components are based on `Dash`, and they are shipped with a set of sensible 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 could also be added as an element inside the [actions chain](actions.md#chain-actions), and it can be triggered with one of many 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. - + The [`Figure`][vizro.models.Figure] model accepts the `figure` argument, where you can enter _any_ custom figure function as explained in the [user guide on figures](figure.md). ## 2) Dash customizations -Since Vizro is built using Dash, it is possible to use Dash callbacks directly in any Vizro dashboard - +Since Vizro is built using Dash, it is possible to use Dash callbacks directly in any Vizro dashboard - allowing users to go beneath the Vizro layer to control Dash directly, which is especially useful when working with callbacks -Here is a very simple example showing a Dash callback within Vizro, +Here is a very simple 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" @@ -83,7 +83,7 @@ enabling an interaction between data points in a scatter plot and the content of import vizro.models as vm import vizro.plotly.express as px from vizro import Vizro - + @callback( Output("card_id", "children"), Input("source_chart", "clickData") @@ -92,7 +92,7 @@ enabling an interaction between data points in a scatter plot and the content of 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=[ @@ -102,9 +102,9 @@ enabling an interaction between data points in a scatter plot and the content of text="Click on the graph to apply filter interaction."), ] ) - + dashboard = vm.Dashboard(pages=[page]) - + Vizro().build(dashboard).run() ``` @@ -113,4 +113,4 @@ enabling an interaction between data points in a scatter plot and the content of It is possible to create custom React.js components and add them directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control React.js directly -For more information view the documentation on [using React.js components with Dash](https://dash.plotly.com/plugins) \ No newline at end of file +For more information view the documentation on [using React.js components with Dash](https://dash.plotly.com/plugins) From f036c7f1482bee8e39ab552e74bdd81222634907 Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 8 Aug 2024 15:18:28 +0200 Subject: [PATCH 07/15] Add overview to extensions navigation --- vizro-core/mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/vizro-core/mkdocs.yml b/vizro-core/mkdocs.yml index 953a49f50..b39b2fd2f 100644 --- a/vizro-core/mkdocs.yml +++ b/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 From 19fd1ded3ff40addfcd87257e50a6a7cfb12dbb1 Mon Sep 17 00:00:00 2001 From: Maximilian Schulz Date: Thu, 8 Aug 2024 15:29:32 +0200 Subject: [PATCH 08/15] Pre-emptive change for upcoming PR --- vizro-core/docs/pages/user-guides/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index 1f9c7e64b..3cb0d10e7 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -78,7 +78,7 @@ enabling an interaction between data points in a scatter plot and the content of !!! example "Dash callback example" === "app.py" - ```py + ```{.python pycafe-link} from dash import callback, Input, Output import vizro.models as vm import vizro.plotly.express as px From 922c03939e4f6adca097f8cb9fa3ef3ea00f7528 Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 8 Aug 2024 16:06:02 +0200 Subject: [PATCH 09/15] Fix spelling and lint --- ...n_extensions_and_customisations_summary.md | 48 +++++++++++++++++++ .../docs/pages/user-guides/extensions.md | 24 ++++++---- 2 files changed, 62 insertions(+), 10 deletions(-) create mode 100644 vizro-core/changelog.d/20240808_160555_huong_li_nguyen_extensions_and_customisations_summary.md diff --git a/vizro-core/changelog.d/20240808_160555_huong_li_nguyen_extensions_and_customisations_summary.md b/vizro-core/changelog.d/20240808_160555_huong_li_nguyen_extensions_and_customisations_summary.md new file mode 100644 index 000000000..f1f65e73c --- /dev/null +++ b/vizro-core/changelog.d/20240808_160555_huong_li_nguyen_extensions_and_customisations_summary.md @@ -0,0 +1,48 @@ + + + + + + + + + diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index 3cb0d10e7..b8bf75459 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -1,11 +1,11 @@ # How to extend and customize Vizro dashboards -Vizro provides the ability to extensively customize a wide range of functioanlity, -and go far beyond the default Vizro capabilities - to avoid beining limited by any low-code configuration: +Vizro provides the ability to extensively customize a wide range of functionality, +and go far beyond the default Vizro capabilities - to avoid being limited by any low-code configuration: 1) **Vizro customizations** - can be used to seamlessly extend the default functionality of Vizro -by allowing users to quickly create Python functions for customizing charts, tables, dashboard components -callbacks in the form of actions, and reactive HTML components - then easily plug them directly +by allowing users to create Python functions for customizing charts, tables, dashboard components +callbacks in the form of actions, and reactive HTML components - then plug them directly into the existing Vizro dashboard configuration @@ -25,16 +25,16 @@ combining low-code and high-code approaches to provide the best of both worlds ## 1) Vizro customizations Vizro custom functions can be used to seamlessly extend the default functionality of Vizro -by allowing users to quickly create Python functions for customizing charts, tables, dashboard components -callbacks in the form of actions, and reactive HTML components - then easily plug them directly +by allowing users to create Python functions for customizing charts, tables, dashboard components +callbacks in the form of actions, and reactive HTML components - then plug them directly into the existing Vizro dashboard configuration - ### [Custom charts](custom-charts.md) It is possible to create custom chart functions in Vizro by wrapping Plotly chart code inside a - Vizro chart function wrapper, and then use them easily directly inside Vizro dashboard configuration. - This allows the creation of things like plotly.graph_objects charts with multiple traces, or plotly_express - charts with update_layout customizations + Vizro chart function wrapper, and then use them directly inside Vizro dashboard configuration. + This enables the creation of things like `plotly.graph_objects` charts with multiple traces, or `plotly_express` + charts with post update customizations - ### [Custom tables](custom-tables.md) @@ -73,7 +73,7 @@ Since Vizro is built using Dash, it is possible to use Dash callbacks directly i allowing users to go beneath the Vizro layer to control Dash directly, which is especially useful when working with callbacks -Here is a very simple example showing a Dash callback within Vizro, +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" @@ -108,8 +108,12 @@ enabling an interaction between data points in a scatter plot and the content of Vizro().build(dashboard).run() ``` + + ## 3) React.js customizations + + It is possible to create custom React.js components and add them directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control React.js directly From 2697859c6efd17280e3e9e639f0bc076a65cdf28 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Thu, 8 Aug 2024 15:18:23 +0100 Subject: [PATCH 10/15] Update extensions.md --- vizro-core/docs/pages/user-guides/extensions.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index b8bf75459..7fb2a0786 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -1,20 +1,14 @@ # How to extend and customize Vizro dashboards -Vizro provides the ability to extensively customize a wide range of functionality, -and go far beyond the default Vizro capabilities - to avoid being limited by any low-code configuration: +At its simplest, Vizro enables low-code configuration, but you can also customize it to go beyond its default capabilities: -1) **Vizro customizations** - can be used to seamlessly extend the default functionality of Vizro -by allowing users to create Python functions for customizing charts, tables, dashboard components -callbacks in the form of actions, and reactive HTML components - then plug them directly -into the existing Vizro dashboard configuration +* **Vizro customizations** can be used to extend the default functionality of Vizro by enabling users to create Python functions to customize charts, tables, dashboard components, callbacks in the form of actions, and reactive HTML components, then plug them directly into the existing Vizro dashboard configuration. -2) **Dash customizations** - it is possible to create custom Dash callbacks and add them -directly to any Vizro dashboard - allowing users to go beneath the Vizro layer to control Dash directly +* **Dash customizations**, as custom Dash callbacks, can be added directly to any Vizro dashboard enabling you to code beneath the Vizro layer and control Dash directly. -3) **React.js customizations** - it is possible to create custom React.js components and add them -directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control React.js directly +* **React.js customizations** as custom React.js components can be added directly to any Vizro dashboard enabling users to go beneath both the Vizro and Dash layers and control React.js directly This ability for extensive customization combines the ease and simplicity of Vizro configurations, From 8a5d20f04b606ffdc3c621b4a23efaba04a267df Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Fri, 9 Aug 2024 12:26:38 +0100 Subject: [PATCH 11/15] Update extensions.md --- .../docs/pages/user-guides/extensions.md | 67 ++++++++----------- 1 file changed, 29 insertions(+), 38 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index 7fb2a0786..cbdc3b5f8 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -2,75 +2,68 @@ At its simplest, Vizro enables low-code configuration, but you can also customize it to go beyond its default capabilities: -* **Vizro customizations** can be used to extend the default functionality of Vizro by enabling users to create Python functions to customize charts, tables, dashboard components, callbacks in the form of actions, and reactive HTML components, then plug them directly into the existing Vizro dashboard configuration. +* **[Vizro customizations](#vizro-customizations)**. You can customize Vizro to extend the default functionality of Vizro and create Python functions to customize charts, tables, dashboard components, callbacks in the form of actions, and reactive HTML components, then plug them directly into the existing Vizro dashboard configuration. -* **Dash customizations**, as custom Dash callbacks, can be added directly to any Vizro dashboard enabling you to code beneath the Vizro layer and control Dash directly. +* **[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** as custom React.js components can be added directly to any Vizro dashboard enabling users to go beneath both the Vizro and Dash layers and control React.js 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 -This ability for extensive customization combines the ease and simplicity of Vizro configurations, -with the power go beyond that configuration and extend the dashboard functionality almost infinitely - -combining low-code and high-code approaches to provide the best of both worlds +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. -## 1) Vizro customizations +## Vizro customizations -Vizro custom functions can be used to seamlessly extend the default functionality of Vizro -by allowing users to create Python functions for customizing charts, tables, dashboard components +Vizro custom functions can be used to extend the default functionality of Vizro. You can create Python functions for customizing charts, tables, dashboard components callbacks in the form of actions, and reactive HTML components - then plug them directly into the existing Vizro dashboard configuration -- ### [Custom charts](custom-charts.md) +### [Custom charts](custom-charts.md) - It is possible to create custom chart functions in Vizro by wrapping Plotly chart code inside a - Vizro chart function wrapper, and then use them directly inside Vizro dashboard configuration. - This enables the creation of things like `plotly.graph_objects` charts with multiple traces, or `plotly_express` - charts with post update customizations +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) +### [Custom tables](custom-tables.md) - In cases where the available arguments for the [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] models are not sufficient, - you can create a custom Dash AG Grid or Dash DataTable. +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) +### [Custom components](custom-components.md) - In general, 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)). +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 our components are based on `Dash`, and they are shipped with a set of sensible 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. +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) +### [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 could also be added as an element inside the [actions chain](actions.md#chain-actions), and it can be triggered with one of many dashboard components. +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](custom-figures.md) - Custom figures are useful when you need a component that reacts to - [filter](filters.md) and [parameter](parameters.md) controls. +Custom figures are useful when you need a component that reacts to +[filter](filters.md) and [parameter](parameters.md) controls. - The [`Figure`][vizro.models.Figure] model accepts the `figure` argument, where you can enter _any_ custom figure function - as explained in the [user guide on figures](figure.md). +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). -## 2) Dash customizations +## Dash customizations -Since Vizro is built using Dash, it is possible to use Dash callbacks directly in any Vizro dashboard - -allowing users to go beneath the Vizro layer to control Dash directly, +Since Vizro is built using Dash, it is possible to use Dash 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 @@ -102,13 +95,11 @@ enabling an interaction between data points in a scatter plot and the content of Vizro().build(dashboard).run() ``` - -## 3) React.js customizations - +## React.js customizations It is possible to create custom React.js components and add them -directly to any Vizro dashboard - allowing users to go beneath both the Vizro and Dash layers to control React.js directly +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 view the documentation on [using React.js components with Dash](https://dash.plotly.com/plugins) +For more information, see the documentation on [using React.js components with Dash](https://dash.plotly.com/plugins) From 542521309bcb3aae5eeb77f91b3e9883ca3514a2 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Fri, 9 Aug 2024 12:29:09 +0100 Subject: [PATCH 12/15] Update vizro-core/docs/pages/user-guides/extensions.md --- vizro-core/docs/pages/user-guides/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index cbdc3b5f8..ae0776ab0 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -18,7 +18,7 @@ Vizro offers the ability to combine ease of use of low-code configuration, with Vizro custom functions can be used to extend the default functionality of Vizro. You can create Python functions for customizing charts, tables, dashboard components callbacks in the form of actions, and reactive HTML components - then plug them directly -into the existing Vizro dashboard configuration +into the existing Vizro dashboard configuration. ### [Custom charts](custom-charts.md) From b193571242764ee606b0bc231075f8ce54d65871 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Fri, 9 Aug 2024 15:30:45 +0100 Subject: [PATCH 13/15] Update extensions.md --- vizro-core/docs/pages/user-guides/extensions.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index ae0776ab0..0c5815c3d 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -1,6 +1,6 @@ # 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: +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 to customize charts, tables, dashboard components, callbacks in the form of actions, and reactive HTML components, then plug them directly into the existing Vizro dashboard configuration. @@ -16,10 +16,6 @@ Vizro offers the ability to combine ease of use of low-code configuration, with ## Vizro customizations -Vizro custom functions can be used to extend the default functionality of Vizro. You can create Python functions for customizing charts, tables, dashboard components -callbacks in the form of actions, and reactive HTML components - then plug them directly -into the existing Vizro dashboard configuration. - ### [Custom charts](custom-charts.md) You can create custom chart functions in Vizro by wrapping Plotly chart code inside a From 22d192aeab154b230a3a2972da414b0dc65fe394 Mon Sep 17 00:00:00 2001 From: joseph_perkins Date: Mon, 12 Aug 2024 10:21:56 +0100 Subject: [PATCH 14/15] make adjustments for PR comments --- vizro-core/docs/pages/user-guides/extensions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index 0c5815c3d..a35d13cbd 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -2,7 +2,7 @@ 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 to customize charts, tables, dashboard components, callbacks in the form of actions, and reactive HTML components, then plug them directly into the existing Vizro dashboard configuration. +* **[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, and reactive HTML components - 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. @@ -52,7 +52,7 @@ 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 directly in any Vizro dashboard. This enables you to code beneath the Vizro layer and control Dash directly, +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, From 33e1f1de1b3d00cbfb6d6195384d20813cdfcd4a Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 12 Aug 2024 13:04:32 +0100 Subject: [PATCH 15/15] Update extensions.md --- vizro-core/docs/pages/user-guides/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md index a35d13cbd..bfe887799 100644 --- a/vizro-core/docs/pages/user-guides/extensions.md +++ b/vizro-core/docs/pages/user-guides/extensions.md @@ -2,7 +2,7 @@ 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, and reactive HTML components - then plug them directly into the existing Vizro dashboard configuration (as explained below). +* **[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.