Improvement of custom charts docs

vizro-core/changelog.d/20231219_162443_maximilian_schulz_improve_custom_chart_docs.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/custom_charts.md

@@ -29,11 +29,15 @@ def minimal_example(data_frame:pd.DataFrame=None):
     return go.Figure()
 ```
 
-Building on the above, there are several routes one can take. The following examples are guides on the most common custom requests, but also serve as an illustration of more general principles:
+Building on the above, there are several routes one can take. The following examples are guides on the most common custom requests, but also serve as an illustration of more general principles.
+
+!!! tip
+
+    Custom charts can be targeted by [Filters](filters.md) or [Parameters](parameters.md). We will showcase both possibilities in the following examples. In particular the `Parameters` in combination with custom charts can be extremely versatile in achieving custom functionality.
 
 ## Enhanced `plotly.express` chart with reference line
 
-!!! example "Custom waterfall chart"
+!!! example "Custom `plotly.express` scatter chart"
     === "app.py"
         ```py
         import vizro.models as vm
@@ -65,13 +69,18 @@ Building on the above, there are several routes one can take. The following exam
                 ),
             ],
             controls=[
-                vm.Filter(column="petal_width"),
+                vm.Parameter( # (1)!
+                    targets=["enhanced_scatter.hline"],
+                    selector=vm.Slider(min=2, max=5, step=1, value=3, title="Horizontal line"),
+                ),
             ],
         )
         dashboard = vm.Dashboard(pages=[page_0])
 
         Vizro().build(dashboard).run()
         ```
+
+        1.  Note how we are able to target *any custom argument* of our custom chart. Since there is complete flexibility in terms of what can be derived from such custom arguments this allows for a wide range of customization options by the dashboard user.
     === "app.yaml"
         ```yaml
         # Custom charts are currently only possible via python configuration
@@ -86,7 +95,7 @@ Building on the above, there are several routes one can take. The following exam
 
 The below examples shows a more involved use-case. We create and style a waterfall chart, and add it alongside a filter to the dashboard. The example is based on [this](https://plotly.com/python/waterfall-charts/) tutorial.
 
-!!! example "Custom waterfall chart"
+!!! example "Custom `go.Figure()` waterfall chart"
     === "app.py"
         ```py
         import pandas as pd
@@ -136,13 +145,15 @@ The below examples shows a more involved use-case. We create and style a waterfa
                 ),
             ],
             controls=[
-                vm.Filter(column="x", selector=vm.Dropdown(title="Financial categories", multi=True)),
+                vm.Filter(column="x", selector=vm.Dropdown(title="Financial categories", multi=True)),# (1)!
             ],
         )
         dashboard = vm.Dashboard(pages=[page_0])
 
         Vizro().build(dashboard).run()
         ```
+
+        1.  Note how we are able to apply a filter even to a custom chart
     === "app.yaml"
         ```yaml
         # Custom charts are currently only possible via python configuration